Convenience Helpers

QuerySet and Manager Classes

class bridgekeeper.querysets.PermissionManager(*args, **kwargs)
visible_to(*args, **kwargs)

Filter the QuerySet to objects a user has a permission for.

Parameters

This method only works with permissions that are defined in perms; regular Django row-level permission checkers can’t be invoked on the QuerySet level.

It is a convenience wrapper around filter().

class bridgekeeper.querysets.PermissionQuerySet(model=None, query=None, using=None, hints=None)[source]

A QuerySet subclass that provides a convenience method.

visible_to(user, permission)[source]

Filter the QuerySet to objects a user has a permission for.

Parameters

This method only works with permissions that are defined in perms; regular Django row-level permission checkers can’t be invoked on the QuerySet level.

It is a convenience wrapper around filter().

View Mixins

class bridgekeeper.mixins.CreatePermissionGuardMixin(permission_map=None, *args, **kwargs)[source]

A view that checks permissions before creating model instances.

Use this mixin with CreateView, and supply the permission_name of a Bridgekeeper permission. Your view will then do two things:

  • Check that it’s possible for a user to create any new instances at all (i.e. that is_possible_for() returns True on the supplied permission). If not, the mixin raises PermissionDenied.

  • Just before the form is saved, checks the unsaved model instance against the supplied permission; if it fails, the mixin raises SuspiciousOperation.

Note that unlike QuerySetPermissionMixin, this mixin won’t automatically apply permissions for you. Ideally, your view (or the form class your view uses) should make it impossible for users to create instances they’re not allowed to create; fields that must be set to a certain value should be set automatically and not displayed in the form, choice fields should have their choices limited to only values the user is allowed to set, and so on.

Bridgekeeper can’t (and arguably shouldn’t) reach into your form and modify it for you. Instead, this mixin provides a last line of defence; if your view has a bug where a user can create something they’re not allowed to, the mixin will prevent the object from actually being created, and crash loudly in a way that your error reporting systems can pick up, allowing you to fix the bug.

permission_name

The name of the Bridgekeeper permission to check against, e.g. 'shrubberies.change_shrubbery'.

class bridgekeeper.mixins.QuerySetPermissionMixin(permission_map=None, *args, **kwargs)[source]

View mixin that filters QuerySets according to a permission.

Use this mixin with any class-based view that expects a get_queryset method (e.g. ListView, DetailView, UpdateView, or any other views that subclass from MultipleObjectMixin or SingleObjectMixin), and supply a permission_name attribute with the name of a Bridgekeeper permission.

The view’s queryset will then be automatically filtered to objects that the user requesting the page has the supplied permission for. For multiple-object views like ListView, objects the user doesn’t have the permission for just won’t be in the list. For single-object views like UpdateView, attempts to access objects the user doesn’t have the permission for will just 404.

permission_name

The name of the Bridgekeeper permission to check against, e.g. 'shrubberies.change_shrubbery'.