Asynchronous WSGI¶

This section describes the asynchronous WSGI specification used by pulsar. It is a superset of the WSGI 1.0.1 specification for synchronous server/middleware. If an application handler is synchronous, this specification is exactly equivalent to WSGI 1.0.1. Changes with respect WSGI 1.0.1 concern asynchronous responses and nothing else.

Introduction¶

The WSGI interface has two sides: the server or gateway side, and the application or framework side. The server side invokes a callable object, here referred as application handler, that is provided by the application side.

Note

A standard WSGI application handler is always a callable, either a function or a callable object, which accepts two positional arguments: environ and start_response. When called by the server, the application object must return an iterable yielding zero or more bytes.

Application handlers¶

An asynchronous application handler must conform with the standard WSGI 1.0.1 specification with the following two exceptions:

It can return an awaitable object
If it returns an awaitable object, this object must result in an asynchronous iterable.

An awaitable object is an object that can be used in an await expression. Can be a coroutine or an object with an __await__() method (a Future for example). See also PEP 492. Pulsar is shipped with two WSGI application handlers documented below.

Asynchronous Iterable¶

An asynchronous iterable is an iterable over a combination of bytes and/or awaitable objects which result in bytes. For example this could be an asynchronous iterable:

def simple_async():
    yield b'hello'
    c = Future()
    c.set_result(b' ')
    yield c
    yield b'World!'

WsgiHandler¶

The first application handler is the WsgiHandler which is a step above the hello callable in the tutorial. It accepts two iterables, a list of wsgi middleware and an optional list of response middleware.

class pulsar.apps.wsgi.handlers.WsgiHandler(middleware=None, response_middleware=None, async=True)[source]¶

An handler for applications conforming to python WSGI.

middleware¶: List of asynchronous WSGI middleware callables which accept environ and start_response as arguments. The order matter, since the response returned by the callable is the non None value returned by a middleware.

response_middleware¶

List of functions of the form:

def ..(environ, response):
    ...

where response is a WsgiResponse. Pulsar contains some response middlewares.

Lazy Wsgi Handler¶

class pulsar.apps.wsgi.handlers.LazyWsgi[source]¶

A wsgi handler which loads the actual handler the first time it is called.

Subclasses must implement the setup() method. Useful when working in multiprocessing mode when the application handler must be a picklable instance. This handler can rebuild its wsgi handler every time is pickled and un-pickled without causing serialisation issues.

setup(environ=None)[source]¶

The setup function for this LazyWsgi.

Called once only the first time this application handler is invoked. This must be implemented by subclasses and must return a wsgi application handler.

Pulsar Variables¶

Pulsar injects two server-defined variables into the WSGI environ:

pulsar.connection, the Connection serving the request
pulsar.cfg, the Config dictionary of the server

The event loop serving the application can be retrieved from the connection via the _loop attribute:

loop = environ['pulsar.connection']._loop