saturnin.component.single

Simplified controller and executor for running a single Saturnin service.

This module provides SingleController and SingleExecutor classes to streamline the process of configuring, starting, and managing a single Saturnin service instance. It acts as a higher-level abstraction over the more detailed DirectController and ThreadController implementations, allowing for easier integration or standalone execution of services.

Classes

class saturnin.component.single.SingleController(*args, **kwargs)

Bases: TracedMixin

A controller that manages a single service, allowing it to be executed either directly in the current thread (using DirectController) or in a separate thread (using ThreadController).

This class simplifies the setup by managing the underlying controller type based on the direct flag.

Parameters:

• parser – Optional ConfigParser instance to be used for service configuration. If None, a new one is created.

• manager – Optional ChannelManager to use. If None, a new one is created and managed internally.

• direct – If True, the service will be run using an internal DirectController. If False (default), a .`ThreadController` is used.

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

Configures the service to be run.

This method loads the service configuration from the config (ConfigParser instance), validates it, and instantiates the appropriate inner controller (DirectController or ThreadController) for the specified service.

Parameters:

section (str) – Configuration section name in config that contains the service specification (e.g., its agent UID). Defaults to SECTION_SERVICE.

Return type:

None

join(timeout=None) → None

Wait until service stops.

Parameters:

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

Return type:

None

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

Starts service.

Parameters:

timeout (int) – Timeout for starting the 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 start in time.

Return type:

None

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

Stop runing service.

Parameters:

timeout (int) – Timeout for stopping the 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 configuration

controller: ThreadController | DirectController

Service controller

direct: bool

Use DirectController instead ThreadController

mngr: ChannelManager

Channel manager

class saturnin.component.single.SingleExecutor(*, direct: bool = False)

Bases: object

A context manager for executing a single Saturnin service.

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

Parameters:

direct (bool) – If True, the underlying SingleController will be configured to run the service directly in the current thread. If False (default), the service runs in a separate thread.

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

Initializes and configures the internal SingleController.

This involves creating a ChannelManager, instantiating a SingleController with the specified direct mode, reading configuration files into the controller’s ConfigParser, and then calling the controller’s configure method.

Parameters:

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

• section (str) – The name of the configuration section that specifies the service to be run. Defaults to SECTION_SERVICE.

Return type:

None

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

Runs the configured service.

If the executor is configured for non-direct (threaded) execution, this method starts the service, waits for it to join (handling KeyboardInterrupt for graceful shutdown), and then returns the execution outcome.

If configured for direct execution, this method starts the service, which will block until it finishes or is interrupted. In direct mode, this method returns None as the outcome is managed within the blocking call.

Returns:

• If not in direct mode: A tuple containing the service’s execution Outcome and a list of strings with details (e.g., error messages).

• If in direct mode: None.

Return type:

tuple[Outcome, list[str]] | None

controller: SingleController

Controller

direct: bool

Use DirectController instead ThreadController

mngr: ChannelManager

Channel manager