.. _manual:

######
Manual
######


.. _manual-permission-function:

Permission Function
===================

The *permission function* is a callback associated with a model.

Using the :class:`model_permissions.backends.ObjectModelBackend` the object permissions are
extended with :attr:`django.contrib.auth.models.User.user_permissions` and
:attr:`django.contrib.auth.models.Group.permissions`.

.. tip:: Use the same permissions as in your database and add your custom permissions to
   :attr:`django.db.models.Options.permissions` to handle both nicely.


There are 2 ways to define it:

1. On the model itself:

   .. code-block:: python

      class MyModel(models.Model):

          owner = models.ForeignKey(settings.AUTH_USER_MODEL, models.CASCADE)

          def get_permissions(self, user):
              if user == self.owner:
                  return [
                      'myapp.change_mymodel',
                      'myapp.delete_mymodel',
                  ]

2. Using the ``MODEL_PERMISSIONS`` setting in your `settings.py`:

   It accepts functions and module paths.

   .. code-block:: python

      def get_mymodel_permissions(user, obj):
          if user in obj.moderator_set.all():
              return [
                  'myapp.change_mymodel',
                  'myapp.delete_mymodel',
              ]

      MODEL_PERMISSIONS = {
          AUTH_USER_MODEL: 'accounts.models.get_profile_permissions',
          'myapp.mymodel': get_mymodel_permissions,
      }

.. note:: When you define a permission function for your user model, keep in mind that it will
   receive 2 user objects! The user who is requesting permissions first and the user
   which he/she/it is requesting permissions for as second argument.


.. _manual-related-permissions:

Related Permissions
===================

Related permissions are a good way to handle the ``add_*`` permission.

Basically you just ask another model if the user may add a relation:

.. code-block:: python

   # models.py

   class Thread(models.Model):

       owner = models.ForeignKey(settings.AUTH_USER_MODEL, models.CASCADE)

       def get_permissions(self, user):
           if user == self.owner:
              return [
                  'myforum.change_thread',
                  'myforum.delete_thread',
                  'myforum.add_post',
              ]


   class Post(models.Model):

       owner = models.ForeignKey(settings.AUTH_USER_MODEL, models.CASCADE)


.. code-block:: python

   # views.py

   class PostCreateView(CreateView):
       required_permission = 'myforum.add_post'

       def get_permission_object(self):
           pk = self.kwargs.get("thread_pk", None)
           if pk is None:
               return
           return Thread.objects.get(pk=pk)