saturnin.component.bundle

Saturnin service bundle controller and executor.

This module provides BundleThreadController and BundleExecutor classes to streamline the process of configuring, starting, and managing a collection of Saturnin services as a single unit (a “bundle”). It acts as a higher-level abstraction, coordinating multiple internal ThreadController instances, one for each service in the bundle.

Classes

class saturnin.component.bundle.ServiceBundleConfig(name: str)

Bases: Config

Service bundle configuration.

Parameters:

name (str) – Conf. section name

agents: ConfigListOption

Agents (services) in bundle

class saturnin.component.bundle.BundleThreadController(*args, **kwargs)

Bases: TracedMixin

Service controller that manages collection of services executed in separate threads.

Parameters:

• parser – ConfigParser instance to be used for bundle configuration.

• manager – ChannelManager to be used. If None, a new one is created.

configure(*, section: str = 'bundle') → None

Configures the service bundle and all its constituent services.

This method loads the main bundle configuration to identify the services it contains. Then, for each service in the bundle, it instantiates and configures an internal ThreadController.

Parameters:

section (str) – The name of the configuration section that defines the service bundle (listing its member services). Defaults to SECTION_BUNDLE.

Return type:

None

join(timeout=None) → None

Wait until all services stop.

Parameters:

timeout – Floating point number specifying a timeout for the operation in seconds (or fractions thereof).

Return type:

None

start(*, timeout: int = 10000) → None

Start all services in bundle.

Parameters:

timeout (int) – Timeout for starting each service. None (infinity), or a floating point number specifying a timeout for the operation in seconds (or fractions thereof) [Default: 10s].

Return type:

None

Important

Services are started in order they are listed in bundle configuration. If any service fails to start, all previously started services are stopped.

Raises:

• ServiceError – On error in communication with service.

• TimeoutError – When service does not start in time.

Parameters:

timeout (int)

Return type:

None

stop(*, timeout: int = 10000) → None

Stop all runing services in bundle. The services are stopped in the reverse order in which they were started.

Parameters:

timeout (int) – Timeout for stopping each service. None (infinity), or a floating point number specifying a timeout for the operation in seconds (or fractions thereof) [Default: 10s].

Raises:

• ServiceError – On error in communication with service.

• TimeoutError – When service does not stop in time.

Return type:

None

config: ConfigParser

ConfigParser with service bundle configuration

mngr: ChannelManager

Channel manager

services: list[ThreadController]

List with ThreadControllers for all service instances in bundle

class saturnin.component.bundle.BundleExecutor

Bases: object

A context manager for executing a bundle of Saturnin services.

This class simplifies the lifecycle management of a BundleThreadController, ensuring proper initialization and cleanup (like ZMQ context termination) when used in a with statement.

configure(cfg_files: list[str], *, section: str = 'bundle') → None

Initializes and configures the internal BundleThreadController.

This involves creating a ChannelManager, instantiating a BundleThreadController, reading configuration files into the controller’s ConfigParser, and then calling the controller’s configure method to set up all services in the bundle.

Parameters:

• cfg_files (list[str]) – A list of paths to configuration files to be read.

• section (str) – The name of the configuration section that defines the service bundle. Defaults to SECTION_BUNDLE.

Return type:

None

run() → list[tuple[str, Outcome, list[str]]]

Runs services in bundle.

Returns:

List with (service_name, outcome, details) tuples.

Return type:

list[tuple[str, Outcome, list[str]]]

Tuple items:

• service_name: Name used for service in bundle configuration.

• outcome: Outcome of service execution.

• details: List of strings with additional outcome information (typically error text)

controller: BundleThreadController

Controller

mngr: ChannelManager

Channel manager