===============
django-guardian
===============
.. image:: https://github.com/django-guardian/django-guardian/workflows/Tests/badge.svg?branch=devel
:target: https://github.com/django-guardian/django-guardian/actions/workflows/tests.yml
.. image:: https://img.shields.io/pypi/v/django-guardian.svg
:target: https://pypi.python.org/pypi/django-guardian
.. image:: https://img.shields.io/pypi/pyversions/django-guardian.svg
:target: https://pypi.python.org/pypi/django-guardian
``django-guardian`` is an implementation of per object permissions [1]_ on top
of Django's authorization backend
Documentation
-------------
Online documentation is available at https://django-guardian.readthedocs.io/.
Requirements
------------
* Python 3.5+
* A supported version of Django (currently 2.2+)
GitHub Actions run tests against Django versions 2.2, 3.0, 3.1, 3.2, and main.
Installation
------------
To install ``django-guardian`` simply run::
pip install django-guardian
Configuration
-------------
We need to hook ``django-guardian`` into our project.
1. Put ``guardian`` into your ``INSTALLED_APPS`` at settings module:
.. code:: python
INSTALLED_APPS = (
...
'guardian',
)
2. Add extra authorization backend to your ``settings.py``:
.. code:: python
AUTHENTICATION_BACKENDS = (
'django.contrib.auth.backends.ModelBackend', # default
'guardian.backends.ObjectPermissionBackend',
)
3. Create ``guardian`` database tables by running::
python manage.py migrate
Usage
-----
After installation and project hooks we can finally use object permissions
with Django_.
Lets start really quickly:
.. code:: python
>>> from django.contrib.auth.models import User, Group
>>> jack = User.objects.create_user('jack', 'jack@example.com', 'topsecretagentjack')
>>> admins = Group.objects.create(name='admins')
>>> jack.has_perm('change_group', admins)
False
>>> from guardian.models import UserObjectPermission
>>> UserObjectPermission.objects.assign_perm('change_group', jack, obj=admins)
<UserObjectPermission: admins | jack | change_group>
>>> jack.has_perm('change_group', admins)
True
Of course our agent jack here would not be able to *change_group* globally:
.. code:: python
>>> jack.has_perm('change_group')
False
Admin integration
-----------------
Replace ``admin.ModelAdmin`` with ``GuardedModelAdmin`` for those models
which should have object permissions support within admin panel.
For example:
.. code:: python
from django.contrib import admin
from myapp.models import Author
from guardian.admin import GuardedModelAdmin
# Old way:
#class AuthorAdmin(admin.ModelAdmin):
# pass
# With object permissions support
class AuthorAdmin(GuardedModelAdmin):
pass
admin.site.register(Author, AuthorAdmin)
.. [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>`_.
.. _Django: http://www.djangoproject.com/
Raw data
{
"_id": null,
"home_page": "http://github.com/django-guardian/django-guardian",
"name": "django-guardian",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.5",
"maintainer_email": "",
"keywords": "",
"author": "Lukasz Balcerzak",
"author_email": "lukaszbalcerzak@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/6f/4c/d1f6923a0ad7f16c403a54c09e94acb76ac6c3765e02523fb09b2b03e1a8/django-guardian-2.4.0.tar.gz",
"platform": "",
"description": "===============\ndjango-guardian\n===============\n\n.. image:: https://github.com/django-guardian/django-guardian/workflows/Tests/badge.svg?branch=devel\n :target: https://github.com/django-guardian/django-guardian/actions/workflows/tests.yml\n\n.. image:: https://img.shields.io/pypi/v/django-guardian.svg\n :target: https://pypi.python.org/pypi/django-guardian\n\n.. image:: https://img.shields.io/pypi/pyversions/django-guardian.svg\n :target: https://pypi.python.org/pypi/django-guardian\n\n``django-guardian`` is an implementation of per object permissions [1]_ on top\nof Django's authorization backend\n\nDocumentation\n-------------\n\nOnline documentation is available at https://django-guardian.readthedocs.io/.\n\nRequirements\n------------\n\n* Python 3.5+\n* A supported version of Django (currently 2.2+)\n\nGitHub Actions run tests against Django versions 2.2, 3.0, 3.1, 3.2, and main.\n\nInstallation\n------------\n\nTo install ``django-guardian`` simply run::\n\n pip install django-guardian\n\nConfiguration\n-------------\n\nWe need to hook ``django-guardian`` into our project.\n\n1. Put ``guardian`` into your ``INSTALLED_APPS`` at settings module:\n\n.. code:: python\n\n INSTALLED_APPS = (\n ...\n 'guardian',\n )\n\n2. Add extra authorization backend to your ``settings.py``:\n\n.. code:: python\n\n AUTHENTICATION_BACKENDS = (\n 'django.contrib.auth.backends.ModelBackend', # default\n 'guardian.backends.ObjectPermissionBackend',\n )\n\n3. Create ``guardian`` database tables by running::\n\n python manage.py migrate\n\nUsage\n-----\n\nAfter installation and project hooks we can finally use object permissions\nwith Django_.\n\nLets start really quickly:\n\n.. code:: python\n\n >>> from django.contrib.auth.models import User, Group\n >>> jack = User.objects.create_user('jack', 'jack@example.com', 'topsecretagentjack')\n >>> admins = Group.objects.create(name='admins')\n >>> jack.has_perm('change_group', admins)\n False\n >>> from guardian.models import UserObjectPermission\n >>> UserObjectPermission.objects.assign_perm('change_group', jack, obj=admins)\n <UserObjectPermission: admins | jack | change_group>\n >>> jack.has_perm('change_group', admins)\n True\n\nOf course our agent jack here would not be able to *change_group* globally:\n\n.. code:: python\n\n >>> jack.has_perm('change_group')\n False\n\nAdmin integration\n-----------------\n\nReplace ``admin.ModelAdmin`` with ``GuardedModelAdmin`` for those models\nwhich should have object permissions support within admin panel.\n\nFor example:\n\n.. code:: python\n\n from django.contrib import admin\n from myapp.models import Author\n from guardian.admin import GuardedModelAdmin\n\n # Old way:\n #class AuthorAdmin(admin.ModelAdmin):\n # pass\n\n # With object permissions support\n class AuthorAdmin(GuardedModelAdmin):\n pass\n\n admin.site.register(Author, AuthorAdmin)\n\n\n.. [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>`_.\n\n.. _Django: http://www.djangoproject.com/\n\n\n",
"bugtrack_url": null,
"license": "BSD",
"summary": "Implementation of per object permissions for Django.",
"version": "2.4.0",
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "dfe84f444671fd8769099fb6e7746a6a",
"sha256": "440ca61358427e575323648b25f8384739e54c38b3d655c81d75e0cd0d61b697"
},
"downloads": -1,
"filename": "django_guardian-2.4.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "dfe84f444671fd8769099fb6e7746a6a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.5",
"size": 106107,
"upload_time": "2021-05-23T22:11:22",
"upload_time_iso_8601": "2021-05-23T22:11:22.750116Z",
"url": "https://files.pythonhosted.org/packages/a2/25/869df12e544b51f583254aadbba6c1a95e11d2d08edeb9e58dd715112db5/django_guardian-2.4.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"md5": "6e961a95b2fe10c0f795b3f3d313b20c",
"sha256": "c58a68ae76922d33e6bdc0e69af1892097838de56e93e78a8361090bcd9f89a0"
},
"downloads": -1,
"filename": "django-guardian-2.4.0.tar.gz",
"has_sig": false,
"md5_digest": "6e961a95b2fe10c0f795b3f3d313b20c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.5",
"size": 159008,
"upload_time": "2021-05-23T22:11:26",
"upload_time_iso_8601": "2021-05-23T22:11:26.230597Z",
"url": "https://files.pythonhosted.org/packages/6f/4c/d1f6923a0ad7f16c403a54c09e94acb76ac6c3765e02523fb09b2b03e1a8/django-guardian-2.4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2021-05-23 22:11:26",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "django-guardian",
"github_project": "django-guardian",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "Django",
"specs": [
[
">=",
"2.2"
]
]
},
{
"name": "django-environ",
"specs": []
},
{
"name": "bumpversion",
"specs": []
},
{
"name": "mock",
"specs": []
}
],
"tox": true,
"lcname": "django-guardian"
}