Application API¶

Configurator¶

class pulsar.apps.Configurator(name=None, description=None, epilog=None, version=None, argv=None, parse_console=True, script=None, cfg=None, **params)[source]¶

A mixin for configuring and loading a pulsar application server.

Parameters:

name – to override the class name attribute. description – to override the class cfg.description attribute. epilog – to override the class cfg.epilog attribute. version – Optional version of this application, it overrides the class cfg.version attribute. argv – Optional list of command line parameters to parse, if not supplied the sys.argv list will be used. The parameter is only relevant if parse_console is True. parse_console – True (default) if the console parameters needs parsing. script – Optional string which set the script attribute. params – a dictionary of configuration parameters which overrides the defaults and the cfg class attribute. They will be overwritten by a config file or command line arguments.

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.

classmethod create_config(params, prefix=None, name=None)[source]¶

Create a new Config container.

Invoked during initialisation, it overrides defaults with params and apply the prefix to non global settings.

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:

• default parameters.
• the key-valued params passed in the initialisation.
• the parameters in the optional configuration file
• the parameters passed in the command line.

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.

python_path(script)[source]¶

Called during initialisation to obtain the script name.

If script does not evaluate to True it is evaluated from the __main__ import. Returns the real path of the python script which runs the application.

root_dir¶

Root directory of this Configurator.

Evaluated from the script attribute.

start(exit=True)[source]¶

Invoked the application callable method and start the arbiter if it wasn’t already started.

It returns a Future called back once the application/applications are running. It returns None if called more than once.

version¶

Version of this Application

Application¶

class 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:

• It derives from Configurator so that it has all the functionalities to parse command line arguments and setup the cfg placeholder of Setting.
• Instances of an 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.
• When an Application is called for the first time, a new monitor is added to the arbiter, ready to perform its duties.

Parameters:	callable – Initialise the callable attribute. load_config – If False the load_config() method is not invoked. Default True. params – Passed to the Configurator initialiser.

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.

actorparams(monitor, params=None)[source]¶

Hook to add additional entries when the monitor spawn new actors.

monitor_info(monitor, info)[source]¶

Hook to add additional entries to the monitor info dictionary.

monitor_start(monitor)[source]¶

Callback by the monitor when starting.

monitor_stopping(monitor)[source]¶

Callback by the monitor before stopping.

monitor_task(monitor)[source]¶

Executed by the Monitor serving this application at each event loop.

stop(actor=None)[source]¶

Stop the application

stream¶

Actor stream handler.

worker_info(worker, info)[source]¶

Hook to add additional entries to the worker info dictionary.

worker_start(worker, exc=None)[source]¶

Added to the start worker hook.

worker_stopping(worker, exc=None)[source]¶

Added to the stopping worker hook.

Multi App¶

class pulsar.apps.MultiApp(name=None, description=None, epilog=None, version=None, argv=None, parse_console=True, script=None, cfg=None, **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.

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, "rpc", callable=..., ...)
        yield self.new_app(WSGIserver, "web", callable=..., ...)

apps()[source]¶

List of Application for this MultiApp.

The list is lazily loaded from the build() method.

build()[source]¶

Virtual method, must be implemented by subclasses and return an iterable over results obtained from calls to the new_app() 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:

App – an Application class. prefix – The prefix to use for the application, the prefix is appended to the application config parameters and to the application name. Each call to this method must use a different value of for this parameter. It can be None. callable – optional callable (function of object) used during initialisation of App (the Application.callable). params – additional key-valued parameters used when creating an instance of App.

Returns:

a tuple used by the apps() method.

Get application¶

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.

When monitor start¶

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.