From 47e1df896b17aaaa97b73ef64010a7df4ea3d8d6 Mon Sep 17 00:00:00 2001 From: Russell Keith-Magee Date: Sat, 15 Dec 2012 22:15:11 +0800 Subject: Fixed #19412 -- Added PermissionsMixin to the auth.User heirarchy. This makes it easier to make a ModelBackend-compliant (with regards to permissions) User model. Thanks to cdestigter for the report about the relationship between ModelBackend and permissions, and to the many users on django-dev that contributed to the discussion about mixins. --- docs/topics/auth.txt | 70 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 70 insertions(+) (limited to 'docs') diff --git a/docs/topics/auth.txt b/docs/topics/auth.txt index bd5cfdaac2..3e2b6bbdbf 100644 --- a/docs/topics/auth.txt +++ b/docs/topics/auth.txt @@ -2136,6 +2136,76 @@ override any of the definitions that refer to fields on :class:`~django.contrib.auth.models.AbstractUser` that aren't on your custom User class. +Custom users and permissions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To make it easy to include Django's permission framework into your own User +class, Django provides :class:`~django.contrib.auth.model.PermissionsMixin`. +This is an abstract model you can include in the class heirarchy for your User +model, giving you all the methods and database fields necessary to support +Django's permission model. + +:class:`~django.contrib.auth.model.PermissionsMixin` provides the following +methods and attributes: + +.. class:: models.PermissionsMixin + + .. attribute:: models.PermissionsMixin.is_superuser + + Boolean. Designates that this user has all permissions without + explicitly assigning them. + + .. method:: models.PermissionsMixin.get_group_permissions(obj=None) + + Returns a set of permission strings that the user has, through his/her + groups. + + If ``obj`` is passed in, only returns the group permissions for + this specific object. + + .. method:: models.PermissionsMixin.get_all_permissions(obj=None) + + Returns a set of permission strings that the user has, both through + group and user permissions. + + If ``obj`` is passed in, only returns the permissions for this + specific object. + + .. method:: models.PermissionsMixin.has_perm(perm, obj=None) + + Returns ``True`` if the user has the specified permission, where perm is + in the format ``"."`` (see + `permissions`_). If the user is inactive, this method will + always return ``False``. + + If ``obj`` is passed in, this method won't check for a permission for + the model, but for this specific object. + + .. method:: models.PermissionsMixin.has_perms(perm_list, obj=None) + + Returns ``True`` if the user has each of the specified permissions, + where each perm is in the format + ``"."``. If the user is inactive, + this method will always return ``False``. + + If ``obj`` is passed in, this method won't check for permissions for + the model, but for the specific object. + + .. method:: models.PermissionsMixin.has_module_perms(package_name) + + Returns ``True`` if the user has any permissions in the given package + (the Django app label). If the user is inactive, this method will + always return ``False``. + +.. admonition:: ModelBackend + + If you don't include the + :class:`~django.contrib.auth.model.PermissionsMixin`, you must ensure you + don't invoke the permissions methods on ``ModelBackend``. ``ModelBackend`` + assumes that certain fields are available on your user model. If your User + model doesn't provide those fields, you will receive database errors when + you check permissions. + Custom users and Proxy models ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- cgit v1.3