Plugins API Reference

This page contains auto-generated documentation for all Domovoy plugins.

Hass Plugin

The main Home Assistant integration plugin. Provides access to entity states, service calls, triggers, and events.

class domovoy.plugins.hass.ServiceDetails(has_response)

Bases: object

Parameters:

has_response (bool)

has_response: bool

class domovoy.plugins.hass.HassPlugin(name, wrapper, hass_core)

Bases: AppPlugin

Parameters:

• name (str)

• wrapper (AppWrapper)

• hass_core (HassCore)

prepare()

Return type:

None

get_full_state(entity_id)

Get the complete state object for a Home Assistant entity.

Parameters:

entity_id (EntityID) – The EntityID to retrieve state for. Can also accept string for backwards compatibility.

Return type:

EntityState

Returns:

EntityState object containing state, attributes, last_changed, and last_updated.

Raises:

HassUnknownEntityError – If the entity does not exist in the state cache.

warn_if_entity_doesnt_exists(entity_id)

Log a warning if the specified entity or entities don’t exist in the Home Assistant cache.

Useful for debugging typos in entity IDs during development.

Parameters:

entity_id (EntityID | Sequence[EntityID] | None) – Single EntityID, sequence of EntityIDs, or None. If None, no action is taken.

Return type:

None

get_entity_id_by_attribute(attribute, value)

Find all entities that have a specific attribute with the given value.

Parameters:

• attribute (str) – The name of the attribute to search for.

• value (str | None) – The value to match. If None, returns entities that have the attribute regardless of value.

Return type:

list[EntityID]

Returns:

List of EntityIDs that match the criteria.

get_all_entities()

Get the complete state objects for all entities in the Home Assistant cache.

Return type:

list[EntityState]

Returns:

List of EntityState objects for every entity known to Home Assistant.

get_all_entity_ids()

Get all entity IDs currently in the Home Assistant cache.

Return type:

frozenset[EntityID]

Returns:

Frozen set of EntityID objects representing all known entities.

async fire_event(event_type, event_data=None)

Fire a custom event on the Home Assistant event bus.

Parameters:

• event_type (str) – The type/name of the event to fire.

• event_data (dict[str, int | float | str | bool | datetime | EntityID | list[int | float | str | bool | datetime | EntityID | dict[str, int | float | str | bool | datetime | EntityID | None]] | dict[str, int | float | str | bool | datetime | EntityID | list[int | float | str | bool | datetime | EntityID] | None] | None] | None) – Optional dictionary of data to include with the event.

Return type:

None

async get_service_definitions()

Retrieve service definitions from Home Assistant.

Return type:

dict[str, int | float | str | bool | datetime | EntityID | list[int | float | str | bool | datetime | EntityID | dict[str, int | float | str | bool | datetime | EntityID | None]] | dict[str, int | float | str | bool | datetime | EntityID | list[int | float | str | bool | datetime | EntityID] | None] | None]

Returns:

Dictionary containing all available services and their schemas.

async listen_trigger(trigger, callback, oneshot=False, *callback_args, **callback_kwargs)

Subscribe to a Home Assistant trigger configuration.

Triggers are HA’s automation system primitives (state, numeric_state, time, etc.).

Parameters:

• trigger (dict[str, int | float | str | bool | datetime | EntityID | list[int | float | str | bool | datetime | EntityID | dict[str, int | float | str | bool | datetime | EntityID | None]] | dict[str, int | float | str | bool | datetime | EntityID | list[int | float | str | bool | datetime | EntityID] | None] | None]) – Dictionary containing the trigger configuration (e.g., {“platform”: “state”, “entity_id”: “…”}).

• callback (Callable[[Concatenate[dict[str, int | float | str | bool | datetime | EntityID | list[int | float | str | bool | datetime | EntityID | dict[str, int | float | str | bool | datetime | EntityID | None]] | dict[str, int | float | str | bool | datetime | EntityID | list[int | float | str | bool | datetime | EntityID] | None] | None], ParamSpec(P, bound= None)]], None | Awaitable[None]]) – Function to call when trigger fires. Receives trigger variables as first argument.

• oneshot (bool) – If True, unsubscribe after the first trigger event.

