Merge branch 'master' into schema-alteration

9 files changed, 77 insertions, 42 deletions

diff --git a/docs/topics/auth.txt b/docs/topics/auth.txt
index c0e56dbba0..307691bd4a 100644
--- a/docs/topics/auth.txt
+++ b/docs/topics/auth.txt
@@ -98,12 +98,13 @@ Fields
 
         This doesn't necessarily control whether or not the user can log in.
         Authentication backends aren't required to check for the ``is_active``
-        flag, so if you want to reject a login based on ``is_active`` being
-        ``False``, it's up to you to check that in your own login view.
-        However, the :class:`~django.contrib.auth.forms.AuthenticationForm`
-        used by the :func:`~django.contrib.auth.views.login` view *does*
-        perform this check, as do the permission-checking methods such as
-        :meth:`~models.User.has_perm` and the authentication in the Django
+        flag, and the default backends do not. If you want to reject a login
+        based on ``is_active`` being ``False``, it's up to you to check that in
+        your own login view or a custom authentication backend. However, the
+        :class:`~django.contrib.auth.forms.AuthenticationForm` used by the
+        :func:`~django.contrib.auth.views.login` view (which is the default)
+        *does* perform this check, as do the permission-checking methods such
+        as :meth:`~models.User.has_perm` and the authentication in the Django
         admin. All of those functions/methods will return ``False`` for
         inactive users.
 
@@ -1447,10 +1448,10 @@ The permission_required decorator
 
 .. currentmodule:: django.contrib.auth
 
-Limiting access to generic views
---------------------------------
+Applying permissions to generic views
+-------------------------------------
 
