Hopiu/django-authority
1
0
Fork 0
mirror of https://github.com/jazzband/django-authority.git synced 2026-05-05 14:14:44 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Minor revision to the documentation

Browse source
This commit is contained in:
Jannis Leidel 2009-07-12 21:31:00 +02:00
parent b82700f6b4
commit 2a2675087b
10 changed files with 78 additions and 69 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

17
docs/check_decorator.txt
View file

@ -23,13 +23,15 @@ Lets start with an example permission::
A decorator for such a simple view would look like::
from authority.decorators import permission_required
@permission_required('flatpage_permission.can_do_foo')
def my_view(request):
# ...
The decorator automatically takes the user object from the view's request and
calls ``can_do_foo``. If this function returns ``True``, the view gets passed
otherwise the user will be redirected to the login page.
The decorator automatically takes the user object from the view's arguments
and calls ``can_do_foo``. If this function returns ``True``, the view gets
called, otherwise the user will be redirected to the login page.
Passing arguments to the permission
-----------------------------------
@ -95,10 +97,15 @@ Contributed decorators
======================
django-authority contributes two decorators, the syntax of both is the same as
described upper:
described above:
* permission_required
* permission_required_or_403
In a nutshell, ``permission_required_or_403`` does the same as ``permission_required``
except it returns a Http403 Response instead of redirecting to the login page.
except it returns a Http403 Response instead of redirecting to the login page.
Just like Django's ``500.html`` and ``404.html`` you are able to override the
template used in the permission denied page. Simply create a ``403.html``
template in your template directory. It will get the path of the denied page
passed as the context variable ``request_path``.

2
docs/check_templates.txt
View file

@ -71,4 +71,4 @@ Example::
I've got ze power to change ze pollllllzzz. Muahahaa.
{% else %}
Meh. No power for meeeee.
{% endif %}
{% endif %}

2
docs/configuration.txt
View file

@ -12,7 +12,7 @@ Configuration
settings.py
===========
To enable django-authority just need to add the package to your
To enable django-authority you just need to add the package to your
``INSTALLED_APPS`` setting within your ``settings.py``::
# settings.py

37
docs/create_basic_permission.txt
View file

@ -13,13 +13,13 @@ Where to store permissions?
===========================
First of all: All following permission classes should be placed in a file
called ``permissions.py`` in your application or project-directory. For the
*why* please have a look on `How permissions are discovered`_.
called ``permissions.py`` in your application. For the *why* please have a
look on `How permissions are discovered`_.
A basic permission
==================
Basic permissions
=================
Let's start with a example::
Let's start with an example::
import authority
from authority import permissions
@ -30,26 +30,26 @@ Let's start with a example::
authority.register(Flatpage, FlatpagePermission)
Let's make the code clear. First of, if you want to create a new permission
you have to subclass it from the BasePermission class::
Let's have a look at the code above. First of, if you want to create a new
permission you have to subclass it from the BasePermission class::
from authority import permissions
class FlatpagePermission(permissions.BasePermission):
# ...
Next you need to name this permission using the ``label`` attribute::
Next, you need to name this permission using the ``label`` attribute::
class FlatpagePermission(permissions.BasePermission):
label = 'flatpage_permission'
And finally you need to register the permission to the pool of all other
And finally you need to register the permission with the pool of all other
permissions::
authority.register(Flatpage, FlatpagePermission)
The syntax of this is simple::
authority.register(<model>, <permissionclass>)
authority.register(<model>, <permission_class>)
While this is not much code, you already wrapped Django's basic permissions
(add_flatpage, change_flatpage, delete_flatpage) for the model ``Flatpage``
@ -64,7 +64,7 @@ Example permission checks
=========================
This section shows you how to check for Django's basic permissions with
django-authorit
django-authority.
In your python code
-------------------
@ -102,18 +102,17 @@ See :ref:`check-templates` how the templatetag works in detail.
How permissions are discovered
==============================
On first runtime of your project ``authority.autodiscover()`` will load all
``permission.py`` files that are in your ``settings.INSTALLED_APPS``
On first runtime of your Django project ``authority.autodiscover()`` will
load all ``permissions.py`` files that are in your ``settings.INSTALLED_APPS``
applications. See :ref:`configuration` how to set up ``autodiscover``.
.. image:: .static/authority-permission-py.png
:align: left
We encourage you to place your permission-classes in a file called
``permission.py`` inside your project or application directory. Not only that
this behaviour will keep your application structure clean, if you use
``authority.autodiscover()`` it's guaranteed that every permission-class is
loaded at runtime.
We encourage you to place your permission classes in a file called
``permissions.py`` inside your application directories. This will not only
keep your application files clean, but it will also load every permission
class at runtime when used with ``authority.autodiscover()``.
If you really want, you can place these permission-classes in other files
that are loaded at runtime. ``__init__.py`` or ``models.py`` are such files.
that are loaded at runtime. ``__init__.py`` or ``models.py`` are such files.

