From 2a2675087b9fa5af00e845af74c21760aebd8a9b Mon Sep 17 00:00:00 2001 From: Jannis Leidel Date: Sun, 12 Jul 2009 21:31:00 +0200 Subject: [PATCH 1/2] Minor revision to the documentation --- docs/check_decorator.txt | 17 ++++++++---- docs/check_templates.txt | 2 +- docs/configuration.txt | 2 +- docs/create_basic_permission.txt | 37 +++++++++++++-------------- docs/create_custom_permission.txt | 31 +++++++++++----------- docs/create_per_object_permission.txt | 29 ++++++++++----------- docs/index.txt | 17 ++++++------ docs/installation.txt | 4 +-- docs/support.txt | 6 ++++- docs/tips_tricks.txt | 2 +- 10 files changed, 78 insertions(+), 69 deletions(-) diff --git a/docs/check_decorator.txt b/docs/check_decorator.txt index dfe8d86..a52f9c3 100644 --- a/docs/check_decorator.txt +++ b/docs/check_decorator.txt @@ -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. \ No newline at end of file +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``. diff --git a/docs/check_templates.txt b/docs/check_templates.txt index 5f13a1c..c60c021 100644 --- a/docs/check_templates.txt +++ b/docs/check_templates.txt @@ -71,4 +71,4 @@ Example:: I've got ze power to change ze pollllllzzz. Muahahaa. {% else %} Meh. No power for meeeee. - {% endif %} \ No newline at end of file + {% endif %} diff --git a/docs/configuration.txt b/docs/configuration.txt index 8a6fafd..1e6f48c 100644 --- a/docs/configuration.txt +++ b/docs/configuration.txt @@ -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 diff --git a/docs/create_basic_permission.txt b/docs/create_basic_permission.txt index 9e05b39..62452e2 100644 --- a/docs/create_basic_permission.txt +++ b/docs/create_basic_permission.txt @@ -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(, ) + authority.register(, ) 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. \ No newline at end of file +that are loaded at runtime. ``__init__.py`` or ``models.py`` are such files. diff --git a/docs/create_custom_permission.txt b/docs/create_custom_permission.txt index 8916c14..91e4401 100644 --- a/docs/create_custom_permission.txt +++ b/docs/create_custom_permission.txt @@ -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 - ``_`` 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 + ``_`` 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. \ No newline at end of file +See :ref:`check-templates` how the templatetag works in detail. diff --git a/docs/create_per_object_permission.txt b/docs/create_per_object_permission.txt index 2474b14..bdec807 100644 --- a/docs/create_per_object_permission.txt +++ b/docs/create_per_object_permission.txt @@ -13,26 +13,26 @@ permission*. A description would be:: If the user has and the object has 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_``). -.. 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 has and has : @@ -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. \ No newline at end of file +See :ref:`check-templates` how the template tag works in detail. diff --git a/docs/index.txt b/docs/index.txt index 2ed31f6..9774c70 100644 --- a/docs/index.txt +++ b/docs/index.txt @@ -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 ============= diff --git a/docs/installation.txt b/docs/installation.txt index ec50c79..9ccbafb 100644 --- a/docs/installation.txt +++ b/docs/installation.txt @@ -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/ \ No newline at end of file +.. _Mercurial: http://www.selenic.com/mercurial/ diff --git a/docs/support.txt b/docs/support.txt index 954da3e..76c4dc2 100644 --- a/docs/support.txt +++ b/docs/support.txt @@ -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 \ No newline at end of file +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/ diff --git a/docs/tips_tricks.txt b/docs/tips_tricks.txt index 0259f2a..c102fc5 100644 --- a/docs/tips_tricks.txt +++ b/docs/tips_tricks.txt @@ -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) \ No newline at end of file + authority.register(Campaign, CampaignPermission) From 456afd3153d14ef0362c8f52afefe1357521fb87 Mon Sep 17 00:00:00 2001 From: Jannis Leidel Date: Sun, 12 Jul 2009 22:04:26 +0200 Subject: [PATCH 2/2] Minor updates to docs --- docs/check_templates.txt | 8 ++++---- docs/configuration.txt | 8 ++++---- docs/create_basic_permission.txt | 8 ++++---- docs/create_custom_permission.txt | 2 +- docs/index.txt | 2 +- docs/support.txt | 6 +++--- 6 files changed, 17 insertions(+), 17 deletions(-) diff --git a/docs/check_templates.txt b/docs/check_templates.txt index c60c021..f84566c 100644 --- a/docs/check_templates.txt +++ b/docs/check_templates.txt @@ -1,14 +1,14 @@ .. _check-templates: +============================== +Check permissions in templates +============================== + .. index:: single: ifhasperm single: get_permissions single: get_permission -============================== -Check permissions in templates -============================== - django-authority provides a couple of template tags which allows you to get permissions for a user (and a related object). diff --git a/docs/configuration.txt b/docs/configuration.txt index 1e6f48c..053f833 100644 --- a/docs/configuration.txt +++ b/docs/configuration.txt @@ -1,13 +1,13 @@ .. _configuration: +============= +Configuration +============= + .. index:: single: urls.py single: settings.py single: autodiscover - -============= -Configuration -============= settings.py =========== diff --git a/docs/create_basic_permission.txt b/docs/create_basic_permission.txt index 62452e2..47a2a36 100644 --- a/docs/create_basic_permission.txt +++ b/docs/create_basic_permission.txt @@ -1,14 +1,14 @@ .. _create-basic-permission: +========================= +Create a basic permission +========================= + .. index:: single: autodiscover single: permissions.py single: BasePermission -========================= -Create a basic permission -========================= - Where to store permissions? =========================== diff --git a/docs/create_custom_permission.txt b/docs/create_custom_permission.txt index 91e4401..7bed43f 100644 --- a/docs/create_custom_permission.txt +++ b/docs/create_custom_permission.txt @@ -74,7 +74,7 @@ would allow an user to have permission to edit a flatpage only between Check custom permissions ======================== -The permission check is similiar to :ref:`create-basic-permisson` and +The permission check is similiar to :ref:`create-basic-permission` and :ref:`create-per-object-permission`. .. warning:: Although *per-object* permissions are translated to diff --git a/docs/index.txt b/docs/index.txt index 9774c70..a632664 100644 --- a/docs/index.txt +++ b/docs/index.txt @@ -80,4 +80,4 @@ Other pages tips_tricks support - documentation_guidelines \ No newline at end of file + documentation_guidelines diff --git a/docs/support.txt b/docs/support.txt index 76c4dc2..f183d3d 100644 --- a/docs/support.txt +++ b/docs/support.txt @@ -1,12 +1,12 @@ .. _support: -.. index:: - single: Support - ======= Support ======= +.. index:: + single: Support + We've created a `google group`_ for django-authority. If you have questions or suggestions, please drop us a note.