Web Server Gateway Interface

"WSGI" redirects here. For the radio station in Springfield, Tennessee, seeWSGI (AM).

TheWeb Server Gateway Interface(WSGI,pronouncedwhiskeyorWIZ-ghee) is a simplecalling conventionforweb serversto forward requests toweb applicationsorframeworkswritten in thePython programming language.The current version of WSGI, version 1.0.1, is specified inPython Enhancement Proposal(PEP) 3333.

WSGI was originally specified as PEP-333 in 2003.PEP-3333, published in 2010, updates the specification forPython 3.

Background

In 2003, Pythonweb frameworkswere typically written against onlyCGI,FastCGI,mod_ Python,or some other customAPIof a specificweb 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-neutralinterfacebetween web servers and web applications or frameworks to promote common ground forportableweb application development.

Specification overview

The WSGI has two sides:

• theserver/gateway side. This is often running full web server software such asApacheorNginx,or is a lightweight application server that can communicate with a webserver, such asflup.
• the application/framework side. This is a Python callable, supplied by the Python program or framework.

Between the server and the application, there may be one or moreWSGImiddleware 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:

• Routing a request to different application objects based on the targetURL,after changing theenvironment variablesaccordingly.
• Allowing multiple applications or frameworks to run side-by-side in the sameprocess
• Load balancingand remote processing, by forwarding requests and responses over anetwork
• Performing content post-processing, such as applyingXSLTstylesheets

Examples

Example application

A WSGI-compatible "Hello, World!"application written inPython:

defapplication(environ,start_response):
start_response('200 OK',[('Content-Type','text/plain')])
yieldb'Hello, World!\n'

Where:

• Line 1 defines a functionnamedapplication,which takes two parameters,environandstart_response.environis a dictionary containingCGI environment variablesas well as other request parameters and metadata under well-defined keys.start_responseis a callable itself, taking two positional parameters,statusandresponse_headers.
• Line 2 callsstart_response,specifying "200 OK" as the HTTP status and a "Content-Type" response header.
• Line 3 makes the function into agenerator.The body of the response is returned as an iterable ofbyte strings.

Example of calling an application

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 theenvirondict have been omitted.

fromioimportBytesIO

defcall_application(app,environ):
status=None
headers=None
body=BytesIO()

defstart_response(rstatus,rheaders):
nonlocalstatus,headers
status,headers=rstatus,rheaders

app_iter=app(environ,start_response)
try:
fordatainapp_iter:
assertstatusisnotNoneandheadersisnotNone,\
"start_response() was not called"
body.write(data)
finally:
ifhasattr(app_iter,'close'):
app_iter.close()
returnstatus,headers,body.getvalue()

environ={...}# "environ" dict
status,headers,body=call_application(app,environ)

WSGI-compatible applications and frameworks

Numerousweb frameworkssupport WSGI:

• bjoern
• BlueBream
• bobo
• Bottle
• CherryPy
• Django
• Eventlet
• FastWSGI
• Flask
• Falcon (web framework)
• Gevent-FastCGI
• Google App Engine's webapp2
• Gunicorn
• prestans
• mod_wsgifor use withApache
• netius
• pycnic
• Pastecomponent WebOb is specifically a WSGI extension. It was adopted by thePylons project.
• Pylons
• Pyramid
• restlite
• Tornado
• Trac
• TurboGears
• Uliweb
• uWSGI
• Waitress
• web.py
• web2py
• weblayer
• Werkzeug
• Radicale

Currently wrappers are available forFastCGI,CGI,SCGI,AJP(using flup),twisted.web,Apache (usingmod_wsgiormod_ Python),Nginx(using ngx_http_uwsgi_module),Nginx Unit(using the Python language module),andMicrosoft IIS(using WFastCGI,isapi-wsgi,PyISAPIe,or anASPgateway).

See also

• Asynchronous Server Gateway Interface (ASGI)– The spiritual successor to WSGI, adding support for asynchronous applications
• Rack–Rubyweb server interface
• PSGI–PerlWeb Server Gateway Interface
• SCGI– Simple Common Gateway Interface
• JSGI–JavaScriptweb server gateway interface

External links

• PEP 333 – Python Web Server Gateway Interface
• PEP 3333 – Python Web Server Gateway Interface v1.0.1
• WSGI metaframework
• Comprehensive wiki about everything WSGI
• WSGI Tutorial
• Python standard library module wsgiref
• Getting Started with WSGI
• NWSGI–.NET implementation of the Python WSGI specification for IronPython and IIS
• Gevent-FastCGI server implemented using gevent coroutine-based networking library