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

Docs: Removed deprecated doc pages

Browse source
This commit is contained in:
Martin Mahner 2009-07-12 19:58:48 +02:00
parent d909843116
commit b82700f6b4
11 changed files with 0 additions and 412 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

22
docs/permission_admin_handling.txt
View file

@ -1,22 +0,0 @@
.. _permission_admin_handling:
===================================================
Handling permissions using Django's admin interface
===================================================
Using python-code
-----------------
*to be written*
Using Django's admin interface
------------------------------
The more easy way to add per-object permissions is to use Django's admin
interface.
Using templatetags
------------------
*to be written*

5
docs/permission_check_decorator.txt
View file

@ -1,5 +0,0 @@
.. _permission_check_decorator::
=====================================
Check permissions using the decorator
=====================================

5
docs/permission_check_in_templates.txt
View file

@ -1,5 +0,0 @@
.. _permission_check_in_templates::
==============================
Check permissions in templates
==============================

5
docs/permission_check_in_views.txt
View file

@ -1,5 +0,0 @@
.. _permission_check_in_views:
===================================
Check for permissions in your views
===================================

5
docs/permission_check_using_the_decorator.txt
View file

@ -1,5 +0,0 @@
.. _permission_check_using_the_decorator:
=======================================
Check for permissions using a decorator
=======================================

114
docs/permission_create_basic.txt
View file

