Shortcuts

Convenient shortcuts to manage or check object permissions.

assign_perm

guardian.shortcuts.assign_perm(perm, user_or_group, obj=None)

Assigns permission to user/group and object pair.

Parameters:
  • perm – proper permission for given obj, as string (in format: app_label.codename or codename). If obj is not given, must be in format app_label.codename.
  • user_or_group – instance of User, AnonymousUser or Group; passing any other object would raise guardian.exceptions.NotUserNorGroup exception
  • obj – persisted Django’s Model instance or None if assigning global permission. Default is None.

We can assign permission for Model instance for specific user:

>>> from django.contrib.sites.models import Site
>>> from guardian.models import User
>>> from guardian.shortcuts import assign_perm
>>> site = Site.objects.get_current()
>>> user = User.objects.create(username='joe')
>>> assign_perm("change_site", user, site)
<UserObjectPermission: example.com | joe | change_site>
>>> user.has_perm("change_site", site)
True

... or we can assign permission for group:

>>> group = Group.objects.create(name='joe-group')
>>> user.groups.add(group)
>>> assign_perm("delete_site", group, site)
<GroupObjectPermission: example.com | joe-group | delete_site>
>>> user.has_perm("delete_site", site)
True

Global permissions

This function may also be used to assign standard, global permissions if obj parameter is omitted. Added Permission would be returned in that case:

>>> assign_perm("sites.change_site", user)
<Permission: sites | site | Can change site>

remove_perm

guardian.shortcuts.remove_perm(perm, user_or_group=None, obj=None)

Removes permission from user/group and object pair.

Parameters:
  • perm – proper permission for given obj, as string (in format: app_label.codename or codename). If obj is not given, must be in format app_label.codename.
  • user_or_group – instance of User, AnonymousUser or Group; passing any other object would raise guardian.exceptions.NotUserNorGroup exception
  • obj – persisted Django’s Model instance or None if assigning global permission. Default is None.

get_perms

guardian.shortcuts.get_perms(user_or_group, obj)

Returns permissions for given user/group and object pair, as list of strings.

get_perms_for_model

guardian.shortcuts.get_perms_for_model(cls)

Returns queryset of all Permission objects for the given class. It is possible to pass Model as class or instance.

get_users_with_perms

guardian.shortcuts.get_users_with_perms(obj, attach_perms=False, with_superusers=False, with_group_users=True)

Returns queryset of all User objects with any object permissions for the given obj.

Parameters:
  • obj – persisted Django’s Model instance
  • attach_perms – Default: False. If set to True result would be dictionary of User instances with permissions’ codenames list as values. This would fetch users eagerly!
  • with_superusers – Default: False. If set to True result would contain all superusers.
  • with_group_users – Default: True. If set to False result would not contain those users who have only group permissions for given obj.

Example:

>>> from django.contrib.flatpages.models import FlatPage
>>> from django.contrib.auth.models import User
>>> from guardian.shortcuts import assign_perm, get_users_with_perms
>>>
>>> page = FlatPage.objects.create(title='Some page', path='/some/page/')
>>> joe = User.objects.create_user('joe', 'joe@example.com', 'joesecret')
>>> assign_perm('change_flatpage', joe, page)
>>>
>>> get_users_with_perms(page)
[<User: joe>]
>>>
>>> get_users_with_perms(page, attach_perms=True)
{<User: joe>: [u'change_flatpage']}

get_groups_with_perms

guardian.shortcuts.get_groups_with_perms(obj, attach_perms=False)

Returns queryset of all Group objects with any object permissions for the given obj.

Parameters:
  • obj – persisted Django’s Model instance
  • attach_perms – Default: False. If set to True result would be dictionary of Group instances with permissions’ codenames list as values. This would fetch groups eagerly!

Example:

