Decorators

permission_required

guardian.decorators.permission_required(perm, lookup_variables=None, **kwargs)

Decorator for views that checks whether a user has a particular permission enabled.

Optionally, instances for which check should be made may be passed as an second argument or as a tuple parameters same as those passed to get_object_or_404 but must be provided as pairs of strings. This way decorator can fetch i.e. User instance based on performed request and check permissions on it (without this, one would need to fetch user instance at view’s logic and check permission inside a view).

Parameters:

• login_url – if denied, user would be redirected to location set by this parameter. Defaults to django.conf.settings.LOGIN_URL.
• redirect_field_name – name of the parameter passed if redirected. Defaults to django.contrib.auth.REDIRECT_FIELD_NAME.
• return_403 – if set to True then instead of redirecting to the login page, response with status code 403 is returned ( django.http.HttpResponseForbidden instance or rendered template - see GUARDIAN_RENDER_403). Defaults to False.
• return_404 – if set to True then instead of redirecting to the login page, response with status code 404 is returned ( django.http.HttpResponseNotFound instance or rendered template - see GUARDIAN_RENDER_404). Defaults to False.
• accept_global_perms – if set to True, then object level permission would be required only if user does NOT have global permission for target model. If turned on, makes this decorator like an extension over standard django.contrib.admin.decorators.permission_required as it would check for global permissions first. Defaults to False.

Examples:

@permission_required('auth.change_user', return_403=True)
def my_view(request):
    return HttpResponse('Hello')

@permission_required('auth.change_user', (User, 'username', 'username'))
def my_view(request, username):
    '''
    auth.change_user permission would be checked based on given
    'username'. If view's parameter would be named ``name``, we would
    rather use following decorator::

        @permission_required('auth.change_user', (User, 'username', 'name'))
    '''
    user = get_object_or_404(User, username=username)
    return user.get_absolute_url()

@permission_required('auth.change_user',
    (User, 'username', 'username', 'groups__name', 'group_name'))
def my_view(request, username, group_name):
    '''
    Similar to the above example, here however we also make sure that
    one of user's group is named same as request's ``group_name`` param.
    '''
    user = get_object_or_404(User, username=username,
        group__name=group_name)
    return user.get_absolute_url()

permission_required_or_403

guardian.decorators.permission_required_or_403(perm, *args, **kwargs)

Simple wrapper for permission_required decorator.

Standard Django’s permission_required decorator redirects user to login page in case permission check failed. This decorator may be used to return HttpResponseForbidden (status 403) instead of redirection.

The only difference between permission_required decorator is that this one always set return_403 parameter to True.