[soc2009/model-validation] Merged to trunk at r11603

SECURITY ALERT: Corrected regular expressions for URL and email fields.

git-svn-id: http://code.djangoproject.com/svn/django/branches/soc2009/model-validation@11617 bcc190cf-cafb-0310-a4f2-bffc1f526a37

8 files changed, 92 insertions, 27 deletions

diff --git a/docs/topics/auth.txt b/docs/topics/auth.txt
index 615382bb07..6a62be8c32 100644
--- a/docs/topics/auth.txt
+++ b/docs/topics/auth.txt
@@ -212,14 +212,15 @@ Methods
     .. method:: models.User.has_perm(perm)
 
         Returns ``True`` if the user has the specified permission, where perm is
-        in the format ``"<application name>.<lowercased model name>"``. If the
-        user is inactive, this method will always return ``False``.
+        in the format ``"<app label>.<permission codename>"``.
+        If the user is inactive, this method will always return ``False``.
 
     .. method:: models.User.has_perms(perm_list)
 
         Returns ``True`` if the user has each of the specified permissions,
-        where each perm is in the format ``"package.codename"``. If the user is
-        inactive, this method will always return ``False``.
+        where each perm is in the format 
+        ``"<app label>.<permission codename>"``. If the user is inactive,
+        this method will always return ``False``.
 
     .. method:: models.User.has_module_perms(package_name)
 
@@ -689,8 +690,10 @@ The login_required decorator
 
         * If the user isn't logged in, redirect to
           :setting:`settings.LOGIN_URL <LOGIN_URL>` (``/accounts/login/`` by
-          default), passing the current absolute URL in the query string as
-          ``next`` or the value of ``redirect_field_name``. For example:
+          default), passing the current absolute URL in the query string. The
+          name of the GET argument is determined by the ``redirect_field_name``
+          argument provided to the decorator. The default argument name is
+          ``next``. For example:
           ``/accounts/login/?next=/polls/3/``.
 
         * If the user is logged in, execute the view normally. The view code is
@@ -726,14 +729,14 @@ the following line to your URLconf::
 
         * ``next``: The URL to redirect to after successful login. This may
           contain a query string, too.
-        
+
         * ``site``: The current :class:`~django.contrib.sites.models.Site`,
           according to the :setting:`SITE_ID` setting. If you don't have the
           site framework installed, this will be set to an instance of
           :class:`~django.contrib.sites.models.RequestSite`, which derives the
           site name and domain from the current
           :class:`~django.http.HttpRequest`.
-        
+
         * ``site_name``: An alias for ``site.name``. If you don't have the site
           framework installed, this will be set to the value of
           :attr:`request.META['SERVER_NAME'] <django.http.HttpRequest.META>`.
@@ -745,11 +748,11 @@ the following line to your URLconf::
     :file:`myapp/login.html` instead::
 
         (r'^accounts/login/$', 'django.contrib.auth.views.login', {'template_name': 'myapp/login.html'}),
-        
+
     You can also specify the name of the ``GET`` field which contains the URL
     to redirect to after login by passing ``redirect_field_name`` to the view.
     By default, the field is called ``next``.
-        
+
     Here's a sample :file:`registration/login.html` template you can use as a
     starting point. It assumes you have a :file:`base.html` template that
     defines a ``content`` block:
@@ -803,7 +806,7 @@ includes a few other useful built-in views located in
         * ``template_name``: The full name of a template to display after
           logging the user out. This will default to
           :file:`registration/logged_out.html` if no argument is supplied.
-          
+
         * ``redirect_field_name``: The name of a ``GET`` field containing the
           URL to redirect to after log out. Overrides ``next_page`` if the given
           ``GET`` parameter is passed.
@@ -862,17 +865,17 @@ includes a few other useful built-in views located in
         * ``email_template_name``: The full name of a template to use for
           generating the e-mail with the new password. This will default to
           :file:`registration/password_reset_email.html` if not supplied.
-        
+
         * ``password_reset_form``: Form that will be used to set the password.
           Defaults to ``SetPasswordForm``.
-        
+
         * ``token_generator``: Instance of the class to check the password. This
           will default to ``default_token_generator``, it's an instance of
           ``django.contrib.auth.tokens.PasswordResetTokenGenerator``.
-          
+
         * ``post_reset_redirect``: The URL to redirect to after a successful
           password change.
-          
+
     **Template context:**
 
         * ``form``: The form for resetting the user's password.
