pip_services3_commons.run package

Submodules

• pip_services3_commons.run.Cleaner module
  • pip_services3_commons.run.Cleaner
• pip_services3_commons.run.Closer module
  • pip_services3_commons.run.Closer
• pip_services3_commons.run.Executor module
  • pip_services3_commons.run.Executor
• pip_services3_commons.run.FixedRateTimer module
  • pip_services3_commons.run.FixedRateTimer
• pip_services3_commons.run.ICleanable module
  • pip_services3_commons.run.ICleanable
• pip_services3_commons.run.IClosable module
  • pip_services3_commons.run.IClosable
• pip_services3_commons.run.IExecutable module
  • pip_services3_commons.run.IExecutable
• pip_services3_commons.run.INotifiable module
  • pip_services3_commons.run.INotifiable
• pip_services3_commons.run.IOpenable module
  • pip_services3_commons.run.IOpenable
• pip_services3_commons.run.IParameterized module
  • pip_services3_commons.run.IParameterized
• pip_services3_commons.run.Notifier module
  • pip_services3_commons.run.Notifier
• pip_services3_commons.run.Opener module
  • pip_services3_commons.run.Opener
• pip_services3_commons.run.Parameters module
  • pip_services3_commons.run.Parameters

Module contents

pip_services3_commons.run.__init__

Contains design patterns for the standard lifecycle of objects (opened, closed, openable, closable, runnable). Helper classes for lifecycle provisioning.

copyright

Conceptual Vision Consulting LLC 2018-2019, see AUTHORS for more details.

license

MIT, see LICENSE for more details.

class pip_services3_commons.run.Cleaner

Bases: object

Helper class that cleans stored object state.

static clear(correlation_id: Optional[str, None], components: List[Any])

Clears state of multiple components.

To be cleaned state components must implement ICleanable interface. If they don’t the call to this method has no effect.

Parameters

• correlation_id – (optional) transaction id to trace execution through call chain.

• components – the list of components that are to be cleaned.

static clear_one(correlation_id: Optional[str, None], component: Any)

Clears state of specific component.

To be cleaned state components must implement ICleanable interface. If they don’t the call to this method has no effect.

Parameters

• correlation_id – (optional) transaction id to trace execution through call chain.

• component – the component that is to be cleaned.

class pip_services3_commons.run.Closer

Bases: object

Helper class that closes previously opened components.

static close(correlation_id: Optional[str, None], components: List[Any])

Closes multiple components.

To be closed components must implement IClosable interface. If they don’t the call to this method has no effect.

Parameters

• correlation_id – (optional) transaction id to trace execution through call chain.

• components – the list of components that are to be closed.

static close_one(correlation_id: Optional[str, None], component: Any)

Closes specific component.

To be closed components must implement IClosable interface. If they don’t the call to this method has no effect.

Parameters

• correlation_id – (optional) transaction id to trace execution through call chain.

• component – the component that is to be closed.

class pip_services3_commons.run.Executor

Bases: object

Helper class that executes components.

static execute(correlation_id: Optional[str, None], components: List[Any], args: pip_services3_commons.run.Parameters.Parameters = None)

Executes multiple components.

To be executed components must implement IExecutable interface. If they don’t the call to this method has no effect.

Parameters

• correlation_id – (optional) transaction id to trace execution through call chain.

• components – a list of components that are to be executed.

• args – execution arguments.

Returns

execution result

static execute_one(correlation_id: Optional[str, None], component: Any, args: pip_services3_commons.run.Parameters.Parameters)

Executes specific component. To be executed components must implement IExecutable interface. If they don’t the call to this method has no effect.

Parameters

• correlation_id – (optional) transaction id to trace execution through call chain.

• component – the component that is to be executed.

• args – execution arguments.

Returns

execution result

class pip_services3_commons.run.FixedRateTimer(task_or_object: Any = None, interval: int = None, delay: int = None)

Bases: pip_services3_commons.run.IClosable.IClosable

Timer that is triggered in equal time intervals.

It has summetric cross-language implementation and is often used by Pip.Services toolkit to perform periodic processing and cleanup in microservices.

close(correlation_id: Optional[str, None])

Closes the timer. This is __required by IClosable interface, but besides that it is identical to stop().

Parameters

correlation_id – (optional) transaction id to trace execution through call chain.

get_callback() → Callable

Gets the callback function that is called when this timer is triggered.

Returns

the callback function or null if it is not set.

get_delay() → int

Gets initial delay before the timer is triggered for the first time.

Returns

the delay in milliseconds.

get_interval() → int

Gets periodic timer triggering interval.

Returns

the interval in milliseconds

get_task() → <module ‘pip_services3_commons.run.INotifiable’ from ‘/pip_services3_commons/run/INotifiable.py’>

Gets the INotifiable object that receives notifications from this timer.

Returns

