Usage

After Restrain is set up, the only object you need to use is the Restraint object.

Restraint Initialization

The Restraint object is initialized as follows:

from restraint import Restaint

# Load all permissions for the user
r = Restraint(user)

# Load some permissions for the user
r = Restraint(user, ['can_edit_accounts'])

The above code example shows how to initialize the object by loading all of the permissions for the user in the restraint object and how to also only load some of the permissions.

Checking For Permissions

When the Restraint object is initialized, the has_perm method may be used to determine the user has a particular permission.

from restraint import Restaint

# Load all permissions for the user
r = Restraint(user)

# Check if the user has any level for a permission
r.has_perm('can_edit_accounts')

# Check if the user has a particular level for a permission
r.has_perm('can_edit_accounts', 'all_accounts')

The above example shows how to check if a user has any level for a permission or if they have a level for a permission.

Checking Object Access

The user has the ability to define what IDs may be edited based on an id_filter function for each level in the Restraint configuration. The Restraint object can filter a queryset by the filters owned by the user by calling filter_qset.

from restraint import Restaint

# Load all permissions for the user
r = Restraint(user)

# Filter a queryset based on the user's permission levels
users_i_can_edit = r.filter_qset(User.objects.all(), 'can_edit_accounts')

In the above example, all User objects were filtered down to the ones that can be edited by the user.

Dynamically Syncing Permission Set Access

Restraint provides a model manager method if a user wants to sync a permission set access configuration to the database.

from restraint.models import PermAccess

PermAccess.objects.update_perm_set_access({
    'super': {
        'can_edit_stuff': ['all_stuff', 'some_stuff'],
        'can_view_stuff': [constants.BOOLEAN_LEVELS_NAME],
    },
    'individual': {
        'can_edit_stuff': ['some_stuff'],
    },
    'staff': {
        'can_edit_stuff': ['some_stuff', 'only_superusers']
    }
}, True)

In the above example, the same format as the default_access part of the Restraint configuration is used to sync the configuration of permission sets.

Adding And Removing Permissions For Individuals

Along with allowing permissions to be specified over permission sets, Restraint also provides the ability to assign permission levels to specific users.

To add a permission level to a user, do the following:

from restraint import constants
from restraint.models import PermAccess

user = individual_user_model_object

# Add a defined level
PermAccess.add_individual_access(user, 'my_perm', 'my_perm_level')

# Add the boolean level
PermAccess.add_individual_access(user, 'my_perm', constants.BOOLEAN_LEVELS_NAME)

To remove a permission level to a user, do the following:

from restraint import constants
from restraint.models import PermAccess

user = individual_user_model_object

# Remove a defined level
PermAccess.remove_individual_access(user, 'my_perm', 'my_perm_level')

# Remove the boolean level
PermAccess.remove_individual_access(user, 'my_perm', constants.BOOLEAN_LEVELS_NAME)

When individual permissions are added, they will be accessed the same way as permission set levels with the Restraint object.