1.1. Decorators¶
The main feature of the Connectors package are the following decorators.
-
class
connectors.
Output
(caching=True, parallelization=<Parallelization.THREAD: 2>, executor=<connectors._common._executors.ThreadingExecutor object>)¶ A decorator, that marks a method as an output connector. These connections can be used to automatically update a processing chain when a value has changed. The decorated method must not take any arguments.
Parameters: - caching – True, if caching shall be enabled, False otherwise. See
the
OutputConnector
’sset_caching()
method for details - parallelization – a flag from the
connectors.Parallelization
enum. See theOutputConnector
’sset_parallelization()
method for details - executor – an
Executor
instance, that can be created with theconnectors.executor()
function. See theOutputConnector
’sset_executor()
method for details
- caching – True, if caching shall be enabled, False otherwise. See
the
-
class
connectors.
Input
(observers=(), laziness=<Laziness.ON_REQUEST: 1>, parallelization=<Parallelization.SEQUENTIAL: 1>, executor=<connectors._common._executors.ThreadingExecutor object>)¶ A decorator, that marks a method as an input for single connections. These connections can be used to automatically update a processing chain when a value has changed. The decorated method must take exactly one argument.
Parameters: - observers – the names of output methods that are affected by passing a value to this connector. For convenience it is also possible to pass a string here, if only one output connector depends on this input.
- laziness – a flag from the
connectors.Laziness
enum. See theSingleInputConnector
’sset_laziness()
method for details - parallelization – a flag from the
connectors.Parallelization
enum. See theMultiInputConnector
’sset_parallelization()
method for details - executor – an
Executor
instance, that can be created with theconnectors.executor()
function. See theInputConnector
’sset_executor()
method for details
-
announce_condition
(method)¶ A decorator, that can be used as a method of the connector method, to define a condition for the propagation of announcements through the input connector.
The decorated method shall return
True
, if the announcement shall be propagated andFalse`
otherwise. For normal input connectors, it shall not require any arguments, while for multi-input connectors, it must accept the data ID of the connection, through which the announcement was received.Before the values in a processing chain are updated, the value changes are announced to the downstream processors. Only if data is retrieved through an output connector, that has pending announcements, the actual value changes are requested from the upstream processors (lazy execution). If an input connector has defined a condition on the propagation of announcements and this condition evaluates to
False
, the announcements are not forwarded to the downstream processors. This also prevents those processors from requesting updated values from upstream.The usage is described by the following example: if A is the name of the method, that is decorated with
connectors.Input
orconnectors.MultiInput
, the method for the condition has to be decorated with@A.announce_condition
.Param: the method, that defines the condition Returns: the same method
-
notify_condition
(method)¶ A decorator, that can be used as a method of the connector method, to define a condition for notifying the observing output connectors about a value, that has been changed by this connector.
The decorated method shall return
True
, if the notification shall be sent andFalse
otherwise. For normal input connectors, it shall accept the new value as an argument, while for multi-input connectors, it must accept the data ID of the connection, through which the announcement was received and the new value.This condition is checked after the input connector (the setter method) has been executed. If an input connector has defined a condition on the notification of its observing output connectors and this condition evaluates to
False
, the output connectors are sent a cancel notification, that informs them, that the state of the object, to which the connectors belong, has not changed in a relevant way. This prevents the update of values further down the processing chain.The usage is described by the following example: if A is the name of the method, that is decorated with
connectors.Input
orconnectors.MultiInput
, the method for the condition has to be decorated with@A.notify_condition
.Param: the method, that defines the condition Returns: the same method
-
class
connectors.
MultiInput
(observers=(), laziness=<Laziness.ON_REQUEST: 1>, parallelization=<Parallelization.SEQUENTIAL: 1>, executor=<connectors._common._executors.ThreadingExecutor object>)¶ A decorator, that marks a method as an input for multiple connections. These connections can be used to automatically update a processing chain when a value has changed.
The decorated method must take exactly one argument and return a unique id. For every MultiInput-method a remove method has to be provided, which removes a value, that has previously been added.
A replace method can be provided optionally. This method is called, when the value of a connected output has changed, rather than removing the old value and adding the new.
See the
remove()
andreplace()
methods for documentation about how to define these methods for a multi-input connector.Parameters: - observers – the names of output methods that are affected by passing a value to this connector. For convenience it is also possible to pass a string here, if only one output connector depends on this input.
- laziness – a flag from the
connectors.Laziness
enum. See theMultiInputConnector
’sset_laziness()
method for details - parallelization – a flag from the
connectors.Parallelization
enum. See theMultiInputConnector
’sset_parallelization()
method for details - executor – an
Executor
instance, that can be created with theconnectors.executor()
function. See theMultiInputConnector
’sset_executor()
method for details
-
announce_condition
(method)¶ A decorator, that can be used as a method of the connector method, to define a condition for the propagation of announcements through the input connector.
The decorated method shall return
True
, if the announcement shall be propagated andFalse`
otherwise. For normal input connectors, it shall not require any arguments, while for multi-input connectors, it must accept the data ID of the connection, through which the announcement was received.Before the values in a processing chain are updated, the value changes are announced to the downstream processors. Only if data is retrieved through an output connector, that has pending announcements, the actual value changes are requested from the upstream processors (lazy execution). If an input connector has defined a condition on the propagation of announcements and this condition evaluates to
False
, the announcements are not forwarded to the downstream processors. This also prevents those processors from requesting updated values from upstream.The usage is described by the following example: if A is the name of the method, that is decorated with
connectors.Input
orconnectors.MultiInput
, the method for the condition has to be decorated with@A.announce_condition
.Param: the method, that defines the condition Returns: the same method
-
notify_condition
(method)¶ A decorator, that can be used as a method of the connector method, to define a condition for notifying the observing output connectors about a value, that has been changed by this connector.
The decorated method shall return
True
, if the notification shall be sent andFalse
otherwise. For normal input connectors, it shall accept the new value as an argument, while for multi-input connectors, it must accept the data ID of the connection, through which the announcement was received and the new value.This condition is checked after the input connector (the setter method) has been executed. If an input connector has defined a condition on the notification of its observing output connectors and this condition evaluates to
False
, the output connectors are sent a cancel notification, that informs them, that the state of the object, to which the connectors belong, has not changed in a relevant way. This prevents the update of values further down the processing chain.The usage is described by the following example: if A is the name of the method, that is decorated with
connectors.Input
orconnectors.MultiInput
, the method for the condition has to be decorated with@A.notify_condition
.Param: the method, that defines the condition Returns: the same method
-
remove
(method)¶ A method of the decorated method to decorate the remove method, with which data, that has been added through the decorated method can be removed.
A remove method has to take the ID, which has been returned by the multi-input method as a parameter, so it knows which value has to be removed.
The usage is described by the following example: if A is the name of the method, that is decorated with
MultiInput
, the remove method has to be decorated with@A.remove
.Parameters: method – the decorated remove method Returns: a MultiInputAssociateDescriptor, that generates a MultiInputAssociateProxy, which enhances the decorated method with the functionality, that is required for the multi-input connector
-
replace
(method)¶ A method of the decorated method to decorate the replace method, with which data, that has been added through the decorated method, can be replaced with new data without changing the ID under which it is stored.
A replace method has to take the ID, under which the old data is stored, as first parameter and the new data as second parameter. It is strongly recommended, that this method stores the new data under the same ID as the old data. And this method must return the ID, under which the new data is stored.
Also, if no data has been stored under the given ID, yet, the replace method shall simply store the data under the given ID instead of raising an error.
Specifying a replace method is optional. If no method has been decorated to be a replace method, the
MultiInput
connector falls back to removing the old data and adding the updated one, whenever updated data is propagated through its connections.The usage is described by the following example: if A is the name of the method, that is decorated with
MultiInput
, the remove method has to be decorated with@A.replace
.Parameters: method – the decorated replace method Returns: a MultiInputAssociateDescriptor, that generates a MultiInputAssociateProxy, which enhances the decorated method with the functionality, that is required for the multi-input connector