README

========================================
Django Object Permissions 
========================================

This is an implementation of Object Permissions, a.k.a. row level permissions.
Object Permissions allow you to assign a permission to an instance of any
Model in your django project.  This app provides a authentication backend
that works with Django >= 1.2.

This specific implementation includes the ability to assign permissions to
Users and UserGroups. Later versions may include the ability to create
PermissionGroups and ObjectPermissionGroups.

Installation
----------------------------------------

There are several ways to install Object Permissions.

Object Permissions ships a standard distutils setup.py. A classic invocation
to install from setup.py might be::

 $ python setup.py install

You may need to add sudo in order to install to the system Python.

::

 $ sudo python setup.py install

We also have Object Permissions on PyPI, so it can be installed using pip.
(easy_install also works, but we do not recommend easy_install. Just use pip.)

::

 $ pip install django-object-permissions

If you are installing Object Permissions directly into a Django app, and want
to distribute Object Permissions with your app, simply copy the
object_permissions folder into your Django project.

Configuring Your Django Project
----------------------------------------

1) Add "object_permissions" to INSTALLED_APPS
2) Add "object_permissions.backend.ObjectPermBackend" to AUTHENTICATION_BACKENDS. 
3) Run ./manage.py syncdb

if South is enabled for your project you will need to create tables using migrate

3b) Run ./manage.py migrate

Using Object Permissions
----------------------------------------

First, register some permissions onto a Model in your models.py. This can only
be done once per model; see registration.py for more information.

>>> from object_permissions import register
>>> register(['permission'], Model)

Now, that permission can be granted, revoked, or checked for any instance of
that Model.

>>> user.grant('permission', object)
>>> user.revoke('permission', object)
>>> user.has_perm('permission', object)
>>> group.grant('permission', object)
>>> group.revoke('permission', object)

Authors
-------

Object Permissions was originally implemented by Peter Krenesky at the Oregon
State University Open Source Lab (OSUOSL). This release is maintained by
Ken Lett.