@@ -900,11 +903,11 @@ includes a few other useful built-in views located in
 
         * ``login_url``: The URL of the login page to redirect to. This will
           default to :setting:`settings.LOGIN_URL <LOGIN_URL>` if not supplied.
-          
+
         * ``redirect_field_name``: The name of a ``GET`` field containing the
           URL to redirect to after log out. Overrides ``next`` if the given
           ``GET`` parameter is passed.
-          
+
 .. function:: password_reset_confirm(request[, uidb36, token, template_name, token_generator, set_password_form, post_reset_redirect])
 
     Presents a form for entering a new password.
@@ -929,7 +932,7 @@ includes a few other useful built-in views located in
    Presents a view which informs the user that the password has been
    successfully changed.
 
-   **Optional arguments:** 
+   **Optional arguments:**
 
        * ``template_name``: The full name of a template to display the view.
          This will default to :file:`registration/password_reset_complete.html`.
@@ -1060,8 +1063,8 @@ The permission_required decorator
         my_view = permission_required('polls.can_vote')(my_view)
 
     As for the :meth:`User.has_perm` method, permission names take the form
-    ``"<application name>.<lowercased model name>"`` (i.e. ``polls.choice`` for
-    a ``Choice`` model in the ``polls`` application).
+    ``"<app label>.<permission codename>"`` (i.e. ``polls.can_vote`` for a
+    permission on a model in the ``polls`` application).
 
     Note that :func:`~django.contrib.auth.decorators.permission_required()`
     also takes an optional ``login_url`` parameter. Example::
diff --git a/docs/topics/cache.txt b/docs/topics/cache.txt
index 174dbae121..c9fd1b4012 100644
--- a/docs/topics/cache.txt
+++ b/docs/topics/cache.txt
@@ -361,6 +361,17 @@ then requests to ``/foo/1/`` and ``/foo/23/`` will be cached separately, as
 you may expect. But once a particular URL (e.g., ``/foo/23/``) has been
 requested, subsequent requests to that URL will use the cache.
 
+``cache_page`` can also take an optional keyword argument, ``key_prefix``, which
+works in the same way as the ``CACHE_MIDDLEWARE_KEY_PREFIX`` setting for the
+middleware.  It can be used like this::
+
+    my_view = cache_page(my_view, 60 * 15, key_prefix="site1")
+
+Or, using Python 2.4's decorator syntax::
+
+    @cache_page(60 * 15, key_prefix="site1")
+    def my_view(request):
+
 Specifying per-view cache in the URLconf
 ----------------------------------------
 
diff --git a/docs/topics/db/queries.txt b/docs/topics/db/queries.txt
index 5e353b2ec3..968ea7fbc8 100644
--- a/docs/topics/db/queries.txt
+++ b/docs/topics/db/queries.txt
@@ -622,6 +622,8 @@ To avoid this problem, simply save the ``QuerySet`` and reuse it::
     >>> print [p.headline for p in queryset] # Evaluate the query set.
     >>> print [p.pub_date for p in queryset] # Re-use the cache from the evaluation.
 
+.. _complex-lookups-with-q:
+
 Complex lookups with Q objects
 ==============================
 
diff --git a/docs/topics/forms/modelforms.txt b/docs/topics/forms/modelforms.txt
index add581268b..c5aa9c8a77 100644
--- a/docs/topics/forms/modelforms.txt
+++ b/docs/topics/forms/modelforms.txt
@@ -371,6 +371,35 @@ parameter when declaring the form field::
    ...     class Meta:
    ...         model = Article
 
+.. note::
+
+    If you explicitly instantiate a form field like this, Django assumes that you
+    want to completely define its behavior; therefore, default attributes (such as
+    ``max_length`` or ``required``) are not drawn from the corresponding model. If
+    you want to maintain the behavior specified in the model, you must set the
+    relevant arguments explicitly when declaring the form field.
+
+    For example, if the ``Article`` model looks like this::
+
+        class Article(models.Model):
+            headline = models.CharField(max_length=200, null=True, blank=True,
+                                        help_text="Use puns liberally")
+            content = models.TextField()
+
+    and you want to do some custom validation for ``headline``, while keeping
+    the ``blank`` and ``help_text`` values as specified, you might define
+    ``ArticleForm`` like this::
+
+        class ArticleForm(ModelForm):
+            headline = MyFormField(max_length=200, required=False,
+                                   help_text="Use puns liberally")
+
+            class Meta:
+                model = Article
+
+    See the :ref:`form field documentation <ref-forms-fields>` for more information
+    on fields and their arguments.
+
 Changing the order of fields
 ----------------------------
 