• *callback_args (ParamSpecArgs) – Additional positional arguments to pass to callback.

• **callback_kwargs (ParamSpecKwargs) – Additional keyword arguments to pass to callback.

Return type:

str

Returns:

Subscription ID string that can be used to cancel the trigger subscription.

async call_service(service_name, *, return_response=False, throw_on_error=False, **kwargs)

Call a Home Assistant service.

Prefer using the typed service stubs (self.services.domain.service_name) over this method.

Parameters:

• service_name (str) – Service to call in format “domain.service” (e.g., “light.turn_on”).

• return_response (bool) – If True, wait for and return the service response data.

• throw_on_error (bool) – If True, raise exceptions on errors. If False, log errors without raising.

• **kwargs (int | float | str | bool | datetime | EntityID | list[int | float | str | bool | datetime | EntityID | dict[str, int | float | str | bool | datetime | EntityID | None]] | dict[str, int | float | str | bool | datetime | EntityID | list[int | float | str | bool | datetime | EntityID] | None] | None) – Service data parameters. entity_id can be EntityID or list[EntityID].

Return type:

dict[str, int | float | str | bool | datetime | EntityID | list[int | float | str | bool | datetime | EntityID | dict[str, int | float | str | bool | datetime | EntityID | None]] | dict[str, int | float | str | bool | datetime | EntityID | list[int | float | str | bool | datetime | EntityID] | None] | None] | None

Returns:

Service response data if return_response is True and service returns data, otherwise None.

Raises:

HassApiCommandError – If throw_on_error is True and service call fails.

async wait_for_state_to_be(entity_id, states, duration=None, timeout=None)

Asynchronously wait for an entity to reach one of the specified states.

This is an awaitable method that blocks until the condition is met or timeout occurs.

Parameters:

• entity_id (EntityID) – The entity to monitor.

• states (str | list[str]) – Single state string or list of state strings to wait for.

• duration (Interval | None) – If specified, entity must stay in the target state for this duration.

• timeout (Interval | None) – Optional timeout interval. Raises asyncio.TimeoutError if exceeded.

Raises:

asyncio.TimeoutError – If timeout is specified and exceeded before condition is met.

Return type:

None

async search_related(item_type, item_id)

Search for entities and items related to a specific Home Assistant item.

Parameters:

• item_type (str) – Type of item to search for (e.g., “entity”, “device”, “area”).

• item_id (str) – The ID of the item to find relations for.

Return type:

dict[str, int | float | str | bool | datetime | EntityID | list[int | float | str | bool | datetime | EntityID | dict[str, int | float | str | bool | datetime | EntityID | None]] | dict[str, int | float | str | bool | datetime | EntityID | list[int | float | str | bool | datetime | EntityID] | None] | None]

Returns:

Dictionary containing related items organized by type.

async send_raw_command(command_type, command_args)

Send a raw WebSocket command directly to Home Assistant.

This is a low-level method for advanced use cases not covered by other plugin methods.

Parameters:

• command_type (str) – The WebSocket command type to send.

• command_args (dict[str, int | float | str | bool | datetime | EntityID | list[int | float | str | bool | datetime | EntityID | dict[str, int | float | str | bool | datetime | EntityID | None]] | dict[str, int | float | str | bool | datetime | EntityID | list[int | float | str | bool | datetime | EntityID] | None] | None]) – Dictionary of arguments for the command.

Return type:

dict[str, int | float | str | bool | datetime | EntityID | list[int | float | str | bool | datetime | EntityID | dict[str, int | float | str | bool | datetime | EntityID | None]] | dict[str, int | float | str | bool | datetime | EntityID | list[int | float | str | bool | datetime | EntityID] | None] | None] | list[dict[str, int | float | str | bool | datetime | EntityID | list[int | float | str | bool | datetime | EntityID | dict[str, int | float | str | bool | datetime | EntityID | None]] | dict[str, int | float | str | bool | datetime | EntityID | list[int | float | str | bool | datetime | EntityID] | None] | None]]

Returns:

The response from Home Assistant, either a single data dict or list of dicts.

get_typed_state(entity_id)

Get the state of an entity, cast to the entity’s native type.

