newforms-admin: Merged from trunk up to [7120].

git-svn-id: http://code.djangoproject.com/svn/django/branches/newforms-admin@7121 bcc190cf-cafb-0310-a4f2-bffc1f526a37

12 files changed, 129 insertions, 25 deletions

diff --git a/docs/api_stability.txt b/docs/api_stability.txt
index 5ccf104327..769359b75e 100644
--- a/docs/api_stability.txt
+++ b/docs/api_stability.txt
@@ -88,7 +88,7 @@ change:
      API changes may be necessary.
 
    - Generic relations will most likely be moved out of core and into the
-     content-types contrib package to avoid core dependancies on optional
+     content-types contrib package to avoid core dependencies on optional
      components.
 
    - The comments framework, which is yet undocumented, will likely get a complete
diff --git a/docs/contenttypes.txt b/docs/contenttypes.txt
index 3ef83f2066..51ca8f0198 100644
--- a/docs/contenttypes.txt
+++ b/docs/contenttypes.txt
@@ -215,7 +215,7 @@ each ``TaggedItem`` will have a ``content_object`` field that returns the
 object it's related to, and you can also assign to that field or use it when
 creating a ``TaggedItem``::
 
-    >>> from django.contrib.models.auth import User
+    >>> from django.contrib.auth.models import User
     >>> guido = User.objects.get(username='Guido')
     >>> t = TaggedItem(content_object=guido, tag='bdfl')
     >>> t.save()
@@ -235,7 +235,7 @@ a "reverse" generic relationship to enable an additional API. For example::
 ``Bookmark`` instances will each have a ``tags`` attribute, which can
 be used to retrieve their associated ``TaggedItems``::
 
-    >>> b = Bookmark('http://www.djangoproject.com/')
+    >>> b = Bookmark(url='http://www.djangoproject.com/')
     >>> b.save()
     >>> t1 = TaggedItem(content_object=b, tag='django')
     >>> t1.save()
diff --git a/docs/distributions.txt b/docs/distributions.txt
index 48c30c7068..0c051c8da5 100644
--- a/docs/distributions.txt
+++ b/docs/distributions.txt
@@ -5,7 +5,7 @@ Third-party distributions of Django
 Several third-party distributors are now providing versions of Django integrated
 with their package-management systems. These can make installation and upgrading
 much easier for users of Django since the integration includes the ability to
-automatically install dependancies (like database adapters) that Django
+automatically install dependencies (like database adapters) that Django
 requires.
 
 Typically, these packages are based on the latest stable release of Django, so
diff --git a/docs/django-admin.txt b/docs/django-admin.txt
index 21821ab2e9..e79c105bbd 100644
--- a/docs/django-admin.txt
+++ b/docs/django-admin.txt
@@ -717,7 +717,7 @@ in Python package syntax, e.g. ``mysite.settings``. If this isn't provided,
 variable.
 
 Note that this option is unnecessary in ``manage.py``, because it uses
-``settings.py`` from the current project by default. 
+``settings.py`` from the current project by default.
 
 Extra niceties
 ==============
@@ -765,9 +765,9 @@ a command that can be executed as an action when you run ``manage.py``::
                 __init__.py
                 explode.py
         views.py
-        
+
 In this example, the ``explode`` command will be made available to any project
-that includes the ``fancy_blog`` application in ``settings.INSTALLED_APPS``.
+that includes the ``blog`` application in ``settings.INSTALLED_APPS``.
 
 The ``explode.py`` module has only one requirement -- it must define a class
 called ``Command`` that extends ``django.core.management.base.BaseCommand``.
diff --git a/docs/i18n.txt b/docs/i18n.txt
index 1ae3024157..78404d4503 100644
--- a/docs/i18n.txt
+++ b/docs/i18n.txt
@@ -292,6 +292,14 @@ translation string. Example::
 In this case, both the tag and the filter will see the already-translated
 string, so they don't need to be aware of translations.
 
+.. note::
+    In this example, the translation infrastructure will be passed the string
+    ``"yes,no"``, not the individual strings ``"yes"`` and ``"no"``. The
+    translated string will need to contain the comma so that the filter
+    parsing code knows how to split up the arguments. For example, a German
+    translator might translate the string ``"yes,no"`` as ``"ja,nein"``
+    (keeping the comma intact).
+
 .. _Django templates: ../templates_python/
 
 Working with lazy translation objects
diff --git a/docs/install.txt b/docs/install.txt
index 331a5ea8e3..542036e2af 100644
--- a/docs/install.txt
+++ b/docs/install.txt
@@ -138,7 +138,7 @@ Installing a distribution-specific package
 Check the `distribution specific notes`_ to see if your
 platform/distribution provides official Django packages/installers.
 Distribution-provided packages will typically allow for automatic
-installation of dependancies and easy upgrade paths.
+installation of dependencies and easy upgrade paths.
 
 Installing an official release
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/docs/localflavor.txt b/docs/localflavor.txt
index 75ec95382e..5a2e5b8fda 100644
--- a/docs/localflavor.txt
+++ b/docs/localflavor.txt
@@ -113,10 +113,23 @@ postal code or a CPA_.
 
 .. _CPA: http://www.correoargentino.com.ar/consulta_cpa/home.php
 
