1.15.1.1 What is a WSGI application?

The WSGI PEP can be quite confusing if all you want to do is write applications quickly and easily. The best way to explain the WSGI is to work through an example demonstrating how an application written as a CGI script has to be modified to work as a WSGI application.

Consider the CGI script code below:

#!/usr/bin/env python
print 'Content-type: text/plain\n\n'
print 'Hello world!'

This does nothing more than print the words 'Hello world!' to a web browser in plain text. What we have done is sent an HTTP header Content-type: text/plain\n\n and then a text string to the browser. The webserver may also have sent a '200 OK' response if the application didn't crash.

To create the same result using a WSGI application we would use this code:

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

WSGI servers are configured to look for an object with a particular name, usually application, and call it, passing the application callable a dictionary named environ containing environmental variables and also a function named start_response which must be called before the application returns a value. Our callable named application is our WSGI application. You could name it differently if your WSGI server had a different naming convention.

You may not be happy with the function start_response being passed as a parameter to our application callable. Whilst this is not possible in some other languages it is perfectly legitimate in Python. This ability to pass callables as function parameters is crucial to understanding how the WSGI works.

Here is an example to consider:

def b(text):
    print text
    
def a(print_response):
    print_response("Hello World!")
    return "It worked!"
    
print a(b)

In this case we are passing the function b to the a as the parameter print_response. We are then printing the value returned from a. What do you think the result will be?

The answer is this:

Hello World!
It worked!

Make sure you understand this example before you read on.

A WSGI application must do two things, these are:

Call the start_response function (passed to our application callable) with the parameters status and headers in the correct order. This will set the status of the application and send the HTTP headers. In our example the status is '200 OK' meaning everything has gone according to plan and we only send one header, the Content-type header with the value text/plain.
Return an iterable containing nothing but strings. In this example the iterable is simply a list containing one string. The return value could equally well have been ['Hello', ' ', 'world!'] but there was no need to make things more complicated.

There are some big advantages in rewriting our code as a WSGI application:

All HTTP headers are sent at the same time before the main content avoiding the possibility of sending HTTP headers at the wrong time.
The application has control over its status. For example if the application encountered an error it could send an '500 Error' status message and the WSGI server would display its appropriate error page.
And most importantly, by using callables in this standard way it is possible to chain together applications called middleware components to provide applications with extra functionality with very little programming effort.