saturnin.component.registry

Saturnin component registration and discovery.

Services are registered as entry points where EntryPoint.load() is expected to return an instance of .ServiceDescriptor.

The default group for service registration is saturnin.service, but it’s possible to install additional service discovery iterators.

Custom service iterator must be a generator that accepts optional uid in string format, and yileds importlib.metadata.EntryPoint instances. If uid is specified, it must return only EntryPoint only for service with given uid, otherwise it should return all services.

Note

Custom iterator can return objects that are not EntryPoint instances, but they MUST implement load() method that will return ServiceDescriptor instance.

Custom iterators must be registered as entry points in saturnin.service.iterator group.

Globals

saturnin.component.registry.service_registry: ServiceRegistry

Global ServiceRegistry instance, automatically populated by load() upon module import.

Classes

class saturnin.component.registry.ServiceInfo(*, uid: UUID, name: str, version: str, vendor: UUID, classification: str, description: str, facilities: list[str], api: list[UUID], factory: str, descriptor: str, distribution: str)[source]

Bases: Distinct

Information about service stored in ServiceRegistry.

Parameters:

  • uid (UUID) – Service UID

  • name (str) – Service name

  • version (str) – Service version

  • vendor (UUID) – Service vendor UID

  • classification (str) – Service classification

  • description (str) – Service description

  • facilities (list[str]) – List of service facilities

  • api (list[UUID]) – List of interfaces provided by service

  • factory (str) – Service factory specification (entry point)

  • descriptor (str) – Service descriptor specification (entry point)

  • distribution (str) – Installed distribution package that contains this service

as_toml_dict() → dict[source]

Returns dictionary with instance data suitable for storage in TOML format (values that are not of basic type are converted to string).

Return type:

dict

get_key() → Hashable[source]

Returns service UID

Return type:

Hashable

api: list[UUID]

List of interfaces provided by service

classification: str

Service classification

description: str

Service description

descriptor: str

Service descriptor specification (entry point)

property descriptor_obj: ServiceDescriptor

Service descriptor object. If it’s not assigned directly, then it’s loaded using descriptor on first access.

distribution: str

Installed distribution package that contains this service

facilities: list[str]

List of service facilities

factory: str

Service factory specification (entry point)

property factory_obj: Any

Service factory object. If it’s not assigned directly, then it’s loaded using factory on first access.

name: str

Service name

uid: UUID

Service UID

vendor: UUID

Service vendor UID

version: str

Service version

class saturnin.component.registry.ServiceRegistry(data: Mapping[Any, Distinct] | Sequence[Distinct] | Registry = None)[source]

Bases: Registry

Saturnin service registry.

Holds ServiceInfo instances.

It is used in two modes:

  1. In a full Saturnin deployment, information about services is loaded from a TOML file. Service descriptors and factories are then loaded on demand.

  2. In standalone service/bundle mode, service information, including service descriptors and factories, is stored directly by the executor script. This allows for scenarios where dynamic discovery is not used, and the application can be compiled (e.g., with Nuitka).

Parameters:

data (Mapping[Any, Distinct] | Sequence[Distinct] | Registry)

add(descriptor: ServiceDescriptor, factory: Any, distribution: str) → None[source]

Registers a service directly, typically used in environments that do not support or use dynamic entry point discovery (e.g., applications compiled with Nuitka).

Parameters:

  • descriptor (ServiceDescriptor) – The ServiceDescriptor instance for the service.

  • factory (Any) – The factory object or callable for creating the service instance.

  • distribution (str) – The name of the distribution package that provides this service.

Return type:

None

as_toml() → str[source]

Returns registry content as TOML document.

Return type:

str

get_by_name(name: str, default: Any = None) → Distinct[source]

Get service by its name.

Parameters:

  • name (str) – Service name.

  • default (Any) – Default value returned when service is not found.

Return type:

Distinct

load() → None[source]

Reads information about installed services from a previously saved TOML file, located at directory_scheme.site_services_toml, if it exists.

Return type:

None

load_from_installed(*, ignore_errors: bool = False) → None[source]

Populate registry from descriptors of installed services.

Parameters:

ignore_errors (bool) – When True, errors are ignored, otherwise Error is raised.

Return type:

None

load_from_toml(toml: str, *, ignore_errors: bool = False) → None[source]

Populate registry from TOML document.

Parameters:

  • toml (str) – TOML document (as created by as_toml method).

  • ignore_errors (bool) – When True, errors are ignored, otherwise Error is raised.

Return type:

None

save() → None[source]

Saves the current information about installed services to a TOML file located at directory_scheme.site_services_toml.

Return type:

None