Uses the EntityID’s type information to parse and cast the state value.

Parameters:

entity_id (EntityID[TypeVar(T)]) – Typed EntityID that includes parsing logic for its domain.

Return type:

TypeVar(T) | None

Returns:

State value cast to the appropriate type, or None if parsing fails.

get_state(entity_id)

Get the current state value of an entity.

Returns only the state value, not the full EntityState object.

Parameters:

entity_id (EntityID) – The entity to get state for.

Return type:

int | float | str | bool | datetime | EntityID

Returns:

The entity’s current state as a primitive value (str, int, float, or bool).

domovoy.plugins.hass.wrap_entity_id_as_list(val)

Convert a single EntityID or sequence of EntityIDs into a list.

Utility function to normalize entity ID arguments that can be either single or multiple values.

Parameters:

val (EntityID | Sequence[EntityID]) – Single EntityID or sequence of EntityIDs.

Return type:

list[EntityID]

Returns:

List containing the EntityID(s).

Hass Exceptions

exception domovoy.plugins.hass.exceptions.HassError

Bases: Exception

exception domovoy.plugins.hass.exceptions.HassApiAuthenticationError

Bases: HassError

Return type:

None

exception domovoy.plugins.hass.exceptions.HassApiParseError

Bases: HassError

exception domovoy.plugins.hass.exceptions.HassApiConnectionError

Bases: HassError, DomovoyLogOnlyOnDebugWhenUncaughtError

exception domovoy.plugins.hass.exceptions.HassApiConnectionResetError

Bases: HassApiConnectionError

exception domovoy.plugins.hass.exceptions.HassApiInvalidValueError

Bases: HassError

exception domovoy.plugins.hass.exceptions.HassUnknownEntityError(entity_id)

Bases: HassError

Parameters:

entity_id (EntityID)

Return type:

None

exception domovoy.plugins.hass.exceptions.HassApiCommandError(*, command_id, code, message, full_response, original_command)

Bases: HassError

Parameters:

• command_id (int)

• code (int)

• message (str)

• full_response (dict[str, Any])

• original_command (dict[str, Any])

Return type:

None

message: str

full_response: dict[str, Any]

command_id: int

code: int

Callbacks Plugin

Event listening and scheduling functionality.

class domovoy.plugins.callbacks.CallbacksPlugin(name, wrapper, register)

Bases: AppPlugin

Parameters:

• name (str)

• wrapper (AppWrapper)

• register (CallbackRegister)

prepare()

Return type:

None

listen_event(events, callback, *, oneshot=False)

Return type:

str

Parameters:

• events (str | list[str])

• callback (EventListenerCallbackFull | EventListenerCallbackWithEventName | EventListenerCallbackWithEventData | Callable[[], None | Awaitable[None]])

• oneshot (bool)

listen_event_extended(events, callback, oneshot=False, *callback_args, **callback_kwargs)

Return type:

str

Parameters:

• events (str | list[str])

• callback (Callable[[Concatenate[str, dict[str, Any], ~P]], None | Awaitable[None]])

• oneshot (bool)

• callback_args (~P)

• callback_kwargs (~P)

listen_state(entity_id, callback, *, immediate=False, oneshot=False)

Return type:

list[str]

Parameters:

• entity_id (EntityID | Sequence[EntityID])

• callback (EntityListenerCallbackFull | EntityListenerCallbackWithAttributeAndOldAndNew | EntityListenerCallbackWithEntityIDAndOldAndNew | EntityListenerCallbackWithEntityIDAndAttributeAndNew | EntityListenerCallbackWithEntityIDAndAttributeAndOld | EntityListenerCallbackWithEntityIDAndAttribute | EntityListenerCallbackWithEntityIDAndOld | EntityListenerCallbackWithEntityIDAndNew | EntityListenerCallbackWithAttributeAndOld | EntityListenerCallbackWithAttributeAndNew | EntityListenerCallbackWithOldAndNew | EntityListenerCallbackWithEntityID | EntityListenerCallbackWithAttribute | EntityListenerCallbackWithOld | EntityListenerCallbackWithNew | Callable[[], None | Awaitable[None]])

• immediate (bool)

