The Web Server Gateway Interface (WSGI, pronounced ''whiskey'' or ) is a simple
calling convention
In computer science, a calling convention is an implementation-level (low-level) scheme for how subroutines or functions receive parameters from their caller and how they return a result. When some code calls a function, design choices have been ...
for
web server
A web server is computer software and underlying hardware that accepts requests via HTTP (the network protocol created to distribute web content) or its secure variant HTTPS. A user agent, commonly a web browser or web crawler, initiate ...
s to forward requests to
web application
A web application (or web app) is application software that is accessed using a web browser. Web applications are delivered on the World Wide Web to users with an active network connection.
History
In earlier computing models like client-serve ...
s or
framework
A framework is a generic term commonly referring to an essential supporting structure which other things are built on top of.
Framework may refer to:
Computing
* Application framework, used to implement the structure of an application for an op ...
s written in the
Python programming language
Python is a high-level, general-purpose programming language. Its design philosophy emphasizes code readability with the use of significant indentation.
Python is dynamically-typed and garbage-collected. It supports multiple programming p ...
. The current version of WSGI, version 1.0.1, is specified in
Python Enhancement Proposal
Python is a high-level programming language, high-level, general-purpose programming language. Its design philosophy emphasizes code readability with the use of off-side rule, significant indentation.
Python is type_system#DYNAMIC, dynamically- ...
(PEP) 3333.
WSGI was originally specified as PEP-333 in 2003. PEP-3333, published in 2010, updates the specification for .
Background
In 2003, Python
web framework
A web framework (WF) or web application framework (WAF) is a software framework that is designed to support the development of web applications including web services, web resources, and web APIs. Web frameworks provide a standard way to build and ...
s were typically written against only
CGI,
FastCGI
FastCGI is a binary protocol
A communication protocol is a system of rules that allows two or more entities of a communications system to transmit information via any kind of variation of a physical quantity. The protocol defines the rules, s ...
,
mod_python
mod_python is an Apache HTTP Server module that integrates the Python programming language with the server. It is intended to provide a Python language binding for the Apache HTTP Server.
When mod_python released it was one of the more efficient ...
, or some other custom
API
An application programming interface (API) is a way for two or more computer programs to communicate with each other. It is a type of software Interface (computing), interface, offering a service to other pieces of software. A document or standa ...
of a specific
web server
A web server is computer software and underlying hardware that accepts requests via HTTP (the network protocol created to distribute web content) or its secure variant HTTPS. A user agent, commonly a web browser or web crawler, initiate ...
. 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-neutral
interface
Interface or interfacing may refer to:
Academic journals
* ''Interface'' (journal), by the Electrochemical Society
* ''Interface, Journal of Applied Linguistics'', now merged with ''ITL International Journal of Applied Linguistics''
* '' Inte ...
between web servers and web applications or frameworks to promote common ground for
portable
Portable may refer to:
General
* Portable building, a manufactured structure that is built off site and moved in upon completion of site and utility work
* Portable classroom, a temporary building installed on the grounds of a school to provide a ...
web application development.
Specification overview
The WSGI has two sides:
* the
server
Server may refer to:
Computing
*Server (computing), a computer program or a device that provides functionality for other programs or devices, called clients
Role
* Waiting staff, those who work at a restaurant or a bar attending customers and su ...
/gateway side. This is often running full web server software such as
Apache
The Apache () are a group of culturally related Native American tribes in the Southwestern United States, which include the Chiricahua, Jicarilla, Lipan, Mescalero, Mimbreño, Ndendahe (Bedonkohe or Mogollon and Nednhi or Carrizaleño an ...
or
Nginx
Nginx (pronounced "engine x" ) is a web server that can also be used as a reverse proxy, load balancer, mail proxy and HTTP cache. The software was created by Igor Sysoev and publicly released in 2004. Nginx is free and open-source software ...
, or is a lightweight application server that can communicate with a webserver, such a
flup
* 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 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:
* Routing a request to different application objects based on the target
URL
A Uniform Resource Locator (URL), colloquially termed as a web address, is a reference to a web resource that specifies its location on a computer network and a mechanism for retrieving it. A URL is a specific type of Uniform Resource Identifie ...
, after changing the
environment variables
An environment variable is a dynamic-named value that can affect the way running processes will behave on a computer. They are part of the environment in which a process runs. For example, a running process can query the value of the TEMP envi ...
accordingly.
* Allowing multiple applications or frameworks to run side-by-side in the same
process
A process is a series or set of activities that interact to produce a result; it may occur once-only or be recurrent or periodic.
Things called a process include:
Business and management
*Business process, activities that produce a specific se ...
*
Load balancing and remote processing, by forwarding requests and responses over a
network
Network, networking and networked may refer to:
Science and technology
* Network theory, the study of graphs as a representation of relations between discrete objects
* Network science, an academic field that studies complex networks
Mathematics
...
* Performing content post-processing, such as applying
XSLT
XSLT (Extensible Stylesheet Language Transformations) is a language originally designed for transforming XML documents into other XML documents, or other formats such as HTML for web pages, plain text or XSL Formatting Objects, which may subseque ...
stylesheets
Examples
Example application
A WSGI-compatible "
Hello, World!" application written in
Python
Python may refer to:
Snakes
* Pythonidae, a family of nonvenomous snakes found in Africa, Asia, and Australia
** ''Python'' (genus), a genus of Pythonidae found in Africa and Asia
* Python (mythology), a mythical serpent
Computing
* Python (pro ...
:
def application(environ, start_response):
start_response('200 OK', 'Content-Type', 'text/plain')
yield b'Hello, World!\n'
Where:
* Line 1 defines a function named
application
, which takes two parameters,
environ
and
start_response
.
environ
is a dictionary containing
CGI environment variables as well as other request parameters and metadata under well-defined keys.
start_response
is a callable itself, taking two positional parameters,
status
and
response_headers
.
* Line 2 calls
start_response
, specifying "200 OK" as the HTTP status and a "Content-Type" response header.
* Line 3 makes the function into a
generator
Generator may refer to:
* Signal generator, electronic devices that generate repeating or non-repeating electronic signals
* Electric generator, a device that converts mechanical energy to electrical energy.
* Generator (circuit theory), an eleme ...
. The body of the response is returned as an iterable of
byte string
In computer programming, a string is traditionally a sequence of characters, either as a literal constant or as some kind of variable. The latter may allow its elements to be mutated and the length changed, or it may be fixed (after creation). ...
s.
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 the
environ
dict have been omitted.
from io import BytesIO
def call_application(app, environ):
status = None
headers = None
body = BytesIO()
def start_response(rstatus, rheaders):
nonlocal status, headers
status, headers = rstatus, rheaders
app_iter = app(environ, start_response)
try:
for data in app_iter:
assert status is not None and headers is not None, \
"start_response() was not called"
body.write(data)
finally:
if hasattr(app_iter, 'close'):
app_iter.close()
return status, headers, body.getvalue()
environ = # "environ" dict
status, headers, body = call_application(app, environ)
WSGI-compatible applications and frameworks
Numerous
web framework
A web framework (WF) or web application framework (WAF) is a software framework that is designed to support the development of web applications including web services, web resources, and web APIs. Web frameworks provide a standard way to build and ...
s support WSGI:
bjoern*
BlueBream
Zope is a family of free and open-source web application servers written in Python, and their associated online community. Zope stands for "Z Object Publishing Environment", and was the first system using the now common object publishing methodolo ...
* bobo
* Bottle
*
CherryPy
CherryPy is an object-oriented web application framework using the Python programming language. It is designed for rapid development of web applications by wrapping the HTTP protocol but stays at a low level and does not offer much more than what ...
*
Django
*
Eventlet
FastWSGI*
Flask
Flask may refer to:
Container
* Hip flask, a small container used to carry a small amount of liquid
* Laboratory flask, laboratory glassware for holding larger volumes than simple test tubes
** Erlenmeyer flask, a common laboratory flask with a ...
* Falcon (web framework)
*
Gevent-FastCGI
*
Google App Engine
Google App Engine (often referred to as GAE or simply App Engine) is a cloud computing platform as a service for developing and hosting web applications in Google-managed data centers. Applications are sandboxed and run across multiple servers. ...
's webapp2
*
Gunicorn
The Gunicorn "Green Unicorn" (pronounced jee-unicorn or gun-i-corn) is a Python Web Server Gateway Interface (WSGI) HTTP server. It is a pre-fork worker model, ported from Ruby's Unicorn project. The Gunicorn server is broadly compatible with a ...
* prestans
*
mod_wsgi
mod_wsgi is an Apache HTTP Server module by Graham Dumpleton that provides a WSGI compliant interface for hosting Python based web applications under Apache. As of version 4.5.3, mod_wsgi supports Python 2 and 3 (starting from 2.6 and 3.2).
It i ...
for use with
Apache
The Apache () are a group of culturally related Native American tribes in the Southwestern United States, which include the Chiricahua, Jicarilla, Lipan, Mescalero, Mimbreño, Ndendahe (Bedonkohe or Mogollon and Nednhi or Carrizaleño an ...
* netius
* pycnic
*
Paste component WebOb is specifically a WSGI extension. It was adopted by the
Pylons project
Pylons Project is an open-source organization that develops a set of web application technologies written in Python. Initially the project was a single web framework called Pylons, but after the merger with the repoze.bfg framework under the new na ...
.
*
Pylons
Pylon may refer to:
Structures and boundaries
* Pylon (architecture), the gateway to the inner part of an Ancient Egyptian temple or Christian cathedral
* Pylon, a support tower structure for suspension bridges or highways
* Pylon, an orange mar ...
*
Pyramid
A pyramid (from el, πυραμίς ') is a structure whose outer surfaces are triangular and converge to a single step at the top, making the shape roughly a pyramid in the geometric sense. The base of a pyramid can be trilateral, quadrilat ...
* restlite
*
Tornado
A tornado is a violently rotating column of air that is in contact with both the surface of the Earth and a cumulonimbus cloud or, in rare cases, the base of a cumulus cloud. It is often referred to as a twister, whirlwind or cyclone, altho ...
*
Trac
Trac is an open-source software, open-source, web-based Project management software, project management and bug tracking system. It has been adopted by a variety of organizations for use as a bug tracking system for both free and open-source s ...
*
TurboGears
TurboGears is a Python web application framework consisting of several WSGI components such as WebOb, SQLAlchemyKajikitemplate language and Repoze.
TurboGears is designed around the model–view–controller (MVC) architecture, much like Struts ...
*
Uliweb
*
uWSGI
uWSGI is an open source software application that "aims at developing a full stack for building hosting services". It is named after the Web Server Gateway Interface (WSGI), which was the first plugin supported by the project. uWSGI is maintained ...
* Waitress
*
web.py
*
web2py
Web2py is an open-source web application framework written in the Python programming language. Web2py allows web developers to program dynamic web content using Python. Web2py is designed to help reduce tedious web development tasks, such as d ...
* weblayer
* Werkzeug
* Radicale
Currently wrappers are available for
FastCGI
FastCGI is a binary protocol
A communication protocol is a system of rules that allows two or more entities of a communications system to transmit information via any kind of variation of a physical quantity. The protocol defines the rules, s ...
,
CGI,
SCGI
The Simple Common Gateway Interface (SCGI) is a protocol for applications to interface with HTTP servers, as an alternative to the CGI protocol. It is similar to FastCGI but is designed to be easier to parse. Unlike CGI, it permits a long-running ...
,
AJP (using flup),
twisted.web, Apache (using
mod_wsgi
mod_wsgi is an Apache HTTP Server module by Graham Dumpleton that provides a WSGI compliant interface for hosting Python based web applications under Apache. As of version 4.5.3, mod_wsgi supports Python 2 and 3 (starting from 2.6 and 3.2).
It i ...
or
mod_python
mod_python is an Apache HTTP Server module that integrates the Python programming language with the server. It is intended to provide a Python language binding for the Apache HTTP Server.
When mod_python released it was one of the more efficient ...
),
Nginx
Nginx (pronounced "engine x" ) is a web server that can also be used as a reverse proxy, load balancer, mail proxy and HTTP cache. The software was created by Igor Sysoev and publicly released in 2004. Nginx is free and open-source software ...
(using ngx_http_uwsgi_module), and
Microsoft IIS
Internet Information Services (IIS-pronounced 2S, formerly Internet Information Server) is an extensible web server software created by Microsoft for use with the Windows NT family. IIS supports HTTP, HTTP/2, HTTPS, FTP, FTPS, SMTP and NNTP. ...
(using WFastCGI, isapi-wsgi, PyISAPIe,
or an
ASP
Asp may refer to:
Places
* Asp, part of Densbüren, Aargau, Switzerland
* Aspe (''Asp'' in Valencian), Alicante, Spain
* Asp Lake, a lake in Minnesota
Animals
* Asp (fish)
* Asp (snake), in antiquity, one of several venomous snakes
** ''Cera ...
gateway).
See also
*
Asynchronous Server Gateway Interface (ASGI) – The spiritual successor to WSGI, adding support for asynchronous applications
*
Rack
Rack or racks may refer to:
Storage and installation
* Amp rack, short for amplifier rack, a piece of furniture in which amplifiers are mounted
* Bicycle rack, a frame for storing bicycles when not in use
* Bustle rack, a type of storage bin ...
–
Ruby
A ruby is a pinkish red to blood-red colored gemstone, a variety of the mineral corundum ( aluminium oxide). Ruby is one of the most popular traditional jewelry gems and is very durable. Other varieties of gem-quality corundum are called sa ...
web server interface
*
PSGI
Plack is a Perl web application programming framework inspired by Rack for Ruby and WSGI for Python, and it is the project behind the PSGI specification used by other frameworks such as Catalyst and Dancer. Plack allows for testing of Perl web ...
–
Perl
Perl is a family of two high-level, general-purpose, interpreted, dynamic programming languages. "Perl" refers to Perl 5, but from 2000 to 2019 it also referred to its redesigned "sister language", Perl 6, before the latter's name was offici ...
Web Server Gateway Interface
*
SCGI
The Simple Common Gateway Interface (SCGI) is a protocol for applications to interface with HTTP servers, as an alternative to the CGI protocol. It is similar to FastCGI but is designed to be easier to parse. Unlike CGI, it permits a long-running ...
– Simple Common Gateway Interface
*
JSGI
JSGI, or JavaScript Gateway Interface, is an interface (computer science), interface between web servers and JavaScript-based web applications and web framework, frameworks. It was inspired by the Rack (web server interface), Rack for Ruby (progra ...
–
JavaScript
JavaScript (), often abbreviated as JS, is a programming language that is one of the core technologies of the World Wide Web, alongside HTML and CSS. As of 2022, 98% of Website, websites use JavaScript on the Client (computing), client side ...
web server gateway interface
References
External links
PEP 333 – Python Web Server Gateway InterfacePEP 3333 – Python Web Server Gateway Interface v1.0.1WSGI metaframeworkComprehensive wiki about everything WSGIWSGI TutorialGetting Started with WSGINWSGI– .NET implementation of the Python WSGI specification for IronPython and IIS
Gevent-FastCGI server implemented using gevent coroutine-based networking library
{{Web interfaces
Python (programming language)