Web Server Gateway Interface: Difference between revisions

Revision as of 11:05, 14 April 2007

Latest revision as of 20:33, 12 August 2025

(364 intermediate revisions by more than 100 users not shown)

Line 1:

{{short description|Calling convention for web servers to forward requests to web applications written in Python}}

The '''Web Server Gateway Interface''' defines a simple and universal [[interface (computer science)|interface]] between [[web server]]s and [[web application]]s or [[web application framework|framework]]s for the [[Python (programming language)|Python programming language]].

{{redirect|WSGI|the radio station in Springfield, Tennessee|WSGI (AM)}}

{{TOC right}}

==Idea==

The '''Web Server Gateway Interface''' ('''WSGI''', pronounced ''whiskey''<ref>{{cite web |last1=Simionato |first1=Michele |title=An Introduction to Web Programming with WSGI |date=June 11, 2007 |url=http://www.phyast.pitt.edu/~micheles/python/europython07/talk.html}}</ref><ref>{{cite journal |last1=Edge |first1=Jake |title=Mucking about with microframeworks |journal=LWN |date=July 9, 2019 |url=https://lwn.net/Articles/792882/}}</ref> or {{Respell|WIZ|ghee}}<ref>{{Cite web|last=Goldberg|first=Kevin|date=2016-05-09|title=An Introduction to Python WSGI Servers for Performance {{!}} AppDynamics|url=https://www.appdynamics.com/blog/engineering/an-introduction-to-python-wsgi-servers-part-1/|access-date=2020-08-20|website=Application Performance Monitoring Blog {{!}} AppDynamics|language=en-US}}</ref>) is a simple [[calling convention]] for [[web server]]s to forward requests to [[web application]]s or [[web framework|framework]]s written in the [[Python (programming language)|Python programming language]]. The current version of WSGI, version 1.0.1, is specified in [[Python Enhancement Proposal]] (PEP) 3333.<ref name=":0">{{cite web|url=https://www.python.org/dev/peps/pep-3333/|title=PEP 3333 - Python Web Server Gateway Interface v1.0.1|website=Python.org|access-date=2018-04-04}}</ref>

Python boasts a wide variety of web application frameworks. This can be a problem for new Python users because, generally speaking, their choice of web framework will limit their choice of usable [[web server]]s, and vice versa.

WSGI was originally specified as PEP-333 in 2003.<ref>{{Cite web|url=https://www.python.org/dev/peps/pep-0333/|title=PEP 333 -- Python Web Server Gateway Interface v1.0|website=Python.org|language=en|access-date=2018-04-04}}</ref> PEP-3333, published in 2010, updates the specification for {{nowrap|[[Python 3]]}}.

WSGI proposes a simple and universal [[interface (computer science)|interface]] between web servers and web applications or frameworks.

==Background==

In 2003, Python [[web framework]]s were typically written against only [[Common Gateway Interface|CGI]], [[FastCGI]], [[mod_python]], or some other custom [[Application programming interface|API]] of a specific [[web server]].<ref>{{cite web|url=https://www.python.org/cgi-bin/moinmoin/WebProgramming|title=FrontPage - Python Wiki|website=Python.org|access-date=2017-01-27}}</ref> To quote PEP 333:

<blockquote>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.</blockquote>

WSGI was thus created as an implementation-neutral [[interface (computer science)|interface]] between web servers and web applications or frameworks to promote common ground for [[software portability|portable]] web application development.<ref name=":0" />

==Specification overview==

The WSGI has two sides:

The WSGI interface has two sides: the "[[server]]" or "gateway" side, and the "application" or "framework" side. The server side invokes a callable object (usually a [[function (programming)|function]] or a [[method (computer science)|method]]) that is provided by the application side. Additionally WSGI provides [[middleware]]s; a WSGI middleware implements both sides of the API, so that it can be inserted "between" a WSGI server and a WSGI application -- the middleware will act as an application from the server's point of view, and as a server from the application's point of view.

* the [[server (computing)|server]]/gateway side. This is often running full web server software such as [[Apache HTTP Server|Apache]] or [[Nginx]], or is a lightweight application server that can communicate with a webserver, such as [https://www.saddi.com/software/flup/ 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|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.<ref name=":1">{{Cite web|url=https://www.python.org/dev/peps/pep-3333/#middleware-components-that-play-both-sides|title=PEP 3333 -- Python Web Server Gateway Interface v1.0.1|website=Python.org|language=en|access-date=2018-04-04}}</ref>

A "middleware" component can perform such functions as:<ref name=":1" />

* Routing a request to different application objects based on the target [[Uniform Resource Locator|URL]], after changing the [[environment variables]] accordingly.

* Allowing multiple applications or frameworks to run side-by-side in the same [[process (computing)|process]]

* [[Load balancing (computing)|Load balancing]] and remote processing, by forwarding requests and responses over a [[computer network|network]]

* PerformPerforming content postprocessingpost-processing, such as applying [[XSL stylesheetXSLT]]s stylesheets

==Examples==
===Example application===

A WSGI -compatible "[["Hello, World!" program|Hello, World!]]" application written in [[Python (programming language)|Python]]:

<syntaxhighlight lang="python" line="1">

<pre>

def appapplication(environ, start_response):

start_response('"200 OK'", [('"Content-Type'", '"text/plain'")])

returnyield ['b"Hello, World!\n']"

</syntaxhighlight>

</pre>

Where:

==WSGI-compatible applications and frameworks==

* Line 1 defines a function<ref>i.e. "a function, method, class, or an instance with a <code>__call__</code> method"</ref> named <code>application</code>, which takes two parameters, <code>environ</code> and <code>start_response</code>. <code>environ</code> is a dictionary containing [[Common Gateway Interface#Environment variables|CGI environment variables]] as well as other request parameters and metadata under well-defined keys.<ref>{{Cite web|url=https://www.python.org/dev/peps/pep-3333/#environ-variables|title=PEP 3333 -- Python Web Server Gateway Interface v1.0.1|website=Python.org|language=en|access-date=2018-04-04}}</ref> <code>start_response</code> is a callable itself, taking two positional parameters, <code>status</code> and <code>response_headers</code>.

There are numerous [[Web application framework]]s supporting WSGI:

* Line 2 calls <code>start_response</code>, specifying "200 OK" as the HTTP status and a "Content-Type" response header.

* [[CherryPy]]

* Line 3 makes the function into a [[Generator (computer programming)|generator]]. The body of the response is returned as an iterable of [[byte string]]s.

* [[Django (web framework)|Django]]

* [[TurboGears]]

* [[Pylons (web framework)|Pylons]]

* [[web.py]] [http://webpy.org/]

* [[Zope]] (supported in version 3)

===Example of calling an application===

Other web applications:

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.<ref>{{cite web|url=https://www.youtube.com/watch?v=afnDANxsaYo |archive-url=https://ghostarchive.org/varchive/youtube/20211212/afnDANxsaYo| archive-date=2021-12-12 |url-status=live|title=Creating WSGI Middleware - Alan Christopher Thomas - Minted - PythonKC|date=2015-08-28|publisher=[[YouTube]]|access-date=2017-01-27}}{{cbignore}}</ref> Details of how to construct the <code>environ</code> dict have been omitted.

* [[Roundup (issue tracker)]] (since version 1.3)

<syntaxhighlight lang="python3">

from io import BytesIO

Additionally there are two simple publishers:

* [http://www.saddi.com/software/flup/ flup]

* [http://wsgiarea.pocoo.org/colubrid/ Colubrid]

def call_application(app, environ):

==Wrappers==

status = None

The server or gateway invokes the application callable once for each request it receives from an [[HTTP]] client, that is directed at the application.

headers = None

body = BytesIO()

def start_response(rstatus, rheaders):

Currently wrappers are available for [[FastCGI]], [[Common Gateway Interface|CGI]], [[SCGI]], [[Apache JServ Protocol|AJP]] using the flup package.

nonlocal status, headers

status, headers = rstatus, rheaders

app_iter = app(environ, start_response)

A [[mod_python]] gateway is available at: http://projects.amor.org/misc/wiki/ModPythonGateway

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()

A gateway for [[IIS]] + [[Active_Server_Pages|ASP]] is available at: http://projects.amor.org/misc/wiki/ASPGateway

environ = {...} # "environ" dict

==External links==

status, headers, body = call_application(app, environ)

* [http://www.python.org/peps/pep-0333.html PEP 333] defining the interface standard

</syntaxhighlight>

* http://www.pythonpaste.org/ - WSGI metaframework

* http://wsgi.org/ - comprehensive wiki about everything WSGI

==WSGI-compatible applications and frameworks==

[[Category:Python programming language]]

{{example farm|section|date=September 2018}}

Numerous [[web framework]]s support WSGI:

{{div col|colwidth=}}

* [https://github.com/jonashaag/bjoern bjoern]

* [[BlueBream]]

* bobo<ref name="bobo">{{cite web|url=http://bobo.digicool.com |title=プエラリアジェルの効果は? |website=Bobo.digicool.com |access-date=2017-01-27}}</ref>

* Bottle

* [[CherryPy]]

* [[Django (web framework)|Django]]<ref name="djangowsgi">{{cite web|url=http://www.djangoproject.com/weblog/2005/jul/18/local_server/ |title=Django without mod_python, and WSGI support &#124; Weblog &#124; Django |website=Djangoproject.com |date=2005-07-18 |access-date=2017-01-27}}</ref>

* [[Eventlet]]<ref>{{cite web|url=http://eventlet.net/doc/modules/wsgi.html |title=wsgi – WSGI server — Eventlet 0.20.1 documentation |website=Eventlet.net |access-date=2017-01-27}}</ref>

* [https://github.com/jamesroberts/fastwsgi FastWSGI]

* [[Flask (programming)|Flask]]

* Falcon (web framework)<ref>{{cite web|url=https://falconframework.org |title=Falcon - Bare-metal web API framework for Python |access-date=2017-10-22}}</ref>

* [[Gevent-FastCGI]]<ref name="gevent-fastcgi">{{cite web|url=https://pypi.python.org/pypi/gevent-fastcgi |title=gevent-fastcgi 1.0.2.1 : Python Package Index |website=Pypi.python.org |date=2015-12-06 |access-date=2017-01-27}}</ref>

* [[Google App Engine]]'s webapp2

* [[Gunicorn (HTTP server)|Gunicorn]]

* prestans<ref name="prestans">{{cite web|url=https://github.com/prestans/prestans/ |title=anomaly/prestans: A WSGI compliant REST micro-framework |website=GitHub.com |access-date=2017-01-27}}</ref>

* [[mod_wsgi]] for use with [[Apache (web server)|Apache]]<ref>{{cite web|url=http://code.google.com/p/modwsgi/ |title=Google Code Archive - Long-term storage for Google Code Project Hosting |website=Code.google.com |access-date=2017-01-27}}</ref>

* netius

* pycnic<ref name="pycnic">{{cite web|url=http://pycnic.nullism.com |title=Pycnic Framework |website=Pycnic.nullism.com |access-date=2017-01-27}}</ref>

* [[Python Paste|Paste]] component WebOb is specifically a WSGI extension. It was adopted by the [[Pylons project]].

* [[Pylons project|Pylons]]

* [[Pyramid (web framework)|Pyramid]]

* restlite<ref name="restlite">{{cite web|url=https://github.com/theintencity/restlite |title=theintencity/restlite: Light-weight RESTful server tools in Python |website=GitHub.com |access-date=2017-01-27}}</ref>

* Socketify<ref name="Socketify">{{cite web|url=https://github.com/cirospaciari/socketify.py |title=Socketify: Bringing Http/Https and WebSockets High Performance servers for PyPy3 and Python3 |website=GitHub.com |access-date=2025-08-12}}</ref>

* [[Tornado (web server)|Tornado]]

* [[Trac]]

* [[TurboGears]]

* [[Uliweb]]<ref name="Uliweb">{{cite web|url=https://github.com/limodou/uliweb |title=limodou/uliweb: Simple and easy use python web framework |website=GitHub.com |access-date=2017-01-27}}</ref>

* [[uWSGI]]

* Waitress<ref name="waitress">{{cite web|url=https://docs.pylonsproject.org/projects/waitress/en/latest/ |title=waitress documentation |website=docs.pylonsproject.org |access-date=2018-09-26}}</ref>

* [[web.py]]<ref name="web.py">{{cite web|url=http://webpy.org/ |title=Welcome to |website=Web.py |date=2009-09-11 |access-date=2017-01-27}}</ref>

* [[web2py]]

* weblayer<ref name="weblayer">{{cite web|url=http://packages.python.org/weblayer |title=weblayer — weblayer v0.4.3 documentation |website=Packages.python.org |access-date=2017-01-27}}</ref>

* Werkzeug<ref name="Werkzeug">{{cite web|url=http://werkzeug.pocoo.org/ |title=Welcome &#124; Werkzeug (The Python WSGI Utility Library) |website=Werkzeug.pocoo.org |access-date=2017-01-27}}</ref>

* Radicale<ref name="Radicale">{{cite web|url=http://radicale.org/ |title=CalDAV and CardDAV Server - A Simple Calendar and Contact Server |website=Radicale.org |access-date=2017-01-27}}</ref>

{{div col end}}

Currently wrappers are available for [[FastCGI]], [[Common Gateway Interface|CGI]], [[SCGI]], [[Apache JServ Protocol|AJP]] (using flup), [[Twisted (software)|twisted.web]], Apache (using [[mod_wsgi]] or [[mod_python]]), [[Nginx]] (using ngx_http_uwsgi_module),<ref>{{cite web|url=http://nginx.org/en/docs/http/ngx_http_uwsgi_module.html |title=Module ngx_http_uwsgi_module |website=Nginx.org |access-date=2017-01-27}}</ref> [[Nginx#Nginx Unit|Nginx Unit]] (using the Python language module),<ref>{{cite web|url=https://unit.nginx.org/configuration/#python |title=Configuration — NGINX Unit |website=Unit.nginx.org |access-date=2023-05-04}}</ref> and [[Internet Information Services|Microsoft IIS]] (using WFastCGI,<ref>{{cite web|url=https://pytools.codeplex.com/wikipage?title=wfastcgi |title=Python Tools for Visual Studio - Documentation |website=Pytools.codeplex.com |access-date=2017-01-27}}</ref> isapi-wsgi,<ref>{{cite web|url=http://code.google.com/p/isapi-wsgi/ |title=Google Code Archive - Long-term storage for Google Code Project Hosting |website=Code.google.com |access-date=2017-01-27}}</ref> PyISAPIe,<ref>{{cite web|url=https://pyisapie.sourceforge.net/ |title=Python ISAPI Extension for IIS download &#124; SourceForge.net |website=Pyisapie.sourceforge.net |date=2012-04-24 |access-date=2017-01-27}}</ref> or an [[Active Server Pages|ASP]] gateway).

==See also==

* [[Asynchronous Server Gateway Interface| Asynchronous Server Gateway Interface (ASGI)]] – The spiritual successor to WSGI, adding support for asynchronous applications

* [[Rack (web server interface)|Rack]] – [[Ruby (programming language)|Ruby]] web server interface

* [[PSGI]] – [[Perl]] Web Server Gateway Interface

* [[SCGI]] – Simple Common Gateway Interface

* [[JSGI]] – [[JavaScript]] web server gateway interface

==References==

{{Reflist|30em}}

==External links==

* [https://www.python.org/dev/peps/pep-0333/ PEP 333 – Python Web Server Gateway Interface]

* [https://www.python.org/dev/peps/pep-3333/ PEP 3333 – Python Web Server Gateway Interface v1.0.1]

* [http://www.pythonpaste.org/ WSGI metaframework]

* [http://www.wsgi.org/ Comprehensive wiki about everything WSGI]

* [http://wsgi.tutorial.codepoint.net/ WSGI Tutorial]

* [https://docs.python.org/library/wsgiref.html Python standard library module wsgiref]

* [http://lucumr.pocoo.org/2007/5/21/getting-started-with-wsgi/ Getting Started with WSGI]

* [http://nwsgi.codeplex.com/ NWSGI] {{Webarchive|url=https://web.archive.org/web/20131027092821/http://nwsgi.codeplex.com/ |date=2013-10-27 }} – .NET implementation of the Python WSGI specification for IronPython and IIS

* [http://pypi.python.org/pypi/gevent-fastcgi Gevent-FastCGI server implemented using gevent coroutine-based networking library]

{{Python (programming language)}}

{{Web interfaces}}

[[Category:Python (programming language)]]

{{comp-stub}}