@@ -512,6 +541,12 @@ Then, pass your ``BaseAuthorFormSet`` class to the factory function::
 
     >>> AuthorFormSet = modelformset_factory(Author, formset=BaseAuthorFormSet)
 
+If you want to return a formset that doesn't include *any* pre-existing
+instances of the model, you can specify an empty QuerySet::
+
+   >>> AuthorFormSet(queryset=Author.objects.none())
+
+
 Controlling which fields are used with ``fields`` and ``exclude``
 -----------------------------------------------------------------
 
diff --git a/docs/topics/generic-views.txt b/docs/topics/generic-views.txt
index e4094ac000..c48c858f0b 100644
--- a/docs/topics/generic-views.txt
+++ b/docs/topics/generic-views.txt
@@ -64,7 +64,7 @@ code! --, actually the ``direct_to_template`` view simply grabs information from
 the extra-parameters dictionary and uses that information when rendering the
 view.
 
-Because this generic view -- and all the others -- is a regular view functions
+Because this generic view -- and all the others -- is a regular view function
 like any other, we can reuse it inside our own views. As an example, let's
 extend our "about" example to map URLs of the form ``/about/<whatever>/`` to
 statically rendered ``about/<whatever>.html``. We'll do this by first modifying
diff --git a/docs/topics/http/sessions.txt b/docs/topics/http/sessions.txt
index d3956504c7..3b1429b440 100644
--- a/docs/topics/http/sessions.txt
+++ b/docs/topics/http/sessions.txt
@@ -453,6 +453,20 @@ Default: ``'sessionid'``
 
 The name of the cookie to use for sessions. This can be whatever you want.
 
+SESSION_COOKIE_PATH
+-------------------
+
+.. versionadded:: 1.0
+
+Default: ``'/'``
+
+The path set on the session cookie. This should either match the URL path of
+your Django installation or be parent of that path.
+
+This is useful if you have multiple Django instances running under the same
+hostname. They can use different cookie paths, and each instance will only see
+its own session cookie.
+
 SESSION_COOKIE_SECURE
 ---------------------
 
diff --git a/docs/topics/http/shortcuts.txt b/docs/topics/http/shortcuts.txt
index 2bc35a3b9f..e8039fe253 100644
--- a/docs/topics/http/shortcuts.txt
+++ b/docs/topics/http/shortcuts.txt
@@ -147,7 +147,7 @@ will be returned::
 ``get_object_or_404``
 =====================
 
-.. function:: get_object_or_404(object, *args, **kwargs)
+.. function:: get_object_or_404(klass, *args, **kwargs)
 
    Calls :meth:`~django.db.models.QuerySet.get()` on a given model manager,
    but it raises ``django.http.Http404`` instead of the model's
diff --git a/docs/topics/testing.txt b/docs/topics/testing.txt
index cec6002b7b..25d2f083fd 100644
--- a/docs/topics/testing.txt
+++ b/docs/topics/testing.txt
@@ -515,7 +515,7 @@ arguments at time of construction:
         >>> c = Client()
         >>> c.get('/customers/details/?name=fred&age=7')
 
-        If you provide URL both an encoded GET data and a data argument,
+        If you provide a URL with both an encoded GET data and a data argument,
         the data argument will take precedence.
 
         If you set ``follow`` to ``True`` the client will follow any redirects
@@ -627,7 +627,7 @@ arguments at time of construction:
 
         .. versionadded:: 1.1
 
-        Makes an PUT request on the provided ``path`` and returns a
+        Makes a PUT request on the provided ``path`` and returns a
         ``Response`` object. Useful for testing RESTful interfaces. Acts just
         like :meth:`Client.post` except with the PUT request method.
 
@@ -1127,11 +1127,11 @@ Django, such as your machine's mail server, if you're running one.)
 
 During test running, each outgoing e-mail is saved in
 ``django.core.mail.outbox``. This is a simple list of all
-:class:`<~django.core.mail.EmailMessage>` instances that have been sent.
+:class:`~django.core.mail.EmailMessage` instances that have been sent.
 It does not exist under normal execution conditions, i.e., when you're not
 running unit tests. The outbox is created during test setup, along with the
-dummy :class:`<~django.core.mail.SMTPConnection>`. When the test framework is
-torn down, the standard :class:`<~django.core.mail.SMTPConnection>` class is
+dummy :class:`~django.core.mail.SMTPConnection`. When the test framework is
+torn down, the standard :class:`~django.core.mail.SMTPConnection` class is
 restored, and the test outbox is destroyed.
 
 The ``outbox`` attribute is a special attribute that is created *only* when