repoze.what.plugins.dj API documentation

The repoze.what Django plugin.

In-view functions

These are the functions that are meant to be used in your views:

repoze.what.plugins.dj.require(predicate, msg=None, denial_handler=None)

Enforce predicate before running a view.

Parameters:

This is a decorator for Django views, so you can be sure that it’s safe to proceed with the view.

Sample use:

from django.http import HttpResponse

from repoze.what.predicates import in_any_group
from repoze.what.plugins.dj import require

@require(in_any_group("admins", "dev"))
def sample_view(request):
    return HttpResponse("You're an admin and/or a developer!")

If the user does not belong to the “admins” or “dev” groups, the code inside the view won’t get executed and authorization will be denied using the default handler.

repoze.what.plugins.dj.enforce(predicate, request, msg=None, denial_handler=None)

Stop here if predicate is not met within the request.

Parameters:
Raises _AuthorizationDenial:
 

If the predicate is not met.

Sample use:

from django.http import HttpResponse

from repoze.what.predicates import in_any_group
from repoze.what.plugins.dj import enforce

def sample_view(request):
    enforce(in_any_group("admins", "dev"))
    return HttpResponse("You're an admin and/or a developer!")

If the user does not belong to the “admins” or “dev” groups, the code inside the view will get executed until the enforce() statement, where an exception will be raised and authorization will be denied using the default handler.

repoze.what.plugins.dj.can_access(path, request, view_func=None, view_args=(), view_kwargs={})

Forge a request to path and report whether authorization would be granted on ingress.

Parameters:
  • path (basestring) – The path to another place in the website; it may include the query string.
  • request (django.http.HttpRequest) – The Django request to be used as an starting point to forge the request.
  • view_func – The Django view at path.
  • view_args (tuple) – The positional arguments for view_func.
  • view_kwargs (dict) – The named arguments for view_func.
Raises django.core.urlresolvers.Resolver404:
 

If path does not exist.

If view_func is not passed, this function will resolve it.

Sample use:

from django.core.urlresolvers import reverse
from django.http import HttpResponse, HttpResponseRedirect

from repoze.what.plugins.dj import can_access

def take_me_somewhere(request):
    if can_access("/admin/", request):
        # The current user can access the admin site.
        return HttpResponseRedirect("/admin/")
    elif can_access("/blog/posts/16", request):
        # The current user can access blog post #16.
        return HttpResponseRedirect("/blog/post/16")
    
    if not can_access("/", request):
        # The current user cannot access the homepage.
        request.user.message_set.create("You cannot even visit the "
                                        "homepage!")
    
    return HttpResponse("You're staying here in the mean time!")

Note

Only access rules available in the global ACL collection will be taken into account. Rules set with @require or enforce cannot be taken into account.

repoze.what.plugins.dj.is_met(predicate, request)

Report whether predicate is met in the request.

Parameters:
Returns:

Whether the predicate is met.

Return type:

bool

This function is intented to help you get finer grained control on what is authorized. If you are controlling access to the whole view, this function is not the right one: Use @require or enforce instead.

Sample use:

from django.http import HttpResponse

from repoze.what.plugins.dj import is_met
from repoze.what.predicates import not_anonymous
from repoze.what.plugins.ip import ip_from

def my_view(request):
    if is_met(not_anonymous() & ip_from(["127.0.0.1", "192.168.1.0/24"]), request):
        request.user.message_set.create("This is a secret message. "
                                        "Only people on this network "
                                        "can see it.")
    return HttpResponse("Hi there!")
repoze.what.plugins.dj.not_met(predicate, request)

Report whether predicate is not met in the request.

Parameters:
Returns:

Whether the predicate is not met.

Return type:

bool

This function is intented to help you get finer grained control on what is authorized. If you are controlling access to the whole view, this function is not the right one: Use @require or enforce instead.

Sample use:

from django.http import HttpResponse

from repoze.what.plugins.dj import not_met
from repoze.what.predicates import not_anonymous
from repoze.what.plugins.ip import ip_from

def my_view(request):
    rights = ["You can watch TV", "You can eat", "You can jump"]
    if not_met(not_anonymous() & ip_from(["127.0.0.1", "192.168.1.0/24"]), request):
        # If the user is not authenticated and within the local network,
        # he cannot watch TV!
        del rights[0]
    return HttpResponse(", ".join(rights))

Django-specific predicate checkers

class repoze.what.plugins.dj.IsStaff(msg=None)

Check that the current user can access the Django’s admin site.

Under the hood, it uses request.user.is_staff.

class repoze.what.plugins.dj.IsActive(msg=None)

Check that the account for the current user is active.

Under the hood, it uses request.user.is_active.

class repoze.what.plugins.dj.IsSuperuser(msg=None)

Check that the current user is admin.

Under the hood, it uses request.user.is_superuser.

Ready to use instances

repoze.what.plugins.dj.IS_STAFF

Check that the current user can access the Django’s admin site.

Under the hood, it uses request.user.is_staff.

repoze.what.plugins.dj.IS_ACTIVE

Check that the account for the current user is active.

Under the hood, it uses request.user.is_active.

repoze.what.plugins.dj.IS_SUPERUSER

Check that the current user is admin.

Under the hood, it uses request.user.is_superuser.

Django middleware

class repoze.what.plugins.dj.RepozeWhatMiddleware

Django middleware to support repoze.what-powered authorization.

process_exception(request, exception)

Generate a proper response if authorization was denied in the view.

Both @require and enforce rely on this.

If no authorization denial handler was explicitly set, repoze.what.plugins.dj.denial_handlers.default_denial_handler() will be used.

When authorization is denied, a warning will be logged.

process_view(request, view_func, view_args, view_kwargs)

Check if authorization should be granted for this request or reject access if not.

Authorization will be granted if either:

  • it was explicitly granted according to the global ACL collection.
  • no decision was made by the global ACL collection.

It will only be denied if authorization was explicitly denied by the global ACL collection.

Whatever happens will be logged every time. Denials will be logged as warnings and the rest as informational logs.

It does nothing when requested media files.

Denial handlers

Default denial handler implementations.

repoze.what.plugins.dj.denial_handlers.default_denial_handler(request, denial_reason)

Return a 401/403 response and explain the user why authorization was denied.

Parameters:
Returns:

The Django response

Return type:

django.http.HttpResponse

This will return a 401 response if the user is anonymous or 403 if the user is authenticated.

Strictly speaking, a 401 status must come along a WWW-Authenticate header, but because we are only dealing with authorization, we are not going to do it – It’s up to the authentication routine to challenge the user however it wants, even replacing the 401 status code with something else.

If a denial_reason is set, it will be shown to the user if he is authenticated.