README.rst
1===============
2django-guardian
3===============
4
5.. image:: https://travis-ci.org/django-guardian/django-guardian.svg?branch=devel
6 :target: https://travis-ci.org/django-guardian/django-guardian
7
8``django-guardian`` is an implementation of per object permissions [1]_ on top
9of Django's authorization backend
10
11Documentation
12-------------
13
14Online documentation is available at https://django-guardian.readthedocs.io/.
15
16Requirements
17------------
18
19* Python 2.7 or 3.4+
20* A supported version of Django (currently 1.8+)
21
22Travis CI tests on Django version 1.8, 1.10, and 1.11.
23
24Installation
25------------
26
27To install ``django-guardian`` simply run::
28
29 pip install django-guardian
30
31Configuration
32-------------
33
34We need to hook ``django-guardian`` into our project.
35
361. Put ``guardian`` into your ``INSTALLED_APPS`` at settings module:
37
38.. code:: python
39
40 INSTALLED_APPS = (
41 ...
42 'guardian',
43 )
44
452. Add extra authorization backend to your ``settings.py``:
46
47.. code:: python
48
49 AUTHENTICATION_BACKENDS = (
50 'django.contrib.auth.backends.ModelBackend', # default
51 'guardian.backends.ObjectPermissionBackend',
52 )
53
543. Create ``guardian`` database tables by running::
55
56 python manage.py migrate
57
58Usage
59-----
60
61After installation and project hooks we can finally use object permissions
62with Django_.
63
64Lets start really quickly:
65
66.. code:: python
67
68 >>> from django.contrib.auth.models import User, Group
69 >>> jack = User.objects.create_user('jack', 'jack@example.com', 'topsecretagentjack')
70 >>> admins = Group.objects.create(name='admins')
71 >>> jack.has_perm('change_group', admins)
72 False
73 >>> from guardian.models import UserObjectPermission
74 >>> UserObjectPermission.objects.assign_perm('change_group', jack, obj=admins)
75 <UserObjectPermission: admins | jack | change_group>
76 >>> jack.has_perm('change_group', admins)
77 True
78
79Of course our agent jack here would not be able to *change_group* globally:
80
81.. code:: python
82
83 >>> jack.has_perm('change_group')
84 False
85
86Admin integration
87-----------------
88
89Replace ``admin.ModelAdmin`` with ``GuardedModelAdmin`` for those models
90which should have object permissions support within admin panel.
91
92For example:
93
94.. code:: python
95
96 from django.contrib import admin
97 from myapp.models import Author
98 from guardian.admin import GuardedModelAdmin
99
100 # Old way:
101 #class AuthorAdmin(admin.ModelAdmin):
102 # pass
103
104 # With object permissions support
105 class AuthorAdmin(GuardedModelAdmin):
106 pass
107
108 admin.site.register(Author, AuthorAdmin)
109
110
111.. [1] Great paper about this feature is available at `djangoadvent articles <https://github.com/djangoadvent/djangoadvent-articles/blob/master/1.2/06_object-permissions.rst>`_.
112
113.. _Django: http://www.djangoproject.com/
114
115