+ARDNIField
+----------
+
+A form field that validates input as a Documento Nacional de Identidad (DNI)
+number.
+
+ARCUITField
+-----------
+
+A form field that validates input as a Código Único de Identificación
+Tributaria (CUIT) number.
+
 ARProvinceSelect
 ----------------
 
-A ``Select`` widget that uses a list of Argentina's provinces as its choices.
+A ``Select`` widget that uses a list of Argentina's provinces and autonomous
+cities as its choices.
 
 Australia (``django.contrib.localflavor.au``)
 =============================================
@@ -610,7 +623,7 @@ UKNationSelect
 
 A ``Select`` widget that uses a list of UK nations as its choices.
 
-United States of America (``django.contrib.localflavor.us``) 
+United States of America (``django.contrib.localflavor.us``)
 ============================================================
 
 USPhoneNumberField
@@ -635,7 +648,7 @@ A valid SSN must obey the following rules:
 USStateField
 ------------
 
-A form field that validates input as a U.S. state name or abbreviation. It 
+A form field that validates input as a U.S. state name or abbreviation. It
 normalizes the input to the standard two-letter postal service abbreviation
 for the given state.
 
diff --git a/docs/model-api.txt b/docs/model-api.txt
index 3f908ec158..7eb0fdbb28 100644
--- a/docs/model-api.txt
+++ b/docs/model-api.txt
@@ -384,7 +384,7 @@ The admin represents this as an ``<input type="text">`` (a single-line input).
 ``IPAddressField``
 ~~~~~~~~~~~~~~~~~~
 
-An IP address, in string format (i.e. "24.124.1.30").
+An IP address, in string format (e.g. "192.0.2.30").
 
 The admin represents this as an ``<input type="text">`` (a single-line input).
 
@@ -952,10 +952,10 @@ the relationship should work. All are optional:
     ``limit_choices_to``     See the description under ``ForeignKey`` above.
 
     ``symmetrical``          Only used in the definition of ManyToManyFields on self.
-                             Consider the following model:
+                             Consider the following model::
 
-                             class Person(models.Model):
-                                 friends = models.ManyToManyField("self")
+                                 class Person(models.Model):
+                                     friends = models.ManyToManyField("self")
 
                              When Django processes this model, it identifies that it has
                              a ``ManyToManyField`` on itself, and as a result, it
@@ -1872,7 +1872,7 @@ more simply as::
 
 If you define a ``__unicode__()`` method on your model and not a ``__str__()``
 method, Django will automatically provide you with a ``__str__()`` that calls
-``__unicode()__`` and then converts the result correctly to a UTF-8 encoded
+``__unicode__()`` and then converts the result correctly to a UTF-8 encoded
 string object. This is recommended development practice: define only
 ``__unicode__()`` and let Django take care of the conversion to string objects
 when required.
diff --git a/docs/modelforms.txt b/docs/modelforms.txt
index 0136540bed..b9f0d88165 100644
--- a/docs/modelforms.txt
+++ b/docs/modelforms.txt
@@ -17,7 +17,7 @@ class from a Django model.
 For example::
 
     >>> from django.newforms import ModelForm
-    
+
     # Create the form class.
     >>> class ArticleForm(ModelForm):
     ...     class Meta:
@@ -113,7 +113,7 @@ In addition, each generated form field has attributes set as follows:
       ``default`` value will be initially selected instead).
 
 Finally, note that you can override the form field used for a given model
-field. See "Overriding the default field types" below.
+field. See `Overriding the default field types`_ below.
 
 A full example
 --------------
@@ -278,7 +278,7 @@ model fields:
     To avoid this failure, you must instantiate your model with initial values
     for the missing, but required fields, or use ``save(commit=False)`` and
     manually set any extra required fields::
-    
+
         instance = Instance(required_field='value')
         form = InstanceForm(request.POST, instance=instance)
         new_instance = form.save()
@@ -295,7 +295,7 @@ model fields:
 Overriding the default field types
 ----------------------------------
 
-The default field types, as described in the "Field types" table above, are
+The default field types, as described in the `Field types`_ table above, are
 sensible defaults. If you have a ``DateField`` in your model, chances are you'd
 want that to be represented as a ``DateField`` in your form. But
 ``ModelForm`` gives you the flexibility of changing the form field type
@@ -311,3 +311,48 @@ field, you could do the following::
     ...
     ...     class Meta:
     ...         model = Article