>>> from django.contrib.flatpages.models import FlatPage
>>> from guardian.shortcuts import assign_perm, get_groups_with_perms
>>> from guardian.models import Group
>>>
>>> page = FlatPage.objects.create(title='Some page', path='/some/page/')
>>> admins = Group.objects.create(name='Admins')
>>> assign_perm('change_flatpage', admins, page)
>>>
>>> get_groups_with_perms(page)
[<Group: admins>]
>>>
>>> get_groups_with_perms(page, attach_perms=True)
{<Group: admins>: [u'change_flatpage']}

get_objects_for_user

guardian.shortcuts.get_objects_for_user(user, perms, klass=None, use_groups=True, any_perm=False)

Returns queryset of objects for which a given user has all permissions present at perms.

Parameters:
  • userUser or AnonymousUser instance for which objects would be returned.
  • perms – single permission string, or sequence of permission strings which should be checked. If klass parameter is not given, those should be full permission names rather than only codenames (i.e. auth.change_user). If more than one permission is present within sequence, their content type must be the same or MixedContentTypeError exception would be raised.
  • klass – may be a Model, Manager or QuerySet object. If not given this parameter would be computed based on given params.
  • use_groups – if False, wouldn’t check user’s groups object permissions. Default is True.
  • any_perm – if True, any of permission in sequence is accepted
Raises:
  • MixedContentTypeError – when computed content type for perms and/or klass clashes.
  • WrongAppError – if cannot compute app label for given perms/ klass.

Example:

>>> from django.contrib.auth.models import User
>>> from guardian.shortcuts import get_objects_for_user
>>> joe = User.objects.get(username='joe')
>>> get_objects_for_user(joe, 'auth.change_group')
[]
>>> from guardian.shortcuts import assign_perm
>>> group = Group.objects.create('some group')
>>> assign_perm('auth.change_group', joe, group)
>>> get_objects_for_user(joe, 'auth.change_group')
[<Group some group>]

The permission string can also be an iterable. Continuing with the previous example:

>>> get_objects_for_user(joe, ['auth.change_group', 'auth.delete_group'])
[]
>>> get_objects_for_user(joe, ['auth.change_group', 'auth.delete_group'], any_perm=True)
[<Group some group>]
>>> assign_perm('auth.delete_group', joe, group)
>>> get_objects_for_user(joe, ['auth.change_group', 'auth.delete_group'])
[<Group some group>]

get_objects_for_group

guardian.shortcuts.get_objects_for_group(group, perms, klass=None, any_perm=False)

Returns queryset of objects for which a given group has all permissions present at perms.

Parameters:
  • groupGroup instance for which objects would be returned.
  • perms – single permission string, or sequence of permission strings which should be checked. If klass parameter is not given, those should be full permission names rather than only codenames (i.e. auth.change_user). If more than one permission is present within sequence, their content type must be the same or MixedContentTypeError exception would be raised.
  • klass – may be a Model, Manager or QuerySet object. If not given this parameter would be computed based on given params.
  • any_perm – if True, any of permission in sequence is accepted
Raises:
  • MixedContentTypeError – when computed content type for perms and/or klass clashes.
  • WrongAppError – if cannot compute app label for given perms/ klass.

Example:

Let’s assume we have a Task model belonging to the tasker app with the default add_task, change_task and delete_task permissions provided by Django:

>>> from guardian.shortcuts import get_objects_for_group
>>> from tasker import Task
>>> group = Group.objects.create('some group')
>>> task = Task.objects.create('some task')
>>> get_objects_for_group(group, 'tasker.add_task')
[]
>>> from guardian.shortcuts import assign_perm
>>> assign_perm('tasker.add_task', group, task)
>>> get_objects_for_group(group, 'tasker.add_task')
[<Task some task>]
The permission string can also be an iterable. Continuing with the previous example:
>>> get_objects_for_group(group, ['tasker.add_task', 'tasker.delete_task'])
[]
>>> assign_perm('tasker.delete_task', group, task)
>>> get_objects_for_group(group, ['tasker.add_task', 'tasker.delete_task'])
[<Task some task>]