• oneshot (bool)

listen_attribute(entity_id, attribute, callback, *, immediate=False, oneshot=False)

Return type:

list[str]

Parameters:

• entity_id (EntityID | Sequence[EntityID])

• attribute (str)

• callback (EntityListenerCallbackFull | EntityListenerCallbackWithAttributeAndOldAndNew | EntityListenerCallbackWithEntityIDAndOldAndNew | EntityListenerCallbackWithEntityIDAndAttributeAndNew | EntityListenerCallbackWithEntityIDAndAttributeAndOld | EntityListenerCallbackWithEntityIDAndAttribute | EntityListenerCallbackWithEntityIDAndOld | EntityListenerCallbackWithEntityIDAndNew | EntityListenerCallbackWithAttributeAndOld | EntityListenerCallbackWithAttributeAndNew | EntityListenerCallbackWithOldAndNew | EntityListenerCallbackWithEntityID | EntityListenerCallbackWithAttribute | EntityListenerCallbackWithOld | EntityListenerCallbackWithNew | Callable[[], None | Awaitable[None]])

• immediate (bool)

• oneshot (bool)

listen_state_extended(entity_id, callback, immediate=False, oneshot=False, *callback_args, **callback_kwargs)

Return type:

list[str]

Parameters:

• entity_id (EntityID | list[EntityID])

• callback (Callable[[Concatenate[EntityID, str, int | float | str | bool | datetime | EntityID | list[int | float | str | bool | datetime | EntityID | dict[str, int | float | str | bool | datetime | EntityID | None]] | dict[str, int | float | str | bool | datetime | EntityID | list[int | float | str | bool | datetime | EntityID] | None] | None, int | float | str | bool | datetime | EntityID | list[int | float | str | bool | datetime | EntityID | dict[str, int | float | str | bool | datetime | EntityID | None]] | dict[str, int | float | str | bool | datetime | EntityID | list[int | float | str | bool | datetime | EntityID] | None] | None, ~P]], None | Awaitable[None]])

• immediate (bool)

• oneshot (bool)

• callback_args (~P)

• callback_kwargs (~P)

listen_attribute_extended(entity_id, attribute, callback, immediate=False, oneshot=False, *callback_args, **callback_kwargs)

Return type:

list[str]

Parameters:

• entity_id (EntityID | Sequence[EntityID])

• attribute (str)

• callback (Callable[[Concatenate[EntityID, str, int | float | str | bool | datetime | EntityID | list[int | float | str | bool | datetime | EntityID | dict[str, int | float | str | bool | datetime | EntityID | None]] | dict[str, int | float | str | bool | datetime | EntityID | list[int | float | str | bool | datetime | EntityID] | None] | None, int | float | str | bool | datetime | EntityID | list[int | float | str | bool | datetime | EntityID | dict[str, int | float | str | bool | datetime | EntityID | None]] | dict[str, int | float | str | bool | datetime | EntityID | list[int | float | str | bool | datetime | EntityID] | None] | None, ~P]], None | Awaitable[None]])

• immediate (bool)

• oneshot (bool)

• callback_args (~P)

• callback_kwargs (~P)

cancel_callback(callback_id)

Return type:

None

Parameters:

callback_id (str)

run_once(time, callback, *callback_args, **callback_kwargs)

Return type:

str

Parameters:

• time (time)

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

• callback_args (~P)

• callback_kwargs (~P)

run_in(interval, callback, *callback_args, **callback_kwargs)

Return type:

str

Parameters:

• interval (Interval)

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

• callback_args (~P)

• callback_kwargs (~P)

run_daily_on_sun_event(callback, sun_event, delta=None, *callback_args, **callback_kwargs)

Return type:

str

Parameters:

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

• sun_event (Literal['dawn', 'sunrise', 'noon', 'sunset', 'dusk'])

• delta (Interval | None)

• callback_args (~P)

• callback_kwargs (~P)

run_at(callback, datetime, *callback_args, **callback_kwargs)

Return type:

str

Parameters:

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

• datetime (datetime)

• callback_args (~P)

• callback_kwargs (~P)

run_daily(callback, time='now', *callback_args, **callback_kwargs)

Return type:

