View method middleware

In most circumstances, data in requests & responses is added, removed or updated in a piecemeal fashion in view methods. However, sometimes it's convenient to apply these changes on all requests and responses.

For example, if you want to access certain data on all view methods, it's easier to use a middleware class to make this data accessible across all requests. Just as if you want to enforce a security check on all responses, it's easier to do so globally with a middleware class.

Since middleware is a rather abstract concept, before I describe the structure of a Django middleware class, I'll walk you through the various built-in Django middleware classes so you can get a firmer understanding of where middleware is good design choice.

Built-in middleware classes

Django comes equipped with a series of middleware classes, some of which are enabled by default on all Django projects. If you open a Django project's settings.py file you'll notice the MIDDLEWARE variable whose default contents are shown in listing 2-29.

Listing 2-29 Default Django middleware classes in MIDDLEWARE

MIDDLEWARE = [
    'django.middleware.security.SecurityMiddleware',
    'django.contrib.sessions.middleware.SessionMiddleware',
    'django.middleware.common.CommonMiddleware',
    'django.middleware.csrf.CsrfViewMiddleware',
    'django.contrib.auth.middleware.AuthenticationMiddleware',
    'django.contrib.messages.middleware.MessageMiddleware',
    'django.middleware.clickjacking.XFrameOptionsMiddleware',
]

As you can see in listing 2-29, Django projects in their out-of-the-box state come enabled with seven middleware classes, so all requests and responses are set to run through these seven classes. If you plan to leverage Django's main features, I advise you not to remove any of these default middleware classes. However, you can leave the MIDDLEWARE variable empty if you wish, just be aware doing so may break certain Django functionalities.

To give you a better understanding of what the Django middleware classes in listing 2-29 do and help you make a more informed decision to disable them or not, table 2-7 describes the functionality for each of these middleware classes.

Table 2-7 Django default middleware classes and functionality

As you can see in table 2-7, although the purpose of the various default middleware classes varies considerably, their functionality applies to features that need to be applied across all requests or responses in a project.

Another important factor of the middleware classes in table 2-7 is that some are dependent on others. For example, the AuthenticationMiddleware class is designed on the assumption it will have access to functionality provided by the SessionMiddleware class. Such dependencies are important because it makes the middleware class definition order relevant (i.e. certain middleware classes need to be defined before others in MIDDLEWARE) a topic I'll elaborate on more in the next section.

In addition to the default middleware classes presented in table 2-7, Django also offers other middleware classes. Table 2-7 illustrates the remaining set of Django middleware classes you can leverage in your projects, which can be helpful so you don't have to write middleware classes from scratch.

Table 2-8 Other Django middleware classes and functionality

Now that you know about Django's built-in middleware classes and what it's they're used for, lets take a look at the structure of middleware classes and their execution process.

Middleware structure & execution process

A Django middleware class has two required methods and three optional methods that execute at different points of the view request/response life-cycle. Listing 2-30 illustrates a sample middleware class with its various parts.

Listing 2-30. Django middleware class structure

class CoffeehouseMiddleware(object):

    def __init__(self, get_response):
        self.get_response = get_response
        # One-time configuration and initialization on start-up
	
    def __call__(self, request):
        # Logic executed on a request before the view (and other middleware) is called.
        # get_response call triggers next phase
        response = self.get_response(request)
        # Logic executed on response after the view is called.
        # Return response to finish middleware sequence
        return response
	
    def process_view(self, request, view_func, view_args, view_kwargs):
        # Logic executed before a call to view
        # Gives access to the view itself & arguments
	
    def process_exception(self,request, exception):
        # Logic executed if an exception/error occurs in the view
	
    def process_template_response(self,request, response):
        # Logic executed after the view is called, 
        # ONLY IF view response is TemplateResponse, see listing 2-24 

In order for view methods to execute the Django middleware class in listing 2-30, middleware classes must be added to the MIDDLEWARE variable in settings.py. So for example, if the CoffeehouseMiddleware class in listing 2-30 is stored in a file/module named middleware.py under the coffeehouse/utils/ project folders, you would add the coffeehouse.utils.middleware.CoffeeMiddleware statement to the list of MIDDLEWARE values in settings.py.

Next, I'll describe the two required methods in every Django middleware class shown In listing 2-30:

• __init__.- Used in all Python classes to bootstrap object instances. The __init__ method in Django middleware classes only gets called once, when the web server backing the Django application starts. The __init__ method in Django middleware must declare a get_response input, which represents a reference to a prior middleware class response. The get_response input is assigned to an instance variable -- also named get_response -- which is later used in the main processing logic of the middleware class. The purpose of the get_response reference should become clearer shortly when I expand on the Django middleware execution process.
• __call__.- Used in all Python classes to call an object instance as a function. The __call__ method in Django middleware classes is called on every application request. As you can see in listing 2-30, the __call__ method declares a request input which represents the same HttpRequest object used by view methods. The __call__ method goes through three phases:
  • Before view method call.- Once the __call__ method is triggered, you get the opportunity to alter the request reference before it's passed to a view method. If you want to add or modify something in request before it gets turned over to a view method, this is the phase to do it in.
  • Trigger view method call.- After you modify (or not) the original request, you must turn over control to the view method in order for it to run. This phase is triggered when you pass request to the self.get_response reference you set in the __init__ method. This phase effectively says "I'm done modifying the request, go ahead and turn it over to the view method so it can run".
  • Post view method call.- Once a view method finishes, the results are assigned to the response reference in __call__. In this phase, you have the opportunity to perform logic after a view method finishes. You exit this phase by simply returning the response reference from the view method (i.e. return response).

