Utils

Shortcuts

get_user_role(user)

Returns the roles classes of the user.

from rolepermissions.shortcuts import get_user_roles

roles = get_user_roles(user)

assign_role(user, role)

Assigns a role to the user. Role parameter can be passed as string or role class object.

from rolepermissions.shortcuts import assign_role

assign_role(user, 'doctor')

remove_role(user)

Remove a role that was assigned to the specified user.

Remove all roles that was assigned to the specified user.

available_perm_status(user)

Returns a dictionary containg all permissions per role available to the role of the specified user. Role names are the keys of the dictionary with each role represented by another dictionary with permissions as keys. The permissions values are True or False indicating if the permission if granted or not.

from rolepermissions.shortcuts import available_perm_status

permissions = available_perm_status(user)

if permissions['create_medical_record']:
    print 'user can create medical record'

grant_permission(user, permission_name, role=None)

Grants a permission to a user for the given role. If no role passed, it will iterate through all roles of the given user and try to grant the permission for each role that has it. Will not grant a permission if the user doesn’t have the role or the permission is not listed in the role’s available_permissions.

from rolepermissions.shortcuts import grant_permission

grant_permission(user, 'create_medical_record', 'doctor')
>>> True
grant_permission(user, 'create_medical_record')
>>> True

revoke_permission(user, permission_name, role=None)

Revokes a permission for the given role. If no role passed, it will iterate through all roles to remove the permission from each role that contains it.

from rolepermissions.shortcuts import revoke_permission

revoke_permission(user, 'create_medical_record', 'doctor')
>>> True
revoke_permission(user, 'create_medical_record')
>>> True

Permission and role verification

The following functions will always return True for users with supper_user status.

has_role(user, roles)

Receives a user and a role and returns True if user has the specified role. Roles can be passed as object, snake cased string representation or inside a list.

from rolepermissions.verifications import has_role
from my_project.roles import Doctor

if has_role(user, [Doctor, 'nurse']):
    print 'User is a Doctor or a nurse'

has_permission(user, permission, role=None)

Receives a user and a permission and returns True is the user has ths specified permission for the role given. If no role passed it will iterate through all user roles and will check if the user has the given permission for every role that has the permission in the available_permissions list.

from rolepermissions.verifications import has_permission
from my_project.roles import Doctor
from records.models import MedicalRecord

if has_permission(user, 'create_medical_record'):
    medical_record = MedicalRecord(...)
    medical_record.save()

if has_permission(user, 'create_medical_record', 'doctor'):
    medical_record = MedicalRecord(...)
    medical_record.save()

get_role_limit(role)

Receives the role or a string (role name) and returns the limit for that role. Limit can be anything.

from rolepermissions.shortcuts import get_role_limit

permission_limit = get_permission_limit('doctor')

def get_permission_limit(role, permission_name)

Receives the role or a string (role name) and the permission_name and returns the limit for the permission or none if it hasn’t been declared.

from rolepermissions.shortcuts import get_permission_limit

permission_limit = get_permission_limit('doctor', 'create_medical_record')

has_object_permission(checker_name, user, obj)

Receives a string referencing the object permission checker, a user and the object to be verified.

from rolepermissions.verifications import has_object_permission
from clinics.models import Clinic

clinic = Clinic.objects.get(id=1)

if has_object_permission('access_clinic', user, clinic):
    print 'access granted'

Template tags

To load template tags use:

{% load permission_tags %}

*filter* has_role

Receives a camel case representation of a role or more than one separated by coma.

{% load permission_tags %}
{% if user|has_role:'doctor,nurse' %}
    the user is a doctor or a nurse
{% endif %}

*filter* can

Role permission filter. Role after permission is optional.

{% load permission_tags %}
{% if user|can:'create_medical_record:doctor' %}
    <a href="/create_record">create record</a>
{% endif %}

*tag* can

If no user is passed to the tag, the logged user will be used in the verification.

{% load permission_tags %}

{% can "access_clinic" clinic user=user as can_access_clinic %}
{% if can_access_clinic %}
    <a href="/clinic/1/">Clinic</a>
{% endif %}