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:
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:
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 and False` 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 or connectors.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 and False 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 or connectors.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() and replace() methods for documentation about how to define these methods for a multi-input connector.

Parameters:
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 and False` 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 or connectors.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 and False 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 or connectors.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