This is the core logic behind every Django middleware class performed by these two required methods. Now let's take a look at the three optional middleware class methods presented in listing 2-30:

• process_view.- The required middleware methods -- __init__ and __call__ -- lack any knowledge about the view method they're working on. The process_view method gives you access to a view method and its argument before the view method is triggered. If present, the process_view middleware method is invoked right after __call__ and before calling self.get_response(request) which triggers the view method.
• process_exception.- If an error occurs in the logic of a view method, the process_exception middleware method is invoked to give you the opportunity to perform post-error clean up logic.
• process_template_response.- After the self.get_response(request) is called and a view method finishes, it can be necessary to alter the response itself to perform additional logic on it (e.g. modify the context or template). If present, the process_template_response middleware method is invoked after a view method finishes to give you the opportunity to tinker with the response.

In summary, the execution process for a single middleware class is the following:

1. __init__ method triggered (On server start-up).
2. __call__ method triggered (On every request).
3. If declared, process_view() method triggered.
4. View method starts with self.get_response(request) statement in __call__.
5. If declared, process_exception() method triggered when exception occurs in view.
6. View method finishes.
7. If declared, process_template_response() triggered when view returns TemplateResponse.

Although it's important to understand the execution process of a single middleware class, a more important aspect is to understand the execution process of multiple middleware classes. As I mentioned at the outset of this section, Django projects are enabled with seven middleware classes shown in listing 2-29, so the execution of multiple middleware classes is more the norm rather than the exception.

Django middleware classes are executed back-to-back, but the view method represents an inflection point in their execution order. The execution order for the default middleware classes in listing 2-29, is the following:

Server start-up

__init__ on django.middleware.security.SecurityMiddleware called
__init__ on django.contrib.sessions.middleware.SessionMiddleware called
__init__ on django.middleware.common.CommonMiddleware called
__init__ on django.middleware.csrf.CsrfViewMiddleware called
__init__ on django.contrib.auth.middleware.AuthenticationMiddleware called
__init__ on django.contrib.messages.middleware.MessageMiddleware called 
__init__ on django.middleware.clickjacking.XframeOptionsMiddleware called

A request for index() view method

__call__ on django.middleware.security.SecurityMiddleware called
process_view on django.middleware.security.SecurityMiddleware called (if declared)
__call__ on django.contrib.sessions.middleware.SessionMiddleware called
process_view on django.contrib.sessions.middleware.SessionMiddleware called (if declared)
__call__ on django.middleware.common.CommonMiddleware called
process_view on django.middleware.common.CommonMiddleware called (if declared)
__call__ on django.middleware.csrf.CsrfViewMiddleware called
process_view on django.middleware.csrf.CsrfViewMiddleware called (if declared)
__call__ on django.contrib.auth.middleware.AuthenticationMiddleware called
process_view on django.contrib.auth.middleware.AuthenticationMiddleware called (if declared)
__call__ on django.contrib.messages.middleware.MessageMiddleware called
process_view on django.contrib.messages.middleware.MessageMiddleware called (if declared)
__call__ on django.middleware.clickjacking.XframeOptionsMiddleware called
process_view on django.middleware.clickjacking.XframeOptionsMiddleware called (if declared)

Start index() view method logic

If an exception occurs in index() view

process_exception on django.middleware.clickjacking.XframeOptionsMiddleware called (if declared)
process_exception on django.contrib.messages.middleware.MessageMiddleware called (if declared)
process_exception on django.contrib.auth.middleware.AuthenticationMiddleware called(if declared)
process_exception on django.middleware.csrf.CsrfViewMiddleware called (if declared)
process_exception on django.middleware.common.CommonMiddleware called (if declared)
process_exception on django.contrib.sessions.middleware.SessionMiddleware called (if declared)
process_exception on django.middleware.security.SecurityMiddleware called (if declared)

If index() view returns TemplateResponse

process_template_response on django.middleware.clickjacking.XframeOptionsMiddleware called (if declared)
process_template_response on django.contrib.messages.middleware.MessageMiddleware called (if declared)
process_template_response on django.contrib.auth.middleware.AuthenticationMiddleware called(if declared)
process_template_response on django.middleware.csrf.CsrfViewMiddleware called (if declared)
process_template_response on django.middleware.common.CommonMiddleware called (if declared)
process_template_response on django.contrib.sessions.middleware.SessionMiddleware called (if declared)
process_template_response on django.middleware.security.SecurityMiddleware called (if declared) 

Notice the execution order for middleware classes prior to entering the execution of the view method, follows the declared order (i.e. first declared runs first, last declared last). But once the view method is executed, the middleware execution order is inverted (i.e. last declared runs first, first declared last).

This behavior is similar to a corkscrew, where to get to the center (view method) you move in one direction (1 to 7) and to move out you go in the opposite direction (7 to 1). Therefore the middleware methods process_exception and process_template_response execute in the opposite order of __init__, __call__ and process_view.

Visually the execution process for the default Django middleware classes in listing 2-29 is illustrated in figure 2-4.

Figure 2-4. Django middleware execution process