str

Parameters:

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

• time (time | str)

• callback_args (~P)

• callback_kwargs (~P)

run_hourly(callback, start='now', *callback_args, **callback_kwargs)

Return type:

str

Parameters:

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

• start (datetime | str)

• callback_args (~P)

• callback_kwargs (~P)

run_minutely(callback, start='now', *callback_args, **callback_kwargs)

Return type:

str

Parameters:

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

• start (datetime | str)

• callback_args (~P)

• callback_kwargs (~P)

run_secondly(callback, start='now', *callback_args, **callback_kwargs)

Return type:

str

Parameters:

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

• start (datetime | str)

• callback_args (~P)

• callback_kwargs (~P)

run_every(interval, callback, start='now', *callback_args, **callback_kwargs)

Return type:

str

Parameters:

• interval (Interval)

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

• start (datetime | str)

• callback_args (~P)

• callback_kwargs (~P)

domovoy.plugins.callbacks.wrap_entity_id_as_list(val)

Return type:

list[EntityID]

Parameters:

val (EntityID | Sequence[EntityID])

ServEnts Plugin

Modern API for creating Home Assistant entities from Python (recommended).

class domovoy.plugins.servents.ExtraConfig(*, device_config=None, wait_for_creation=True)

Bases: object

Parameters:

• device_config (DeviceConfig | None)

• wait_for_creation (bool)

device_config: DeviceConfig | None = None

wait_for_creation: bool = True

class domovoy.plugins.servents.ServentsPlugin(name, wrapper)

Bases: AppPlugin

Parameters:

• name (str)

• wrapper (AppWrapper)

prepare()

Return type:

None

post_prepare()

Return type:

None

get_default_device_for_app()

Return type:

DeviceConfig

set_default_device_for_app(device_config)

Return type:

None

Parameters:

device_config (DeviceConfig)

update_default_device_name_for_app(name)

Return type:

None

Parameters:

name (str)

async enable_reload_button()

Return type:

ServEntButton

async create_sensor(servent_id, name, *, default_state=None, fixed_attributes=None, entity_category=None, disabled_by_default=False, app_name=None, device_class=None, unit_of_measurement=None, state_class=None, options=None, creation_config=None)

Return type:

ServEntSensor

Parameters:

• servent_id (str)

• name (str)

• default_state (str | bool | float | None)

• fixed_attributes (dict[str, str | bool | float] | None)

• entity_category (Literal['config', 'diagnostic'] | None)

• disabled_by_default (bool)

• app_name (str | None)

• device_class (Literal['date', 'enum', 'timestamp', 'absolute_humidity', 'apparent_power', 'aqi', 'area', 'atmospheric_pressure', 'battery', 'blood_glucose_concentration', 'carbon_monoxide', 'carbon_dioxide', 'conductivity', 'current', 'data_rate', 'data_size', 'distance', 'duration', 'energy', 'energy_distance', 'energy_storage', 'frequency', 'gas', 'humidity', 'illuminance', 'irradiance', 'moisture', 'monetary', 'nitrogen_dioxide', 'nitrogen_monoxide', 'nitrous_oxide', 'ozone', 'ph', 'pm1', 'pm10', 'pm25', 'pm4', 'power_factor', 'power', 'precipitation', 'precipitation_intensity', 'pressure', 'reactive_energy', 'reactive_power', 'signal_strength', 'sound_pressure', 'speed', 'sulphur_dioxide', 'temperature', 'temperature_delta', 'volatile_organic_compounds', 'volatile_organic_compounds_parts', 'voltage', 'volume', 'volume_storage', 'volume_flow_rate', 'water', 'weight', 'wind_direction', 'wind_speed'] | None)

• unit_of_measurement (str | None)

• state_class (Literal['measurement', 'measurement_angle', 'total', 'total_increasing'] | None)

• options (list[str] | None)

• creation_config (ExtraConfig | None)

async create_threshold_binary_sensor(servent_id, name, entity_id, *, lower=None, upper=None, hysteresis=0.0, default_state=None, fixed_attributes=None, entity_category=None, disabled_by_default=False, app_name=None, device_class=None, creation_config=None)

Return type:

