Web Server Gateway Interface


The Web Server Gateway Interface is a simple calling convention for web servers to forward requests to web applications or frameworks written in the Python programming language. The current version of WSGI, version 1.0.1, is specified in Python Enhancement Proposal 3333.
WSGI was originally specified as PEP-333 in 2003. PEP-3333, published in 2010, updates the specification for Python 3.

Background

In 2003, Python web frameworks were typically written against only CGI, FastCGI, mod_python, or some other custom API of a specific web server. To quote PEP 333:
Python currently boasts a wide variety of web application frameworks, such as Zope, Quixote, Webware, SkunkWeb, PSO, and Twisted Web -- to name just a few. This wide variety of choices can be a problem for new Python users, because generally speaking, their choice of web framework will limit their choice of usable web servers, and vice versa... By contrast, although Java has just as many web application frameworks available, Java's "servlet" API makes it possible for applications written with any Java web application framework to run in any web server that supports the servlet API.

WSGI was thus created as an implementation-agnostic interface between web servers and web applications or frameworks to promote common ground for portable web application development.

Specification overview

The WSGI has two sides:
Between the server and the application, there may be one or more WSGI middleware components, which implement both sides of the API, typically in Python code.
WSGI does not specify how the Python interpreter should be started, nor how the application object should be loaded or configured, and different frameworks and webservers achieve this in different ways.

WSGI middleware

A WSGI middleware component is a Python callable that is itself a WSGI application, but may handle requests by delegating to other WSGI applications. These applications can themselves be WSGI middleware components.
A middleware component can perform such functions as:

Example application

A WSGI-compatible "Hello, World" application written in Python:

def application:
start_response
yield b'Hello, World\n'

Where:
A full example of a WSGI network server is outside the scope of this article. Below is a sketch of how one would call a WSGI application and retrieve its HTTP status line, response headers, and response body, as Python objects. Details of how to construct the environ dict have been omitted.

from io import BytesIO
def call_application:
status = None
headers = None
body = BytesIO

def start_response:
nonlocal status, headers
status, headers = rstatus, rheaders

app_iter = app
try:
for data in app_iter:
assert status is not None and headers is not None, \
"start_response was not called"
body.write
finally:
if hasattr:
app_iter.close
return status, headers, body.getvalue
environ = # "environ" dict
status, headers, body = call_application

WSGI-compatible applications and frameworks

Numerous web frameworks support WSGI:
Currently wrappers are available for FastCGI, CGI, SCGI, AJP, twisted.web, Apache, Nginx, and Microsoft IIS.