diff --git a/docs/check_decorator.txt b/docs/check_decorator.txt index e1db38d..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,7 +97,7 @@ 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 @@ -103,6 +105,7 @@ described upper: 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. -.. index:: - single: permission_required - single: permission_required_or_403 \ No newline at end of file +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 2e46e78..f84566c 100644 --- a/docs/check_templates.txt +++ b/docs/check_templates.txt @@ -4,6 +4,11 @@ Check permissions in templates ============================== +.. index:: + single: ifhasperm + single: get_permissions + single: get_permission + django-authority provides a couple of template tags which allows you to get permissions for a user (and a related object). @@ -67,8 +72,3 @@ Example:: {% else %} Meh. No power for meeeee. {% endif %} - -.. index:: - single: ifhasperm - single: get_permissions - single: get_permission \ No newline at end of file diff --git a/docs/configuration.txt b/docs/configuration.txt index abe8de6..caf70f7 100644 --- a/docs/configuration.txt +++ b/docs/configuration.txt @@ -4,10 +4,15 @@ Configuration ============= +.. index:: + single: urls.py + single: settings.py + single: autodiscover + 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 @@ -44,8 +49,3 @@ classes you defined:: That's all (for now). - -.. index:: - single: urls.py - single: settings.py - single: autodiscover \ No newline at end of file diff --git a/docs/create_basic_permission.txt b/docs/create_basic_permission.txt index f3e83ec..47a2a36 100644 --- a/docs/create_basic_permission.txt +++ b/docs/create_basic_permission.txt @@ -4,17 +4,22 @@ Create a basic permission ========================= +.. index:: + single: autodiscover + single: permissions.py + single: BasePermission + 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 @@ -25,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`` @@ -59,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 ------------------- @@ -97,23 +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. - -.. index:: - single: autodiscover - single: permissions.py - single: BasePermission \ No newline at end of file diff --git a/docs/create_custom_permission.txt b/docs/create_custom_permission.txt index 6a0e530..7bed43f 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,26 +61,25 @@ 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 Check custom permissions ======================== -The permission check is similar to :ref:`create-basic-permission` and +The permission check is similiar to :ref:`create-basic-permission` 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..a632664 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 ============= @@ -79,4 +80,4 @@ Other pages tips_tricks support - documentation_guidelines \ No newline at end of file + documentation_guidelines 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 6c1651f..f183d3d 100644 --- a/docs/support.txt +++ b/docs/support.txt @@ -4,10 +4,14 @@ Support ======= +.. index:: + single: 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. -.. index:: - single: Support \ No newline at end of file +.. _google group: http://groups.google.com/group/django-authority +.. _issue tracker: http://bitbucket.org/jezdez/django-authority/issues/