rsb¶

Contains the high-level user interface of RSB.

This package contains all classes that form the high-level user interface of the RSB python implementation. It is the entry point for most users and only in advanced cases client programs need to use classes from other modules.

In order to create basic objects have a look at the functions create_informer, create_listener, create_local_server and create_remote_server.

Code author: jwienke

Code author: jmoringe

Functions

`converters_from_transport_config`(transport)	Return a converter selection strategy suitable for the given transport.
`create_informer`(scope[, config, parent, …])	Create and returns a new `Informer` for `scope`.
`create_listener`(scope[, config, parent])	Create and returns a new `Listener` for `scope`.
`create_local_server`(scope[, config, parent, …])	Create a new `LocalServer` that exposes its methods under `scope`.
`create_participant`(cls, scope, config[, parent])	Create and returns a new participant of type cls.
`create_reader`(scope[, config, parent])	Create and returns a new `Reader` for `scope`.
`create_remote_server`(scope[, config, parent])	Create a new `RemoteServer` that provides methods under `scope`.
`get_default_participant_config`()	Return the current default configuration for new objects.
`set_default_participant_config`(config)	Replace the default configuration for new objects.

Classes

`Event`([event_id, scope, method, data, …])	Basic event class.
`EventId`(participant_id, sequence_number)	Uniquely identifies an Event.
`Hook`()	A mutable collection of callback functions that can be called together.
`Informer`(scope, config, data_type[, …])	Event-sending part of the communication pattern.
`Listener`(scope, config[, configurator, …])	Event-receiving part of the communication pattern.
`MetaData`([create_time, send_time, …])	Stores RSB-specific and user-supplied meta-data items for an event.
`Participant`(scope, config)	Base class for specialized bus participant classes.
`ParticipantConfig`([transports, options, …])	Describes desired configurations for newly created participants.
`QualityOfServiceSpec`([ordering, reliability])	Specification of desired quality of service settings event transmission.
`Scope`(string_rep)	A scope defines a channel of the hierarchical unified bus covered by RSB.

class rsb.Event(event_id=None, scope=Scope('/'), method=None, data=None, data_type=<class 'object'>, meta_data=None, user_infos=None, user_times=None, causes=None)¶

Bases: object

Basic event class.

Events are often caused by other events, which e.g. means that their contained payload was calculated on the payload of one or more other events.

To express these relations each event contains a set of EventIds that express the direct causes of the event. This means, transitive event causes are not modeled.

Cause handling is inspired by the ideas proposed in: David Luckham, The Power of Events, Addison-Wessley, 2007

Code author: jwienke

Construct a new event with undefined type, root scope and no data.

Parameters

event_id – The id of this event
scope – A Scope designating the channel on which the event will be published.
method – A string designating the “method category” which identifies the role of the event in some communication patters. Examples are "REQUEST" and "REPLY".
data – data contained in this event
data_type – python data type of the contained data
meta_data – meta data to use for the new event
user_infos – key-value like store of user infos to add to the meta data of this event
user_times – additional timestamps to add to the meta data. dict from string timestamp name to value of timestamp as dobule of seconds unix epoch
causes – A list of EventId instances of events which causes the newly constructed events.

Type event_id

EventId

Type scope

Scope or accepted by Scope constructor

Type method

str

Type data_type

types.TypeType

Type meta_data

MetaData

Type user_infos

dict of str -> str

Type user_times

dict of str -> str

Type causes

list

add_cause(the_id)¶

Add a causing EventId to the causes of this event.

Parameters: the_id – id to add
Type the_id: EventId
Returns: True if the id was newly added, else False
Rtype: bool

is_cause(the_id)¶

Check whether an id of an event is marked as a cause for this event.

Parameters: the_id – id to check
Type the_id: EventId
Returns: True if the id is a cause of this event, else False
Rtype: bool

remove_cause(the_id)¶

Remove a causing EventId from the causes of this event.

Parameters: the_id – id to remove
Type the_id: EventId
Returns: True if the id was remove, else False (because it did not exist)
Rtype: bool

property causes¶

Return all causes of this event.

Returns: causing event ids
Rtype: list of EventIds

property data¶

Return the user data of this event.

Returns: user data

property data_type¶

Return the type of the user data of this event.

Returns: user data type

