Ligare.programming.application

The framework API for creating applications.

Classes

`AppModule`([exec, app_name])	An Injector module used for instantiating an ApplicationBase application.
`ApplicationBase`()	The base interface for all types of applications built with ApplicationBuilder.
`ApplicationBuilder`()	A builder used to build an application.
`ApplicationConfigBuilder`()	A builder used to build and hydrate an AbstractConfig instance from multiple configuration types for an ApplicationBase instance.
`CreateAppResult`(app, injector)	Contains an instantiated TApp application in app, and its associated Injector IoC container.

class Ligare.programming.application.AppModule(exec=None, app_name=None, *args, **kwargs)[source]

An Injector module used for instantiating an ApplicationBase application.

__init__(exec=None, app_name=None, *args, **kwargs)[source]

Create an Injector module used for instantiating an ApplicationBase application.

kwargs is used by AppModule.configure when instantiating the application. Pass any additional arguments to __init__ that should be passed to exec.

Parameters:

exec (type[TApp] | Callable[..., TApp] | None) – A type or callback used to instantiate the application. The type must not be a Python builtin type. If this variable is None, no application instantiator will be registered.
app_name (str | None) – The name of the application. If this is None, the application will be named “app”.

Raises:

Exception – If exec is a Python built.

configure(binder)[source]

Instantiate the application and bind it to a type. This method also registers a LoggerModule with the name of the application. :rtype: None

If exec is a type, the result of exec(**kwargs) is registered to the type exec.
If exec is a function, the result of exec(**kwargs) is registered to the type of the result of the function call.
If exec is an instance of TApp, it is registered to the type of the instance.

class Ligare.programming.application.ApplicationBase[source]

The base interface for all types of applications built with ApplicationBuilder.

This class is intended for use with Injector in order to resolve an instance of the running application. That application may or may not actually inherit this base class, but it must contain the methods defined in this base class.

abstract run(*args, **kwargs)[source]: Start the application. This method should block and only return when execution is complete.

protocol Ligare.programming.application.ApplicationBaseProtocol[source]

The “shape” of all types of applications built with ApplicationBuilder.

Classes that implement this protocol must have the following methods / attributes:

run(*args, **kwargs)[source]: Start the application. This method should block and only return when execution is complete.

class Ligare.programming.application.ApplicationBuilder(exec: type[TApp])[source]

class Ligare.programming.application.ApplicationBuilder(exec: Callable[[...], TApp])

A builder used to build an application.

__init__(exec)[source]

build()[source]

Return type:: CreateAppResultProtocol[TypeVar(TApp, bound= ApplicationBaseProtocol, covariant=True)]

use_configuration(application_config_builder)[source]

Return type:: Self

with_module(module)[source]

Return type:: Self

with_modules(modules)[source]

Return type:: Self

final class Ligare.programming.application.ApplicationConfigBuilder[source]

A builder used to build and hydrate an AbstractConfig instance from multiple configuration types for an ApplicationBase instance.

__init__()[source]

build()[source]

Build the configured AbstractConfig instance and hydrate values.

Raises:

InvalidBuilderStateError – The builder has not been configured correctly.
BuilderBuildError – The builder failed due to an unexpected error outside the control of this builder.

Return TConfig:

The type-safe AbstractConfig instance, with hydrated values.

Return type:

TypeVar(TConfig, bound= AbstractConfig)

enable_ssm(value)[source]

Try to load configuration values from AWS SSM. If use_filename was configured, a failed attempt to load from SSM will instead attempt to load from the configured filename. If use_filename is not configured and SSM fails, an exception is raised. If SSM succeeds, build will not load from the configured filename.

Parameters:: value (bool) – Whether to use SSM
Return Self:
Return type:: Self

with_config_builder(config_builder)[source]

A ConfigBuilder instance that is used to create the AbstractConfig instance that the application will use.

Parameters:: config_builder (ConfigBuilder[TConfig]) – The configuration builder
Return Self:
Return type:: Self

with_config_filename(filename)[source]

Use and load configuration values from a TOML file.

Parameters:: filename (str) – The TOML filename from which to load configuration values.
Return Self:
Return type:: Self

with_config_type(config_type)[source]

An additional AbstractConfig type that is registered as a property on the root AbstractConfig type.

Parameters:: config_type (type[AbstractConfig]) – _description_
Return Self:: _description_
Return type:: Self

with_config_types(configs)[source]

Additional AbstractConfig types that are registered as properties on the root AbstractConfig type.

Parameters:: configs (list[type[AbstractConfig]] | None)
Return Self:
Return type:: Self

with_config_value_overrides(values)[source]

A dictionary of any depth used to override values that are hydrated into the built AbstractConfig instance. Any values supplied here are used, ignoring values from other sources.

Parameters:: values (dict[str, Any])
Return Self:
Return type:: Self

with_root_config_type(config_type)[source]

The AbstractConfig type that forms the root of the entire type-safe configuration. If this option is not set, the first AbstractConfig registered with with_config_types or with_config_type will be the root AbstractConfig type.

Parameters:: config_type (type[TConfig])
Return Self:
Return type:: Self

protocol Ligare.programming.application.ApplicationConfigBuilderCallback[source]

typing.Protocol.

Classes that implement this protocol must have the following methods / attributes:

__call__(config_builder)[source]

A method used to configure an ApplicationConfigBuilder. Call the builder methods on config_builder to set the desired options.

Do not call `build()` as it is called by the ApplicationBuilder.

Parameters:: config_builder (ApplicationConfigBuilder[TAppConfig])
Return None | ApplicationConfigBuilder[TAppConfig]:: Any return value is ignored.
Return type:: Optional[ApplicationConfigBuilder[TypeVar(TAppConfig, bound= AbstractConfig)]]

class Ligare.programming.application.CreateAppResult(app, injector)[source]

Contains an instantiated TApp application in app, and its associated Injector IoC container.

Parameters:

Generic (TApp) – An instance of the app.
Injector (inject) – The applications IoC container.

__init__(app, injector)

app: TypeVar(TApp, bound= ApplicationBaseProtocol, covariant=True)

injector: Injector

run()[source]

Start the application instance of app.

Return None:: Returns None when the application has finished execution.
Return type:: None

protocol Ligare.programming.application.CreateAppResultProtocol[source]

The “shape” of the result of an application created with ApplicationBuilder.build.

Classes that implement this protocol must have the following methods / attributes:

property app: TApp

property injector: Injector

run()[source]

Return type:: None

protocol Ligare.programming.application.UseConfigurationCallback[source]

The callback for configuring an application’s configuration.

Parameters:: Protocol (TConfig) – The AbstractConfig type to be configured.

Classes that implement this protocol must have the following methods / attributes:

__call__(config_builder, config_overrides)[source]

Set up parameters for the application’s configuration.

Parameters:

config_builder (ConfigBuilder[TConfig]) – The ConfigBuilder instance.
config_overrides (dict[str, Any]) – A dictionary of key/values that are applied over all keys that might exist in an instantiated config.

Raises:

InvalidBuilderStateError – Upon a call to build(), the builder is misconfigured.
BuilderBuildError – Upon a call to build(), a failure occurred during the instantiation of the configuration.
Exception – Upon a call to build(), an unknown error occurred.

Return None | ConfigBuilder[TConfig]:

The callback may return None or the received ConfigBuilder instance so as to support the use of lambdas. This return value is not used.

Return type:

Optional[ConfigBuilder[TypeVar(TConfig, bound= AbstractConfig)]]