Commits

schacki committed 324b6e8

updated docs

  • Participants
  • Parent commits d5120e0

Comments (0)

Files changed (5)

File docs/concepts.rst

+========
+Concepts
+========
+
+**The following concepts are critical for the understanding of django-permissions**
+* Users and Groups
+* Roles and local Roles
+* Principal
+* Permissions
+
+Users
+-----
+
+* Users are actors which may need a permission to do something within the system.
+* Users can be member of several groups.
+* User can have several roles, directly or via a membership to a group (these are considered as global).
+* User can have local roles, directly or via a membership to a group. That is roles for a specific object.
+* Users have all roles of their groups - global and local ones.
+* Users have all permissions of their roles - global and local ones.
+
+**Example**: *John* and *Maria* are users. 
+
+
+Groups
+------
+
+* Groups combines users together.
+* Groups can have roles (these are considered as global).
+* Groups can have local roles, that is roles for a specific object.
+* Groups has all permissions of their roles - global and local ones.
+* Users of a Group have the group's roles and permissions.
+
+**Example**: *Business* is a group that speficies the pricing scheme. *Maria* is a member of *Business*. *John* is not a member of any group.
+
+
+Roles and Local Roles
+---------------------
+
+* Roles are used to grant permissions. 
+* Local roles are roles which are defined for specific content objects.
+* A principal (users or groups) are assigned to roles.
+* Mulitple principals can be assigned to one role.
+
+**Example**: Typical roles are *Reader*, *Manager* or *Editor*. Content objects may be the blogs "Django News" and "Python News". For the content object "Django News" is a local role defined as *EditorDjangoNews*. *Maria* is assigned to the role *Editor* and *John* is assigned the role *EditorDjangoNews*.
+
+
+Principal
+---------
+
+* Principal is just an abstract placeholder for either a user or group, or a role.
+* If roles are active (see :doc:`settings`) , principal must be a role; if roles are not active, it must be a user or a group.
+* If a principal is assigned to a role, it cannot be a role itself.
+
+**Example**: A permission can either be assigend to the principal *John* (which is a user); or the principal *Editor* (which is a role).
+
+Permissions
+-----------
+
+* Permissions define the right to perform certain actions. 
+* Permissions can be specific to certain content types or can be general.
+* Object Permissions are granted to principals in order to allow something to users.
+
+**Example**: *Can_Edit* is a permission that is specific to the blog content type. Everybody who has that permission for a specific blog, is allowed to edit this blog. The role *Editor* is granted the object permission to edit the blogs *Django News" and "Python News". The role *EditorDjangoNews* is granted the object permission to the edit the blog "Django News" only.. 
+

File docs/settings.rst

+============
+Settings
+============
+
+The following settings are available to customize django-permissions:
+
+**PERMISSIONS_ROLES_ENABLED**
+
+* Controls, whether the roles concepts is enabled, i.e. whether permissions MUST be assigned to roles only. If False, permissions must be assigned to users or groups only.
+* *default* : True
+
+
+**PERMISSIONS_OBJECTS_PERM_CHECK**
+
+* If this settings is enabled, for each permission that is assigned to a content type, this content type (model calls), will get a check method for that specific permission. E.g. if the permission "edit" is assigned to the model Blog, the model class Blog will get the a method editable, such that you check if a user has the permission "edit" for the blog "Python News": Blog.get(name="Python News").edit(user)
+* *default* : True
+
+
+**PERMISSIONS_OBJECTS_PERM_CHECK_OVERRIDE**
+
+* If django-permissions adds the permission object check method to the model classes, the name might conflict with existing attributes. Unless this setting is set to False, an Exception will be raised. Please do not change the default, unless you are really sure what you are doing.
+* *default* : False
+
+**PERMISSIONS_OBJECTS_PERM_STRING**
+
+* This string is used the define the the method name of the object permission check function.
+* *default* : '%s'
+
+**PERMISSIONS_OBJECTS_GENERIC_CHECK**
+
+* If this settings is enabled, each content type with an assigned permission, will get a generic check method. E.g. if the permission "edit" is assigned to the model Blog, the model class Blog will get the a method "has_permission", such that you check if a user has the permission "edit" for the blog "Python News": Blog.get(name="Python News").has_permission("edit",user)
+* *default* : True
+
+**PERMISSIONS_OBJECTS_GENERIC_STRING**
+
+* This string is used the define the the method name of the object permission generic check function.
+* *default* : 'has_permission'
+
+**PERMISSIONS_RETURN_403**
+
+* If set to True, the decorator will return a 403 response, if the permission is missing.
+* *default* : True
+
+