31
docs/create_custom_permission.txt
View file

@ -4,7 +4,7 @@
Create a custom permission
==========================
django-authority allows you to define powerful custom permission. Lets start
django-authority allows you to define powerful custom permission. Let's start
again with an example code::
import authority
@ -16,7 +16,7 @@ again with an example code::
authority.register(Flatpage, FlatpagePermission)
A custom permission is a simple functions within the class::
A custom permission is a simple method of the permission class::
import authority
from authority import permissions
@ -39,7 +39,7 @@ attribute, like in :ref:`create-per-object-permission`::
checks = (my_custom_check',)
The permission itself is a simple function that accepts an arbitrary number of
arguments. A permission class should always return a boolean wether the
arguments. A permission class should always return a boolean whether the
permission is True or False::
def my_custom_check(self, flatpage):
@ -47,9 +47,9 @@ permission is True or False::
return True
return False
.. warning:: Unless it's possible to return other values than ``True``, for
example an object which is also True in a boolean way, we highly advise
to return only booleans.
.. warning:: Although it's possible to return other values than ``True``, for
example an object which also evluates to True, we highly advise to only
return booleans.
Custom permissions are not necessary related to a model, you can define more
simpler permissions too. For example, return True if it's between 10 and 12
@ -61,13 +61,13 @@ o'clock::
return True
return False
But mostly you want to combine such permissions checks. The next example would
allow an user to have permission to edit a flatpage only between 10 and 12
o'clock::
But most often you want to combine such permissions checks. The next example
would allow an user to have permission to edit a flatpage only between
8 and 12 o'clock in the morning::
def datetime_flatpage_check(self, flatpage):
def morning_flatpage_check(self, flatpage):
hour = int(datetime.datetime.now().strftime("%H"))
if hour >= 10 and hour <= 12 and flatpage.url == '/about/':
if hour >= 8 and hour <= 12 and flatpage.url == '/about/':
return True
return False
@ -77,10 +77,9 @@ Check custom permissions
The permission check is similiar to :ref:`create-basic-permisson` and
:ref:`create-per-object-permission`.
.. warning:: Until *per-object* permissions gets under the hood translated to
``<permname>_<modelname>`` this is not the case in custom permissions! A
permission ``my_custom_check`` remains ``my_custom_check``.
.. warning:: Although *per-object* permissions are translated to
``<permname>_<modelname>`` this is not the case for custom permissions!
A custom permission ``my_custom_check`` remains ``my_custom_check``.
In your python code
-------------------
@ -117,4 +116,4 @@ In your templates
Nope, sorry. You aren't allowed to change *this* flatpage.
{% endifhasperm %}
See :ref:`check-templates` how the templatetag works in detail.
See :ref:`check-templates` how the templatetag works in detail.

29
docs/create_per_object_permission.txt
View file

@ -13,26 +13,26 @@ permission*. A description would be::
If the user has <codename> and the object has <codename> then do-something,
otherwise do-something-else.
This might sound strange but let's have a deeper look on this. In terms of
users and flatpages a visual example would be:
This might sound strange but let's have a closer look on this pattern.
In terms of users and flatpages a visual example would be:
.. image:: .static/authority-object-1to1.png
*The user is allowed to review the flatpage Events.*
*The user is allowed to review the flatpage "Events".*
You are not limited to a 1:1 relation, you can add this ``codename`` to
multiple objects:
.. image:: .static/authority-object-1toN.png
*The user is allowed to review the flatpages Events and Contact.*
*The user is allowed to review the flatpages "Events" and "Contact".*
And you can do this with any objects in any direction:
.. image:: .static/authority-object-NtoN.png
*The user is allowed to review the flatpages Events and Contact. Another user
is allowed to publish the flatpage Events.*
*The user is allowed to review the flatpages "Events" and "Contact". Another
user is allowed to publish the flatpage "Events".*
Create per-object permissions
=============================
@ -55,8 +55,8 @@ This tells the permission class that it has a permission check (or ``codename``)
``review``. Under the hood this check gets translated to ``review_flatpage``
(``review_<modelname>``).
.. important:: Be sure that you have understand that we have not written any line
of code yet. We just added the ``codename`` to the checks attribute.
.. important:: Be sure that you have understand that we have not written any
line of code yet. We just added the ``codename`` to the checks attribute.
Attach per-object permissions to objects
========================================
@ -66,7 +66,7 @@ Please see :ref:`handling-admin` for this.
Check per-object permissions
============================
As we noted above, we have not written any permission-comparing code yet. This
As we noted above, we have not written any permission comparing code yet. This
is your work. In theory the permission lookup for per-object permissions is::
if <theuser> has <codename> and <object> has <codename>:
@ -76,10 +76,9 @@ is your work. In theory the permission lookup for per-object permissions is::
.. important::
The syntax is similiar to the permission-checks we have already
seen in :ref:`create-basic-permission` for the basic permissions but now we
have to give each function an ``obj`` argument containing the model-instance
we want to check!
The syntax is similiar to the permission checks we've already
seen in :ref:`create-basic-permission` for the basic permissions but now
we have to pass each function a model instance we want to check!
In your python code
-------------------
@ -89,7 +88,7 @@ In your python code
def my_view(request):
check = FlatPagePermission(request.user)
flatpage_object = Flatpage.objects.get(url='/homepage/')
if check.review_flatpage(obj=flatpage_object):
if check.review_flatpage(flatpage_object):
print "Yay, you can change *this* flatpage!"
Using the view decorator
@ -116,4 +115,4 @@ In your templates
Nope, sorry. You aren't allowed to change *this* flatpage.
{% endifhasperm %}
See :ref:`check-templates` how the template tag works in detail.
See :ref:`check-templates` how the template tag works in detail.

17
docs/index.txt
View file

@ -9,23 +9,24 @@ django-authority is a powerful layer between Django's basic permission system
.. image:: .static/authority-scheme-layer.png
Summarized this application provides three abilities:
This application provides three abilities:
1. It gives you the ability to add permissions like Django's generic permissions
to any kind of model without storing them in the model's META attribute.
1. It gives you the ability to add permissions like Django's generic
permissions to any kind of model without having to add them to the model's
Meta class.
2. It provides a very simple way to create per-object-permissions. You might
be more familiar with the term *row level permissions*.
3. It wraps Django's generic permissions so you can use the same syntax as
for the above ones. But note that django-authority does not add any
voodoo-code to Django's ``contrib.auth`` system so your existing permission
system keeps intact!
for the options above. But note that django-authority does not add any
voodoo-code to Django's ``contrib.auth`` system, it keeps your existing
permission system intact!
.. warning:: We have just started with the documentation and it's far from
being perfect. If you find glitches, errors or just have feedback, please
contact the team: :ref:`support`.
Documentation
=============

4
docs/installation.txt
View file

@ -5,7 +5,7 @@ Installation
============
The installation of django-authority is easy. Whether you want to use the
latest stable or development version, you have different options.
latest stable or development version, you have the following options.
The latest stable version
=========================
@ -40,4 +40,4 @@ Then install it manually::
bugs, so we prefer to use the latest package from pypi.
.. _Bitbucket account: http://bitbucket.org/jezdez/django-authority/
.. _Mercurial: http://www.selenic.com/mercurial/
.. _Mercurial: http://www.selenic.com/mercurial/

6
docs/support.txt
View file

@ -10,4 +10,8 @@ Support
We've created a `google group`_ for django-authority. If you have questions or
suggestions, please drop us a note.
.. _google group: http://groups.google.com/group/django-authority
For more specific issues and bug reports please use the `issue tracker`_ on
django-authority's Bitbucket page.
.. _google group: http://groups.google.com/group/django-authority
.. _issue tracker: http://bitbucket.org/jezdez/django-authority/issues/

2
docs/tips_tricks.txt
View file

@ -18,4 +18,4 @@ Within a permission class, you can refer to the user and group using self::
You can unregister permission classes and re-register them::
authority.unregister(Campaign)
authority.register(Campaign, CampaignPermission)
authority.register(Campaign, CampaignPermission)