Skip to main content

Flexible Django permissions backend

Project description

https://badge.fury.io/py/django-fperms.svg https://travis-ci.org/Formulka/django-fperms.svg?branch=master https://codecov.io/gh/Formulka/django-fperms/branch/master/graph/badge.svg

The flexible permissions library uses a custom permission model, that when installed patches itself into the standard django authentication library.

Documentation

The full documentation is at https://django-fperms.readthedocs.io.

Quickstart

Install django-fperms:

pip install django-fperms

Add it to your INSTALLED_APPS:

INSTALLED_APPS = (
    ...
    'fperms.apps.FPermsConfig',
    ...
)

Out of the box you have access to several new permission types:

  • generic: for general purpose project wide permissions

  • model: for per model permissions (similar to django default permissions)

  • instance: for per instance permissions, similar to model permissions but specific per instance

  • field: for per model field permissions, similar to model permissions but specific per model field, work in progress

You can also create your own permission model subclassing the abstract base permission class:

fperms.models.BasePerm

and setting the PERM_MODEL variable in your project settings with the path to your custom model. E.g.

...
PERM_MODEL='fperms.models.Perm'
...

You can find an example of custom permission model at https://github.com/formulka/django-fperms-iscore

Usage

A superuser has for all intents and purposes permission to do everything. For regular users you can assign permissions directly or via a user group.

Creating a new permission:

You can create a new permission directly via its model or via a specially formated string:

from fperms import enums
from fperms.models import Perm

Perm.objects.create(
    type=enums.PERM_TYPE_GENERIC,
    codename='export',
)
Perm.objects.create_from_str('generic.export')

Assigning a permission:

You can assign existing permission via the custom perms manager available for both User (including custom ones) and Group models. You can add single permission or multiple both directly via its instance or using the formated string:

from django.auth.models import User, Group

from fperms.models import Perm

perm_export = Perm.objects.create(
    type=enums.PERM_TYPE_GENERIC,
    codename='export',
)
perm_import = Perm.objects.create(
    type=enums.PERM_TYPE_GENERIC,
    codename='import',
)

user = User.objects.get(pk=1)
user.fperms.add_perm(perm_export)
user.fperms.add_perm(perms=[perm_export, perm_import])

group = Group.objects.get(pk=1)
group.fperms.add_perm(perms=['generic.export', 'generic.import'])

By default if said permission does not exist, it will raise an exception. You can override this behavior by setting PERM_AUTO_CREATE variable in your project settings to True, assigning a permission will then create it as well if it does not exist.

Retrieving permission instance:

You can get a permission instance directly from the model or via the string representation.

perm = Perm.objects.get(type=enums.PERM_TYPE_GENERIC, codename='export')
perm = Perm.objects.get_from_str('generic.export')

Checking permission:

You can check whether the user or group has a required permission via has_perm method of the perms manager again using both the permission instance or the string representation.

...
perm = Perm.objects.create(
    type=enums.PERM_TYPE_GENERIC,
    codename='export',
)

assert user.fperms.has_perm(perm)
assert user.fperms.has_perm('generic.export')

Built in perm types

generic

  • generic permission useful for project wide permissions

  • type is defined as fperms.enums.PERM_TYPE_GENERIC, it is the default permission type

  • it requires type and codename fields (type being default only the codename is actually required)

  • string representation is 'generic.<codename>'

...
# equivalent results:
Perm.objects.create(
    codename='export',
)
Perm.objects.create_from_str('generic.export')

model

  • model level permission analogous to the builtin django permissions

  • type is defined as fperms.enums.PERM_TYPE_MODEL

  • it requires type, content_type and codename fields

  • django admin is using codenames add, change and delete for its inner workings

  • string representation is 'model.<app_label>.<module_name>.<codename>'

