https://github.com/django-guardian/django-guardian

Per object permissions for Django
https://github.com/django-guardian/django-guardian

hacktoberfest

Last synced: 5 days ago
JSON representation

Per object permissions for Django

• Host: GitHub
• URL: https://github.com/django-guardian/django-guardian
• Owner: django-guardian
• License: other
• Created: 2010-06-04T23:15:37.000Z (over 14 years ago)
• Default Branch: devel
• Last Pushed: 2024-10-22T08:51:50.000Z (3 months ago)
• Last Synced: 2025-01-03T22:02:19.948Z (8 days ago)
• Language: Python
• Homepage: https://django-guardian.readthedocs.io/
• Size: 1.72 MB
• Stars: 3,675
• Watchers: 77
• Forks: 567
• Open Issues: 147
• Metadata Files:
  • Readme: README.rst
  • Changelog: CHANGES
  • License: LICENSE
  • Security: SECURITY.md
  • Authors: AUTHORS

Awesome Lists containing this project

• awesome-django-cn - django-guardian, star:1412 - 实现对象级别的权限，来用作授权后端。 (授权)
• -awesome-django - django-guardian - Per object permissions in Django. (Third-Party Packages / General)
• awesome-starts - django-guardian/django-guardian - Per object permissions for Django (Python)
• awesome-django - django-guardian - Implementation of per object permissions as authorization backend. (Authorization)
• awesome-django - django-guardian - Implementation of per object permissions as authorization backend. (Authorization)
• awesome-django - django-guardian - Per object permissions in Django. (Third-Party Packages / Permissions)
• awesome-django-security - Django Guardian - object permissions on top of Django's authorization backend. (Libs / Permissions management)
• best-django-resource - django-guardian - Adds per-object permissions for Django's built-in authentication system. (Security)

README

        
===============

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.8+

* A supported version of Django (currently 3.2+)

GitHub Actions run tests against Django versions 3.2, 4.1, 4.2, 5.0 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', '[email protected]', '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)

      

      >>> 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 `_.

.. _Django: http://www.djangoproject.com/