Commits

Kai Diefenbach committed 25b0cad

Updated docs

  • Participants
  • Parent commits 3c915fa

Comments (0)

Files changed (4)

File docs/api.rst

 
 .. warning::
 
-    django-permissions is in alpha state. Please consider the API as supposed 
+    django-permissions is in alpha state. Please consider the API as supposed
     to be changed until it reaches beta state.
 
 .. automodule:: permissions.utils
         <span>Has permission</span>
     {% else %}
         <span>Doesn't have permission</span>
-    {% endifhasperm %}    
+    {% endifhasperm %}
 
 Models
 ======
 
+.. autoclass:: permissions.models.PermissionBase
+    :members:
+
 .. autoclass:: permissions.models.Permission
+    :members:
+
 .. autoclass:: permissions.models.ObjectPermission
-.. autoclass:: permissions.models.ObjectPermissionInheritanceBlock
+    :members:
+
+.. autoclass:: permissions.models.ObjectPermissionInheritanceBlock
+    :members:
+
+.. autoclass:: permissions.models.Role
+    :members:
+
+.. autoclass:: permissions.models.PrincipalRoleRelation
+    :members:

File docs/usage/additional_groups.rst

 check permissions against them even if the user has not been assigned to these
 groups explicitly.
 
+Create a new user
+-----------------
+
+.. code-block:: python
+
+    >>> from django.contrib.auth.models import User
+    >>> user = User.objects.create(username="doe")
+
 Create new permissions
 ----------------------
 
 .. code-block:: python
 
-    from permissions.utils import register_permission
-    permission = register_permission("View", "view")
-    permission = register_permission("Edit", "edit")
+    >>> from permissions.utils import register_permission
+    >>> permission = register_permission("View", "view")
+    >>> permission = register_permission("Edit", "edit")
 
 Create new role
 ---------------
 
 .. code-block:: python
 
-    from permissions.utils import register_role
-    anonymous = register_role("Anonymous")
-    owner = register_role("Owner")
+    >>> from permissions.utils import register_role
+    >>> anonymous = register_role("Anonymous")
+    >>> owner = register_role("Owner")
 
 This will create default Django groups.
 
 
 .. code-block:: python
 
-    from django.contrib.flatpages.models import FlatPage
-    content = FlatPage.objects.create(title="Example", url="example")
+    >>> from django.contrib.flatpages.models import FlatPage
+    >>> content = FlatPage.objects.create(title="Example", url="example")
+    >>> content.creator = user
 
 Grant permissions
 -----------------
 
 .. code-block:: python
 
-    from permissions.utils import grant_permission
-    grant_permission(content, anonymous, "view")
-    grant_permission(content, owner, "edit")
+    >>> from permissions.utils import grant_permission
+    >>> grant_permission(content, anonymous, "view")
+    >>> grant_permission(content, owner, "edit")
 
 Now all users which are member of the special group "Anonymous" have the
 permission to view the object "content". And all users which are member of the
 
 .. code-block:: python
 
-    from permissions.utils import has_permission
+    >>> from permissions.utils import has_permission
 
     # Every user is automatically within the Anonymous group.
-    roles = [anonymous]
+    >>> roles = [anonymous]
 
     # The creator of the page is also within the Owner group.
     # Note: FlatPages actually don't have a creator attribute.
-    if request.user == content.creator:
-        roles.append(owner)
+    >>> if user == content.creator:
+    ...    roles.append(owner)
 
     # Passing the additional groups to has_permission
-    result = has_permission(content, request.user, "edit", groups)
+    >>> has_permission(content, user, "edit", roles)
+    True
 
-    if result == False:
-        print "Alert!"
+    >>> has_permission(content, user, "view", roles)
+    True
 
 More information
 ----------------

File docs/usage/simple.rst

     django-permissions is in alpha state. Please consider the API as supposed
     to be changed until it reaches beta state.
 
+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")
+    >>> 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")
+    >>> 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")
+    >>> 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")
+    >>> 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".
 
 .. code-block:: python
 
-    from permissions.utils import has_permission
-    result = has_permission(content, request.user, "view")
-
-    if result == False:
-        print "Alert!"
+    >>> from permissions.utils import has_permission
+    >>> result = has_permission(content, user, "view")
+    True
 
 This will check whether the current user has the permission "View" for the
 FlatPage "content".

File permissions/models.py

         return "%s / %s - %s" % (self.permission, self.content_type, self.content_id)
 
 class Role(models.Model):
-    """A role getting permissions for content objects. A role is the only way
-    to grant permissions to user and groups.
+    """A role gets permissions to do something. Principals (users and groups)
+    can only get permissions via roles.
 
     **Attributes:**
 
         return PrincipalRoleRelation.objects.filter(role=self, content=content)
 
 class PrincipalRoleRelation(models.Model):
-    """A role given to a principal user or group. If a content object is passed
-    this is a local role only for the given content object. Otherwise it is
-    a global role.
+    """A role given to a principal (user or group). If a content object is
+    given this is a local role, i.e. the principal has this role only for this
+    content object. Otherwise it is a global role, i.e. the principal has
+    this role generally.
 
     user
         A user instance. Either a user xor a group needs to be given.
         The role which is given to the principal for content.
 
     content
-        The content object which gets the local role.
+        The content object which gets the local role (optional).
     """
     user = models.ForeignKey(User, verbose_name=_(u"User"), blank=True, null=True)
     group = models.ForeignKey(Group, verbose_name=_(u"Group"), blank=True, null=True)