property event_id¶

Return the id of this event.

Returns: id of the event
Rtype: int
Raises RuntimeError: if the event does not have an id so far

property meta_data¶

property method¶

Return the method of this event.

Returns: A string designating the method of this event of None if this event does not have a method.
Rtype: str

property scope¶

Return the scope of this event.

Returns: scope
Rtype: Scope

class rsb.EventId(participant_id, sequence_number)¶

Bases: object

Uniquely identifies an Event.

This is done by the sending participants ID and a sequence number within this participant. Optional conversion to uuid is possible.

Code author: jwienke

get_as_uuid()¶

Return a UUID encoded version of this id.

Returns: id of the event as UUID
Rtype: uuid.uuid

property participant_id¶

Return the sender id of this id.

Returns: sender id
Rtype: uuid.UUID

property sequence_number¶

Return the sequence number of this id.

Returns: sequence number of the id.
Rtype: int

class rsb.Hook¶

Bases: object

A mutable collection of callback functions that can be called together.

Code author: jmoringe

add_handler(handler)¶

remove_handler(handler)¶

run(*args, **kwargs)¶

class rsb.Informer(scope, config, data_type, configurator=None)¶

Bases: rsb.Participant

Event-sending part of the communication pattern.

Code author: jwienke

Code author: jmoringe

Construct a new Informer.

The new instance publishes Events carrying payloads of type type on scope.

Parameters

scope – scope of the informer
config – The configuration that should be used by this Informer.
data_type – A Python object designating the type of objects that will be sent via the new Informer. Instances of subtypes are permitted as well.
configurator – Out route configurator to manage sending of events through out connectors.

Type scope

Scope or accepted by Scope constructor

Type config

ParticipantConfig

Type data_type

types.TypeType

See also

create_informer

activate()¶

deactivate()¶

Deactivate a participant by tearing down all connection logic.

This needs to be called in case you want to ensure that programs can terminate correctly.

classmethod get_connectors(direction, config)¶

publish_data(data, user_infos=None, user_times=None)¶

publish_event(event)¶

Publish a predefined event.

The caller must ensure that the event has the appropriate scope and type according to the Informer’s settings.

Parameters: event – the event to send
Type event: Event

property config¶

property data_type¶

Return the type of data sent by this informer.

Returns: type of sent data

property participant_id¶

property scope¶

property transport_urls¶

Return of list transport URLs for all used transports.

Returns: Set of transport URLs.
Rtype: set

class rsb.Listener(scope, config, configurator=None, receiving_strategy=None)¶

Bases: rsb.Participant

Event-receiving part of the communication pattern.

Code author: jwienke

Code author: jmoringe

Create a new Listener for scope.

Parameters

scope – The scope of the channel in which the new listener should participate.
config – The configuration that should be used by this Listener.
configurator – An in route configurator to manage the receiving of events from in connectors and their filtering and dispatching.

Type scope

Scope or accepted by Scope constructor

Type config

ParticipantConfig

See also

create_listener

activate()¶

add_filter(the_filter)¶

Append a filter to restrict the events received by this listener.

Parameters: the_filter – filter to add

add_handler(handler, wait=True)¶

Add handler to the list of handlers being invoked on new events.

Parameters

handler – Handler to add. callable with one argument, the event.
wait – If set to True, this method will return only after the handler has completely been installed and will receive the next available message. Otherwise it may return earlier.

deactivate()¶

Deactivate a participant by tearing down all connection logic.

This needs to be called in case you want to ensure that programs can terminate correctly.

classmethod get_connectors(direction, config)¶

get_filters()¶

Return all registered filters of this listener.

Returns: list of filters

get_handlers()¶

Return the list of all registered handlers.

Returns: list of handlers to execute on matches
Rtype: list of callables accepting an Event

remove_handler(handler, wait=True)¶

Remove handler from the list of handlers this listener invokes.

Parameters

handler – Handler to remove.
wait – If set to True, this method will return only after the handler has been completely removed from the event processing and will not be called anymore from this listener.

property config¶

property participant_id¶

property scope¶

property transport_urls¶

Return of list transport URLs for all used transports.

Returns: Set of transport URLs.
Rtype: set

class rsb.MetaData(create_time=None, send_time=None, receive_time=None, deliver_time=None, user_times=None, user_infos=None)¶

