rules 0.2

Creating predicates

Let’s ignore rule sets for a moment and go ahead and define a predicate. The easiest way is with the @predicate decorator:

>>> @rules.predicate
>>> def is_book_author(user, book):
...     return book.author == user
...
>>> is_book_author
<Predicate:is_book_author object at 0x10eeaa490>

This predicate will return True if the book’s author is the given user, False otherwise.

Predicates can be created from any callable that accepts anything from zero to two positional arguments:

• fn(obj, target)

• fn(obj)

• fn()

This is their generic form. If seen from the perspective of authorization in Django, the equivalent signatures are:

• fn(user, obj)

• fn(user)

• fn()

Predicates can do pretty much anything with the given arguments, but must always return True if the condition they check is true, False otherwise. rules comes with several predefined predicates that you may read about later on in API Reference, that are mostly useful when dealing with authorization in Django.

Setting up rules

Let’s pretend that we want to let authors edit or delete their books, but not books written by other authors. So, essentially, what determines whether an author can edit or can delete a given book is whether they are its author.

In rules, such requirements are modelled as rules. A rule is a map of a unique identifier (eg. “can edit”) to a predicate. Rules are grouped together into a rule set. rules has two predefined rule sets:

• A default rule set storing shared rules.

• Another rule set storing rules that serve as permissions in a Django context.

So, let’s define our first couple of rules, adding them to the shared rule set. We can use the is_book_author predicate we defined earlier:

>>> rules.add_rule('can_edit_book', is_book_author)
>>> rules.add_rule('can_delete_book', is_book_author)

Assuming we’ve got some data, we can now test our rules:

>>> from django.contrib.auth.models import User
>>> from books.models import Book
>>> guidetodjango = Book.objects.get(isbn='978-1-4302-1936-1')
>>> guidetodjango.author
<User: adrian>
>>> adrian = User.objects.get(username='adrian')
>>> rules.test_rule('can_edit_book', adrian, guidetodjango)
True
>>> rules.test_rule('can_delete_book', adrian, guidetodjango)
True

Nice… but not awesome.

Combining predicates

Predicates by themselves are not so useful – not more useful than any other function would be. Predicates, however, can be combined using binary operators to create more complex ones. Predicates support the following operators:

• P1 & P2: Returns a new predicate that returns True if both predicates return True, otherwise False.

• P1 | P2: Returns a new predicate that returns True if any of the predicates returns True, otherwise False.

• P1 ^ P2: Returns a new predicate that returns True if one of the predicates returns True and the other returns False, otherwise False.

• ~P: Returns a new predicate that returns the negated result of the original predicate.

Suppose the requirement for allowing a user to edit a given book was for them to be either the book’s author, or a member of the “editors” group. Allowing users to delete a book should still be determined by whether the user is the book’s author.

With rules that’s easy to implement. We’d have to define another predicate, that would return True if the given user is a member of the “editors” group, False otherwise. The built-in is_group_member factory will come in handy:

>>> is_editor = rules.is_group_member('editors')
>>> is_editor
<Predicate:is_group_member:editors object at 0x10eee1350>

We could combine it with the is_book_author predicate to create a new one that checks for either condition:

>>> is_book_author_or_editor = is_book_author | is_editor
>>> is_book_author_or_editor
<Predicate:(is_book_author | is_group_member:editors) object at 0x10eee1390>

We can now update our can_edit_book rule:

>>> rules.add_rule('can_edit_book', is_book_author_or_editor)
Traceback (most recent call last):
    ...
KeyError: A rule with name `can_edit_book` already exists
>>> rules.remove_rule('can_edit_book')
>>> rules.add_rule('can_edit_book', is_book_author_or_editor)
>>> rules.test_rule('can_edit_book', adrian, guidetodjango)
True
>>> rules.test_rule('can_delete_book', adrian, guidetodjango)
True

Let’s see what happens with another user:

>>> martin = User.objects.get(username='martin')
>>> list(martin.groups.values_list('name', flat=True))
['editors']
>>> rules.test_rule('can_edit_book', martin, guidetodjango)
True
>>> rules.test_rule('can_delete_book', martin, guidetodjango)
False

Awesome.

So far, we’ve only used the underlying, generic framework for defining and testing rules. This layer is not at all specific to Django; it may be used in any context. There’s actually no import of anything Django-related in the whole app (except in the rules.templatetags module). rules however can integrate tightly with Django to provide authorization.

