txwsgi README


txwsgi is a reference asynchronous implementation of Python Web Server Gateway Interface v1.0 for the Twisted Web server.

The project is a fork of twisted.web.wsgi, but unlike the original implementation, the WSGI application is executed inside the main I/0 thread.

This allows a WSGI application to be seamlessly integrated in Twisted.


txwsgi is available on BitBucket.

The project requires at least Python 2.5. It has been tested with Twisted 10.0.0.

The package can be installed using easy_install:

easy_install http://bitbucket.org/mperillo/txwsgi/get/tip.tar.gz

txwsgi is currently not available on PyPI.


The purpose of txwsgi is to have a reference implementation of WSGI for an asynchronous web server, in order to use it to easy experiment with asynchronous extensions to the WSGI specification.

txwsgi was not designed to be used in a production environment, and no test suite has been written.

The main features of this WSGI implementation are:

  • Support for Twisted IPushProducer interface.

    When the WSGI application produces (yielding in the application iterator) more data that can be processed by the HTTP channel, the execution of the application is suspended. In source code this is called implicit suspension.

    An example is available in doc/examples/demo_producer.py.

  • Support of the x-wsgiorg.suspend extension.

    This extension is documented in doc/x-wsgiorg.suspend.rst document, and has been proposed for standardization.

    This extension enables explicit suspension support, for WSGI applications. This complements the required implicit suspension support and enables support to asynchronous WSGI applications. With txwsgi it can be used to freely access Twisted API.

    An example is available in doc/examples/demo_getpage.py.

  • Support for direct configuration of WSGI middlewares stack.

    An example is available in doc/examples/demo_producer.py.

  • write callable is not supported, since it can not be implemented in an asynchronous server.

    However support is available via a custom adapter, available in txwsgi.greenlet.write_adapter. The adapter use greenlet to provide support for write callable on top of a WSGI implementation that implements the x-wsgiorg.suspend extension. write_adapter is not enabled by default since most WSGI applications do not require the write callable.

    An example is available in doc/examples/demo_write.py.

  • Experimental support for WSGI applications using greenlet.

    The support is enabled using a custom adapter, available in txwsgi.greenlet.greenlet_adapter and support API. The adapter allows execution of WSGI applications in a greenlet, on top of a WSGI implementation that implements the x-wsgiorg.suspend extension.

    An example is available in doc/examples/demo_getpage_green.py.

Open Issues

(The following issues are not specific to txwsgi implementation.)

Using of x-wsgiorg.suspend extension can affect performance of a WSGI application, increasing request lifetime and worsening average request completion latency. This can be verified with the doc/examples/demo_cooperative.py example.

The same problem is present for asynchronous WSGI applications. This can be verified with the doc/examples/demo_fdevent.py example.

In order to increase perforances, suspensions should be reduced. A good example is doc/examples/demo_getpage.py. Using Twisted features allow the application to only suspend execution one time. This should be compared with the doc/examples/demo_fdevent.py example.

When using greenlets, there is an additional problem: the greenlet context switch.

To summarize, the WSGI application SHOULD minimize both suspensions and greenlet context switches. In case the WSGI implementation is written in C, or the event API is written in C (see ngx_http_wsgi_module), the application SHOULD also minimize roundtrips between C and Python code.