the INotifiable object or null if it is not set.

is_started() → bool

Checks if the timer is started.

Returns

true if the timer is started and false if it is stopped.

set_callback(value: Callable)

Sets the callback function that is called when this timer is triggered.

Parameters

value – the callback function to be called.

set_delay(value: int)

Sets initial delay before the timer is triggered for the first time. :param value: a delay in milliseconds.

set_interval(value: int)

Sets periodic timer triggering interval.

Parameters

value – an interval in milliseconds.

set_task(value: <module 'pip_services3_commons.run.INotifiable' from '/pip_services3_commons/run/INotifiable.py'>)

start()

Starts the timer. Initially the timer is triggered after __delay. After that it is triggered after __interval until it is stopped.

stop()

Stops the timer.

class pip_services3_commons.run.ICleanable

Bases: abc.ABC

Interface for components that should clean their state. Cleaning state most often is used during testing. But there may be situations when it can be done in production.

clear(correlation_id: Optional[str, None])

Clears component state.

Parameters

correlation_id – (optional) transaction id to trace execution through call chain.

class pip_services3_commons.run.IClosable

Bases: abc.ABC

Interface for components that require explicit closure.

For components that require opening as well as closing use IOpenable interface instead.

close(correlation_id: Optional[str, None])

Closes component and frees used resources.

Parameters

correlation_id – (optional) transaction id to trace execution through call chain.

class pip_services3_commons.run.IExecutable

Bases: abc.ABC

Interface for components that can be called to execute work.

execute(correlation_id: Optional[str, None], args: <module 'pip_services3_commons.run.Parameters' from '/pip_services3_commons/run/Parameters.py'>)

Executes component with arguments and receives execution result.

Parameters

• correlation_id – (optional) transaction id to trace execution through call chain.

• args – execution arguments.

Returns

execution result

class pip_services3_commons.run.INotifiable

Bases: abc.ABC

Interface for components that can be asynchronously notified. The notification may include optional argument that describe the occured event_name

notify(correlation_id: Optional[str, None], args: <module 'pip_services3_commons.run.Parameters' from '/pip_services3_commons/run/Parameters.py'>)

Notifies the component about occured event_name.

Parameters

• correlation_id – (optional) transaction id to trace execution through call chain.

• args – notification arguments.

class pip_services3_commons.run.IOpenable

Bases: pip_services3_commons.run.IClosable.IClosable

Interface for components that require explicit opening and closing. For components that perform opening on demand consider using IClosable interface instead.

is_open() → bool

Checks if the component is opened.

Returns

true if the component has been opened and false otherwise.

open(correlation_id: Optional[str, None])

Opens the component.

Parameters

correlation_id – (optional) transaction id to trace execution through call chain.

class pip_services3_commons.run.IParameterized

Bases: abc.ABC

Interface for components that require execution parameters.

set_parameters(parameters: <module 'pip_services3_commons.run.Parameters' from '/pip_services3_commons/run/Parameters.py'>)

Sets execution parameters.

Parameters

parameters – execution parameters.

class pip_services3_commons.run.Notifier

Bases: object

Helper class that notifies components.

static notify(correlation_id: Optional[str, None], components: List[Any], args: pip_services3_commons.run.Parameters.Parameters = None)

Notifies multiple components.

To be notified components must implement INotifiable interface. If they don’t the call to this method has no effect.

Parameters

• correlation_id – (optional) transaction id to trace execution through call chain.

• components – a list of components that are to be notified.

• args – notification arguments.

static notify_one(correlation_id: Optional[str, None], component: Any, args: pip_services3_commons.run.Parameters.Parameters)

Notifies specific component. To be notiied components must implement INotifiable interface. If they don’t the call to this method has no effect.

Parameters

• correlation_id – (optional) transaction id to trace execution through call chain.

• component – the component that is to be notified.

• args – notifiation arguments.

class pip_services3_commons.run.Opener

Bases: object

Helper class that opens components.

static is_opened(components: List[Any]) → bool

Checks if all components are opened.

To be checked components must implement IOpenable interface. If they don’t the call to this method returns true.

Parameters

components – a list of components that are to be checked.

Returns

true if all components are opened and false if at least one component is closed.

static is_opened_one(component: Any) → bool

Checks if specified component is opened.

To be checked components must implement IOpenable interface. If they don’t the call to this method returns true.

Parameters

component – the component that is to be checked.

Returns

true if component is opened and false otherwise.

static open(correlation_id: Optional[str, None], components: List[Any])

Opens multiple components.

To be opened components must implement IOpenable interface. If they don’t the call to this method has no effect.

Parameters

• correlation_id – (optional) transaction id to trace execution through call chain.

• components – the list of components that are to be closed.

static open_one(correlation_id: Optional[str, None], component: Any)

Opens specific component.

To be opened components must implement IOpenable interface. If they don’t the call to this method has no effect.

