Write universal django view decorators that work with regular view functions, view classes, and also with view class methods.
Project description
Introduction
In django you can implement views in two different standard ways (regular view function, class based view) and the same project can make use of both techniques in parallel. In case of class based views I’ve seen several ways of decorating them and none of the techniques were really attractive to me (visually and/or functionally).
You are probably familiar at least with the easiest ways of writing a decorator: implementing it as a regular function (or class) and applying it only to regular view functions. Implementing a decorator that can be applied to both regular view functions and instance methods is more challenging especially if you want to access the arguments of the decorated function/method.
If we want to be able to apply the same decorator also to view classes then things get messy very quickly depending on the expected behavior in that case.
I’ve seen several discussions on mailing lists about modifying view class behavior with decorators VS mixins. While it’s obviously easier to use decorators with regular functions I think they have some limited use also in case of classes. I don’t expect you to see this library as THE solution to all of your previous problems. Both decorators and mixins have their own problems in case of view classes. It depends on the scenario which solution is less painful to apply.
Goals
With this library I introduce a new way to implement django view decorators. At the same time I provide a solution to reuse legacy decorators in a more flexible way.
The goals of this library:
Easy way to implement view decorators that can be applied to:
regular view functions
view class methods
view classes
If you have simple legacy view decorators that can be applied only to regular view functions then this library also provides wrappers that make your legacy decorator usable in the previously mentioned scenarios.
The decorator implementation should be able to access view args (like request) easily in a unified way regardless of the type of the view the decorator is applied to.
The way of applying the decorator to different kinds of views should look the same in the code. The code should have “good graphics”. :-)
Additional expectations in case of applying the decorator to view classes:
In case of applying the decorator to a view class I want the decorator to treat the view class as a regular view function. What do I mean by this? When you attach a view class to a url you call its View.as_view() method that basically converts it into a view function to be used by django. When I apply my decorator to a view class I want the decorator to decorate the view function returned by the as_view() method of the view class.
I want the decorator to be inherited by view subclasses and I want it to be difficult for subclasses to execute logic before the logic of the base class decorator. Simply overriding the dispatch() or get() or a similar method of the view subclass shouldn’t allow code execution before the logic of a base class decorator.
A difficult-to-bypass view base class decorator logic like this can come in handy in view base classes where you want to employ critical checks (security/permission related stuff). This inherited decorator can be a very good safeguard when others implement their subclasses by building on your base class and inherit your base class decorators.
Anyway, if you want to provide base class view decoration logic before which a subclass can easily execute its own code then instead of decorating the base class you should probably decorate one of its methods (dispatch(), get(), etc…). This way the subclass can easily execute logic before base class method decorator simply by overriding the method.
Usage
Installation
pip install django-universal-view-decorator
Alternatively you can download the zipped library from https://pypi.python.org/pypi/django-universal-view-decorator
Quick-starter
Implementing decorators using this library
I want an easy way to implement @my_view_decorator that can be applied easily to different kind of views in the following way:
@my_view_decorator
def regular_view_function(request):
pass
@my_view_decorator
class ViewClass(View):
...
class ViewClass2(View):
@my_view_decorator(optional_param)
def get(self, request):
...
The following code block is a possible implementation-skeleton of @my_view_decorator using this library. Despite the long list of my requirements the implementation of the decorator is fairly simple:
from django_universal_view_decorator import ViewDecoratorBase
class MyViewDecorator(ViewDecoratorBase):
# Note: You don't have to override ``__init__()`` if your decorator doesn't
# have arguments and you don't have to setup instance attributes.
def __init__(self, optional_arg=5):
super().__init__()
self.optional_arg = optional_arg
def _call_view_function(self, decoration_instance, view_class_instance, view_function, *args, **kwargs):
# Note: You can of course use ``self.optional_arg`` in this method.
# If you need the request arg of the view...
request = args[0]
# TODO: manipulate the request and other incoming args/kwargs if you want
# TODO: return a response instead of calling the original view if you want
response = view_function(*args, **kwargs)
# TODO: manipulate the response or forge a new one before returning it
return response
# This step makes the decorator compatible with view classes and also makes
# it possible to use the decorator without the ``()`` when the decorator has
# no required arguments and you don't want to pass any of them.
my_view_decorator = MyViewDecorator.universal_decorator
Giving superpowers to legacy decorators
Besides providing an easy way to implement the above “universal” view decorator this library also provides special legacy decorator wrappers that give your legacy view decorators (that can be applied only to regular view functions) some of the superpowers of the previously implemented universal view decorator. These legacy decorator wrappers have to be applied similarly to django.utils.decorators.method_decorator():
Use the universal_view_decorator wrapper when:
your legacy decorator has no arguments
your legacy decorator has arguments but it’s ok to pass the arguments to your legacy decorator BEFORE wrapping it
from django_universal_view_decorator import universal_view_decorator @universal_view_decorator(legacy_decorator) def regular_view_function(request): ... # You can wrap multiple decorators at the same time @universal_view_decorator(legacy_decorator, legacy_decorator_2) def regular_view_function(request): ... # This double decoration is equivalent in behavior to the previous example # where we used one wrapper to wrap both legacy decorators. @universal_view_decorator(legacy_decorator) @universal_view_decorator(legacy_decorator_2) def regular_view_function(request): ... # With ``@universal_view_decorator`` you have to pass the args to your legacy # decorators BEFORE wrapping them. If you want to pass the args to your decorator # after wrapping then you have to use the ``@universal_view_decorator_with_args`` # instead of this wrapper. @universal_view_decorator(legacy_decorator_with_args(arg)) def regular_view_function(request): ... # Applying the decorator to view classes @universal_view_decorator(legacy_decorator_with_args('woof', 'woof')) class ViewClass(View): ... # Applying the decorator to view class methods class ViewClass(View): @universal_view_decorator(legacy_decorator, legacy_decorator_2) def head(self, request): ... # Reusable wrapped decorator reusable_wrapped_legacy_decorator = universal_view_decorator(legacy_decorator_with_args(5)) @reusable_wrapped_legacy_decorator class ViewClass(View): ...
Use the universal_view_decorator_with_args wrapper when your decorator has args and you want to pass these args to your legacy decorator AFTER wrapping it. With this wrapper you can’t wrap multiple legacy decorators at the same time.
from django_universal_view_decorator import universal_view_decorator_with_args # Wrapping the legacy decorator and the reusing the wrapped one multiple times. wrapped_legacy_decorator = universal_view_decorator_with_args(legacy_decorator_with_args) @wrapped_legacy_decorator(legacy_decorator_arg) def regular_view_function(request): ... @wrapped_legacy_decorator(arg1, arg2, kwarg1=1, kwarg2='woof') class ViewClass(View): ... class ViewClass(View): @wrapped_legacy_decorator(arg1, arg2, kwarg1=1, kwarg2='woof') def get(self, request): ...
I have a lot of time to read boring documentation
Popular view decoration techniques
Here comes a brief and probably non-exhaustive collection of popular django view decoration techniques. This section can be useful for quick “visual” comparison of the solutions (including mine).
Regular view functions
Decorating a regular view function if fairly straightforward:
You either simply apply the decorator to the regular view function…
@legacy_decorator def regular_view_function(request): ...
or you apply the decorator only on a per-url basis in your url config when you attach the view function to a specific url.
urlpatterns = [ url(r'^my/url/$', legacy_decorator(views.regular_view_function)), ... ]
Class based views
In case of class based views things are a bit more complicated. Decorating view classes and view class methods is more difficult than decorating regular view functions for several reasons including these:
I think view classes and the related object oriented features (inheritance, etc..) make it a bit more difficult to trace the execution path of the logic. At the same time they make it more difficult to find the right spots to “insert” extra logic for example by applying decorators.
Writing decorators that manipulate classes in fancy and perhaps useful ways isn’t the easiest task.
Despite the previously mentioned problems I think class based views are useful but it doesn’t change the fact that people have been struggling with applying decorators (or other “behavior modifiers”) to them. Probably as a consequence of this and maybe because of the early lack of standard solutions people have hacked around and forged quite a few different solutions.
Decorating class based views:
On a per-url basis in the url config when the class based view gets converted to a regular view function (by calling its as_view() class method). I think this is the most reliable and easy-to-understand way to decorate class based views. This is why my view class decorator uses the same insertion point for its decorator logic. The decorator logic sits in a well defined place exactly between the django url dispatcher and the view function.
urlpatterns = [ url(r'^my/url/$', legacy_decorator(views.ViewClass.as_view())), ... ]
By overriding its dispatch() method or one of the http-request-method specific methods called by dispatch() and decorating the method (usually with the help of django.utils.decorators.method_decorator() or using hand-crafted decorators that make use of ugly function or descriptor magic).
from django.utils.decorators import method_decorator class ViewClass(View): @method_decorator(legacy_decorator) def dispatch(self, request, *args, **kwargs): # We overridden this method without adding logic just # to be able to decorate it. This is a bit ugly. return super().dispatch(request, *args, **kwargs) @method_decorator(legacy_decorator_2) def get(self, request): ...
The previous method decoration technique sometimes overrides a method (e.g.: dispatch()) just for the sake of decorating it. The implementation of the method in that case simply calls the super() version. This is quite an ugly non-pythonic way that has two beautified versions:
You can apply your decorator to the method by applying the django.utils.decorators.method_decorator() to the view class by specifying the name of the method to decorate with the name arg of method_decorator(). (django>=1.9)
@method_decorator(legacy_decorator, name='dispatch') class ViewClass(View): ...
Putting the overridden decorated method into a mixin class that can be added to the base class list of a class based view and can optionally be parametrized through class attributes. This way you make the possibly ugly override + decoration only once in the mixin and then you reuse the mixin several times.
This mixin technique can also be used without/instead of a decorator because the decorator logic can be put directly into the overridden method of the mixin class.
class DecoratorMixin(object): """ Reusable mixin for class based views. """ @method_decorator(legacy_decorator) def dispatch(self, request, *args, **kwargs): return super().dispatch(request, *args, **kwargs) class DecoratorMixin2(object): """ Reusable mixin for class based views. """ def get(self, request, *args, **kwargs): # In this case we haven't actually used a decorator, # we put the decorator logic directly to this method. # TODO: manipulate input args if you want response = super().get(request, *args, **kwargs) # TODO: manipulate the response if you want return response # The order of base classes is important! class ViewClass(DecoratorMixin, DecoratorMixin2, View): ...
Advanced view decorator features
[TODO] Optional decorator arguments
[TODO] View class decorator inheritance explained
[TODO] Managing duplicate view class decorators in the view class hierarchy
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
Built Distribution
Hashes for django-universal-view-decorator-0.0.3.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 305c19d4ba511ab10f1d8e14585b0692b79734aac2fca62364d1ba3a3ef31cb6 |
|
MD5 | 4f3dfe94aa4502a9d7fe6299f63285df |
|
BLAKE2b-256 | bfdf4a9f49784de382981a0b8b19d7be7182556bc5fedd59cd83ee70c992f546 |
Hashes for django_universal_view_decorator-0.0.3-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | e860e604c3ac2e3e280602bf7df95b1cb914c19ddd8a57cbbdda6c9cd4229f22 |
|
MD5 | 64c9273f45b29ca3bf18a7e05196eacb |
|
BLAKE2b-256 | a39c8f2c5bf9318ecfcdcf817d6ef894b4b4a7e6a3c4ed3af8b7e11df624da24 |