File docs/usage/simple.rst

-======
-Simple
-======
-
-Create a new user
------------------
-
-.. code-block:: python
-
-    >>> from django.contrib.auth.models import User
-    >>> user = User.objects.create(username="doe")
-
-Create a new permission
------------------------
-
-.. code-block:: python
-
-    >>> from permissions.utils import register_permission
-    >>> permission = register_permission("View", "view")
-
-Create a new role
------------------
-
-.. code-block:: python
-
-    >>> from permissions.utils import register_role
-    >>> editor = register_role("Editor")
-
-Assign user to role
--------------------
-
-.. code-block:: python
-
-    >>> editor.add_principal(user)
-
-Create a content object
------------------------
-
-.. code-block:: python
-
-    >>> from django.contrib.flatpages.models import FlatPage
-    >>> content = FlatPage.objects.create(title="Example", url="example")
-
-Grant permission
-----------------
-
-.. code-block:: python
-
-    >>> from permissions.utils import grant_permission
-    >>> grant_permission(content, editor, "view")
-
-Now all users which are member of the role "Editor" have the permission to
-view object "content".
-
-Check permission
-----------------
-
-.. code-block:: python
-
-    >>> from permissions.utils import has_permission
-    >>> has_permission(content, user, "view")
-    True
-
-This will check whether the current user has the permission "View" for the
-FlatPage "content".
-
-More information
-----------------
-
-.. seealso::
-
-    This is just a simple use case. Look into the :doc:`API documentation <../api>` for more.

File docs/usage/simple_no_roles.rst

+================================================
+Simple Permission Management with Roles disabled
+================================================
+
+Create a new user
+-----------------
+
+.. code-block:: python
+
+    >>> from django.contrib.auth.models import User
+    >>> user = User.objects.create(username="doe")
+
+Create a new permission
+-----------------------
+
+.. code-block:: python
+
+    >>> from permissions.utils import register_permission
+    >>> permission = register_permission("View", "view")
+
+
+Create a content object
+-----------------------
+
+.. code-block:: python
+
+    >>> from django.contrib.flatpages.models import FlatPage
+    >>> content = FlatPage.objects.create(title="Example", url="example")
+
+Grant permission
+----------------
+
+.. code-block:: python
+
+    >>> from permissions.utils import grant_permission
+    >>> grant_permission(content, user, "view")
+
+Now the user "doe" has the permission to view object "content".
+
+
+Check permission
+----------------
+
+.. code-block:: python
+
+    >>> from permissions.utils import has_permission
+    >>> has_permission(content, user, "view")
+    True
+
+This will check whether the current user has the permission "View" for the
+FlatPage "content".
+
+More information
+----------------
+
+.. seealso::
+
+    This is just a simple use case. Look into the :doc:`API documentation <../api>` for more.

File docs/usage/simple_roles.rst

+=======================================
+Simple Permission Management with Roles
+=======================================
+
+Create a new user
+-----------------
+
+.. code-block:: python
+
+    >>> from django.contrib.auth.models import User
+    >>> user = User.objects.create(username="doe")
+
+Create a new permission
+-----------------------
+
+.. code-block:: python
+
+    >>> from permissions.utils import register_permission
+    >>> permission = register_permission("View", "view")
+
+Create a new role
+-----------------
+
+.. code-block:: python
+
+    >>> from permissions.utils import register_role
+    >>> editor = register_role("Editor")
+
+Assign user to role
+-------------------
+
+.. code-block:: python
+
+    >>> editor.add_principal(user)
+
+Create a content object
+-----------------------
+
+.. code-block:: python
+
+    >>> from django.contrib.flatpages.models import FlatPage
+    >>> content = FlatPage.objects.create(title="Example", url="example")
+
+Grant permission
+----------------
+
+.. code-block:: python
+
+    >>> from permissions.utils import grant_permission
+    >>> grant_permission(content, editor, "view")
+
+Now all users which are member of the role "Editor" have the permission to
+view object "content".
+
+Check permission
+----------------
+
+.. code-block:: python
+
+    >>> from permissions.utils import has_permission
+    >>> has_permission(content, user, "view")
+    True
+
+This will check whether the current user has the permission "View" for the
+FlatPage "content".
+
+More information
+----------------
+
+.. seealso::
+
+    This is just a simple use case. Look into the :doc:`API documentation <../api>` for more.