Applications API Reference

This page contains auto-generated documentation for app base classes and registration functions.

App Base Classes

AppBase

The main base class for all Domovoy apps.

class domovoy.applications.AppConfigBase[source]

Bases: object

The base implementation for App configuration classes.

class domovoy.applications.EmptyAppConfig[source]

Bases: AppConfigBase

A configuration class with no fields. Used when an app doesn’t need config.

class domovoy.applications.AppBaseWithoutConfig(meta, log, scheduler, hass, servents, utils, time)[source]

Bases: object

Parameters:
hass: HassPlugin
callbacks: CallbacksPlugin
servents: ServentsPlugin
meta: MetaPlugin
log: LoggerPlugin
utils: UtilsPlugin
time: TimePlugin
async initialize()[source]

Initialize the App when it is started.

The initialize function is called when an app is first started. It can be used to setup listeners and other parameters needed during operations.

Return type:

None

async finalize()[source]

Clean up resources when the app is being terminated.

This function is called when the app is being terminated. It can be used to cleanup any resources created or used by the app which are not handled by Domovoy

Return type:

None

class domovoy.applications.AppBase(config, meta, log, scheduler, hass, servents, utils, time)[source]

Bases: AppBaseWithoutConfig, Generic

Parameters:
config: TypeVar(TConfig, bound= AppConfigBase)
async initialize()[source]

Initialize the App when it is started.

The initialize function is called when an app is first started. It can be used to setup listeners and other parameters needed during operations.

Return type:

None

async finalize()[source]

Clean up resources when the app is being terminated.

This function is called when the app is being terminated. It can be used to cleanup any resources created or used by the app which are not handled by Domovoy

Return type:

None

Registration Functions

Functions for registering apps with Domovoy.

domovoy.applications.registration.register_app(*, app_class, app_name, config=None, logging_config_name=None, ignore=False)[source]

Register an app in the current running instance of the Domovy App Engine.

Return type:

None

Parameters:

  • app_class (type[AppBase[TConfig]])

  • app_name (str)

  • config (TConfig | None)

  • logging_config_name (str | None)

  • ignore (bool)

Args:

app_class (type[AppBase[TConfig]]): The class defining the App to instantiate app_name (str): The name/id for the app. Needs to be unique across all apps. config (TConfig | None, optional): An instance of the configuration for the App. Will throw if app takes a

config and one is not provided. Defaults to None.

logging_config_name (str | None, optional): The name of the logging config to use for this app. If not

explicitly defined in config, a new config using this name will be created, using the _app_default logging config. Defaults to None.

ignore (bool, optional): Whether this registration should be ignored and not actually ran into the system. Can

be used to avoid an instance running without removing or commenting the code out. Defaults to False.

domovoy.applications.registration.register_app_multiple(*, app_class, configs, logging_config_name=None, ignore=False)[source]

Register a group of apps in the current running instance of the Domovy App Engine, each one using its own config.

Return type:

None

Parameters:

Args:

app_class (type[AppBase[TConfig]]): The class defining the App to instantiate configs (dict[str, TConfig]): Dictionary in which keys are the names of each app instance. The value of each

key is an instance of the configuration for the App. Will throw if app takes a config and one is not provided

logging_config_name (str | None, optional): The name of the logging config to use for this app. If not

explicitly defined in config, a new config using this name will be created, using the _app_default logging config. Defaults to None.

ignore (bool, optional): Whether this registration should be ignored and not actually ran into the system. Can

be used to avoid an instance running without removing or commenting the code out. Defaults to False.

App Infrastructure

Internal infrastructure classes for app lifecycle management.

class domovoy.core.app_infra.EmptyAppBase[source]

Bases: AppBase[EmptyAppConfig]

async initialize()[source]

Initialize the App when it is started.

The initialize function is called when an app is first started. It can be used to setup listeners and other parameters needed during operations.

Return type:

None

async finalize()[source]

Clean up resources when the app is being terminated.

This function is called when the app is being terminated. It can be used to cleanup any resources created or used by the app which are not handled by Domovoy

Return type:

None

class domovoy.core.app_infra.CallbackRegistration(*, id, callback, is_registered, times_called=0, last_call_datetime=None, last_error_datetime=None)[source]

Bases: object

Parameters:
id: str
callback: Callable
is_registered: bool
times_called: int = 0
last_call_datetime: datetime | None = None
last_error_datetime: datetime | None = None
class domovoy.core.app_infra.SchedulerCallbackRegistration(*, id, callback, is_registered, times_called=0, last_call_datetime=None, last_error_datetime=None, trigger, start, job=None)[source]

Bases: CallbackRegistration

Parameters:

  • id (str)

  • callback (Callable)

  • is_registered (bool)

  • times_called (int)

  • last_call_datetime (datetime | None)

  • last_error_datetime (datetime | None)

  • trigger (BaseTrigger | None)

  • start (datetime | None)

  • job (Job | None)

trigger: BaseTrigger | None
start: datetime | None
job: Job | None = None
class domovoy.core.app_infra.EventCallbackRegistration(*, id, callback, is_registered, times_called=0, last_call_datetime=None, last_error_datetime=None, events)[source]

Bases: CallbackRegistration

Parameters:
events: list[str]
class domovoy.core.app_infra.AppStatus(*values)[source]

Bases: StrEnum

CREATED = 'created'
INITIALIZING = 'initializing'
RUNNING = 'running'
FAILED = 'failed'
FINALIZING = 'finalizing'
TERMINATED = 'terminated'
class domovoy.core.app_infra.AppWrapper(config, app_name, filepath, module_name, class_name, status, logging_config_name, app_name_for_logs, app=<factory>, scheduler_callbacks=<factory>, event_callbacks=<factory>, plugins=<factory>)[source]

Bases: object

Parameters:
config: AppConfigBase
app_name: str
filepath: str
module_name: str
class_name: str
status: AppStatus
logging_config_name: str
app_name_for_logs: str
logger: LoggerAdapterWithTrace[Any]
app: AppBase[Any]
scheduler_callbacks: dict[str, SchedulerCallbackRegistration]
event_callbacks: dict[str, EventCallbackRegistration]
plugins: dict[type, dict[str, AppPlugin]]
get_app_name_for_logs()[source]
Return type:

str

get_pluginx(plugin_type, name=None)[source]
Return type:

TypeVar(T, bound= AppPlugin)

Parameters:

  • plugin_type (type[T])

  • name (str | None)

get_plugin(plugin_type, name=None)[source]
Return type:

TypeVar(T, bound= AppPlugin) | None

Parameters:

  • plugin_type (type[T])

  • name (str | None)

register_plugin(plugin, name)[source]
Return type:

None

Parameters:

  • plugin (AppPlugin)

  • name (str)

prepare_all_plugins()[source]
Return type:

None

handle_exception_and_logging(true_callback)[source]
Return type:

Callable[[Callable[[Concatenate[TypeVar(TStrOrInt, bound= int | str), ParamSpec(P, bound= None)]], Coroutine[Any, Any, None]]], Callable[[Concatenate[TypeVar(TStrOrInt, bound= int | str), ParamSpec(P, bound= None)]], Coroutine[Any, Any, None]]]

Parameters:

true_callback (Callable)

TReturn = ~TReturn
instrument_app_callback(callback)[source]
Return type:

Callable[[Concatenate[str | int, ParamSpec(P, bound= None)]], Awaitable[None]]

Parameters:

callback (Callable[[~P], None | Awaitable[None]])