Documentation for pulsar 0.9.2. For development docs, go here.
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.
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.
An asynchronous application handler must conform with the standard WSGI 1.0.1 specification with the following two exceptions:
Future
.Future
, it must results in an
asynchronous iterable.Pulsar is shipped with two WSGI application handlers documented below.
An asynchronous iterable is an iterable over a combination of bytes
or
Future
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!'
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.
pulsar.apps.wsgi.handlers.
WsgiHandler
(middleware=None, response_middleware=None, **kwargs)[source]¶An handler for application 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.
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 injects two server-defined variables into the WSGI environ:
pulsar.connection
, the Connection
serving the requestpulsar.cfg
, the Config
dictionary of the serverThe event loop serving the application can be retrieved from the connection
via the _loop
attribute:
loop = environ['pulsar.connection']._loop