diff options
Diffstat (limited to 'docs/topics')
| -rw-r--r-- | docs/topics/2.2-announcement.md | 39 |
1 files changed, 39 insertions, 0 deletions
diff --git a/docs/topics/2.2-announcement.md b/docs/topics/2.2-announcement.md index 4ed9f970..262ae61d 100644 --- a/docs/topics/2.2-announcement.md +++ b/docs/topics/2.2-announcement.md @@ -101,6 +101,45 @@ In keeping with Django's CharField API, REST framework's `CharField` will only e The `blank` keyword argument will continue to function, but will raise a `PendingDeprecationWarning`. +### Simpler object-level permissions + +Custom permissions classes previously used the signatute `.has_permission(self, request, view, obj=None)`. This method would be called twice, firstly for the global permissions check, with the `obj` parameter set to `None`, and again for the object-level permissions check when appropriate, with the `obj` parameter set to the relevant model instance. + +The global permissions check and object-level permissions check are now seperated into two seperate methods, which gives a cleaner, more obvious API. + +* Global permission checks now use the `.has_permission(self, request, view)` signature. +* Object-level permission checks use a new method `.has_object_permission(self, request, view, obj)`. + +For example, the following custom permission class: + + class IsOwner(permissions.BasePermission): + """ + Custom permission to only allow owners of an object to view or edit it. + Model instances are expected to include an `owner` attribute. + """ + + def has_permission(self, request, view, obj=None): + if obj is None: + # Ignore global permissions check + return True + + return obj.owner == request.user + +Now becomes: + + class IsOwner(permissions.BasePermission): + """ + Custom permission to only allow owners of an object to view or edit it. + Model instances are expected to include an `owner` attribute. + """ + + def has_object_permission(self, request, view, obj): + return obj.owner == request.user + +If you're overriding the `BasePermission` class, the old-style signature will continue to function, and will correctly handle both global and object-level permissions checks, but it's use will raise a `PendingDeprecationWarning`. + +Note also that the usage of the internal APIs for permission checking on the `View` class has been cleaned up slightly, and is now documented and subject to the deprecation policy in all future versions. + [xordoquy]: https://github.com/xordoquy [django-python-3]: https://docs.djangoproject.com/en/dev/faq/install/#can-i-use-django-with-python-3 [porting-python-3]: https://docs.djangoproject.com/en/dev/topics/python3/ |