from fperms import enums
from fprems.utils import get_content_type
...
# equivalent results:
Perm.objects.create(
    type=enums.PERM_TYPE_MODEL,
    content_type=get_content_type(Article),
    codename='add',
)
Perm.objects.create_from_str('model.articles.Article.add')

object

  • model level permission specific per object

  • type is defined as fperms.enums.PERM_TYPE_OBJECT

  • it requires type, content_type, object_id and codename fields

  • django admin is using codenames add, change and delete for its inner workings

  • string representation is 'object.<app_label>.<module_name>.<codename>'

from fperms import enums
from fprems.utils import get_content_type
...
article = Article.objects.get(pk=1)
# equivalent results:
Perm.objects.create(
    type=enums.PERM_TYPE_OBJECT,
    content_type=get_content_type(Article),
    object_id=article.pk,
    codename='add',
)
Perm.objects.create_from_str('object.articles.Article.add', obj_id=article.pk)

# creating multiple permissions for a single object at once is supported
Perm.objects.create_from_str(perms=[
                                'object.articles.Article.add',
                                'object.articles.Article.change',
                                'object.articles.Article.delete',
                            ], obj_id=article.pk)

field

  • model level permission specific per model field

  • type is defined as fperms.enums.PERM_TYPE_FIELD

  • it requires type, content_type, name and codename fields

  • string representation is 'field.<app_label>.<module_name>.<name>.<codename>'

  • TODO: this permission type is not fully implemented yet

from fperms import enums
from fprems.utils import get_content_type
...
article = Article.objects.get(pk=1)
# equivalent results:
Perm.objects.create(
    type=enums.PERM_TYPE_FIELD,
    content_type=get_content_type(Article),
    name='name',
    codename='add',
)
Perm.objects.create_from_str('field.articles.Article.name.add')

Admin

Flexible permisssions support django admin interface, to enable them you need to first update the list of authentication backends in your project settings:

AUTHENTICATION_BACKENDS = [
    'django.contrib.auth.backends.ModelBackend',
    'fperms.backends.PermBackend',
]

and then simply subclass the fperms.admin.PermModelAdmin instead of the regular admin.ModelAdmin:

from django.contrib import admin
from fperms.admin import PermModelAdmin

from articles.models import Article


@admin.register(Article)
class ArticleAdmin(PermModelAdmin):
    pass

To enable per-instance permission support, set perms_per_instance property of the admin class to True.

...
@admin.register(Article)
class ArticleAdmin(PermModelAdmin):

    perms_per_instance = True

User still needs model level permission for each model it should be able to access via admin site.

If the perms_per_instance option is set to True, author of a new instance will automatically receive the permission to update and delete said instance. You can override this behavior by setting perms_per_instance_author_change and perms_per_instance_author_delete admin properties respectively to False.

Running Tests

Does the code actually work?

source <YOURVIRTUALENV>/bin/activate
(myenv) $ pip install tox
(myenv) $ tox

Credits

Tools used in rendering this package:

History

0.4.7 (2020-10-24)

  • Added permission Group

  • Fixed tests

0.1.0 (2018-02-13)

  • First release on PyPI.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

django-fperms-0.4.8.tar.gz (16.3 kB view details)

Uploaded Source

File details

Details for the file django-fperms-0.4.8.tar.gz.

File metadata

  • Download URL: django-fperms-0.4.8.tar.gz
  • Upload date:
  • Size: 16.3 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.3.0 pkginfo/1.7.0 requests/2.23.0 setuptools/45.2.0 requests-toolbelt/0.9.1 tqdm/4.58.0 CPython/3.8.10

File hashes

Hashes for django-fperms-0.4.8.tar.gz
Algorithm Hash digest
SHA256 c5e136237995d393ecd2632968d960a821839b8758264dc4ad5669a6a7182a24
MD5 270131c3b5d7ffc031cbe69c72aa2781
BLAKE2b-256 2e0a419f1aa08e99711b04a13e3f1e63a24f29e925f0b5f0805d43589aa2476b

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page