saturnin.component.apps¶

Saturnin application registration and discovery.

This module handles the registration and discovery of Saturnin applications. Applications are registered as entry points where EntryPoint.load() is expected to return an instance of ApplicationDescriptor. The default entry point group for application registration is saturnin.application.

It provides ApplicationInfo to represent application metadata and ApplicationRegistry to manage these applications.

Globals¶

saturnin.component.apps.application_registry: ApplicationRegistry¶: Global ApplicationRegistry instance, automatically populated by load() upon module import.

Classes¶

class saturnin.component.apps.ApplicationInfo(*, uid: UUID, name: str, version: str, vendor: UUID, classification: str, description: str, descriptor: str, distribution: str, cli_command: str | None = None, recipe_factory: str | None = None)[source]¶

Bases: Distinct

Information about application stored in ApplicationRegistry.

Parameters:

uid (UUID) – Application UID
name (str) – Application name
version (str) – Application version
vendor (UUID) – Application vendor UID
classification (str) – Application classification
description (str) – Application description
cli_command (str | None) – Application factory specification (entry point)
recipe_factory (str | None) – Application configuration factory (entry point)
descriptor (str) – Application descriptor specification (entry point)
distribution (str) – Installed distribution package that contains this application

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 the application UID, which serves as its unique key.

Return type:: Hashable

get_recipe_name() → str[source]¶

Returns default recipe name for this application. If application name contains dots, only part after last dot is returned. Otherwise it returns the application name.

Return type:: str

is_command() → bool[source]¶

Returns tru if application is console command.

Such applications are not installed via recipe, but directly into console.

Return type:: bool

classification: str¶: Application classification

cli_command: str | None¶: Application command specification (entry point)

property cli_command_obj: Callable[[...], Any]¶: Application command factory object. If it’s not assigned directly, then it’s loaded using factory on first access.

description: str¶: Application description

descriptor: str¶: Application descriptor specification (entry point)

property descriptor_obj: ApplicationDescriptor¶: Application 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 application

name: str¶: Application name

recipe_factory: str | None¶: Application recipe factory (entry point)

property recipe_factory_obj: Callable[[], str]¶: Application configuration factory object. If it’s not assigned directly, then it’s loaded using config on first access.

property set_cli_command_obj: Callable[[...], Any]¶: Application command factory object. If it’s not assigned directly, then it’s loaded using factory on first access.

property set_descriptor_obj: ApplicationDescriptor¶: Application descriptor object. If it’s not assigned directly, then it’s loaded using descriptor on first access.

property set_recipe_factory_obj: Callable[[], str]¶: Application configuration factory object. If it’s not assigned directly, then it’s loaded using config on first access.

uid: UUID¶: Application UID

vendor: UUID¶: Application vendor UID

version: str¶: Application version

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

Bases: Registry

Saturnin application registry.

Holds ApplicationInfo instances.

It is used in two modes:

In a full Saturnin deployment, information about applications is loaded from a TOML file. Application descriptors and factories are then loaded on demand.
In standalone service/bundle mode, application information, including application 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: ApplicationDescriptor, factory: Any, distribution: str) → None[source]¶

Direct application registration. Used by systems that do not allow dynamic discovery, for example programs compiled by Nuitka.

Parameters:

descriptor (ApplicationDescriptor) – Application descriptor
factory (Any) – Application factory
distribution (str) – Distribution package name with application

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 application by its name.

Parameters:

name (str) – Application name.
default (Any) – Default value returned when application is not found.

Return type:

Distinct

load() → None[source]¶

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

Return type:: None

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

Populate registry from descriptors of installed applications.

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 applications to a TOML file located at directory_scheme.site_apps_toml.

Return type:: None