ServEntThresholdBinarySensor

Parameters:

• servent_id (str)

• name (str)

• entity_id (EntityID)

• lower (float | None)

• upper (float | None)

• hysteresis (float)

• default_state (bool | None)

• fixed_attributes (dict[str, str | bool | float] | None)

• entity_category (Literal['config', 'diagnostic'] | None)

• disabled_by_default (bool)

• app_name (str | None)

• device_class (Literal['battery', 'battery_charging', 'carbon_monoxide', 'cold', 'connectivity', 'door', 'garage_door', 'gas', 'heat', 'light', 'lock', 'moisture', 'motion', 'moving', 'occupancy', 'opening', 'plug', 'power', 'presence', 'problem', 'running', 'safety', 'smoke', 'sound', 'tamper', 'update', 'vibration', 'window'] | None)

• creation_config (ExtraConfig | None)

async create_binary_sensor(servent_id, name, *, default_state=None, fixed_attributes=None, entity_category=None, disabled_by_default=False, app_name=None, device_class=None, creation_config=None)

Return type:

ServEntBinarySensor

Parameters:

• servent_id (str)

• name (str)

• default_state (bool | None)

• fixed_attributes (dict[str, str | bool | float] | None)

• entity_category (Literal['config', 'diagnostic'] | None)

• disabled_by_default (bool)

• app_name (str | None)

• device_class (Literal['battery', 'battery_charging', 'carbon_monoxide', 'cold', 'connectivity', 'door', 'garage_door', 'gas', 'heat', 'light', 'lock', 'moisture', 'motion', 'moving', 'occupancy', 'opening', 'plug', 'power', 'presence', 'problem', 'running', 'safety', 'smoke', 'sound', 'tamper', 'update', 'vibration', 'window'] | None)

• creation_config (ExtraConfig | None)

async create_number(servent_id, name, mode, *, default_state=None, fixed_attributes=None, entity_category=None, disabled_by_default=False, app_name=None, device_class=None, unit_of_measurement=None, min_value=None, max_value=None, step=None, creation_config=None)

Return type:

ServEntNumber

Parameters:

• servent_id (str)

• name (str)

• mode (Literal['auto', 'box', 'slider'])

• default_state (float | None)

• fixed_attributes (dict[str, str | bool | float] | None)

• entity_category (Literal['config', 'diagnostic'] | None)

• disabled_by_default (bool)

• app_name (str | None)

• device_class (Literal['absolute_humidity', 'apparent_power', 'aqi', 'area', 'atmospheric_pressure', 'battery', 'blood_glucose_concentration', 'carbon_monoxide', 'carbon_dioxide', 'conductivity', 'current', 'data_rate', 'data_size', 'distance', 'duration', 'energy', 'energy_distance', 'energy_storage', 'frequency', 'gas', 'humidity', 'illuminance', 'irradiance', 'moisture', 'monetary', 'nitrogen_dioxide', 'nitrogen_monoxide', 'nitrous_oxide', 'ozone', 'ph', 'pm1', 'pm10', 'pm25', 'pm4', 'power_factor', 'power', 'precipitation', 'precipitation_intensity', 'pressure', 'reactive_energy', 'reactive_power', 'signal_strength', 'sound_pressure', 'speed', 'sulphur_dioxide', 'temperature', 'temperature_delta', 'volatile_organic_compounds', 'volatile_organic_compounds_parts', 'voltage', 'volume', 'volume_storage', 'volume_flow_rate', 'water', 'weight', 'wind_direction', 'wind_speed'] | None)

• unit_of_measurement (str | None)

• min_value (float | None)

• max_value (float | None)

• step (float | None)

• creation_config (ExtraConfig | None)

async create_select(servent_id, name, options, *, default_state=None, fixed_attributes=None, entity_category=None, disabled_by_default=False, app_name=None, creation_config=None)

Return type:

ServEntSelect

Parameters:

• servent_id (str)

• name (str)

• options (list[str])

• default_state (str | None)

• fixed_attributes (dict[str, str | bool | float] | None)

• entity_category (Literal['config', 'diagnostic'] | None)

• disabled_by_default (bool)

• app_name (str | None)

• creation_config (ExtraConfig | None)

