Documentation for pulsar 0.9.2. For development docs, go here.
This module implements the main classes for pulsar application framework. The
framework is built on top of pulsar asynchronous engine and allows to
implement servers with very little effort. The main classes here are:
Application
and MultiApp
which, has the name suggests, is
a factory of several Application
running on a single server.
The Configurator
is a mixin used as base class for both
Application
and MultiApp
.
pulsar.apps.
Configurator
(name=None, description=None, epilog=None, version=None, argv=None, parse_console=True, script=None, cfg=None, load_config=True, **params)[source]¶A mixin for configuring and loading a pulsar application server.
Parameters: |
|
---|
name
¶The name is unique if this is an Application
. In this
case it defines the application monitor name as well and can be
access in the arbiter domain via the get_application()
function.
argv
¶Optional list of command line parameters. If not available the
sys.argv
list will be used when parsing the console.
cfg
¶The Config
for this Configurator
.
If set as class attribute it will be replaced during initialisation.
Default: None
.
console_parsed
¶True
if this application parsed the console before starting.
script
¶Full path of the script which starts the application or None
.
Evaluated during initialization via the python_path()
method.
version
¶Version of this Application
root_dir
¶Root directory of this Configurator
.
Evaluated from the script
attribute.
python_path
(script)[source]¶Called during initialisation to obtain the script
name and
to add the script
directory to the python path if not in the
path already.
If script
does not evalueate to True
it is evaluated from
the __main__
import. Returns the real path of the python
script which runs the application.
on_config
(arbiter)[source]¶Callback when configuration is loaded.
This is a chance to do applications specific checks before the concurrent machinery is put into place.
If it returns False
the application will abort.
load_config
()[source]¶Load the application configuration from a file and/or from the command line.
Called during application initialisation. The parameters overriding order is the following:
pulsar.apps.
Application
(callable=None, load_config=True, **params)[source]¶An application interface.
Applications can be of any sorts or forms and the library is shipped with
several battery included examples in the pulsar.apps
module.
These are the most important facts about a pulsar Application
:
Configurator
so that it has all the
functionalities to parse command line arguments and setup the
cfg
placeholder of Setting
.Application
are callable objects accepting
the calling actor as only argument. The callable method should
not be overwritten, instead one should overwrites the application
hooks available.Application
is called for the first time,
a new monitor
is added to the arbiter
,
ready to perform its duties.Parameters: |
|
---|
callable
¶Optional callable serving or configuring your application. If provided, the callable must be picklable, therefore it is either a function or a picklable object.
Default None
__call__
(actor=None)[source]¶Register this application with the (optional) calling actor
.
If an actor
is available (either via the function argument or via
the get_actor()
function) it must be
arbiter
, otherwise this call is no-op.
If no actor is available, it means this application starts
pulsar engine by creating the arbiter
with its
global settings
copied to the arbiter Config
container.
Returns: | the start one time event fired once this application
has fired it. |
---|
stream
¶Actor stream handler.
worker_start
(worker, exc=None)[source]¶Added to the start
worker hook.
worker_stopping
(worker, exc=None)[source]¶Added to the stopping
worker hook.
pulsar.apps.
MultiApp
(name=None, description=None, epilog=None, version=None, argv=None, parse_console=True, script=None, cfg=None, load_config=True, **params)[source]¶A MultiApp
is a tool for creating several Application
and starting them at once.
It makes sure all settings for the
applications created are available in the command line.
Check the server
class in the
taskqueue example for an actual
implementation.
MultiApp
derives from Configurator
and therefore
supports all its configuration utilities,
build()
is the only method which must be implemented by
subclasses.
A minimal example usage:
import pulsar
class Server(pulsar.MultiApp):
def build(self):
yield self.new_app(TaskQueue)
yield self.new_app(WSGIserver, prefix="rpc", callable=..., ...)
yield self.new_app(WSGIserver, prefix="web", callable=..., ...)
build
()[source]¶Virtual method, must be implemented by subclasses and return an
iterable over results obtained from calls to the
new_app()
method.
apps
()[source]¶List of Application
for this MultiApp
.
The list is lazily loaded from the build()
method.
new_app
(App, prefix=None, callable=None, **params)[source]¶Invoke this method in the build()
method as many times
as the number of Application
required by this
MultiApp
.
Parameters: |
|
---|---|
Returns: | a tuple used by the |
pulsar.apps.
get_application
(name)[source]¶Fetch an Application
associated with name
if available.
This function may return an asynchronous component.
The application name is set during initialisation. Check the
Configurator.name
attribute for more information.
The application framework provides a way for adding hooks which are executed every time a new application starts. A hook is registered by:
from pulsar.apps import when_monitor_start
def myhook(monitor):
...
when_monitor_start.append(myhook)
By default, the list of hooks only contains a callback to start the default data store if it needs to.