Fixed #11010 - Add a foundation for object permissions to authentication backends. Thanks to Florian Apolloner for writing the initial patch.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@11807 bcc190cf-cafb-0310-a4f2-bffc1f526a37

1 files changed, 45 insertions, 4 deletions

diff --git a/docs/topics/auth.txt b/docs/topics/auth.txt
index ebd31e4e20..c85ff604bf 100644
--- a/docs/topics/auth.txt
+++ b/docs/topics/auth.txt
@@ -202,29 +202,49 @@ Methods
         :meth:`~django.contrib.auth.models.User.set_unusable_password()` has
         been called for this user.
 
-    .. method:: models.User.get_group_permissions()
+    .. method:: models.User.get_group_permissions(obj=None)
 
         Returns a list of permission strings that the user has, through his/her
         groups.
 
-    .. method:: models.User.get_all_permissions()
+        .. versionadded:: 1.2
+
+        If ``obj`` is passed in, only returns the group permissions for
+        this specific object.
+
+    .. method:: models.User.get_all_permissions(obj=None)
 
         Returns a list of permission strings that the user has, both through
         group and user permissions.
 
-    .. method:: models.User.has_perm(perm)
+        .. versionadded:: 1.2
+
+        If ``obj`` is passed in, only returns the permissions for this
+        specific object.
+
+    .. method:: models.User.has_perm(perm, obj=None)
 
         Returns ``True`` if the user has the specified permission, where perm is
         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)
+        .. versionadded:: 1.2
+
+        If ``obj`` is passed in, this method won't check for a permission for
+        the model, but for this specific object.
+
+    .. method:: models.User.has_perms(perm_list, obj=None)
 
         Returns ``True`` if the user has each of the specified permissions,
         where each perm is in the format 
         ``"<app label>.<permission codename>"``. If the user is inactive,
         this method will always return ``False``.
 
+        .. versionadded:: 1.2
+
+        If ``obj`` is passed in, this method won't check for permissions for
+        the model, but for the specific object.
+
     .. method:: models.User.has_module_perms(package_name)
 
         Returns ``True`` if the user has any permissions in the given package
@@ -1521,3 +1541,24 @@ A full authorization implementation can be found in
 the ``auth_permission`` table most of the time.
 
 .. _django/contrib/auth/backends.py: http://code.djangoproject.com/browser/django/trunk/django/contrib/auth/backends.py
+
+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).
+
+To enable object permissions in your own
+:ref:`authentication backend <ref-authentication-backends>` you'll just have
+to allow passing an ``obj`` parameter to the permission methods and set the
+``supports_objects_permissions`` class attribute to ``True``.
+
+A nonexistent ``supports_objects_permissions`` will raise a hidden
+``PendingDeprecationWarning`` if used in Django 1.2. In Django 1.3, this
+warning will be upgraded to a ``DeprecationWarning``, which will be displayed
+loudly. Additionally ``supports_objects_permissions`` will be set to ``False``.
+Django 1.4 will assume that every backend supports object permissions and
+won't check for the existence of ``supports_objects_permissions``, which
+means not supporting ``obj`` as a parameter will raise a ``TypeError``.