async create_switch(servent_id, name, *, default_state=None, fixed_attributes=None, entity_category=None, disabled_by_default=False, app_name=None, device_class=None, creation_config=None)

Return type:

ServEntSwitch

Parameters:

• servent_id (str)

• name (str)

• default_state (bool | None)

• fixed_attributes (dict[str, str | bool | float] | None)

• entity_category (Literal['config', 'diagnostic'] | None)

• disabled_by_default (bool)

• app_name (str | None)

• device_class (Literal['outlet', 'switch'] | None)

• creation_config (ExtraConfig | None)

async listen_button_press(callback, button_name, event_name_to_fire, *, event_data=None, device_class=None, entity_category=None, disabled_by_default=False, creation_config=None)

Return type:

ServEntButton

Parameters:

• callback (EventListenerCallbackFull | EventListenerCallbackWithEventName | EventListenerCallbackWithEventData | Callable[[], None | Awaitable[None]])

• button_name (str)

• event_name_to_fire (str)

• event_data (dict[str, Any] | None)

• device_class (Literal['identify', 'restart', 'update'] | None)

• entity_category (Literal['config', 'diagnostic'] | None)

• disabled_by_default (bool)

• creation_config (ExtraConfig | None)

Logger Plugin

Logging functionality scoped to each app.

class domovoy.plugins.logger.LogLevels(*values)

Bases: Enum

CRITICAL = 50

ERROR = 40

WARNING = 30

INFO = 20

DEBUG = 10

NOTSET = 0

class domovoy.plugins.logger.LoggerCallbackRegistration(id, callback, minimum_log_level)

Bases: object

Parameters:

• id (str)

• callback (Callable[[str], Awaitable[None]])

• minimum_log_level (LogLevels)

id: str

callback: Callable[[str], Awaitable[None]]

minimum_log_level: LogLevels

class domovoy.plugins.logger.LoggerPlugin(name, wrapper)

Bases: AppPlugin

Parameters:

• name (str)

• wrapper (AppWrapper)

listen_log(minimim_log_level, callback, *callback_args, **callback_kwargs)

Return type:

str

Parameters:

• minimim_log_level (LogLevels)

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

• callback_args (~P)

• callback_kwargs (~P)

cancel_callback(callback_id)

Return type:

None

Parameters:

callback_id (str)

set_level(level)

Return type:

None

Parameters:

level (LogLevels)

trace(msg, *args, exc_info=None, stack_info=False, stacklevel=1, extra=None, **kwargs)

Return type:

None

Parameters:

• msg (object)

• args (object)

• exc_info (Any)

• stack_info (bool)

• stacklevel (int)

• extra (Mapping[str, object] | None)

• kwargs (object)

debug(msg, *args, exc_info=None, stack_info=False, stacklevel=1, extra=None, **kwargs)

Return type:

None

Parameters:

• msg (object)

• args (object)

• exc_info (Any)

• stack_info (bool)

• stacklevel (int)

• extra (Mapping[str, object] | None)

• kwargs (object)

info(msg, *args, exc_info=None, stack_info=False, stacklevel=1, extra=None, **kwargs)

Return type:

None

Parameters:

• msg (object)

• args (object)

• exc_info (Any)

• stack_info (bool)

• stacklevel (int)

• extra (Mapping[str, object] | None)

• kwargs (object)

warning(msg, *args, exc_info=None, stack_info=False, stacklevel=1, extra=None, **kwargs)

Return type:

None

Parameters:

• msg (object)

• args (object)

• exc_info (Any)

• stack_info (bool)

• stacklevel (int)

• extra (Mapping[str, object] | None)

• kwargs (object)

error(msg, *args, exc_info=None, stack_info=False, stacklevel=1, extra=None, **kwargs)

Return type:

None

Parameters:

• msg (object)

• args (object)

• exc_info (Any)

• stack_info (bool)

• stacklevel (int)

• extra (Mapping[str, object] | None)

• kwargs (object)

exception(msg, *args, exc_info=None, stack_info=False, stacklevel=1, extra=None, **kwargs)

Return type:

None

Parameters:

• msg (object)

• args (object)

• exc_info (Any)

