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 createInformer, createListener, createServer and createRemoteServer.

Code author: jwienke

Code author: jmoringe

Functions

convertersFromTransportConfig(transport) Returns an object implementing the rsb.converter.ConverterSelectionStrategy protocol suitable for transport.
createInformer(scope[, config, parent, dataType]) Creates and returns a new Informer for scope.
createListener(scope[, config, parent]) Creates and returns a new Listener for scope.
createLocalServer(scope[, config, parent, …]) Create and return a new LocalServer object that exposes its methods under scope.
createParticipant(cls, scope, config[, parent])
createRemoteServer(scope[, config, parent]) Create a new RemoteServer object for a remote server that provides its methods under scope.
createServer(scope[, config, parent, …]) Like createLocalServer.
getDefaultParticipantConfig() Returns the current default configuration for new objects.
haveSpread() Indicates whether the installation of RSB has spread support.
setDefaultParticipantConfig(config) Replaces the default configuration for new objects.

Classes

Event([id, scope, method, data, type, …]) Basic event class.
EventId(participantId, sequenceNumber) Uniquely identifies an Event by the sending participants ID and a sequence number within this participant.
Hook() A mutable collection of callback functions that can be called together.
Informer(scope, config, dataType[, configurator]) Event-sending part of the communication pattern.
Listener(scope, config[, configurator, …]) Event-receiving part of the communication pattern
MetaData([createTime, sendTime, …]) Objects of this class store RSB-specific and user-supplied meta-data items such as timing information.
Participant(scope, config) Base class for specialized bus participant classes.
ParticipantConfig([transports, options, …]) Objects of this class describe desired configurations for newly
QualityOfServiceSpec([ordering, reliability]) Specification of desired quality of service settings for sending and receiving events.
Scope(stringRep) A scope defines a channel of the hierarchical unified bus covered by RSB.
class rsb.Event(id=None, scope=Scope("/"), method=None, data=None, type=<type 'object'>, metaData=None, userInfos=None, userTimes=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

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

Parameters:
  • id (EventId) – The id of this event
  • scope (Scope or accepted by Scope constructor) – A Scope designating the channel on which the event will be published.
  • method (str) – 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
  • type (types.TypeType) – python data type of the contained data
  • metaData (MetaData) – meta data to use for the new event
  • userInfos (dict of str -> str) – key-value like store of user infos to add to the meta data of this event
  • userTimes (dict of str -> str) – additional timestamps to add to the meta data. dict from string timestamp name to value of timestamp as dobule of seconds unix epoch
  • causes (list) – A list of EventId instances of events which causes the newly constructed events.
addCause(theId)

Adds a causing EventId to the causes of this event.

Parameters:theId (EventId) – id to add
Returns:True if the id was newly added, else False
Return type:bool
getCauses()

Returns all causes of this event.

Returns:causing event ids
Return type:list of EventIds
getData()

Returns the user data of this event.

Returns:user data
getId()

Returns the id of this event.

Returns:id of the event
Return type:int
Raises:RuntimeError – if the event does not have an id so far
getMetaData()
getMethod()

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.
Return type:str
getScope()

Returns the scope of this event.

Returns:scope
Return type:Scope
getSenderId()

Return the sender id of this event.

Deprecated since version 0.13: use getId() instead

Returns:sender id
Return type:uuid.UUID
getSequenceNumber()

Return the sequence number of this event.

Deprecated since version 0.13: use getId() instead

Returns:sequence number of the event.
Return type:int
getType()

Returns the type of the user data of this event.

Returns:user data type
isCause(theId)

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

Parameters:theId (EventId) – id to check
Returns:True if the id is a cause of this event, else False
Return type:bool
removeCause(theId)

Removes a causing EventId from the causes of this event.

Parameters:theId (EventId) – id to remove
Returns:True if the id was remove, else False (because it did not exist)
Return type:bool
setCauses(causes)

Overwrites the cause vector of this event with the given one.

Parameters:causes (list of EventId) – new cause vector
setData(data)

Sets the user data of this event

Parameters:data – user data
setId(theId)
setMetaData(metaData)
setMethod(method)

Sets the method of this event.

Parameters:method (str) – The new method. None is allowed.
setScope(scope)

Sets the scope of this event.

Parameters:scope (Scope) – scope to set
setType(theType)

Sets the type of the user data of this event

Parameters:theType – user data type
causes

Returns all causes of this event.

Returns:causing event ids
Return type:list of EventIds
data

Returns the user data of this event.

Returns:user data
id

Returns the id of this event.

Returns:id of the event
Return type:int
Raises:RuntimeError – if the event does not have an id so far
metaData
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.
Return type:str
scope

Returns the scope of this event.

Returns:scope
Return type:Scope
senderId

Return the sender id of this event.

Deprecated since version 0.13: use getId() instead

Returns:sender id
Return type:uuid.UUID
sequenceNumber

Return the sequence number of this event.

Deprecated since version 0.13: use getId() instead

Returns:sequence number of the event.
Return type:int
type

Returns the type of the user data of this event.

Returns:user data type
class rsb.EventId(participantId, sequenceNumber)

Bases: object

Uniquely identifies an Event by the sending participants ID and a sequence number within this participant. Optional conversion to uuid is possible.

Code author: jwienke

getAsUUID()

Returns a UUID encoded version of this id.

Returns:id of the event as UUID
Return type:uuid.uuid
getParticipantId()

Return the sender id of this id.

Returns:sender id
Return type:uuid.UUID
getSequenceNumber()

Return the sequence number of this id.

Returns:sequence number of the id.
Return type:int
setParticipantId(participantId)

Sets the participant id of this event.

Parameters:participantId (uuid.UUID) – sender id to set.
setSequenceNumber(sequenceNumber)

Sets the sequence number of this id.

Parameters:sequenceNumber (int) – new sequence number of the id.
participantId

Return the sender id of this id.

Returns:sender id
Return type:uuid.UUID
sequenceNumber

Return the sequence number of this id.

Returns:sequence number of the id.
Return type:int
class rsb.Hook

Bases: object

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

Code author: jmoringe

addHandler(handler)
removeHandler(handler)
run(*args, **kwargs)
class rsb.Informer(scope, config, dataType, configurator=None)

Bases: rsb.Participant

Event-sending part of the communication pattern.

Code author: jwienke

Code author: jmoringe

Constructs a new Informer that publishes Events carrying payloads of type type on scope.

Parameters:
  • scope (Scope or accepted by Scope constructor) – scope of the informer
  • config (ParticipantConfig) – The configuration that should be used by this Informer.
  • dataType (types.TypeType) – 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.

See also

createInformer

activate()
deactivate()
getConfig()
getConnectors(direction, config)
getId()
getScope()
getTransportURLs()
getType()

Returns the type of data sent by this informer.

Returns:type of sent data
publishData(data, userInfos=None, userTimes=None)
publishEvent(event)

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

Parameters:event (Event) – the event to send
setId(theId)
setScope(scope)
config
id
scope
transportURLs
type

Returns the type of data sent by this informer.

Returns:type of sent data
class rsb.Listener(scope, config, configurator=None, receivingStrategy=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 (Scope or accepted by Scope constructor) – The scope of the channel in which the new listener should participate.
  • config (ParticipantConfig) – 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.

See also

createListener

activate()
addFilter(theFilter)

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

Parameters:theFilter – filter to add
addHandler(handler, wait=True)

Adds handler to the list of handlers this listener invokes for received 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()
getConfig()
getConnectors(direction, config)
getFilters()

Returns all registered filters of this listener.

Returns:list of filters
getHandlers()

Returns the list of all registered handlers.

Returns:list of handlers to execute on matches
Return type:list of callables accepting an Event
getId()
getScope()
getTransportURLs()
removeHandler(handler, wait=True)

Removes handler from the list of handlers this listener invokes for received events.

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.
setId(theId)
setScope(scope)
config
id
scope
transportURLs
class rsb.MetaData(createTime=None, sendTime=None, receiveTime=None, deliverTime=None, userTimes=None, userInfos=None)

Bases: object

Objects of this class store RSB-specific and user-supplied meta-data items such as timing information.

Code author: jmoringe

Constructs a new MetaData object.

Parameters:
  • createTime – A timestamp designating the time at which the associated event was created.
  • sendTime – A timestamp designating the time at which the associated event was sent onto the bus.
  • receiveTime – A timestamp designating the time at which the associated event was received from the bus.
  • deliverTime – A timestamp designating the time at which the associated event was delivered to the user-level handler by RSB.
  • userTimes (dict of str -> float) – A dictionary of user-supplied timestamps. dict from string name to double value as seconds since unix epoche
  • userInfos (dict of str -> str) – A dictionary of user-supplied meta-data items.
getCreateTime()
getDeliverTime()
getReceiveTime()
getSendTime()
getUserInfos()
getUserTimes()
setCreateTime(createTime=None)
setDeliverTime(deliverTime=None)
setReceiveTime(receiveTime=None)
setSendTime(sendTime=None)
setUserInfo(key, value)
setUserInfos(userInfos)
setUserTime(key, timestamp=None)
setUserTimes(userTimes)
createTime
deliverTime
receiveTime
sendTime
userInfos
userTimes
class rsb.Participant(scope, config)

Bases: object

Base class for specialized bus participant classes. Has a unique id and a scope.

Code author: jmoringe

Constructs a new Participant. This should not be done by clients.

Parameters:
  • scope (Scope or accepted by Scope constructor) – scope of the bus channel.
  • config (ParticipantConfig) – Configuration that the participant should use
activate()
deactivate()

Deactivates a participant by tearing down all connection logic. This needs to be called in case you want to ensure that programs can terminate correctly.

getConfig()
classmethod getConnectors(direction, config)
getId()
getScope()
getTransportURLs()

Returns of list transport URLs describing transport used by the participant.

Returns:Set of transport URLs.
Return type:set
setId(theId)
setScope(scope)
config
id
scope
transportURLs

Returns of list transport URLs describing transport used by the participant.

Returns:Set of transport URLs.
Return type:set
class rsb.ParticipantConfig(transports=None, options=None, qos=None, introspection=False)

Bases: object

Objects of this class describe desired configurations for newly created Participant instances with respect to:

  • 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

Objects of this class describe configurations of transports connectors. These consist of

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

Code author: jmoringe

getConverterRules()
getConverters()
getName()
getOptions()
isEnabled()
setConverterRules(converterRules)
setConverters(converters)
setEnabled(flag)
converterRules
converters
enabled
name
options
classmethod fromDefaultSources(defaults=None)

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

  1. /etc/rsb.conf
  2. $prefix/etc/rsb.conf
  3. ~/.config/rsb.conf
  4. $(PWD)/rsb.conf
  5. Environment Variables
Parameters:defaults (dict of str -> str) – dictionary with default options
Returns:A ParticipantConfig object that contains the merged configuration options from the sources mentioned above.
Return type:ParticipantConfig
classmethod fromDict(options)
classmethod fromEnvironment(defaults=None)

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 (dict of str -> str) – dictionary with default options
Returns:ParticipantConfig object that contains the merged configuration options from defaults and relevant environment variables.
Return type:ParticipantConfig
classmethod fromFile(path, defaults=None)

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 (dict of str -> str) – dictionary with default options
Returns:

A new ParticipantConfig object containing the options read from path.

Return type:

ParticipantConfig

getIntrospection()
getQualityOfServiceSpec()
getTransport(name)
getTransports(includeDisabled=False)
setIntrospection(newValue)
setQualityOfServiceSpec(newValue)
introspection
qualityOfServiceSpec
transports
class rsb.QualityOfServiceSpec(ordering=EnumValue('UNORDERED', 10), reliability=EnumValue('RELIABLE', 20))

Bases: object

Specification of desired quality of service settings for sending and receiving events. 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

Constructs a new QoS specification with desired details. Defaults are unordered but reliable.

Parameters:
  • ordering – desired ordering type
  • reliability – desired reliability type
getOrdering()

Returns the desired ordering settings.

Returns:ordering settings
getReliability()

Returns the desired reliability settings.

Returns:reliability settings
setOrdering(ordering)

Sets the desired ordering settings

Parameters:ordering – ordering to set
setReliability(reliability)

Sets the desired reliability settings

Parameters:reliability – reliability to set
Ordering = Enum(['UNORDERED', 'ORDERED'], [10, 20])
Reliability = Enum(['UNRELIABLE', 'RELIABLE'], [10, 20])
ordering

Returns the desired ordering settings.

Returns:ordering settings
reliability

Returns the desired reliability settings.

Returns:reliability settings
class rsb.Scope(stringRep)

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

Parses a scope from a string representation.

Parameters:stringRep (str or unicode) – string representation of the scope
Raises:ValueError – if stringRep does not have the right syntax
concat(childScope)

Creates 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:childScope (Scope) – child to concatenate to the current scope for forming a sub-scope
Returns:new scope instance representing the created sub-scope
Return type:Scope
classmethod ensureScope(thing)
getComponents()

Returns 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
Return type:list
isSubScopeOf(other)

Tests whether this scope is a sub-scope of the given other scope, which means that the other scope is a prefix of this scope. E.g. “/a/b/” is a sub-scope of “/a/”.

Parameters:other (Scope) – other scope to test
Returns:True if this is a sub-scope of the other scope, equality gives False, too
Return type:Bool
isSuperScopeOf(other)

Inverse operation of isSubScopeOf.

Parameters:other (Scope) – other scope to test
Returns:True if this scope is a strict super scope of the other scope. Equality also gives False.
Return type:Bool
superScopes(includeSelf=False)

Generates 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:includeSelf (Bool) – if set to True, this scope is also included as last element of the returned list
Returns:list of all super scopes ordered by hierarchy, “/” being first
Return type:list of Scopes
toString()

Reconstructs a fully formal string representation of the scope with leading an trailing slashes.

Returns:string representation of the scope
Return type:str
components

Returns 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
Return type:list
rsb.convertersFromTransportConfig(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.converterRules is used.

Returns:The constructed ConverterSelectionStrategy object.
Return type:ConverterSelectionStrategy
rsb.createInformer(scope, config=None, parent=None, dataType=<type 'object'>, **kwargs)

Creates and returns a new Informer for scope.

Parameters:
  • scope (Scope or accepted by Scope constructor) – The scope of the new Informer. Can be a Scope object or a string.
  • config (ParticipantConfig) – The configuration that should be used by this Informer.
  • parent (Participant or NoneType) – None or the Participant which should be considered the parent of the new Informer.
  • dataType (types.TypeType) – A Python object designating the type of objects that will be sent via the new Informer. Instances of subtypes are permitted as well.
Returns:

a new Informer object.

Return type:

Informer

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

Creates and returns a new Listener for scope.

Parameters:
Returns:

a new Listener object.

Return type:

Listener

rsb.createLocalServer(scope, config=None, parent=None, object=None, expose=None, methods=None, **kwargs)

Create and return a new LocalServer object 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 (Scope or accepted by Scope constructor) – The scope under which the newly created server should expose its methods.
  • config (ParticipantConfig) – The configuration that should be used by this server.
  • parent (Participant or NoneType) – None or the Participant which should be considered the parent of the new server.
  • object – 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.
Returns:

A newly created LocalServer object.

Return type:

rsb.patterns.LocalServer

rsb.createParticipant(cls, scope, config, parent=None, **kwargs)
rsb.createRemoteServer(scope, config=None, parent=None, **kwargs)

Create a new RemoteServer object for a remote server that provides its methods under scope.

Parameters:
  • scope (Scope or accepted by Scope constructor) – The scope under which the remote server provides its methods.
  • config (ParticipantConfig) – The transport configuration that should be used for communication performed by this server.
  • parent (Participant or NoneType) – None or the Participant which should be considered the parent of the new server.
Returns:

A newly created RemoteServer object.

Return type:

rsb.patterns.RemoteServer

rsb.createServer(scope, config=None, parent=None, object=None, expose=None, methods=None, **kwargs)

Like createLocalServer.

Deprecated since version 0.12: Use createLocalServer instead.

rsb.getDefaultParticipantConfig()

Returns the current default configuration for new objects.

rsb.haveSpread()

Indicates whether the installation of RSB has spread support.

Returns:True if spread is available, else False
rsb.setDefaultParticipantConfig(config)

Replaces the default configuration for new objects.

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