User authentication extensions¶
While Django comes with a built in user authentication system it leaves a couple of common use-cases incomplete. Django Extras fills in the missing pieces.
Installation¶
No installation is required, this extension does not require additional database models.
Convenience decorators¶
The staff_required decorator¶
-
staff_required
([include_superusers=True, login_url=None, raise_exception=False])¶ This decorator provides a simple way of restricting access to a particular view to users who have the is_staff flag set. Rather than using the ~django.contrib.auth.decorators.user_passes_test() decorator restricting a view to staff can be written as:
from django_extras.contrib.auth.decorators import staff_required @staff_required def my_view(request): ...
By default this decorator also includes users with the is_superuser flag set, these users can be excluded with the optional
include_superuser
parameter. Example:from django_extras.contrib.auth.decorators import staff_required @staff_required(include_superusers=False) def my_view(request): ...
As in the
login_required()
,login_url
defaults tosettings.LOGIN_URL
.Mirroring the change in Django 1.4 this decorator also accepts the
raise_exception
parameter. If given, the decorator will raisePermissionDenied
.
The superuser_required decorator¶
-
superuser_required
([login_url=None, raise_exception=False])¶ This decorator provides a simple way of restricting access to a particular view to users who have the is_superuser flag set. Rather than using the ~django.contrib.auth.decorators.user_passes_test() decorator restricting a view to super users can be written as:
from django_extras.contrib.auth.decorators import superuser_required @superuser_required def my_view(request): ...
As in the
login_required()
,login_url
defaults tosettings.LOGIN_URL
.Mirroring the change in Django 1.4 this decorator also accepts the
raise_exception
parameter. If given, the decorator will raisePermissionDenied
.
Ownership Mixin Models¶
Two mixin classes are provided that provide a consistent API for assigning ownership of a model instance to a user.
Example:
class MyModel(SingleOwnerMixin, models.Model):
name = models.CharField(max_length=50)
Many methods include include_staff and include_superuser parameters, these are used to treat staff and superuser users as if they are owners of the instance.
Both SingleOwnerMixin
and MultipleOwnerMixin
provide the
following methods.
-
class
OwnerMixinBase
¶
-
OwnerMixinBase.
owned_by
(user[, include_staff=False, include_superuser=False])¶ Returns a boolean value to indicate if the supplied user is a valid owner of a model instance.
-
OwnerMixinBase.
owner_list
()¶ Returns a list of
User
models that are owners of the model instance. A list is returned by both single and multiple versions of the mixin.
SingleOwnerMixin
¶
MultipleOwnerMixin
¶
OwnerMixinManager
¶
-
class
OwnerMixinManager
¶ Manager class used by
SingleOwnerMixin
andMultipleOwnerMixin
to obtain the instances of a model that has ownership assigned to a particular user.
Fetching owned instances¶
-
OwnerMixinManager.
owned_by
(user[, include_staff=False, include_superuser=False])¶
Returns a QuerySet
filtered by a user or users. The user parameter can
be either a single User
object or primary key, a sequence of User
objects or
primary keys.
Example:
# Single user
>>> MyModel.objects.owned_by(request.user)
[<MyModel: Foo>, <MyModel: Bar>]
# Multiple primary keys
>>> MyModel.objects.owned_by([1, 2, 3])
[<MyModel: Foo>, <MyModel: Bar>, <MyModel: Eek>]
Note
It is not possible to use the include_staff and include_superuser
parameters when passing a sequence for the user parameter. A
TypeError
exception will be raised in this case.
Shortcuts¶
-
get_owned_object_or_40x
([klass, owner, include_staff=False, include_superuser=False, *args, **kwargs])¶
A convenience method that mirrors the Django shortcut get_object_or_404.
If the object cannot be loaded a Http404
exception is raised, if a
user cannot be verified as an owner a PermissionDenied
exception is
raised.
As with the other extensions include_staff and include_superuser flags are provided. *args and **kwargs work in the same way as get_object_or_404.