@ -1,114 +0,0 @@
.. _permission_create_basic:
=========================
Create a basic permission
=========================
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`_.
A basic permission
==================
Let's start with a example::
import authority
from authority import permissions
from django.contrib.flatpages.models import Flatpage
class FlatpagePermission(permissions.BasePermission):
label = 'flatpage_permission'
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::
from authority import permissions
class FlatpagePermission(permissions.BasePermission):
# ...
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
permissions::
authority.register(Flatpage, FlatpagePermission)
The syntax of this is simple::
authority.register(<model>, <permissionclass>)
While this is not much code, you already wrapped Django's basic permissions
(add_flatpage, change_flatpage, delete_flatpage) for the model ``Flatpage``
and you are ready to use it within your templates or code:
.. note:: See `Django's basic permissions`_ how Django creates this permissions for you.
.. _Django's basic permissions: http://docs.djangoproject.com/en/dev/topics/auth/#permissions
Example permission checks
=========================
This section shows you how to check for Django's basic permissions with
django-authorit
In your python code
-------------------
::
def my_view(request):
check = FlatPagePermission(request.user)
if check.change_flatpage():
print "Yay, you can change a flatpage!"
Using the view decorator
------------------------
::
from authority.decorators import permission_required_or_403
@permission_required_or_403('flatpage_permission.change_flatpage')
def my_view(request):
# ...
See :ref:`permission_check_decorator` how the decorator works in detail.
In your templates
-----------------
::
{% ifhasperm "flatpage_permission.change_flatpage" request.user %}
Yay, you can change a flatpage!
{% else %}
Nope, sorry. You aren't allowed to change a flatpage.
{% endifhasperm %}
See :ref:`permission_check_in_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``
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.
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.

120
docs/permission_create_custom.txt
View file

@ -1,120 +0,0 @@
.. _permission_create_custom:
==========================
Create a custom permission
==========================
django-authority allows you to define powerful custom permission. Lets start
again with an example code::
import authority
from authority import permissions
from django.contrib.flatpages.models import Flatpage
class FlatpagePermission(permissions.BasePermission):
label = 'flatpage_permission'
authority.register(Flatpage, FlatpagePermission)
A custom permission is a simple functions within the class::
import authority
from authority import permissions
from django.contrib.flatpages.models import Flatpage
class FlatpagePermission(permissions.BasePermission):
label = 'flatpage_permission'
checks = (my_custom_check',)
def my_custom_check(self, flatpage):
if(flatpage.url == '/about/'):
return True
return False
authority.register(Flatpage, FlatpagePermission)
Note that we first added the name of your custom permission to the ``checks``
attribute, like in :ref:`permission_create_per_object`::
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
permission is True or False::
def my_custom_check(self, flatpage):
if flatpage.url == '/about/':
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.
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
o'clock::
def datetime_check(self):
hour = int(datetime.datetime.now().strftime("%H"))
if hour >= 10 and hour <= 12:
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::
def datetime_flatpage_check(self, flatpage):
hour = int(datetime.datetime.now().strftime("%H"))
if hour >= 10 and hour <= 12 and flatpage.url == '/about/':
return True
return False
Check custom permissions
========================
The permission check is similiar to :ref:`permission_create_basic` and
:ref:`permission_create_per_object`.
.. 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``.
In your python code
-------------------
::
from myapp.permissions import FlatPagePermission
def my_view(request):
check = FlatPagePermission(request.user)
flatpage_object = Flatpage.objects.get(url='/homepage/')
if check.my_custom_check(flatpage=flatpage_object):
print "Yay, you can change *this* flatpage!"
Using the view decorator
------------------------
::
from django.contrib.auth import Flatpage
from authority.decorators import permission_required_or_403
@permission_required_or_403('flatpage_permission.my_custom_check',
(Flatpage, 'url__iexact', 'url')) # The flatpage_object
def my_view(request, url):
# ...
See :ref:`permission_check_decorator` how the decorator works in detail.
In your templates
-----------------
::
{% ifhasperm "flatpage_permission.my_custom_check" request.user flatpage_object %}
Yay, you can change *this* flatpage!
{% else %}
Nope, sorry. You aren't allowed to change *this* flatpage.
{% endifhasperm %}
See :ref:`permission_check_in_templates` how the templatetag works in detail.

9
docs/permission_create_key_lock.txt
View file

@ -1,9 +0,0 @@
.. _permission_create_key_lock:
==============================
Create a *key-lock* permission
==============================
Using the admin
===============

117
docs/permission_create_per_object.txt
View file

@ -1,117 +0,0 @@
.. _permission_create_per_object:
==============================
Create a per-object permission
==============================
django-authority provides a super simple but nifty feature called *per-object
permission*. A description would be::
Attach a <codename> to an object
Attach a <codename> to an user
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:
.. image:: .static/authority-object-1to1.png
*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.*
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 fltapage Events.*
Create per-object permissions
=============================
Creating per-object permissions is super simple. See this piece of permission
class code::
class FlatPagePermission(BasePermission):
label = 'flatpage_permission'
checks = ('review',)
authority.register(FlatPage, FlatPagePermission)
This permission class is similar to the one we already created in
:ref:`permission_create_basic` but we added the line::
checks = ('review',)
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.
Attach per-object permissions to objects
========================================
Please see :ref:`permission_admin_handling` for this.
Check per-object permissions
============================
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>:
return True
else:
return False
The syntax is similiar to the permission-checks we have already
seen in :ref:`permission_create_basic` for the basic permissions but now we
have to give each function an ``obj`` argument containing the model-instance
we want to check!
In your python code
-------------------
::
from myapp.permissions import FlatPagePermission
def my_view(request):
check = FlatPagePermission(request.user)
flatpage_object = Flatpage.objects.get(url='/homepage/')
if check.review_flatpage(obj=flatpage_object):
print "Yay, you can change *this* flatpage!"
Using the view decorator
------------------------
::
from django.contrib.auth import Flatpage
from authority.decorators import permission_required_or_403
@permission_required_or_403('flatpage_permission.review_flatpage',
(Flatpage, 'url__iexact', 'url')) # The flatpage_object
def my_view(request, url):
# ...
See :ref:`permission_check_decorator` how the decorator works in detail.
In your templates
-----------------
::
{% ifhasperm "flatpage_permission.review_flatpage" request.user flatpage_object %}
Yay, you can change *this* flatpage!
{% else %}
Nope, sorry. You aren't allowed to change *this* flatpage.
{% endifhasperm %}
See :ref:`permission_check_in_templates` how the templatetag works in detail.

5
docs/permission_create_your_own.txt
View file

@ -1,5 +0,0 @@
.. _permission_create_your_own:
==========================
Create your own permission
==========================

5
docs/permission_template_handling.txt
View file

@ -1,5 +0,0 @@
.. _permission_template_handling:
====================================
Handling permissions using templates
====================================