-To limit access to a :doc:`class-based generic view 
+To apply a permission to a :doc:`class-based generic view
 </ref/class-based-views/index>`, decorate the :meth:`View.dispatch
 <django.views.generic.base.View.dispatch>` method on the class. See
 :ref:`decorating-class-based-views` for details.
@@ -1476,12 +1477,13 @@ The Django admin site uses permissions as follows:
 * Access to delete an object is limited to users with the "delete"
   permission for that type of object.
 
-Permissions are set globally per type of object, not per specific object
-instance. For example, it's possible to say "Mary may change news stories," but
-it's not currently possible to say "Mary may change news stories, but only the
-ones she created herself" or "Mary may only change news stories that have a
-certain status, publication date or ID." The latter functionality is something
-Django developers are currently discussing.
+Permissions can be set not only per type of object, but also per specific
+object instance. By using the
+:meth:`~django.contrib.admin.ModelAdmin.has_add_permission`,
+:meth:`~django.contrib.admin.ModelAdmin.has_change_permission` and
+:meth:`~django.contrib.admin.ModelAdmin.has_delete_permission` methods provided
+by the :class:`~django.contrib.admin.ModelAdmin` class, it is possible to
+customize permissions for different object instances of the same type.
 
 Default permissions
 -------------------
@@ -1747,7 +1749,11 @@ By default, :setting:`AUTHENTICATION_BACKENDS` is set to::
 
     ('django.contrib.auth.backends.ModelBackend',)
 
-That's the basic authentication scheme that checks the Django users database.
+That's the basic authentication backend that checks the Django users database
+and queries the builtin permissions. It does not provide protection against
+brute force attacks via any rate limiting mechanism. You may either implement
+your own rate limiting mechanism in a custom auth backend, or use the
+mechanisms provided by most Web servers.
 
 The order of :setting:`AUTHENTICATION_BACKENDS` matters, so if the same
 username and password is valid in multiple backends, Django will stop
@@ -1767,8 +1773,9 @@ processing at the first positive match.
 Writing an authentication backend
 ---------------------------------
 
-An authentication backend is a class that implements two methods:
-``get_user(user_id)`` and ``authenticate(**credentials)``.
+An authentication backend is a class that implements two required methods:
+``get_user(user_id)`` and ``authenticate(**credentials)``, as well as a set of
+optional permission related :ref:`authorization methods <authorization_methods>`.
 
 The ``get_user`` method takes a ``user_id`` -- which could be a username,
 database ID or whatever -- and returns a ``User`` object.
@@ -1837,6 +1844,8 @@ object the first time a user authenticates::
             except User.DoesNotExist:
                 return None
 
+.. _authorization_methods:
+
 Handling authorization in custom backends
 -----------------------------------------
 
@@ -1867,13 +1876,16 @@ fairly simply::
                 return False
 
 This gives full permissions to the user granted access in the above example.
-Notice that the backend auth functions all take the user object as an argument,
-and they also accept the same arguments given to the associated
-:class:`django.contrib.auth.models.User` functions.
+Notice that in addition to the same arguments given to the associated
+:class:`django.contrib.auth.models.User` functions, the backend auth functions
+all take the user object, which may be an anonymous user, as an argument.
 
-A full authorization implementation can be found in
-`django/contrib/auth/backends.py`_, which is the default backend and queries
-the ``auth_permission`` table most of the time.
+A full authorization implementation can be found in the ``ModelBackend`` class
+in `django/contrib/auth/backends.py`_, which is the default backend and queries
+the ``auth_permission`` table most of the time. If you wish to provide
+custom behavior for only part of the backend API, you can take advantage of
+Python inheritence and subclass ``ModelBackend`` instead of implementing the
+complete API in a custom backend.
 
 .. _django/contrib/auth/backends.py: https://github.com/django/django/blob/master/django/contrib/auth/backends.py
 
@@ -1889,25 +1901,27 @@ authorize anonymous users to browse most of the site, and many allow anonymous
 posting of comments etc.
 
 Django's permission framework does not have a place to store permissions for
-anonymous users. However, it has a foundation that allows custom authentication
-backends to specify authorization for anonymous users. This is especially useful
-for the authors of re-usable apps, who can delegate all questions of authorization
-to the auth backend, rather than needing settings, for example, to control
-anonymous access.
+anonymous users. However, the user object passed to an authentication backend
+may be an :class:`django.contrib.auth.models.AnonymousUser` object, allowing
+the backend to specify custom authorization behavior for anonymous users. This
+is especially useful for the authors of re-usable apps, who can delegate all
+questions of authorization to the auth backend, rather than needing settings,
+for example, to control anonymous access.
 
+.. _inactive_auth:
 
 Authorization for inactive users
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. versionadded:: 1.3
+.. versionchanged:: 1.3
 
 An inactive user is a one that is authenticated but has its attribute
 ``is_active`` set to ``False``. However this does not mean they are not
 authorized to do anything. For example they are allowed to activate their
 account.
 
-The support for anonymous users in the permission system allows for
-anonymous users to have permissions to do something while inactive
+The support for anonymous users in the permission system allows for a scenario
+where anonymous users have permissions to do something while inactive
 authenticated users do not.
 
 Do not forget to test for the ``is_active`` attribute of the user in your own
@@ -1915,9 +1929,11 @@ backend permission methods.
 
 
 Handling object permissions
----------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Django's permission framework has a foundation for object permissions, though
 there is no implementation for it in the core. That means that checking for
 object permissions will always return ``False`` or an empty list (depending on
-the check performed).
+the check performed). An authentication backend will receive the keyword
+parameters ``obj`` and ``user_obj`` for each object related authorization
+method and can return the object level permission as appropriate.
diff --git a/docs/topics/cache.txt b/docs/topics/cache.txt
index 03afa86647..219b6c7795 100644
--- a/docs/topics/cache.txt
+++ b/docs/topics/cache.txt
@@ -595,7 +595,8 @@ the ``cache`` template tag. To give your template access to this tag, put
 
 The ``{% cache %}`` template tag caches the contents of the block for a given
 amount of time. It takes at least two arguments: the cache timeout, in seconds,
-and the name to give the cache fragment. For example:
+and the name to give the cache fragment. The name will be taken as is, do not
+use a variable. For example:
 
 .. code-block:: html+django
 
@@ -863,7 +864,7 @@ key version to provide a final cache key. By default, the three parts
 are joined using colons to produce a final string::
 
     def make_key(key, key_prefix, version):
-        return ':'.join([key_prefix, str(version), smart_str(key)])
+        return ':'.join([key_prefix, str(version), smart_bytes(key)])
 
 If you want to combine the parts in different ways, or apply other
 processing to the final key (e.g., taking a hash digest of the key
diff --git a/docs/topics/class-based-views/index.txt b/docs/topics/class-based-views/index.txt
index 6c2848944c..1ac70e6938 100644
--- a/docs/topics/class-based-views/index.txt
+++ b/docs/topics/class-based-views/index.txt
@@ -87,7 +87,7 @@ Where class based views shine is when you want to do the same thing many times.
 Suppose you're writing an API, and every view should return JSON instead of
 rendered HTML.
 
-We can use create a mixin class to use in all of our views, handling the
+We can create a mixin class to use in all of our views, handling the
 conversion to JSON once.
 
 For example, a simple JSON mixin might look something like this::
diff --git a/docs/topics/db/optimization.txt b/docs/topics/db/optimization.txt
index 573e1fd0aa..772792d39d 100644
--- a/docs/topics/db/optimization.txt
+++ b/docs/topics/db/optimization.txt
@@ -230,7 +230,7 @@ It is optimal because:
 #. Use of :ttag:`with` means that we store ``user.emails.all`` in a variable
    for later use, allowing its cache to be re-used.
 
-#. The line ``{% if emails %}`` causes ``QuerySet.__nonzero__()`` to be called,
+#. The line ``{% if emails %}`` causes ``QuerySet.__bool__()`` to be called,
    which causes the ``user.emails.all()`` query to be run on the database, and
    at the least the first line to be turned into an ORM object. If there aren't
    any results, it will return False, otherwise True.
diff --git a/docs/topics/forms/modelforms.txt b/docs/topics/forms/modelforms.txt
index 4cfde400a7..0ca37745c7 100644
--- a/docs/topics/forms/modelforms.txt
+++ b/docs/topics/forms/modelforms.txt
@@ -437,6 +437,10 @@ parameter when declaring the form field::
             class Meta:
                 model = Article
 
+    You must ensure that the type of the form field can be used to set the
+    contents of the corresponding model field. When they are not compatible,
+    you will get a ``ValueError`` as no implicit conversion takes place.
+
     See the :doc:`form field documentation </ref/forms/fields>` for more information
     on fields and their arguments.
 
diff --git a/docs/topics/i18n/formatting.txt b/docs/topics/i18n/formatting.txt
index d18781c0a9..b09164769e 100644
--- a/docs/topics/i18n/formatting.txt
+++ b/docs/topics/i18n/formatting.txt
@@ -21,7 +21,10 @@ necessary to set :setting:`USE_L10N = True <USE_L10N>` in your settings file.
 
     The default :file:`settings.py` file created by :djadmin:`django-admin.py
     startproject <startproject>` includes :setting:`USE_L10N = True <USE_L10N>`
-    for convenience.
+    for convenience.  Note, however, that to enable number formatting with
+    thousand separators it is necessary to set :setting:`USE_THOUSAND_SEPARATOR
+    = True <USE_THOUSAND_SEPARATOR>` in your settings file. Alternatively, you
+    could use :tfilter:`intcomma` to format numbers in your template.
 
 .. note::
 
diff --git a/docs/topics/i18n/translation.txt b/docs/topics/i18n/translation.txt
index c912bf9575..bdbb04823d 100644
--- a/docs/topics/i18n/translation.txt
+++ b/docs/topics/i18n/translation.txt
@@ -1247,6 +1247,12 @@ Activate this view by adding the following line to your URLconf::
 
 (Note that this example makes the view available at ``/i18n/setlang/``.)
 
+.. warning::
+
+    Make sure that you don't include the above URL within
+    :func:`~django.conf.urls.i18n.i18n_patterns` - it needs to be
+    language-independent itself to work correctly.
+
 The view expects to be called via the ``POST`` method, with a ``language``
 parameter set in request. If session support is enabled, the view
 saves the language choice in the user's session. Otherwise, it saves the
@@ -1266,7 +1272,7 @@ Here's example HTML template code:
 
 .. code-block:: html+django
 
-    <form action="/i18n/setlang/" method="post">
+    <form action="{% url 'set_language' %}" method="post">
     {% csrf_token %}
     <input name="next" type="hidden" value="{{ redirect_to }}" />
     <select name="language">
diff --git a/docs/topics/python3.txt b/docs/topics/python3.txt
index 3f799edac7..b09c1d2347 100644
--- a/docs/topics/python3.txt
+++ b/docs/topics/python3.txt
@@ -36,6 +36,11 @@ In order to enable the same behavior in Python 2, every module must import
     my_string = "This is an unicode literal"
     my_bytestring = b"This is a bytestring"
 
+If you need a byte string under Python 2 and a unicode string under Python 3,
+use the :func:`str` builtin::
+
+    str('my string')
+
 Be cautious if you have to `slice bytestrings`_.
 
 .. _slice bytestrings: http://docs.python.org/py3k/howto/pyporting.html#bytes-literals
diff --git a/docs/topics/serialization.txt b/docs/topics/serialization.txt
index 505ac17f09..ac1a77ed98 100644
--- a/docs/topics/serialization.txt
+++ b/docs/topics/serialization.txt
@@ -173,12 +173,12 @@ In particular, :ref:`lazy translation objects <lazy-translations>` need a
 
     import json
     from django.utils.functional import Promise
-    from django.utils.encoding import force_unicode
+    from django.utils.encoding import force_text
 
     class LazyEncoder(json.JSONEncoder):
         def default(self, obj):
             if isinstance(obj, Promise):
-                return force_unicode(obj)
+                return force_text(obj)
             return super(LazyEncoder, self).default(obj)
 
 .. _special encoder: http://docs.python.org/library/json.html#encoders-and-decoders