Bases: object

Stores RSB-specific and user-supplied meta-data items for an event.

Code author: jmoringe

Construct a new MetaData object.

Parameters

create_time – A timestamp designating the time at which the associated event was created.
send_time – A timestamp designating the time at which the associated event was sent onto the bus.
receive_time – A timestamp designating the time at which the associated event was received from the bus.
deliver_time – A timestamp designating the time at which the associated event was delivered to the user-level handler by RSB.
user_times – A dictionary of user-supplied timestamps. dict from string name to double value as seconds since unix epoche
user_infos – A dictionary of user-supplied meta-data items.

Type user_times

dict of str -> float

Type user_infos

dict of str -> str

set_create_time(create_time=None)¶

set_deliver_time(deliver_time=None)¶

set_receive_time(receive_time=None)¶

set_send_time(send_time=None)¶

set_user_info(key, value)¶

set_user_time(key, timestamp=None)¶

property create_time¶

property deliver_time¶

property receive_time¶

property send_time¶

property user_infos¶

property user_times¶

class rsb.Participant(scope, config)¶

Bases: object

Base class for specialized bus participant classes.

Has a unique id and a scope.

Code author: jmoringe

Construct a new Participant.

This should not be done by clients.

Parameters

scope – scope of the bus channel.
config – Configuration that the participant should use

Type scope

Scope or accepted by Scope constructor

Type config

ParticipantConfig

activate()¶

deactivate()¶

Deactivate a participant by tearing down all connection logic.

This needs to be called in case you want to ensure that programs can terminate correctly.

classmethod get_connectors(direction, config)¶

property config¶

property participant_id¶

property scope¶

property transport_urls¶

Return of list transport URLs for all used transports.

Returns: Set of transport URLs.
Rtype: set

class rsb.ParticipantConfig(transports=None, options=None, qos=None, introspection=False)¶

Bases: object

Describes desired configurations for newly created participants.

Configured aspects comprise:

Quality of service settings
Error handling strategies (not currently used)
Employed transport mechanisms
- Their configurations (e.g. port numbers)
- Associated converters
Whether introspection should be enabled for the participant (enabled by default)

Code author: jmoringe

class Transport(name, options=None, converters=None)¶

Bases: object

Describes configurations of transports connectors.

The configured aspects consist of

Transport name
Enabled vs. Disabled
Optional converter selection
Transport-specific options

Code author: jmoringe

property converter_rules¶

property converters¶

property enabled¶

property name¶

property options¶

classmethod from_default_sources(defaults=None)¶

Parse the configuration from a default set of sources.

Obtain configuration options from multiple sources, store them in a ParticipantConfig object and return it. The following sources of configuration information will be consulted:

/etc/rsb.conf

$prefix/etc/rsb.conf

~/.config/rsb.conf

$(PWD)/rsb.conf

Environment Variables

Parameters: defaults – dictionary with default options
Type defaults: dict of str -> str
Returns: A ParticipantConfig object that contains the merged configuration options from the sources mentioned above.
Rtype: ParticipantConfig

See also

fromFile, fromEnvironment

classmethod from_dict(options)¶

classmethod from_environment(defaults=None)¶

Parse the configuration options specified via environment variables.

Obtain configuration options from environment variables, store them in a ParticipantConfig object and return it. Environment variable names are mapped to RSB option names as illustrated in the following example:

RSB_TRANSPORT_SPREAD_PORT -> transport spread port

Parameters: defaults – dictionary with default options
Type defaults: dict of str -> str
Returns: ParticipantConfig object that contains the merged configuration options from defaults and relevant environment variables.
Rtype: ParticipantConfig

See also

fromFile, fromDefaultSources

classmethod from_file(path, defaults=None)¶

Parse the configuration options specified in the provided config file.

Obtain configuration options from the configuration file path, store them in a ParticipantConfig object and return it.

A simple configuration file may look like this:

[transport.spread]
host = azurit # default type is string
port = 5301 # types can be specified in angle brackets
# A comment

Parameters

path – File of path
defaults – dictionary with default options

Type defaults

dict of str -> str

Returns

A new ParticipantConfig object containing the options read from path.

Rtype

ParticipantConfig

See also

fromEnvironment, fromDefaultSources

