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. |
getLoggerByClass (klass) |
Get a python logger instance based on a class instance. |
haveSpread () |
Indicates whether the installation of RSB has spread support. |
setDefaultParticipantConfig (config) |
Replaces the default configuration for new objects. |
Classes
Enum (name, keys[, values]) |
Generates enum-like classes in python with proper printing support. |
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
-
getSenderId
()¶ Return the sender id of this event.
Deprecated since version 0.13: use
getId()
insteadReturns: sender id Return type: uuid.UUID
-
getSequenceNumber
()¶ Return the sequence number of this event.
Deprecated since version 0.13: use
getId()
insteadReturns: 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.
-
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
-
senderId
¶ Return the sender id of this event.
Deprecated since version 0.13: use
getId()
insteadReturns: sender id Return type: uuid.UUID
-
sequenceNumber
¶ Return the sequence number of this event.
Deprecated since version 0.13: use
getId()
insteadReturns: 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
-
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.
-
-
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 publishesEvents
carrying payloads of typetype
onscope
.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
-
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
forscope
.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
-
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
See also
createListener
,createInformer
,createServer
,createRemoteServer
-
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
¶
-
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:/etc/rsb.conf
$prefix/etc/rsb.conf
~/.config/rsb.conf
$(PWD)/rsb.conf
- 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 See also
-
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 fromdefaults
and relevant environment variables.Return type: ParticipantConfig See also
-
classmethod
fromFile
(path, defaults=None)¶ Obtain configuration options from the configuration file
path
, store them in aParticipantConfig
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 frompath
.Return type: See also
-
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
¶
-
Reliability
¶
-
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
– ifstringRep
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 givesFalse
, tooReturn 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 givesFalse
.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 listReturns: 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 fortransport
.If
transport.converters
is notNone
, it is used unmodified. Otherwise the specification intransport.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
forscope
.Parameters: - scope (Scope or accepted by
Scope
constructor) – The scope of the newInformer
. Can be aScope
object or a string. - config (ParticipantConfig) – The configuration that should be used by this
Informer
. - parent (Participant or NoneType) –
None
or theParticipant
which should be considered the parent of the newInformer
. - 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: - scope (Scope or accepted by
-
rsb.
createListener
(scope, config=None, parent=None, **kwargs)¶ Creates and returns a new
Listener
forscope
.Parameters: - scope (Scope or accepted by
Scope
constructor) – the scope of the newListener
. Can be aScope
object or a string. - config (ParticipantConfig) – The configuration that should be used by this
Listener
. - parent (Participant or NoneType) –
None
or theParticipant
which should be considered the parent of the newListener
.
Returns: a new
Listener
object.Return type: - scope (Scope or accepted by
-
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 underscope
.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 theParticipant
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: - scope (Scope or accepted by
-
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 underscope
.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 theParticipant
which should be considered the parent of the new server.
Returns: A newly created
RemoteServer
object.Return type:
-
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.