• stack_info (bool)

• stacklevel (int)

• extra (Mapping[str, object] | None)

• kwargs (object)

critical(msg, *args, exc_info=None, stack_info=False, stacklevel=1, extra=None, **kwargs)

Return type:

None

Parameters:

• msg (object)

• args (object)

• exc_info (Any)

• stack_info (bool)

• stacklevel (int)

• extra (Mapping[str, object] | None)

• kwargs (object)

log(level, msg, *args, exc_info=None, stack_info=False, stacklevel=1, extra=None, **kwargs)

Return type:

None

Parameters:

• level (int)

• msg (object)

• args (object)

• exc_info (Any)

• stack_info (bool)

• stacklevel (int)

• extra (Mapping[str, object] | None)

• kwargs (object)

Meta Plugin

App metadata and lifecycle control.

class domovoy.plugins.meta.MetaPlugin(name, wrapper, app_restart_callback)

Bases: AppPlugin

Parameters:

• name (str)

• wrapper (AppWrapper)

• app_restart_callback (Callable[[], Awaitable[None]])

get_app_name()

Return type:

str

get_filepath()

Return type:

str

get_module_name()

Return type:

str

get_class_name()

Return type:

str

get_status()

Return type:

AppStatus

get_config_tz()

Return type:

tzinfo

async restart_app()

Return type:

None

get_plugin(plugin_type, name=None)

Return type:

TypeVar(T, bound= AppPlugin) | None

Parameters:

• plugin_type (type[T])

• name (str | None)

get_app_engine_stats()

Return type:

AppEngineStats

Time Plugin

Time utilities for timezone-aware operations.

class domovoy.plugins.time.TimePlugin(name, wrapper)

Bases: AppPlugin

Parameters:

• name (str)

• wrapper (AppWrapper)

async sleep_for(interval)

Return type:

None

Parameters:

interval (Interval)

parse_date(string)

Return type:

datetime

Parameters:

string (str)

timedelta_from_now(date, target_tz=None)

Return type:

timedelta

Parameters:

• date (datetime | str)

• target_tz (BaseTzInfo | None)

datetime_to_local_timezone(dt)

Return type:

datetime

Parameters:

dt (datetime)

parse_timestamp_to_local_timezone(timestamp)

Return type:

datetime

Parameters:

timestamp (float)

now(*, tz=None)

Return type:

datetime

Parameters:

tz (tzinfo | None)

today(*, tz=None)

Return type:

date

Parameters:

tz (tzinfo | None)

make_datetime_aware(*, dt, tz=None)

Return type:

datetime

Parameters:

• dt (datetime)

• tz (tzinfo | None)

is_datetime_aware(dt)

Return type:

bool

Parameters:

dt (datetime)

is_now_between_dawn_and_dusk()

Return type:

bool

is_between_dawn_and_dusk(dt)

Return type:

bool

Parameters:

dt (datetime)

Utils Plugin

General utility functions.

class domovoy.plugins.utils.UtilsPlugin(name, wrapper)

Bases: AppPlugin

Parameters:

• name (str)

• wrapper (AppWrapper)

parse_float(val, default=None)

Return type:

float | TypeVar(TFloat, bound= float | None)

Parameters:

• val (object)

• default (TFloat)

parse_int(val, default=None)

Return type:

int | TypeVar(TInt, bound= float | None)

Parameters:

• val (object)

• default (TInt)

parse_int_or_float(val)

Return type:

int | float | None

Parameters:

val (object)

run_async(callback, *args, **kwargs)

Return type:

Task[TypeVar(T)]

Parameters:

• callback (Callable[[~P], Awaitable[T]])

• args (~P)

• kwargs (~P)

run_in_executor(callback, *args, **kwargs)

Return type:

Future[TypeVar(T)]

Parameters:

• callback (Callable[[~P], T])

• args (~P)

• kwargs (~P)

async sleep_for(interval)

Return type:

None

Parameters:

interval (Interval)

parse_date(string)

Return type:

datetime

Parameters:

string (str)

timedelta_from_now(date, target_tz=None)

Return type:

timedelta

Parameters:

• date (datetime | str)

• target_tz (BaseTzInfo | None)