get_transport(name)¶

property all_transports¶

property enabled_transports¶

property introspection¶

property quality_of_service_spec¶

class rsb.QualityOfServiceSpec(ordering=<Ordering.UNORDERED: 10>, reliability=<Reliability.RELIABLE: 20>)¶

Bases: object

Specification of desired quality of service settings event transmission.

Specification given here are required “at least”. This means concrete connector implementations can provide “better” QoS specs without any notification to the clients. Better is decided by the integer value of the specification enums. Higher values mean better services.

Code author: jwienke

Construct a new QoS specification with desired details.

Defaults are unordered but reliable.

Parameters

ordering – desired ordering type
reliability – desired reliability type

class Ordering¶

Bases: enum.Enum

An enumeration.

ORDERED = 20¶

UNORDERED = 10¶

class Reliability¶

Bases: enum.Enum

An enumeration.

RELIABLE = 20¶

UNRELIABLE = 10¶

property ordering¶

Return the desired ordering settings.

Returns: ordering settings

property reliability¶

Return the desired reliability settings.

Returns: reliability settings

class rsb.Scope(string_rep)¶

Bases: object

A scope defines a channel of the hierarchical unified bus covered by RSB.

It is defined by a surface syntax like "/a/deep/scope".

Code author: jwienke

Parse a scope from a string representation.

Parameters: string_rep – string representation of the scope
Type string_rep: str or unicode
Raises ValueError: if string_rep does not have the right syntax

concat(child_scope)¶

Create a subscope of this one by appending the given other scope.

Create a new scope that is a sub-scope of this one with the subordinated scope described by the given argument. E.g. "/this/is/".concat("/a/test/") results in "/this/is/a/test".

Parameters: child_scope – child to concatenate to the current scope for forming a sub-scope
Type child_scope: Scope
Returns: new scope instance representing the created sub-scope
Rtype: Scope

classmethod ensure_scope(thing)¶

is_sub_scope_of(other)¶

Test whether this scope is a sub-scope of the given other scope.

The result of this method is True if the other scope is a prefix of this scope. E.g. “/a/b/” is a sub-scope of “/a/”.

Parameters: other – other scope to test
Type other: Scope
Returns: True if this is a sub-scope of the other scope, equality gives False, too
Rtype: Bool

is_super_scope_of(other)¶

Check whether this instances is a super scope of the given one.

Inverse operation of is_sub_scope_of.

Parameters: other – other scope to test
Type other: Scope
Returns: True if this scope is a strict super scope of the other scope. Equality also gives False.
Rtype: Bool

super_scopes(include_self=False)¶

Generate all super scopes of this scope including the root scope “/”.

The returned list of scopes is ordered by hierarchy with “/” being the first entry.

Parameters: include_self – if set to True, this scope is also included as last element of the returned list
Type include_self: Bool
Returns: list of all super scopes ordered by hierarchy, “/” being first
Rtype: list of Scopes

to_bytes()¶

Encode the string representation as ASCII-encoded bytes.

Returns: encoded string representation
Rtype: bytes

to_string()¶

Return a formal string representation with leading an trailing slashes.

Returns: string representation of the scope
Rtype: str

property components¶

Return all components of the scope as an ordered list.

Components are the names between the separator character ‘/’. The first entry in the list is the highest level of hierarchy. The scope ‘/’ returns an empty list.

Returns: components of the represented scope as ordered list with highest level as first entry
Rtype: list

rsb.converters_from_transport_config(transport)¶

Return a converter selection strategy suitable for the given transport.

Returns an object implementing the rsb.converter.ConverterSelectionStrategy protocol suitable for transport.

If transport.converters is not None, it is used unmodified. Otherwise the specification in transport.converter_rules is used.

Returns: The constructed ConverterSelectionStrategy object.
Rtype: ConverterSelectionStrategy

rsb.create_informer(scope, config=None, parent=None, data_type=<class 'object'>, **kwargs)¶

Create and returns a new Informer for scope.

Parameters

scope – The scope of the new Informer. Can be a Scope object or a string.
config – The configuration that should be used by this Informer.
parent – None or the Participant which should be considered the parent of the new Informer.
data_type – A Python object designating the type of objects that will be sent via the new Informer. Instances of subtypes are permitted as well.

