WSGI Protocol and Django Implementation

When people start Django development, many of them encounter the term “WSGI” and most still don’t know what WSGI is or what it stands for. I’ll touch on these points in this article.

WSGI Protocol and Django Implementation

When people start Django development, many of them encounter the term “WSGI” and most still don’t know what WSGI is or what it stands for. I’ll touch on these points in this article.

What is WSGI?

“WSGI” stands for Web Server Gateway Interface. It’s a Python standard that defines how a web server and web applications should work together. It’s a simple and universal specification for communication between a web server and web applications — how a server interacts with an application and how the application handles requests.

WSGI consists of two key parts:

• Server/Gateway: The HTTP server (like Nginx or Apache), responsible for receiving client requests, forwarding them to the application, and then returning the application’s response to the client.
• Application/Framework: The Python web application or framework (like Django) that receives the forwarded request, processes it, executes logic, prepares a response, and sends it back.

We can write a very simple WSGI application in Python:

def application(environ, start_response):
    start_response('200 OK', [('Content-Type', 'text/plain')])
    return [b'Hello World!']

Here, environ is a dictionary containing CGI environment variables, and start_response is a callable that takes two required parameters: the HTTP status and response headers. Status and headers are returned to the server via start_response, and the body is returned as an iterable of byte strings.

Why Do We Need WSGI?

Django’s request handling is sequential. While processing the first request, subsequent ones wait in a queue until the first completes. To handle concurrency more effectively, we use WSGI implementations such as uWSGI or Gunicorn, often paired with web servers like Nginx to provide high concurrency and performance.

How Django Implements WSGI

1. Program Entry: runserver Command

When you run:

python manage.py runserver

the Django management command executes a series of internal methods:

• BaseCommand.handle()
• run()
• inner_run()

Within inner_run, Django calls basehttp.run, where a WSGIServer instance is created. This handles the server side of the WSGI protocol.

The WSGI application handler is generated via:

django.core.wsgi.get_wsgi_application()

Internally, this function calls django.setup() and returns a WSGIHandler instance, which Django uses to serve the application. Finally, the server begins listening with serve_forever().

2. Processing Requests

The WSGIHandler class inherits from BaseHandler, which contains much of Django’s request processing logic. One of the key methods is _get_response(request):

def _get_response(self, request):
    """
    Resolve and call the view, then apply view, exception, and
    template_response middleware. This method is everything that
    happens inside the request/response middleware.
    """
    response = None
    callback, callback_args, callback_kwargs = self.resolve_request(request)

    # Apply view middleware
    for middleware_method in self._view_middleware:
        response = middleware_method(request, callback, callback_args, callback_kwargs)
        if response:
            break

    if response is None:
        wrapped_callback = self.make_view_atomic(callback)
        if asyncio.iscoroutinefunction(wrapped_callback):
            wrapped_callback = async_to_sync(wrapped_callback)
        try:
            response = wrapped_callback(request, *callback_args, **callback_kwargs)
        except Exception as e:
            response = self.process_exception_by_middleware(e, request)

    return response

This method resolves which view should handle the request, runs middleware, executes the view, and processes exceptions if needed.

Sources:

An Introduction to Python WSGI Servers: Part 1 WSGI Servers