Shortcuts — django-guardian v1.0.0.beta1 documentation

### Navigation

- index
- modules |
- next |
- previous |
- django-guardian v1.0.0.beta1 documentation »
- API Reference »

# Shortcuts

Convenient shortcuts to manage or check object permissions.

## assign

`guardian.shortcuts.` `assign`(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 django.contrib.auth.models import User, Group
      >>> from guardian.shortcuts import assign
      >>> site = Site.objects.get_current()
      >>> user = User.objects.create(username='joe')
      >>> assign("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("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("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)

  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!

  Example:

      >>> from django.contrib.auth.models import User
      >>> from django.contrib.flatpages.models import FlatPage
      >>> from guardian.shortcuts import assign, 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('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.auth.models import Group
      >>> from django.contrib.flatpages.models import FlatPage
      >>> from guardian.shortcuts import assign, get_groups_with_perms
      >>>
      >>> page = FlatPage.objects.create(title='Some page', path='/some/page/')
      >>> admins = Group.objects.create(name='Admins')
      >>> assign('change_flatpage', group, page)
      >>>
      >>> get_groups_with_perms(page)
      [<Group: admins>]
      >>>
      >>> get_groups_with_perms(page, attach_perms=True)
      {<Group: admins>: [u'change_flatpage']}

### Navigation

- index
- modules |
- next |
- previous |
- django-guardian v1.0.0.beta1 documentation »
- API Reference »