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 to settings.LOGIN_URL.

Mirroring the change in Django 1.4 this decorator also accepts the raise_exception parameter. If given, the decorator will raise PermissionDenied.

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 to settings.LOGIN_URL.

Mirroring the change in Django 1.4 this decorator also accepts the raise_exception parameter. If given, the decorator will raise PermissionDenied.

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

class SingleOwnerMixin

This class provides a simple way to assign ownership of a model instance to a single user.

owner

User object as provided by a ForeignKey model field.

Note

By default the related_name parameter is set to: '%(app_label)s_%(class)s_owner'

MultipleOwnerMixin

class MultipleOwnerMixin

This class provides a simple way to assign ownership of a model instance to multiple users.

owners

RelatedManager object as provided by a ManyToManyField model field.

Note

By default the related_name parameter is set to: '%(app_label)s_%(class)s_owners'

OwnerMixinManager

class OwnerMixinManager

Manager class used by SingleOwnerMixin and MultipleOwnerMixin 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.