Permissions

In rules, permissions are a specialised type of rules. You still define rules by creating and combining predicates. These rules however, must be added to a permissions-specific rule set that comes with rules so that they can be picked up by the rules authorization backend.

>>> rules.add_perm('books.change_book', is_book_author | is_editor)
>>> rules.add_perm('books.delete_book', is_book_author)

>>> adrian.has_perm('books.change_book', guidetodjango)
False

AUTHENTICATION_BACKENDS = (
    'rules.permissions.ObjectPermissionBackend',
    'django.contrib.auth.backends.ModelBackend',
)

>>> adrian.has_perm('books.change_book', guidetodjango)
True
>>> adrian.has_perm('books.delete_book', guidetodjango)
True
>>> martin.has_perm('books.change_book', guidetodjango)
True
>>> martin.has_perm('books.delete_book', guidetodjango)
False

Rules and permissions in templates

rules comes with two template tags to allow you to test for rules and permissions in templates.

Add rules to your INSTALLED_APPS:

INSTALLED_APPS = (
    # ...
    'rules',
)

Then, in your template:

{% load rules %}

{% has_perm 'books.change_book' author book as can_edit_book %}
{% if can_edit_book %}
    ...
{% endif %}

{% test_rule 'has_super_feature' user as has_super_feature %}
{% if has_super_feature %}
    ...
{% endif %}

Rules and permissions in the Admin

If you’ve setup rules to be used with permissions in Django, you’re almost set to also use rules to authorize any add/change/delete actions in the Admin. The Admin asks for four different permissions, depending on action:

• <app_label>.add_<modelname>

• <app_label>.change_<modelname>

• <app_label>.delete_<modelname>

• <app_label>

The first three are obvious. The fourth is the required permission for an app to be displayed in the Admin’s “dashboard”. Here’s some rules for our imaginary books app as an example:

>>> rules.add_perm('books', rules.always_allow)
>>> rules.add_perm('books.add_book', is_staff)
>>> rules.add_perm('books.change_book', is_staff)
>>> rules.add_perm('books.delete_book', is_staff)

# books/admin.py
from django.contrib import admin
from rules.contrib.admin import ObjectPermissionsModelAdmin
from .models import Book

class BookAdmin(ObjectPermissionsModelAdmin):
    pass

admin.site.register(Book, BookAdmin)

>>> rules.add_perm('books', rules.always_allow)
>>> rules.add_perm('books.add_book', has_author_profile)
>>> rules.add_perm('books.change_book', is_book_author_or_editor)
>>> rules.add_perm('books.delete_book', is_book_author)

Class rules.Predicate

You create Predicate instances by passing in a callable:

>>> def is_book_author(user, book):
...     return book.author == user
...
>>> pred = Predicate(is_book_author)
>>> pred
<Predicate:is_book_author object at 0x10eeaa490>

You may optionally provide a different name for the predicate that is used when inspecting it:

>>> pred = Predicate(is_book_author, name='another_name')
>>> pred
<Predicate:another_name object at 0x10eeaa490>

Class rules.RuleSet

RuleSet extends Python’s built-in dict type. Therefore, you may create and use a rule set any way you’d use a dict.

Decorators

@predicate

Decorator that creates a predicate out of any callable:

>>> @predicate
... def is_book_author(user, book):
...     return book.author == user
...
>>> is_book_author
<Predicate:is_book_author object at 0x10eeaa490>

Customising the predicate name:

>>> @predicate(name='another_name')
... def is_book_author(user, book):
...     return book.author == user
...
>>> is_book_author
<Predicate:another_name object at 0x10eeaa490>

Predefined predicates

always_allow()

Always returns True.

always_deny()

Always returns False.

is_authenticated(user)

Returns the result of calling user.is_authenticated(). Returns False if the given user does not have an is_authenticated method.

is_superuser(user)

Returns the result of calling user.is_superuser. Returns False if the given user does not have an is_superuser property.

is_staff(user)

Returns the result of calling user.is_staff. Returns False if the given user does not have an is_staff property.

is_active(user)

Returns the result of calling user.is_active. Returns False if the given user does not have an is_active property.

is_group_member(*groups)

Factory that creates a new predicate that returns True if the given user is a member of all the given groups, False otherwise.

Shortcuts