django-authority/README

================
django-authority
================

This is a Django app for per-object-permissions that includes a bunch of
helpers to create custom permission checks.

The main website for django-authority is
`packages.python.org/django-authority`_. You can also install the
`in-development version`_ of django-authority with
``pip install django-authority==dev`` or ``easy_install django-authority==dev``.

.. _packages.python.org/django-authority: http://packages.python.org/django-authority/
.. _in-development version: http://bitbucket.org/jezdez/django-authority/get/tip.gz#egg=django-authority-dev

Example
=======

To get the example project running do:

- Bootstrap the buildout by running::

    python bootstrap.py

- Get the required packages by running::

    bin/buildout

- Sync the database::

    bin/django-trunk syncdb

- Run the development server and visit the admin at http://127.0.0.1:8000/admin/::

    bin/django-trunk runserver

Now create a flatage and open it to see some of the templatetags in action.
Don't hesitate to use the admin to edit the permission objects.

Full docs coming soon.

Please use http://bitbucket.org/jezdez/django-authority/issues/ for issues and bug reports.

Documentation
=============

The documenation is currently in development. You can create a nice looking
html version using the setup.py::

    python setup.py build_sphinx

Changelog:
==========

0.5dev (2012-09-24):
-----------------

* It is now possible to minimize the number of queries when using
  django-authority by caching the results of the Permission query. This can be
  done by adding ``AUTHORITY_USE_SMART_CACHE = True`` to your settings.py


0.4 (2010-01-15):
-----------------

* Fixed an issue with the UserPermissionForm not being able to override the
  widget of the user field.

* Added ability to override form class in ``add_permission`` view.

* Added easy way to assign permissions via a permission instance, e.g.::

    from django.contrib.auth.models import User
    from mysite.articles.permissions import ArticlePermission

    bob = User.objects.get(username='bob')
    article_permission = ArticlePermission(bob)
    article_permission.assign(content_object=article)


0.3 (2009-07-28):
-----------------

* This version adds multiple fields to the Permission model and is
  therefore a **backwards incompatible** update.

  This was required to add a feature that allows users to request,
  withdraw, deny and approve permissions. Request and approval date
  are now saved, as well as an ``approved`` property. An admin action has
  been added for bulk approval.

  To migrate your existing data you can use the SQL files included in
  the source (`migrations/`_), currently available for MySQL, Postgres
  and SQLite.

* The templatetags have also been refactored to be easier to customize
  which required a change in the template tag signature:

  Old::

    {% permission_form flatpage %}
    {% permission_form flatpage "flatpage_permission.top_secret" %}
    {% permission_form OBJ PERMISSION_LABEL.CHECK_NAME %}

  New::

    {% permission_form for flatpage %}
    {% permission_form for flatpage using "flatpage_permission.top_secret" %}
    {% permission_form for OBJ using PERMISSION_LABEL.CHECK_NAME [with TEMPLATE] %}

  New templatetags:

  * ``permission_request_form``
  * ``get_permission_request``
  * ``get_permission_requests``
  * ``permission_request_approve_link``
  * ``permission_request_delete_link``
  * ``request_url_for_obj``

* The ``add_permission`` view is now accessible with GET requests and
  allows to request permissions, but also add them (only for users with
  the 'authority.add_permission' Django permission).

.. _`migrations/`: http://bitbucket.org/jezdez/django-authority/src/tip/migrations/