Parameters

• correlation_id – (optional) transaction id to trace execution through call chain.

• component – the component that is to be opened.

class pip_services3_commons.run.Parameters(map: Any = None)

Bases: pip_services3_commons.data.AnyValueMap.AnyValueMap

Contains map with execution parameters.

In general, this map may contain non-serializable values. And in contrast with obj maps, its getters and setters support dot notation and able to access properties in the entire object graph.

This class is often use to pass execution and notification arguments, and parameterize classes before execution.

assign_to(value: Any)

Assigns (copies over) properties from the specified args to this map.

Parameters

value – args whose properties shall be copied over.

contains_key(key: str) → bool

Checks if this map contains an element with specified key.

The key can be defined using dot notation and allows to recursively access elements of elements.

Parameters

key – a key to be checked

Returns

true if this map contains the key or false otherwise.

static from_config(config: pip_services3_commons.config.ConfigParams.ConfigParams) → pip_services3_commons.run.Parameters.Parameters

Creates new Parameters from ConfigMap object.

Parameters

config – a ConfigParams that contain parameters.

Returns

a new Parameters object.

static from_json(json: str) → pip_services3_commons.run.Parameters.Parameters

Creates new Parameters from JSON object.

Parameters

json – a JSON string containing parameters.

Returns

a new Parameters object.

static from_tuples(*tuples: Any) → pip_services3_commons.run.Parameters.Parameters

Creates a new Parameters object filled with provided key-args pairs called tuples. Tuples parameters contain a sequence of key1, value1, key2, value2, … pairs.

Parameters

tuples – the tuples to fill a new Parameters object.

Returns

a new Parameters object.

static from_value(value: Any) → pip_services3_commons.run.Parameters.Parameters

Creates a new Parameters object filled with key-args pairs from specified object.

Parameters

value – an object with key-args pairs used to initialize a new Parameters.

Returns

a new Parameters object.

get(key: str) → Any

Gets a map element specified by its key.

The key can be defined using dot notation and allows to recursively access elements of elements.

Parameters

key – a key of the element to get.

Returns

the args of the map element.

get_as_nullable_parameters(key: str) → pip_services3_commons.run.Parameters.Parameters

Converts map element into an Parameters or returns null if conversion is not possible.

Parameters

key – a key of element to get.

Returns

Parameters args of the element or null if conversion is not supported.

get_as_parameters(key: str) → pip_services3_commons.run.Parameters.Parameters

Converts map element into an Parameters or returns empty Parameters if conversion is not possible.

Parameters

key – a key of element to get.

Returns

Parameters args of the element or empty Parameters if conversion is not supported.

get_as_parameters_with_default(key: str, default_value: pip_services3_commons.run.Parameters.Parameters) → pip_services3_commons.run.Parameters.Parameters

Converts map element into an Parameters or returns default args if conversion is not possible.

Parameters

• key – a key of element to get.

• default_value – the default args

Returns

Parameters args of the element or default args if conversion is not supported.

static merge_params(*parameters: pip_services3_commons.run.Parameters.Parameters) → pip_services3_commons.run.Parameters.Parameters

Merges two or more Parameters into one. The following Parameters override previously defined parameters.

Parameters

parameters – a list of Parameters objects to be merged.

Returns

a new Parameters object.

omit(*props: str) → pip_services3_commons.run.Parameters.Parameters

Omits selected parameters from this Parameters and returns the rest as a new Parameters object.

Parameters

props – keys to be omitted from copying over to new Parameters.

Returns

a new Parameters object.

override(parameters: pip_services3_commons.run.Parameters.Parameters, recursive: bool = False) → pip_services3_commons.run.Parameters.Parameters

Overrides parameters with new values from specified Parameters and returns a new Parameters object.

Parameters

• parameters – Parameters with parameters to override the current values.

• recursive – (optional) true to perform deep copy, and false for shallow copy. Default: false

Returns

a new Parameters object.

pick(*props: str) → pip_services3_commons.run.Parameters.Parameters

Picks select parameters from this Parameters and returns them as a new Parameters object.

Parameters

props – keys to be picked and copied over to new Parameters.

Returns

a new Parameters object.

put(key: str, value: Any) → Any

Puts a new args into map element specified by its key.

The key can be defined using dot notation and allows to recursively access elements of elements.

Parameters

• key – a key of the element to put.

• value – a new args for map element.

set_defaults(default_values: pip_services3_commons.run.Parameters.Parameters, recursive: bool = False) → pip_services3_commons.run.Parameters.Parameters

Set default values from specified Parameters and returns a new Parameters object.

Parameters

• default_values – Parameters with default parameter values.

• recursive – (optional) true to perform deep copy, and false for shallow copy. Default: false

Returns

a new Parameters object.

to_json() → str

Converts this map to JSON object.

Returns

a JSON representation of this map.