+
+If you want to override a field's default widget, then specify the ``widget``
+parameter when declaring the form field::
+
+   >>> class ArticleForm(ModelForm):
+   ...     pub_date = DateField(widget=MyDateWidget())
+   ...
+   ...     class Meta:
+   ...         model = Article
+
+Form inheritance
+----------------
+As with the basic forms, you can extend and reuse ``ModelForms`` by inheriting
+them. Normally, this will be useful if you need to declare some extra fields
+or extra methods on a parent class for use in a number of forms derived from
+models. For example, using the previous ``ArticleForm`` class::
+
+    >>> class EnhancedArticleForm(ArticleForm):
+    ...     def clean_pub_date(self):
+    ...         ...
+
+This creates a form that behaves identically to ``ArticleForm``, except there
+is some extra validation and cleaning for the ``pub_date`` field.
+
+You can also subclass the parent's ``Meta`` inner class if you want to change
+the ``Meta.fields`` or ``Meta.excludes`` lists::
+
+    >>> class RestrictedArticleForm(EnhancedArticleForm):
+    ...     class Meta(ArticleForm.Meta):
+    ...         exclude = ['body']
+
+This adds in the extra method from the ``EnhancedArticleForm`` and modifies
+the original ``ArticleForm.Meta`` to remove one field.
+
+There are a couple of things to note, however. Most of these won't normally be
+of concern unless you are trying to do something tricky with subclassing.
+
+ * Normal Python name resolution rules apply. If you have multiple base
+   classes that declare a ``Meta`` inner class, only the first one will be
+   used.  This means the child's ``Meta``, if it exists, otherwise the
+   ``Meta`` of the first parent, etc.
+
+ * For technical reasons, you cannot have a subclass that is inherited from
+   both a ``ModelForm`` and a ``Form`` simultaneously.
+
diff --git a/docs/request_response.txt b/docs/request_response.txt
index e3d794c9ba..47c66355e8 100644
--- a/docs/request_response.txt
+++ b/docs/request_response.txt
@@ -575,6 +575,10 @@ Three things to note about 404 views:
       to the template: ``request_path``, which is the URL that resulted
       in the 404.
 
+    * The 404 view is passed a ``RequestContext`` and will have access to
+      variables supplied by your ``TEMPLATE_CONTEXT_PROCESSORS`` (e.g.
+      ``MEDIA_URL``).
+
     * If ``DEBUG`` is set to ``True`` (in your settings module), then your 404
       view will never be used, and the traceback will be displayed instead.
 
@@ -587,8 +591,9 @@ the view ``django.views.defaults.server_error``, which loads and renders the
 template ``500.html``.
 
 This means you need to define a ``500.html`` template in your root template
-directory. This template will be used for all server errors. The
-default 500 view passes no variables to this template.
+directory. This template will be used for all server errors. The default 500
+view passes no variables to this template and is rendered with an empty
+``Context`` to lessen the chance of additional errors.
 
 This ``server_error`` view should suffice for 99% of Web applications, but if
 you want to override the view, you can specify ``handler500`` in your
diff --git a/docs/shortcuts.txt b/docs/shortcuts.txt
index 19eac4be6d..f1d7f38ffa 100644
--- a/docs/shortcuts.txt
+++ b/docs/shortcuts.txt
@@ -22,16 +22,29 @@ Required arguments
 Optional arguments
 ------------------
 
-``context``
+``dictionary``
     A dictionary of values to add to the template context. By default, this
     is an empty dictionary. If a value in the dictionary is callable, the
     view will call it just before rendering  the template.
 
+``context_instance``
+    The context instance to render the template with. By default, the template
+    will be rendered with a ``Context`` instance (filled with values from
+    ``dictionary``). If you need to use `context processors`_, you will want to
+    render the template with a ``RequestContext`` instance instead. Your code
+    might look something like this::
+
+        return render_to_response('my_template.html',
+                                  my_data_dictionary,
+                                  context_instance=RequestContext(request))
+
 ``mimetype``
     **New in Django development version:** The MIME type to use for the
     resulting document. Defaults to the value of the ``DEFAULT_CONTENT_TYPE``
     setting.
 
+.. _`context processors`: ../templates_python/#subclassing-context-requestcontext
+
 Example
 -------
 
@@ -57,8 +70,6 @@ This example is equivalent to::
         r = HttpResponse(t.render(c),
             mimetype="application/xhtml+xml")
 
-.. _an HttpResponse object: ../request_response/#httpresponse-objects
-
 ``get_object_or_404``
 =====================
 
diff --git a/docs/url_dispatch.txt b/docs/url_dispatch.txt
index 6ed7043fd5..952763f078 100644
--- a/docs/url_dispatch.txt
+++ b/docs/url_dispatch.txt
@@ -190,6 +190,28 @@ The remaining arguments should be tuples in this format::
 ...where ``optional dictionary`` and ``optional name`` are optional. (See
 `Passing extra options to view functions`_ below.)
 
+.. note::
+    Since `patterns()` is a function call, it accepts a maximum of 255
+    arguments (URL patterns, in this case). This is a limit for all Python
+    function calls. This will rarely be  problem in practice, since you'll
+    typically structure your URL patterns modularly by using `include()`
+    sections. However, on the off-chance you do hit the 255-argument limit,
+    realise that `patterns()` returns a Python list, so you can split up the
+    construction of the list.
+
+    ::
+
+        urlpatterns = patterns('',
+            ...
+            )
+        urlpatterns += patterns('',
+            ...
+            )
+
+    Python lists have unlimited size, so there's no limit to how many URL
+    patterns you can construct; merely that you may only create 254 at a time
+    (the 255-th argument is the initial prefix argument).
+
 url
 ---