GitLocker: The Coding Marketplace

Description:

djangofperms 0.4.8

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:

Cookiecutter
cookiecutter-djangopackage

History

0.4.7 (2020-10-24)

Added permission Group
Fixed tests

0.1.0 (2018-02-13)

First release on PyPI.