django-rules Documentation

When Predicate.test() is invoked, a temporary context (a simple dict) is created. This context is valid only for the duration of that specific invocation. You can use it to cache expensive computations or set flags that subsequent predicates in the same chain can access.

Predicate.context also provides an args attribute containing the original arguments passed to test().

>>> @predicate
... def mypred(a, b):
...     value = compute_expensive_value(a)
...     mypred.context['value'] = value
...     return True

>>> @predicate
... def myotherpred(a, b):
...     value = myotherpred.context.get('value')
...     if value is not None:
...         return do_something_with_value(value)
...     else:
...         return do_something_without_value()

Predicates can be combined using binary operators to create complex logic. This allows you to build sophisticated permission requirements from simple building blocks.

Supported operators:

• P1 & P2: AND (Returns True if both are true. If P1 is False, P2 is not evaluated).
• P1 | P2: OR (Returns True if either is true. If P1 is True, P2 is not evaluated).
• P1 ^ P2: XOR (Returns True if exactly one is true).
• ~P: NOT (Negates the result of the predicate).

# Example: Author OR Editor
is_editor = rules.is_group_member('editors')
is_book_author_or_editor = is_book_author | is_editor

# Update an existing rule with the combined predicate
rules.set_rule('can_edit_book', is_book_author_or_editor)

A rule maps a unique identifier (e.g., 'can_edit_book') to a predicate. Rules are managed within a RuleSet. You can add rules to the default rule set using rules.add_rule() and test them using rules.test_rule(rule_name, user, obj).

# Define a predicate
@rules.predicate
def is_book_author(user, book):
    return book.author == user

# Add rules to the rule set
rules.add_rule('can_edit_book', is_book_author)
rules.add_rule('can_delete_book', is_book_author)

# Test the rules
# returns True if the user is the author
rules.test_rule('can_edit_book', adrian, guidetodjango)

You can install the rules library using pip.

$ pip install rules

To debug predicate evaluation, configure the rules logger at the DEBUG level. This will print a log message for each individual predicate when it is evaluated. If using Django, add this configuration to your settings.py.

LOGGING = {
    'version': 1,
    'disable_existing_loggers': False,
    'handlers': {
        'console': {
            'level': 'DEBUG',
            'class': 'logging.StreamHandler',
        },
    },
    'loggers': {
        'rules': {
            'handlers': ['console'],
            'level': 'DEBUG',
            'propagate': True,
        },
    },
}

To enable object-level permissions, you must add the rules.permissions.ObjectPermissionBackend to your Django AUTHENTICATION_BACKENDS setting. It is typically placed before the default ModelBackend.

Note: Calling has_perm on a superuser will always return True regardless of these settings.

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

To integrate rules with Django, you must add it to your INSTALLED_APPS and configure the AUTHENTICATION_BACKENDS to include rules.permissions.ObjectPermissionBackend. This allows Django to use rules for object-level permissions.

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

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

To avoid manual imports and potential circular dependencies, you can configure rules to automatically discover rules.py modules within your Django apps. Add rules.apps.AutodiscoverRulesConfig to your INSTALLED_APPS setting.

INSTALLED_APPS = (
    # replace 'rules' with:
    'rules.apps.AutodiscoverRulesConfig',
)

To use rules in templates, add 'rules' to your INSTALLED_APPS and load the tags using {% load rules %}.

• {% has_perm 'app.perm' object as var %}: Checks if a user has a specific permission for a given object.
• {% test_rule 'rule_name' user as var %}: Tests a specific rule against a user.

{% 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 %}

By default, Django Admin only checks model-level permissions. To enable object-level permission checking in the Admin, use rules.contrib.admin.ObjectPermissionsModelAdmin as the base class for your ModelAdmin.

This allows you to define rules for specific actions like add, view, change, and delete on specific instances.

# 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)

You can create predicates dynamically by wrapping the @rules.predicate decorator inside a factory function. This allows you to inject parameters into the predicate logic.

import rules


def role_is(role_id):
    @rules.predicate
    def user_has_role(user):
        return user.role.id == role_id

    return user_has_role


rules.add_perm("reports.view_report_abc", role_is(12))
rules.add_perm("reports.view_report_xyz", role_is(13))