Tutorial

Example

Please visit http://github.com/robpogorzelski/django-permissionsx-example/ for a full working example of a Django project utilizing class-based views permissions checking and Tastypie integration.

Deeper look

P

permissionsx.models.P

P is the smallest building block. Permissions are defined using keyword arguments, for example:

P(user__is_superuser=True)

It means that the value of request.user.is_superuser will be compared with True. If the final result is True, the user will be granted access. Otherwise the user will be redirected to the settings.LOGIN_URL by default.

P objects can be negated and combined using ~, & and | operators, exactly the same way as Q objects.

Optionally, for more advanced workflows, P can be passed additional two keyword arguments for overriding default behavior:

  • if_false
  • if_true

It is useful in situations where user needs to be redirected to different URLs when specific conditions are met. For example, if user:

  • is not authenticated, redirect to login view by default;
  • is authenticated, but has insufficient permissions (e.g. needs to upgrade account), redirect to a view with payment options and show message using django.contrib.messages;
  • is authenticated and has sufficient permissions, let in.

Arg

permissionsx.models.Arg

Arg is used when permissions checking involves passing parameter to a method of an object attached to the request. This is most often used for checking access to specific objects, e.g.:

P(user__has_access_to=Arg('invoice'))

Note that Arg parameter is passed as a string. Basically, it is equivalent to:

request.user.has_access_to(request.invoice)

Cmp

permissionsx.models.Cmp

Cmp is used when permissions require comparing values of objects attached to the request even if the compared attributes are not currently available in the method scope. Also, Cmp prevents exceptions from non-existing relations (e.g. request.user.company while company can be null).

P(company__main_address__city=Cmp('user.address.city'))

Note that Cmp parameter is passed as a string. It is equivalent to:

request.company.main_address.city == request.user.address.city

So in this scenario, view is passed e.g. kwargs containing {‘slug’: ‘company-xyz’}. Company XYZ instance is retrieved from database and its headquarter’s city is compared to the one of a user currently accessing view. If these match, user is allowed to view page, can be redirected, shown a message etc.

Permissions

permissionsx.models.Permissions

Permissions may be passed as an instance or a class to Django views or Tastypie authorization classes and it encapsulates P definitions, e.g.:

class UserPermissions(Permissions):

    rules = P(user__is_authenticated=True)


class ArticleDetailView(PermissionsDetailView):

    model = Article
    permissions = UserPermissions()


class StaffOnlyAuthorization(TastypieAuthorization):

    permissions = UserPermissions()

Or the same just without subclassing Permissions:

class ArticleDetailView(PermissionsDetailView):

    model = Article
    permissions = Permissions(P(user__is_authenticated=True))

And yet another example, this time by reusing single definition:

is_authenticated = P(user__is_authenticated=True)


class ArticleDetailView(PermissionsDetailView):

    model = Article
    permissions = Permissions(is_authenticated)

Attributes:

  • permissions - required.