15 Jan 2023 - tsp
Last update 15 Jan 2023
Disclaimer: My personal opinion is still that Python is not a suitable language for production environment and especially not for web development. When the author has the choice he would choose a more suitable language for the web such as Java with JavaEE or a language such as PHP (The author personally thinks Python is on par with PHP) - or depending on the application Elixir but there are situations where usage of Python might be a good idea - and then it’s still better than C# based stuff and ASP.NET anyways. And it’s always a good idea to know how all of that stuff works - since it’s about the same for every new hyped technology (one will see that WSGI web applications work just like any other CGI application anyways, there is no new black magic except transparent launching of the interpreter and many fancy names for the components implementing it - as usual).
So I’ve came around WSGI (the protocol as well as the module) lately especially in the context of
Flask applications in a cloud environment and since I’ve been using a little bit more Python lately
in work context I thought that most of the tutorial I’ve read had been way to complicated and did not
really fit my view on the whole Internet infrastructure - and I also thought that it simply could not
be that complicated since the network and the whole stack really works the same as in the early 90’th
even today - so when it sounds complicated it’s usually just formulated in a complicate fashion or to
sound fancy - but the principles are still the same and applications on the network also still work the same,
there is no such thing as too quick movement and development even though the tools evolve and the languages
change. So I thought to dive a little bit into the matter (and also configuration of
turned out to be way more versatile than one will imagine after skimming over this blog article - basically
it’s a great tool when one wants to build a cloud like horizontally scaling system - it offers much
flexibility that one will not use for a typical small to medium scale deployment anyways - usually one
could even just don’t use the tool anyways and deliver a micro HTTP server in ones application since the
gain of using an application server is not that large when doing small to medium scale application development
with Python - so I think the value it can provide is really underestimated in many cases).
Note that this blog article has been written from the viewpoint of someone who already developed many web applications in different frameworks and many different languages (but never a larger project in one of the Python frameworks for the web). So it’s of course heavily biased by previous experience and view of the whole infrastructure - it’s of course also affected from a system and network administration point of view as well as influenced by the knowledge of basic inner workings of the whole WWW infrastructure. So it’s not written from the point of view form a beginner for web development …
__call__method, etc.) should be exposed that’s called each and every incoming request
dict) that’s mutable containing the environment variables and some required WSGI variables
start_repsonseand gets passed a callable. It accepts two positional and one optional argument.
statusthat will be returned to the client - like
404 NOT FOUND.
Content-languagethe second argument could be set to the list
[ ('Content-type', 'text/plain'), ('Content-language', 'en') ]
exc_infotuple in case the callable is called out of an error handler. Since the output of previous
start_responsehas been cached it can be replaced with an error response as long as the output buffers had not been flushed.
start_response callable buffers the parameters passed. As mentioned above - as long as output buffering
has not started flushing - an error handler can call it a second time to replace existing buffered data
by an error handlers output - though the author personally would not consider that a clean application design.
In any other case
start_response can be called more often.
As one can see this is pretty much the same thing that
CGI also did.
The API for the Python side of WSGI has been specified in PEP 3333 and is pretty short. In my opinion it’s a good idea to read information about WSGI directly there to get known to the ideas behind this interface even when it looks really familiar to anyone who has ever written a CGI application in any programming language. WSGI is used by nearly every Python web framework such as Flask, Django.
In contrast to more major and more sophisticated specifications such as JavaEE the life cycle of a WSGI
servlet is not specified in any way. This is container specific though most of them will load a module
once and call the callable more than once. This is especially the case for horizontally scaling
cloud infrastructure that spawns server processes on demand. Whenever the application gets replaced
most containers support swapping the loaded module in a graceful way - i.e. processing existing
running requests with the old code while hot reloading new code. There are containers though
that work like legacy CGI without Pre-Forking an loads code on demand though that leads to a
huge overhead with interpreted languages such as Python. Unfortunately most containers do not provide
clean life cycle callbacks so that you cannot launch background tasks or allocate shared resources
whenever the container is loaded (ok you could use
__init__.py for that) and cleanly release
them whenever the container gets evicted or replaced (this is the problem). For some application
uwsgi you are able to write extensions to provide some kind of background tasks - but
then they have to be deployed independent of the application again. This is in my opinion one of
the points where the whole specification needs major improvement before being really usable in
a general sense.
The following environment variables are required to be present (or omitted if they would be empty):
REQUEST_METHODis the HTTP request method (
SCRIPT_NAMEis the path of the web application exluding the domain (or empty for the root). How this is handled depends on the application server configuration. Sometimes this is empty when a single framework script handles all requests to a given virtual host.
PATH_INFOis as usual the path information relative to the script name - or the full path in case a single script handles all requests to a given vhost.
QUERY_STRINGis - as specified in the HTTP specification - everything following the question mark in an URI in an undecoded form.
CONTENT_TYPEmay be empty or absent and contains the
Content-typeheader of the request. This is not to be confused with the
ACCEPTheader of course. This is often used with
PUTor similar requests. See the HTTP specification for details - it works the same as with any other language.
CONTENT_LENGTHis used in conjunction with
SERVER_PORThave to be strings that are always set to the given server name and port.
SERVER_PROTOCLis set to a value such as
HTTP/1.1dependend on the used protocol
HTTP_. For example any
Host:header should be contained in
HTTP_ACCEPTand so on.
In addition the dictionary also contains some other WSGI specific stuff:
wsgi.versionis the version number of the WSGI protocol as a tuple. For example
wsgi.url_schemecontains the URL scheme used - most likely the string
wsgi.inputcontains any client side input stream like POST parameters or uploaded files. Depending on the application container this has to be consumed to prevent errors. This object can be used like a file opened read only by
open- but without any seeking capabilities.
wsgi.errorsallows one to write errors in a well defined way to a text-mode file type output stream. Terminate lines with
\n. This is usualy written into a logfile (like stderr for most containers)
Truewhen the environment is some kind of one-shot launched application where - like for traditional CGI applications - a new processes is launched for each any every web request.
Truewhen multiple threads may call the application object at once in the same process,
wsgi.multiprocessshould evaluate to
Truewhen multiple instances of the same application might exist in multiple processes. The author personally likes to assume this is the case in any case anyway.
The stream objects support
readlines(hint) as well as
for the sources and
writelines(seq) as well as
flush() for the sinks.
Optionally a container might provide a
wsgi.file_wrapper. This can be used to transmit
file like objects from the filesystem using operating system facilities like
There is a number of dedicated WSGI containers that one can use. The most popular one being uwsgi which is basically a simple wrapper around one of the event handling libraries and the language plugin (Python being always present). It also allows for arbitrary plugins that might handle MQTT messages or other stuff.
Other popular containers are:
In addition there are browser plugins that speak the
wsgi protocol such as mod_wsgi
for the Apache httpd web server.
When using an application server one usually does not expose the application server directly to the
outside world - one usually uses a web server, at least a load balancer or any other component that
plays reverse proxy in front of it. Especially for serving statics, terminating SSL connections, etc.
The most common layouts use web servers such as
Apache http in front of the
application servers. Also keep in mind that you usually don’t want to trust the pretty young and
novel implementations of those Python application servers and take the usual precautions of partitioning
your systems to isolate them in your environment as much as possible - but that’s a good practice anyways.
To get started one might use the uswgi application server. This works
pretty fast especially for development and can also be configured for production environments. Note that
this requires a little bit more considerations than mentioned here in the beginning - don’t use
by simply launching your script on any production machine …
Installation is pretty simple and can be done through packages or ports (don’t install via
pkg install www/uwsgi
cd /usr/ports/www/uwsgi make install clean
The latter approach of course allows one to set compile time options -
uwsgi is pretty flexible. Note that
this also installs the
/usr/local/etc/rc.d/uwsgi init script that allows one to launch uswgi
with the standard
/etc/rc.conf environment variables are:
uwsgi_enablethat can be set to
uwsgi_socketfor a WSGI socket (default
/tmp/uwsgi.sock) in combination with
uwsgi_emperorthat switches emperor mode
uwsgi_configfilesupplies an configuration file defaulting to
/usr/local/etc/uwsgi/vassalsthat’s required for cluster configuration
uwsgi_gidto specify owner and group (default
uwsgi_flagsallows specifying additional flags (defaults to
uwsgi_procnamemight allow one to change the used program
uwsgi_profilesallows one to supply a list of loaded uwsgi profiles (optional)
At time of writing the package does not install any sample
ini scripts though.
So let’s start with the most simple hello world WSGI application. This can be written either imperative
or as a class implementation. The most simple way is the imperative structure - but it can be any
import uwsgi def application(env, start_response): start_response( "200 OK", [ ('Content-type', 'text/plain'), ('Content-language', 'en') ] ) return [ b"Hello world!" ]
To launch a simple test version of this script on the local development machine one can directly launch
it using the
--wsgi-file parameter for
$ uwsgi --http :1234 --wsgi-file helloworld.py --need-app
--http :1234 starts the application server listening to requests at
In addition to
http uswgi is also capable of listening on:
--https-socketthat of course requires certificate and key configuration
--fastcgi-socketwhen being just a wrapper for FastCGI calls
Note that the http or https sockets don’t have to be real network sockets - one can also use a Unix domain socket which might be of special interest behind a reverse proxy (that one should use anyways) when one restricts network access of the container itself. This can be done by simply specifying the filename of the Unix domain socket:
$ uwsgi --http /path/to/socket.sock --wsgi-file helloworld.py --need-app
So running from a file is ok for simple demonstration purposes and the most simple applications but this might
not be what one usually has in mind when deploying a Python application. More likely ones application
will be packaged using
setuptools such as any other Python application.
To build the package one requires again a simple
pyproject.toml and a simple
setup.cfg. For demonstration
purposes the author used the following
[build-system] requires = [ "setuptools>=42", "setuptools-git-versioning", "wheel" ] build-backend = "setuptools.build_meta" [tool.setuptools-git-versioning] enabled = true
and the following
[metadata] name = modulewsgihelloworld-tspspi version = 0.0.1 author = Thomas Spielauer author_email = firstname.lastname@example.org description = Just a demonstration hello world project on how to package WSGI applications long_description = file: README.md long_description_content_type = text/markdown url = https://github.com/tspspi/modulewsgihelloworld classifiers = Programming Language :: Python :: 3 License :: OSI Approved :: BSD License Operating System :: OS Independent [options] package_dir = = src packages = find: python_requires = >=3.8 install_requires = matplotlib >= 3.4.1 [options.packages.find] where = src
src/modulewsgihelloworld/helloworld.py the following source has been added:
import uwsgi def mainhello(env, start_response): start_response( "200 OK", [ ('Content-type', 'text/plain'), ('Content-language', 'en') ] ) return [ b"Hello world!" ]
To be a valid module
src/modulewsgihelloworld/__init__.py is existing (but just an empty file)
and to prevent problems when building the package with git versioning (though not releasing
that one on PyPi or course) one can also add a gitignore to
*.egg-info and a gitignore to
dist/.gitignore that ignores and
*.whl. This results in the following directory structure:
|- pyproject.toml |- setup.cfg |- dist | |- .gitignore |- src |- modulewsgihelloworld |- __init__.py |- helloworld.py
Then the module got built (see my previous blog article for details using
$python -m build
After installing the given module (
pip install dist/*.whl) the module can be executed using the module
$ uwsgi --module modulewsgihelloworld.helloworld:mainhello --http :1234 --need-app
When using packages one is now really able to use either one’s own package repository, package files or even PyPi to distribute and upgrade applications using ones build automation system
Above the configuration for
uwsgi has been read from the command line. This is of course inconvenient
especially when one launches it with more elaborate features (uwsgi supports clustering, local synchronized
caches, various life cycle management algorithms, different event loops, filesystem mounting and unmounting
when running a horizontally scalable cloud system; it supports reloading on different external mechanisms,
monitoring via metrics and statistics, multicasting, async mode, lazy loading mode, different clock sources,
static file serving, etc.). Most of the features are especially important when moving to a production
system or writing more complex applications.
Some of the interesting options for a beginner that one should know of are:
--module my.example.module.file:MyHandler()that might also be installed in a virtual environment specified by
--py-autoreloadso one does not have to reload the file every time.
--master --processes NPROCESSES --threads NTHREADS
--enable-threadsbecause GIL else is disabled and threads are not available. Though threads on CPython are not really usable as of today anyways
--gidto drop privileges as soon as possible after binding to sockets.
--daemonizeor after application loading using
All of those options can be set in an
yaml file that’s then passed to
ini this might look like the following:
[uwsgi] http = :1234 https = :1235,mycert.crt,mykey.key chdir = /my/app/directory module = my.example.module.file:MyHandler() virtualenv = /path/to/venv master = true processes = 4 threads = 8
One can then launch
$ uwsgi --ini filename.ini
This article is tagged:
Dipl.-Ing. Thomas Spielauer, Wien (email@example.com)
This webpage is also available via TOR at http://coihcmhmb6cg6bvtelykwlte45yqhxkl6ffdoco5kc3a4qn3uno53oqd.onion/