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
orcodename
). Ifobj
is not given, must be in formatapp_label.codename
. - user_or_group – instance of
User
,AnonymousUser
orGroup
; passing any other object would raiseguardian.exceptions.NotUserNorGroup
exception - obj – persisted Django’s
Model
instance orNone
if assigning global permission. Default isNone
.
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>
- perm – proper permission for given
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
orcodename
). Ifobj
is not given, must be in formatapp_label.codename
. - user_or_group – instance of
User
,AnonymousUser
orGroup
; passing any other object would raiseguardian.exceptions.NotUserNorGroup
exception - obj – persisted Django’s
Model
instance orNone
if assigning global permission. Default isNone
.
- perm – proper permission for given
get_perms¶
-
guardian.shortcuts.
get_perms
(user_or_group, obj)¶ Returns permissions for given user/group and object pair, as list of strings.
get_user_perms¶
-
guardian.shortcuts.
get_user_perms
(user, obj)¶ Returns permissions for given user and object pair, as list of strings, only those assigned directly for the user.
get_group_perms¶
-
guardian.shortcuts.
get_group_perms
(user_or_group, obj)¶ Returns permissions for given user/group and object pair, as list of strings. It returns only those which are inferred through groups.
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 givenobj
.Parameters: - obj – persisted Django’s
Model
instance - attach_perms – Default:
False
. If set toTrue
result would be dictionary ofUser
instances with permissions’ codenames list as values. This would fetch users eagerly! - with_superusers – Default:
False
. If set toTrue
result would contain all superusers. - with_group_users – Default:
True
. If set toFalse
result would not contain those users who have only group permissions for givenobj
.
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']}
- obj – persisted Django’s
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 givenobj
.Parameters: - obj – persisted Django’s
Model
instance - attach_perms – Default:
False
. If set toTrue
result would be dictionary ofGroup
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']}
- obj – persisted Django’s
get_objects_for_user¶
-
guardian.shortcuts.
get_objects_for_user
(user, perms, klass=None, use_groups=True, any_perm=False, with_superuser=True, accept_global_perms=True)¶ Returns queryset of objects for which a given
user
has all permissions present atperms
.If
perms
is an empty list, then it returns objects for which a givenuser
has any object permission.Parameters: - user –
User
orAnonymousUser
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 orMixedContentTypeError
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 isTrue
. - any_perm – if True, any of permission in sequence is accepted. Default is
False
. - with_superuser – if
True
and ifuser.is_superuser
is set, returns the entire queryset. Otherwise will only return objects the user has explicit permissions. This must beTrue
for the accept_global_perms parameter to have any affect. Default isTrue
. - accept_global_perms – if
True
takes global permissions into account. Object based permissions are taken into account if more than one permission is handed in in perms and at least one of these perms is not globally set. If any_perm is set to false then the intersection of matching object is returned. Note, that if with_superuser is False, accept_global_perms will be ignored, which means that only object permissions will be checked! Default isTrue
.
Raises: - MixedContentTypeError – when computed content type for
perms
and/orklass
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>]
Take global permissions into account:
>>> jack = User.objects.get(username='jack') >>> assign_perm('auth.change_group', jack) # this will set a global permission >>> get_objects_for_user(jack, 'auth.change_group') [<Group some group>] >>> group2 = Group.objects.create('other group') >>> assign_perm('auth.delete_group', jack, group2) >>> get_objects_for_user(jack, ['auth.change_group', 'auth.delete_group']) # this retrieves intersection [<Group other group>] >>> get_objects_for_user(jack, ['auth.change_group', 'auth.delete_group'], any_perm) # this retrieves union [<Group some group>, <Group other group>]
If accept_global_perms is set to
True
, then all assigned global permissions will also be taken into account.Scenario 1: a user has view permissions generally defined on the model ‘books’ but no object based permission on a single book instance:
- If accept_global_perms is
True
: List of all books will be returned. - If accept_global_perms is
False
: list will be empty.
- If accept_global_perms is
Scenario 2: a user has view permissions generally defined on the model ‘books’ and also has an object based permission to view book ‘Whatever’:
- If accept_global_perms is
True
: List of all books will be returned. - If accept_global_perms is
False
: list will only contain book ‘Whatever’.
- If accept_global_perms is
Scenario 3: a user only has object based permission on book ‘Whatever’:
- If accept_global_perms is
True
: List will only contain book ‘Whatever’. - If accept_global_perms is
False
: List will only contain book ‘Whatever’.
- If accept_global_perms is
Scenario 4: a user does not have any permission:
- If accept_global_perms is
True
: Empty list. - If accept_global_perms is
False
: Empty list.
- If accept_global_perms is
- user –
get_objects_for_group¶
-
guardian.shortcuts.
get_objects_for_group
(group, perms, klass=None, any_perm=False, accept_global_perms=True)¶ Returns queryset of objects for which a given
group
has all permissions present atperms
.Parameters: - group –
Group
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 orMixedContentTypeError
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
- accept_global_perms – if
True
takes global permissions into account. If any_perm is set to false then the intersection of matching objects based on global and object based permissions is returned. Default isTrue
.
Raises: - MixedContentTypeError – when computed content type for
perms
and/orklass
clashes. - WrongAppError – if cannot compute app label for given
perms
/klass
.
Example:
Let’s assume we have a
Task
model belonging to thetasker
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>]
- Global permissions assigned to the group are also taken into account. Continuing with previous example:
>>> task_other = Task.objects.create('other task') >>> assign_perm('tasker.change_task', group) >>> get_objects_for_group(group, ['tasker.change_task']) [<Task some task>, <Task other task>] >>> get_objects_for_group(group, ['tasker.change_task'], accept_global_perms=False) [<Task some task>]
- group –