Type scope

Scope or accepted by Scope constructor

Type config

ParticipantConfig

Type parent

Participant or NoneType

Type data_type

types.TypeType

Returns

a new Informer object.

Rtype

Informer

rsb.create_listener(scope, config=None, parent=None, **kwargs)¶

Create and returns a new Listener for scope.

Parameters

scope – the scope of the new Listener. Can be a Scope object or a string.
config – The configuration that should be used by this Listener.
parent – None or the Participant which should be considered the parent of the new Listener.

Type scope

Scope or accepted by Scope constructor

Type config

ParticipantConfig

Type parent

Participant or NoneType

Returns

a new Listener object.

Rtype

Listener

rsb.create_local_server(scope, config=None, parent=None, provider=None, expose=None, methods=None, **kwargs)¶

Create a new LocalServer that exposes its methods under scope.

The keyword parameters object, expose and methods can be used to associate an initial set of methods with the newly created server object.

Parameters

scope – The scope under which the newly created server should expose its methods.
config – The configuration that should be used by this server.
parent – None or the Participant which should be considered the parent of the new server.
provider – An object the methods of which should be exposed via the newly created server. Has to be supplied in combination with the expose keyword parameter.
expose – A list of names of attributes of object that should be expose as methods of the newly created server. Has to be supplied in combination with the object keyword parameter.
methods –
A list or tuple of lists or tuples of the length four:
- a method name,
- a callable implementing the method,
- a type designating the request type of the method and
- a type designating the reply type of the method.

Type scope

Scope or accepted by Scope constructor

Type config

ParticipantConfig

Type parent

Participant or NoneType

Returns

A newly created LocalServer object.

Rtype

rsb.patterns.LocalServer

rsb.create_participant(cls, scope, config, parent=None, **kwargs)¶

Create and returns a new participant of type cls.

Parameters

cls – The type of participant that should be created. For example Listener.
scope – the scope of the new participant. Can be a Scope object or a string.
config – The configuration that should be used by the new participant.
parent – None or the Participant which should be considered the parent of the new participant.

Type cls

type

Type scope

Scope or accepted by Scope constructor

Type config

ParticipantConfig

Type parent

Participant or NoneType

Returns

A new Participant object of type cls.

Rtype

Participant

rsb.create_reader(scope, config=None, parent=None, **kwargs)¶

Create and returns a new Reader for scope.

Parameters

scope – the scope of the new Reader. Can be a Scope object or a string.
config – The configuration that should be used by this Reader.
parent – None or the Participant which should be considered the parent of the new Reader.

Type scope

Scope or accepted by Scope constructor

Type config

ParticipantConfig

Type parent

Participant or NoneType

Returns

a new Reader object.

Rtype

Reader

rsb.create_remote_server(scope, config=None, parent=None, **kwargs)¶

Create a new RemoteServer that provides methods under scope.

Parameters

scope – The scope under which the remote server provides its methods.
config – The transport configuration that should be used for communication performed by this server.
parent – None or the Participant which should be considered the parent of the new server.

Type scope

Scope or accepted by Scope constructor

Type config

ParticipantConfig

Type parent

Participant or NoneType

Returns

A newly created RemoteServer object.

Rtype

rsb.patterns.RemoteServer

rsb.get_default_participant_config()¶: Return the current default configuration for new objects.

rsb.set_default_participant_config(config)¶

Replace the default configuration for new objects.

Parameters: config – A ParticipantConfig object which contains the new defaults.
Type config: ParticipantConfig

rsb.CONFIG_DEBUG_VARIABLE = 'RSB_CONFIG_DEBUG'¶

rsb.CONFIG_FILES_VARIABLE = 'RSB_CONFIG_FILES'¶

rsb.CONFIG_FILE_KEY_PREFIX = '%prefix'¶

rsb.CONFIG_FILE_KEY_PWD = '%pwd'¶

rsb.CONFIG_FILE_KEY_SYSTEM = '%system'¶

rsb.CONFIG_FILE_KEY_USER = '%user'¶

rsb.DEFAULT_CONFIG_FILES = ['%system', '%prefix', '%user', '%pwd']¶

rsb.participant_creation_hook = <rsb.Hook object>¶

rsb.participant_destruction_hook = <rsb.Hook object>¶