README.md 3.94 KB
Newer Older
Lincoln Smith's avatar
Lincoln Smith committed
1
2
Implements permissions for model fields in Django

3
## Requirements
Lincoln Smith's avatar
Lincoln Smith committed
4
* Python 3.4+
5
* Django 1.11+ 
Lincoln Smith's avatar
Lincoln Smith committed
6

7
8
## Installation
`pip install django-perfieldperms`
Lincoln Smith's avatar
Lincoln Smith committed
9

10
11
12
13
14
15
16
17
Add perfieldperms to INSTALLED_APPS and AUTHENTICATION_BACKENDS:
```python
INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    ...
    'perfieldperms.apps.PerfieldpermsConfig',
    ]
Lincoln Smith's avatar
Lincoln Smith committed
18

19
20
21
22
AUTHENTICATION_BACKENDS = [
    'perfieldperms.backends.PFPBackend',
    ]
```
Lincoln Smith's avatar
Lincoln Smith committed
23

24
Run `manage.py migrate`
Lincoln Smith's avatar
Lincoln Smith committed
25

26
## Configuration
Lincoln Smith's avatar
Lincoln Smith committed
27
28
perfieldperms is configurable via ``settings.py`` or via internal models.

29
30
31
32
33
Once configured you will need to run `./manage.py pfp-makeperms` to create
field permissions.

### settings.py
PFP_MODELS - an iterable of two tuples `[(app_label, model_name)]` of models you
Lincoln Smith's avatar
Lincoln Smith committed
34
35
want perfieldpermissions (pfps) created for.

36
37
38
39
40
PFP_IGNORE_PERMS - a dict of dicts of iterables of permissions you want
ignored when creating pfps. Structured:
```python
{app_label:
    {model name: [<perm codename>, <perm codename>,..]}
Lincoln Smith's avatar
Lincoln Smith committed
41
    }
42
```
Lincoln Smith's avatar
Lincoln Smith committed
43

44
PFP_IGNORE_DELETE - By default perfieldperms doesn't create field level delete
Lincoln Smith's avatar
Lincoln Smith committed
45
46
47
permissions as this doesn't necessarily make sense. Set to False if you want to
create delete pfps.

48
49
50
51
52
53
PFP_IGNORE_VIEW - By default perfieldperms doesn't create field level view 
permissions as this doesn't necessarily make sense. Set to False if you want to
create view pfps.

### Internal models
PFPContentType - Django ContentTypes you want to create pfps for. This setting is
Lincoln Smith's avatar
Lincoln Smith committed
54
55
merged with PFP_MODELS from ``settings.py``.

56
57
58
59
60
61
62
63
64
65
## Management commands
pfp-makeperms - Create field permissions for configured models.

## Forms
`perfieldperms.forms.PFPModelForm` extends `django.forms.ModelForm` to apply
field permissions to a ModelForm. Fields can be disabled or removed entirely
based on class attributes/parameters, or by passing in a user to check
permissions against at form creation.

## Use
Lincoln Smith's avatar
Lincoln Smith committed
66
After configuring which models you want to creats pfps for run the management
67
command `./manage.py pfp-makeperms`.
Lincoln Smith's avatar
Lincoln Smith committed
68
69
70

PerFieldPermission subclasses Permission so pfps can be accessed, allocated and
tested as normal Permission objects. PerFieldPermissions are linked to a parent
71
model permission to create the appropriate hierarchy. Depending on needs you
Lincoln Smith's avatar
Lincoln Smith committed
72
73
74
may not need to access the actual PerFieldPermission objects.

Perfieldperms tries to take a Principle of Least Astonishment approach to
75
76
testing permissions, while attempting to support reasonably complicated
permission structures:
Lincoln Smith's avatar
Lincoln Smith committed
77
78
79
* If a user has a model level permission but no field permissions, they
  are deemed to have all equivalent field permissions (all field permissions
  linked to that model permission).
80
81
82
83
84
85
* Model permissions remain additive as in out of the box Django.
* Field permissions allocated to groups are additive, so field permissions for
  all a user's groups are merged.
* Field permissions allocated to a user override those allocated to groups they
  are a member of. The effect is to explicitly set the fields the user has
  access to. This allows for the creation of limited exceptions within groups.
Lincoln Smith's avatar
Lincoln Smith committed
86
* Possession of a field permission implies access to the model, so testing
87
  access to a model via e.g. ModelAdmin `had_add_permission()` will succeed if
Lincoln Smith's avatar
Lincoln Smith committed
88
89
  the user has any applicable field permission.

90
91
## Admin interface
Two ModelAdmins `PFPModelAdmin` and `PFPInlineAdmin` are provided that
Lincoln Smith's avatar
Lincoln Smith committed
92
extend the appropriate ModelAdmin, disabling fields in forms as appropriate.
93
These can be used as is or as Mixins to extend other ModelAdmin classes.
Lincoln Smith's avatar
Lincoln Smith committed
94

95
96
97
98
There is a permissions management view accessible under
*/admin/perfieldperms/perfieldpermission/manage/*. It provides an alternative
interface to allocating permissions based on a set of filters for
permissions/roles (where a role is a user or group,) and generates a table
99
100
based form listing permissions against users. It is terrible and needs
replacing :)
101

102
103
## Tests
Use `runtests.py` to run tests. Test sub-modules and individual tests can be
Lincoln Smith's avatar
Lincoln Smith committed
104
105
targetted by supplying the appropriate python module address as an argument to
the script.