# 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`) or `Permission` instance. If `obj` is not given, must be in format `app_label.codename` or `Permission` instance.

    - user_or_group – instance of `User`, `AnonymousUser`, `Group`, list of `User` or `Group`, or queryset of `User` or `Group`; passing any other object would raise `guardian.exceptions.NotUserNorGroup` exception

    - obj – persisted Django’s `Model` instance or QuerySet of Django `Model` instances or list of Django `Model` instances 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 QuerySet of Django `Model` instances 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_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, only_with_perms_in=None)

  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`.

    - only_with_perms_in – Default: `None`. If set to an iterable of permission strings then only users with those permissions would be returned.

  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')
      >>> dan = User.objects.create_user('dan', 'dan@example.com', 'dansecret')
      >>> assign_perm('change_flatpage', joe, page)
      >>> assign_perm('delete_flatpage', dan, page)
      >>>
      >>> get_users_with_perms(page)
      [<User: joe>, <User: dan>]
      >>>
      >>> get_users_with_perms(page, attach_perms=True)
      {<User: joe>: [u'change_flatpage'], <User: dan>: [u'delete_flatpage']}
      >>> get_users_with_perms(page, only_with_perms_in=['change_flatpage'])
      [<User: joe>]

## 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, with_superuser=True, accept_global_perms=True)

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

  Parameters:

    - user – `User` 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. Default is `False`.

    - with_superuser – if `True` and if `user.is_superuser` is set, returns the entire queryset. Otherwise will only return objects the user has explicit permissions. This must be `True` for the accept_global_perms parameter to have any affect. Default is `True`.

    - 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 is `True`.

  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>]

  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.

  - 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’.

  - 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’.

  - 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.

## 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 at `perms`.

  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 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

    - 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 is `True`.

  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>]

  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>]