Sync

Auto-generated synchronous facade for Api.

Do not edit this file directly.

It is generated from api.Api by codegen/src/hassette_codegen/sync_facade/.

ApiSyncFacade

Bases: Resource

Synchronous facade for the API service.

This class provides synchronous methods that wrap the asynchronous methods of the Api class, allowing for blocking calls in a synchronous context.

These methods must not be called from within the event loop; doing so raises a RuntimeError. Use the asynchronous methods on Api directly when operating within an event loop.

Source code in src/hassette/api/sync.py

class ApiSyncFacade(Resource):
    """Synchronous facade for the API service.

    This class provides synchronous methods that wrap the asynchronous methods of the Api class,
    allowing for blocking calls in a synchronous context.

    These methods must not be called from within the event loop; doing so raises a RuntimeError.
    Use the asynchronous methods on ``Api`` directly when operating within an event loop.
    """

    _api: "Api"

    def __init__(self, hassette: "Hassette", *, api: "Api", parent: Resource | None = None) -> None:
        super().__init__(hassette, parent=parent)
        self._api = api
        self.helpers = self.add_child(HelperClientSyncFacade, helpers=self._api.helpers)

    async def on_initialize(self) -> None:
        mark_ready(self, reason="Synchronous API facade initialized")

    @property
    def config_log_level(self) -> LOG_LEVEL_TYPE:
        return self.hassette.config.logging.api

    def ws_send_and_wait(self, **data: Any) -> Any:
        """Send a WebSocket message and wait for a response."""
        return self.task_bucket.run_sync(self._api.ws_send_and_wait(**data))

    def ws_send_json(self, **data: Any) -> None:
        """Send a WebSocket message without waiting for a response."""
        return self.task_bucket.run_sync(self._api.ws_send_json(**data))

    def rest_request(
        self,
        method: str,
        url: str,
        params: dict[str, Any] | None = None,
        data: dict[str, Any] | None = None,
        suppress_error_message: bool = False,
        **kwargs: Any,
    ) -> aiohttp.ClientResponse:
        """Make a REST request to the Home Assistant API.

        Args:
            method: The HTTP method to use (e.g., "GET", "POST").
            url: The URL endpoint for the request.
            params: Query parameters for the request.
            data: JSON payload for the request.
            suppress_error_message: Whether to suppress error messages.

        Returns:
            The response from the API.
        """
        return self.task_bucket.run_sync(
            self._api.rest_request(method, url, params, data, suppress_error_message, **kwargs)
        )

    def get_rest_request(self, url: str, params: dict[str, Any] | None = None, **kwargs: Any) -> aiohttp.ClientResponse:
        """Make a GET request to the Home Assistant API.

        Args:
            url: The URL endpoint for the request.
            params: Query parameters for the request.
            kwargs: Additional keyword arguments to pass to the request.

        Returns:
            The response from the API.
        """
        return self.task_bucket.run_sync(self._api.get_rest_request(url, params, **kwargs))

    def post_rest_request(self, url: str, data: dict[str, Any] | None = None, **kwargs: Any) -> aiohttp.ClientResponse:
        """Make a POST request to the Home Assistant API.

        Args:
            url: The URL endpoint for the request.
            data: JSON payload for the request.
            kwargs: Additional keyword arguments to pass to the request.

        Returns:
            The response from the API.
        """
        return self.task_bucket.run_sync(self._api.post_rest_request(url, data, **kwargs))

    def delete_rest_request(self, url: str, **kwargs: Any) -> aiohttp.ClientResponse:
        """Make a DELETE request to the Home Assistant API.

        Args:
            url: The URL endpoint for the request.
            kwargs: Additional keyword arguments to pass to the request.

        Returns:
            The response from the API.
        """
        return self.task_bucket.run_sync(self._api.delete_rest_request(url, **kwargs))

    def get_states_raw(self) -> list["HassStateDict"]:
        """Get all entities in Home Assistant as raw dictionaries.

        Returns:
            A list of states as dictionaries.
        """
        return self.task_bucket.run_sync(self._api.get_states_raw())

    def get_states(self) -> list["BaseState"]:
        """Get all entities in Home Assistant, converted to their appropriate state types.

        If a state fails to convert, it is skipped with an error logged. If there is no registered
        state class for a domain, the generic BaseState is used.

        Returns:
            A list of states, converted to their appropriate state types.
        """
        return self.task_bucket.run_sync(self._api.get_states())

    def get_config(self) -> dict[str, Any]:
        """Get the Home Assistant configuration.

        Returns:
            The configuration data.
        """
        return self.task_bucket.run_sync(self._api.get_config())

    def get_services(self) -> dict[str, Any]:
        """Get the available services in Home Assistant.

        Returns:
            The services data.
        """
        return self.task_bucket.run_sync(self._api.get_services())

    def get_panels(self) -> dict[str, Any]:
        """Get the available panels in Home Assistant.

        Returns:
            The panels data.
        """
        return self.task_bucket.run_sync(self._api.get_panels())

    def fire_event(self, event_type: str, event_data: dict[str, Any] | None = None) -> dict[str, Any]:
        """Fire a custom event in Home Assistant.

        Args:
            event_type: The type of the event to fire (e.g., "custom_event").
            event_data: Additional data to include with the event.

        Returns:
            The response from Home Assistant.
        """
        return self.task_bucket.run_sync(self._api.fire_event(event_type, event_data))

    def call_service(
        self,
        domain: str,
        service: str,
        target: dict[str, str] | dict[str, list[str]] | None = None,
        return_response: bool | None = False,
        **data: Any,
    ) -> ServiceResponse | None:
        """Call a Home Assistant service.

        Args:
            domain: The domain of the service (e.g., "light").
            service: The name of the service to call (e.g., "turn_on").
            target: Target entity IDs or areas.
            return_response: Whether to return the response from Home Assistant. Defaults to False.
            **data: Additional data to send with the service call.

        Returns:
            ServiceResponse | None: The response from Home Assistant if return_response is True. Otherwise None.
        """
        return self.task_bucket.run_sync(self._api.call_service(domain, service, target, return_response, **data))  # pyright: ignore[reportCallIssue, reportArgumentType]

    def turn_on(self, entity_id: str | StrEnum, domain: str | None = None, **data: Any) -> None:
        """Turn on a specific entity in Home Assistant.

        Args:
            entity_id: The ID of the entity to turn on (e.g., "light.office").
            domain: The domain to use for the service call. Defaults to the entity's domain,
                derived from ``entity_id`` (e.g., ``"light.office"`` derives ``"light"``). Pass
                explicitly to override — for example, ``domain="homeassistant"`` to use the
                generic (deprecated) service.
            **data: Additional service data forwarded to the service call.
        """
        return self.task_bucket.run_sync(self._api.turn_on(entity_id, domain, **data))

    def turn_off(self, entity_id: str | StrEnum, domain: str | None = None, **data: Any) -> None:
        """Turn off a specific entity in Home Assistant.

        Args:
            entity_id: The ID of the entity to turn off (e.g., "light.office").
            domain: The domain to use for the service call. Defaults to the entity's domain,
                derived from ``entity_id`` (e.g., ``"light.office"`` derives ``"light"``). Pass
                explicitly to override — for example, ``domain="homeassistant"`` to use the
                generic (deprecated) service.
            **data: Additional service data forwarded to the service call.
        """
        return self.task_bucket.run_sync(self._api.turn_off(entity_id, domain, **data))

    def toggle(self, entity_id: str | StrEnum, domain: str | None = None, **data: Any) -> None:
        """Toggle a specific entity in Home Assistant.

        Args:
            entity_id: The ID of the entity to toggle (e.g., "light.office").
            domain: The domain to use for the service call. Defaults to the entity's domain,
                derived from ``entity_id`` (e.g., ``"light.office"`` derives ``"light"``). Pass
                explicitly to override — for example, ``domain="homeassistant"`` to use the
                generic (deprecated) service.
            **data: Additional service data forwarded to the service call.
        """
        return self.task_bucket.run_sync(self._api.toggle(entity_id, domain, **data))

    def get_state_raw(self, entity_id: str) -> "HassStateDict":
        """Get the state of a specific entity.

        Args:
            entity_id: The ID of the entity to get the state for.

        Returns:
            The state of the entity as raw data.
        """
        return self.task_bucket.run_sync(self._api.get_state_raw(entity_id))

    def entity_exists(self, entity_id: str) -> bool:
        """Check if a specific entity exists.

        Args:
            entity_id: The ID of the entity to check.

        Returns:
            True if the entity exists, False otherwise.
        """
        return self.task_bucket.run_sync(self._api.entity_exists(entity_id))

    def get_entity(self, entity_id: str, model: type["EntityT"]) -> "EntityT":
        """Get an entity object for a specific entity.

        Args:
            entity_id: The ID of the entity to get.
            model: The model class to use for the entity.

        Returns:
            The entity object.
        """
        return self.task_bucket.run_sync(self._api.get_entity(entity_id, model))

    def get_entity_or_none(self, entity_id: str, model: type["EntityT"]) -> "EntityT | None":
        """Get an entity object for a specific entity, or None if it does not exist.

        Args:
            entity_id: The ID of the entity to get.
            model: The model class to use for the entity.

        Returns:
            The entity object, or None if it does not exist.
        """
        return self.task_bucket.run_sync(self._api.get_entity_or_none(entity_id, model))

    def get_state(self, entity_id: str) -> "BaseState":
        """Get the state of a specific entity.

        Args:
            entity_id: The ID of the entity to get the state for.

        Returns:
            The state of the entity converted to the specified model type.
        """
        return self.task_bucket.run_sync(self._api.get_state(entity_id))

    def get_state_or_none(self, entity_id: str) -> "BaseState | None":
        """Get the state of a specific entity, or None if it does not exist.

        Args:
            entity_id: The ID of the entity to get the state for.

        Returns:
            The state of the entity converted to the specified model type, or None if it does not exist.
        """
        return self.task_bucket.run_sync(self._api.get_state_or_none(entity_id))

    def get_state_value(self, entity_id: str) -> Any:
        """Get the state of a specific entity without converting it to a state object.

        Args:
            entity_id: The ID of the entity to get the state for.

        Returns:
            The state of the entity as raw data.

        Note:
            While most default methods in this library work with state objects for
            strong typing, this method is designed to return the raw state value,
            as it is likely overkill to convert it to a state object for simple state value retrieval.
        """
        return self.task_bucket.run_sync(self._api.get_state_value(entity_id))

    def get_attribute(self, entity_id: str, attribute: str) -> Any | FalseySentinel:
        """Get a specific attribute of an entity.

        Args:
            entity_id: The ID of the entity to get the attribute for.
            attribute: The name of the attribute to retrieve. Can be a dot-separated path for nested attributes.

        Returns:
            The value of the specified attribute, or MISSING_VALUE sentinel if the attribute does not exist.
        """
        return self.task_bucket.run_sync(self._api.get_attribute(entity_id, attribute))

    def get_history(
        self,
        entity_id: str,
        start_time: PlainDateTime | ZonedDateTime | Date | str,
        end_time: PlainDateTime | ZonedDateTime | Date | str | None = None,
        significant_changes_only: bool = False,
        minimal_response: bool = False,
        no_attributes: bool = False,
    ) -> list[HistoryEntry]:
        """Get the history of a specific entity.

        Args:
            entity_id: The ID of the entity to get the history for.
            start_time: The start time for the history range.
            end_time: The end time for the history range.
            significant_changes_only: Whether to only include significant changes.
            minimal_response: Whether to request a minimal response.
            no_attributes: Whether to exclude attributes from the response.

        Returns:
            A list of history entries for the specified entity.
        """
        return self.task_bucket.run_sync(
            self._api.get_history(
                entity_id, start_time, end_time, significant_changes_only, minimal_response, no_attributes
            )
        )

    def get_histories(
        self,
        entity_ids: list[str],
        start_time: PlainDateTime | ZonedDateTime | Date | str,
        end_time: PlainDateTime | ZonedDateTime | Date | str | None = None,
        significant_changes_only: bool = False,
        minimal_response: bool = False,
        no_attributes: bool = False,
    ) -> dict[str, list[HistoryEntry]]:
        """Get the history for multiple entities.

        Args:
            entity_ids: The IDs of the entities to get the history for.
            start_time: The start time for the history range.
            end_time: The end time for the history range.
            significant_changes_only: Whether to only include significant changes.
            minimal_response: Whether to request a minimal response.
            no_attributes: Whether to exclude attributes from the response.

        Returns:
            A dictionary mapping entity IDs to their respective history entries.
        """
        return self.task_bucket.run_sync(
            self._api.get_histories(
                entity_ids, start_time, end_time, significant_changes_only, minimal_response, no_attributes
            )
        )

    def get_logbook(
        self,
        entity_id: str,
        start_time: PlainDateTime | ZonedDateTime | Date | str,
        end_time: PlainDateTime | ZonedDateTime | Date | str,
    ) -> list[dict[str, Any]]:
        """Get the logbook entries for a specific entity.

        Args:
            entity_id: The ID of the entity to get the logbook entries for.
            start_time: The start time for the logbook range.
            end_time: The end time for the logbook range.

        Returns:
            A list of logbook entries for the specified entity.
        """
        return self.task_bucket.run_sync(self._api.get_logbook(entity_id, start_time, end_time))

    def set_state(self, entity_id: str | StrEnum, state: Any, attributes: dict[str, Any] | None = None) -> dict:
        """Set the state of a specific entity.

        Args:
            entity_id: The ID of the entity to set the state for.
            state: The new state value to set.
            attributes: Additional attributes to set for the entity.

        Returns:
            The response from Home Assistant after setting the state.
        """
        return self.task_bucket.run_sync(self._api.set_state(entity_id, state, attributes))

    def get_camera_image(
        self, entity_id: str, timestamp: PlainDateTime | ZonedDateTime | Date | str | None = None
    ) -> bytes:
        """Get the latest camera image for a specific entity.

        Args:
            entity_id: The ID of the camera entity to get the image for.
            timestamp: The timestamp for the image. If None, the latest image is returned.

        Returns:
            The camera image data.
        """
        return self.task_bucket.run_sync(self._api.get_camera_image(entity_id, timestamp))

    def get_calendars(self) -> list[dict[str, Any]]:
        """Get the list of calendars."""
        return self.task_bucket.run_sync(self._api.get_calendars())

    def get_calendar_events(
        self,
        calendar_id: str,
        start_time: PlainDateTime | ZonedDateTime | Date | str,
        end_time: PlainDateTime | ZonedDateTime | Date | str,
    ) -> list[dict[str, Any]]:
        """Get events from a specific calendar.

        Args:
            calendar_id: The ID of the calendar to get events from.
            start_time: The start time for the event range.
            end_time: The end time for the event range.

        Returns:
            A list of calendar events.
        """
        return self.task_bucket.run_sync(self._api.get_calendar_events(calendar_id, start_time, end_time))

    def render_template(self, template: str, variables: dict[str, Any] | None = None) -> str:
        """Render a template with given variables.

        Args:
            template: The template string to render.
            variables: Variables to use in the template.

        Returns:
            The rendered template result.
        """
        return self.task_bucket.run_sync(self._api.render_template(template, variables))

    def delete_entity(self, entity_id: str) -> None:
        """Delete a specific entity.

        Args:
            entity_id: The ID of the entity to delete.

        Raises:
            RuntimeError: If the deletion fails.
        """
        return self.task_bucket.run_sync(self._api.delete_entity(entity_id))

ws_send_and_wait(**data: Any) -> Any

Send a WebSocket message and wait for a response.

Source code in src/hassette/api/sync.py

def ws_send_and_wait(self, **data: Any) -> Any:
    """Send a WebSocket message and wait for a response."""
    return self.task_bucket.run_sync(self._api.ws_send_and_wait(**data))

ws_send_json(**data: Any) -> None

Send a WebSocket message without waiting for a response.

Source code in src/hassette/api/sync.py

def ws_send_json(self, **data: Any) -> None:
    """Send a WebSocket message without waiting for a response."""
    return self.task_bucket.run_sync(self._api.ws_send_json(**data))

rest_request(method: str, url: str, params: dict[str, Any] | None = None, data: dict[str, Any] | None = None, suppress_error_message: bool = False, **kwargs: Any) -> aiohttp.ClientResponse

Make a REST request to the Home Assistant API.

Parameters:

Name	Type	Description	Default
method	str	The HTTP method to use (e.g., "GET", "POST").	required
url	str	The URL endpoint for the request.	required
params	dict[str, Any] | None	Query parameters for the request.	None
data	dict[str, Any] | None	JSON payload for the request.	None
suppress_error_message	bool	Whether to suppress error messages.	False

Returns:

Type	Description
ClientResponse	The response from the API.

Source code in src/hassette/api/sync.py

def rest_request(
    self,
    method: str,
    url: str,
    params: dict[str, Any] | None = None,
    data: dict[str, Any] | None = None,
    suppress_error_message: bool = False,
    **kwargs: Any,
) -> aiohttp.ClientResponse:
    """Make a REST request to the Home Assistant API.

    Args:
        method: The HTTP method to use (e.g., "GET", "POST").
        url: The URL endpoint for the request.
        params: Query parameters for the request.
        data: JSON payload for the request.
        suppress_error_message: Whether to suppress error messages.

    Returns:
        The response from the API.
    """
    return self.task_bucket.run_sync(
        self._api.rest_request(method, url, params, data, suppress_error_message, **kwargs)
    )

get_rest_request(url: str, params: dict[str, Any] | None = None, **kwargs: Any) -> aiohttp.ClientResponse

Make a GET request to the Home Assistant API.

Parameters:

Name	Type	Description	Default
url	str	The URL endpoint for the request.	required
params	dict[str, Any] | None	Query parameters for the request.	None
kwargs	Any	Additional keyword arguments to pass to the request.	{}

Returns:

Type	Description
ClientResponse	The response from the API.

Source code in src/hassette/api/sync.py

def get_rest_request(self, url: str, params: dict[str, Any] | None = None, **kwargs: Any) -> aiohttp.ClientResponse:
    """Make a GET request to the Home Assistant API.

    Args:
        url: The URL endpoint for the request.
        params: Query parameters for the request.
        kwargs: Additional keyword arguments to pass to the request.

    Returns:
        The response from the API.
    """
    return self.task_bucket.run_sync(self._api.get_rest_request(url, params, **kwargs))

post_rest_request(url: str, data: dict[str, Any] | None = None, **kwargs: Any) -> aiohttp.ClientResponse

Make a POST request to the Home Assistant API.

Parameters:

Name	Type	Description	Default
url	str	The URL endpoint for the request.	required
data	dict[str, Any] | None	JSON payload for the request.	None
kwargs	Any	Additional keyword arguments to pass to the request.	{}

Returns:

Type	Description
ClientResponse	The response from the API.

Source code in src/hassette/api/sync.py

def post_rest_request(self, url: str, data: dict[str, Any] | None = None, **kwargs: Any) -> aiohttp.ClientResponse:
    """Make a POST request to the Home Assistant API.

    Args:
        url: The URL endpoint for the request.
        data: JSON payload for the request.
        kwargs: Additional keyword arguments to pass to the request.

    Returns:
        The response from the API.
    """
    return self.task_bucket.run_sync(self._api.post_rest_request(url, data, **kwargs))

delete_rest_request(url: str, **kwargs: Any) -> aiohttp.ClientResponse

Make a DELETE request to the Home Assistant API.

Parameters:

Name	Type	Description	Default
url	str	The URL endpoint for the request.	required
kwargs	Any	Additional keyword arguments to pass to the request.	{}

Returns:

Type	Description
ClientResponse	The response from the API.

Source code in src/hassette/api/sync.py

def delete_rest_request(self, url: str, **kwargs: Any) -> aiohttp.ClientResponse:
    """Make a DELETE request to the Home Assistant API.

    Args:
        url: The URL endpoint for the request.
        kwargs: Additional keyword arguments to pass to the request.

    Returns:
        The response from the API.
    """
    return self.task_bucket.run_sync(self._api.delete_rest_request(url, **kwargs))

get_states_raw() -> list[HassStateDict]

Get all entities in Home Assistant as raw dictionaries.

Returns:

Type	Description
list[HassStateDict]	A list of states as dictionaries.

Source code in src/hassette/api/sync.py

def get_states_raw(self) -> list["HassStateDict"]:
    """Get all entities in Home Assistant as raw dictionaries.

    Returns:
        A list of states as dictionaries.
    """
    return self.task_bucket.run_sync(self._api.get_states_raw())

get_states() -> list[BaseState]

Get all entities in Home Assistant, converted to their appropriate state types.

If a state fails to convert, it is skipped with an error logged. If there is no registered state class for a domain, the generic BaseState is used.

Returns:

Type	Description
list[BaseState]	A list of states, converted to their appropriate state types.

Source code in src/hassette/api/sync.py

def get_states(self) -> list["BaseState"]:
    """Get all entities in Home Assistant, converted to their appropriate state types.

    If a state fails to convert, it is skipped with an error logged. If there is no registered
    state class for a domain, the generic BaseState is used.

    Returns:
        A list of states, converted to their appropriate state types.
    """
    return self.task_bucket.run_sync(self._api.get_states())

get_config() -> dict[str, Any]

Get the Home Assistant configuration.

Returns:

Type	Description
dict[str, Any]	The configuration data.

Source code in src/hassette/api/sync.py

def get_config(self) -> dict[str, Any]:
    """Get the Home Assistant configuration.

    Returns:
        The configuration data.
    """
    return self.task_bucket.run_sync(self._api.get_config())

get_services() -> dict[str, Any]

Get the available services in Home Assistant.

Returns:

Type	Description
dict[str, Any]	The services data.

Source code in src/hassette/api/sync.py

def get_services(self) -> dict[str, Any]:
    """Get the available services in Home Assistant.

    Returns:
        The services data.
    """
    return self.task_bucket.run_sync(self._api.get_services())

get_panels() -> dict[str, Any]

Get the available panels in Home Assistant.

Returns:

Type	Description
dict[str, Any]	The panels data.

Source code in src/hassette/api/sync.py

def get_panels(self) -> dict[str, Any]:
    """Get the available panels in Home Assistant.

    Returns:
        The panels data.
    """
    return self.task_bucket.run_sync(self._api.get_panels())

fire_event(event_type: str, event_data: dict[str, Any] | None = None) -> dict[str, Any]

Fire a custom event in Home Assistant.

Parameters:

Name	Type	Description	Default
event_type	str	The type of the event to fire (e.g., "custom_event").	required
event_data	dict[str, Any] | None	Additional data to include with the event.	None

Returns:

Type	Description
dict[str, Any]	The response from Home Assistant.

Source code in src/hassette/api/sync.py

def fire_event(self, event_type: str, event_data: dict[str, Any] | None = None) -> dict[str, Any]:
    """Fire a custom event in Home Assistant.

    Args:
        event_type: The type of the event to fire (e.g., "custom_event").
        event_data: Additional data to include with the event.

    Returns:
        The response from Home Assistant.
    """
    return self.task_bucket.run_sync(self._api.fire_event(event_type, event_data))

call_service(domain: str, service: str, target: dict[str, str] | dict[str, list[str]] | None = None, return_response: bool | None = False, **data: Any) -> ServiceResponse | None

Call a Home Assistant service.

Parameters:

Name	Type	Description	Default
domain	str	The domain of the service (e.g., "light").	required
service	str	The name of the service to call (e.g., "turn_on").	required
target	dict[str, str] | dict[str, list[str]] | None	Target entity IDs or areas.	None
return_response	bool | None	Whether to return the response from Home Assistant. Defaults to False.	False
**data	Any	Additional data to send with the service call.	{}

Returns:

Type	Description
ServiceResponse | None	ServiceResponse | None: The response from Home Assistant if return_response is True. Otherwise None.

Source code in src/hassette/api/sync.py

def call_service(
    self,
    domain: str,
    service: str,
    target: dict[str, str] | dict[str, list[str]] | None = None,
    return_response: bool | None = False,
    **data: Any,
) -> ServiceResponse | None:
    """Call a Home Assistant service.

    Args:
        domain: The domain of the service (e.g., "light").
        service: The name of the service to call (e.g., "turn_on").
        target: Target entity IDs or areas.
        return_response: Whether to return the response from Home Assistant. Defaults to False.
        **data: Additional data to send with the service call.

    Returns:
        ServiceResponse | None: The response from Home Assistant if return_response is True. Otherwise None.
    """
    return self.task_bucket.run_sync(self._api.call_service(domain, service, target, return_response, **data))  # pyright: ignore[reportCallIssue, reportArgumentType]

turn_on(entity_id: str | StrEnum, domain: str | None = None, **data: Any) -> None

Turn on a specific entity in Home Assistant.

Parameters:

Name	Type	Description	Default
entity_id	str | StrEnum	The ID of the entity to turn on (e.g., "light.office").	required
domain	str | None	The domain to use for the service call. Defaults to the entity's domain, derived from entity_id (e.g., "light.office" derives "light"). Pass explicitly to override — for example, domain="homeassistant" to use the generic (deprecated) service.	None
**data	Any	Additional service data forwarded to the service call.	{}

Source code in src/hassette/api/sync.py

def turn_on(self, entity_id: str | StrEnum, domain: str | None = None, **data: Any) -> None:
    """Turn on a specific entity in Home Assistant.

    Args:
        entity_id: The ID of the entity to turn on (e.g., "light.office").
        domain: The domain to use for the service call. Defaults to the entity's domain,
            derived from ``entity_id`` (e.g., ``"light.office"`` derives ``"light"``). Pass
            explicitly to override — for example, ``domain="homeassistant"`` to use the
            generic (deprecated) service.
        **data: Additional service data forwarded to the service call.
    """
    return self.task_bucket.run_sync(self._api.turn_on(entity_id, domain, **data))

turn_off(entity_id: str | StrEnum, domain: str | None = None, **data: Any) -> None

Turn off a specific entity in Home Assistant.

Parameters:

Name	Type	Description	Default
entity_id	str | StrEnum	The ID of the entity to turn off (e.g., "light.office").	required
domain	str | None	The domain to use for the service call. Defaults to the entity's domain, derived from entity_id (e.g., "light.office" derives "light"). Pass explicitly to override — for example, domain="homeassistant" to use the generic (deprecated) service.	None
**data	Any	Additional service data forwarded to the service call.	{}

Source code in src/hassette/api/sync.py

def turn_off(self, entity_id: str | StrEnum, domain: str | None = None, **data: Any) -> None:
    """Turn off a specific entity in Home Assistant.

    Args:
        entity_id: The ID of the entity to turn off (e.g., "light.office").
        domain: The domain to use for the service call. Defaults to the entity's domain,
            derived from ``entity_id`` (e.g., ``"light.office"`` derives ``"light"``). Pass
            explicitly to override — for example, ``domain="homeassistant"`` to use the
            generic (deprecated) service.
        **data: Additional service data forwarded to the service call.
    """
    return self.task_bucket.run_sync(self._api.turn_off(entity_id, domain, **data))

toggle(entity_id: str | StrEnum, domain: str | None = None, **data: Any) -> None

Toggle a specific entity in Home Assistant.

Parameters:

Name	Type	Description	Default
entity_id	str | StrEnum	The ID of the entity to toggle (e.g., "light.office").	required
domain	str | None	The domain to use for the service call. Defaults to the entity's domain, derived from entity_id (e.g., "light.office" derives "light"). Pass explicitly to override — for example, domain="homeassistant" to use the generic (deprecated) service.	None
**data	Any	Additional service data forwarded to the service call.	{}

Source code in src/hassette/api/sync.py

def toggle(self, entity_id: str | StrEnum, domain: str | None = None, **data: Any) -> None:
    """Toggle a specific entity in Home Assistant.

    Args:
        entity_id: The ID of the entity to toggle (e.g., "light.office").
        domain: The domain to use for the service call. Defaults to the entity's domain,
            derived from ``entity_id`` (e.g., ``"light.office"`` derives ``"light"``). Pass
            explicitly to override — for example, ``domain="homeassistant"`` to use the
            generic (deprecated) service.
        **data: Additional service data forwarded to the service call.
    """
    return self.task_bucket.run_sync(self._api.toggle(entity_id, domain, **data))

get_state_raw(entity_id: str) -> HassStateDict

Get the state of a specific entity.

Parameters:

Name	Type	Description	Default
entity_id	str	The ID of the entity to get the state for.	required

Returns:

Type	Description
HassStateDict	The state of the entity as raw data.

Source code in src/hassette/api/sync.py

def get_state_raw(self, entity_id: str) -> "HassStateDict":
    """Get the state of a specific entity.

    Args:
        entity_id: The ID of the entity to get the state for.

    Returns:
        The state of the entity as raw data.
    """
    return self.task_bucket.run_sync(self._api.get_state_raw(entity_id))

entity_exists(entity_id: str) -> bool

Check if a specific entity exists.

Parameters:

Name	Type	Description	Default
entity_id	str	The ID of the entity to check.	required

Returns:

Type	Description
bool	True if the entity exists, False otherwise.

Source code in src/hassette/api/sync.py

def entity_exists(self, entity_id: str) -> bool:
    """Check if a specific entity exists.

    Args:
        entity_id: The ID of the entity to check.

    Returns:
        True if the entity exists, False otherwise.
    """
    return self.task_bucket.run_sync(self._api.entity_exists(entity_id))

get_entity(entity_id: str, model: type[EntityT]) -> EntityT

Get an entity object for a specific entity.

Parameters:

Name	Type	Description	Default
entity_id	str	The ID of the entity to get.	required
model	type[EntityT]	The model class to use for the entity.	required

Returns:

Type	Description
EntityT	The entity object.

Source code in src/hassette/api/sync.py

def get_entity(self, entity_id: str, model: type["EntityT"]) -> "EntityT":
    """Get an entity object for a specific entity.

    Args:
        entity_id: The ID of the entity to get.
        model: The model class to use for the entity.

    Returns:
        The entity object.
    """
    return self.task_bucket.run_sync(self._api.get_entity(entity_id, model))

get_entity_or_none(entity_id: str, model: type[EntityT]) -> EntityT | None

Get an entity object for a specific entity, or None if it does not exist.

Parameters:

Name	Type	Description	Default
entity_id	str	The ID of the entity to get.	required
model	type[EntityT]	The model class to use for the entity.	required

Returns:

Type	Description
EntityT | None	The entity object, or None if it does not exist.

Source code in src/hassette/api/sync.py

def get_entity_or_none(self, entity_id: str, model: type["EntityT"]) -> "EntityT | None":
    """Get an entity object for a specific entity, or None if it does not exist.

    Args:
        entity_id: The ID of the entity to get.
        model: The model class to use for the entity.

    Returns:
        The entity object, or None if it does not exist.
    """
    return self.task_bucket.run_sync(self._api.get_entity_or_none(entity_id, model))

get_state(entity_id: str) -> BaseState

Get the state of a specific entity.

Parameters:

Name	Type	Description	Default
entity_id	str	The ID of the entity to get the state for.	required

Returns:

Type	Description
BaseState	The state of the entity converted to the specified model type.

Source code in src/hassette/api/sync.py

def get_state(self, entity_id: str) -> "BaseState":
    """Get the state of a specific entity.

    Args:
        entity_id: The ID of the entity to get the state for.

    Returns:
        The state of the entity converted to the specified model type.
    """
    return self.task_bucket.run_sync(self._api.get_state(entity_id))

get_state_or_none(entity_id: str) -> BaseState | None

Get the state of a specific entity, or None if it does not exist.

Parameters:

Name	Type	Description	Default
entity_id	str	The ID of the entity to get the state for.	required

Returns:

Type	Description
BaseState | None	The state of the entity converted to the specified model type, or None if it does not exist.

Source code in src/hassette/api/sync.py

def get_state_or_none(self, entity_id: str) -> "BaseState | None":
    """Get the state of a specific entity, or None if it does not exist.

    Args:
        entity_id: The ID of the entity to get the state for.

    Returns:
        The state of the entity converted to the specified model type, or None if it does not exist.
    """
    return self.task_bucket.run_sync(self._api.get_state_or_none(entity_id))

get_state_value(entity_id: str) -> Any

Get the state of a specific entity without converting it to a state object.

Parameters:

Name	Type	Description	Default
entity_id	str	The ID of the entity to get the state for.	required

Returns:

Type	Description
Any	The state of the entity as raw data.

Note

While most default methods in this library work with state objects for strong typing, this method is designed to return the raw state value, as it is likely overkill to convert it to a state object for simple state value retrieval.

Source code in src/hassette/api/sync.py

def get_state_value(self, entity_id: str) -> Any:
    """Get the state of a specific entity without converting it to a state object.

    Args:
        entity_id: The ID of the entity to get the state for.

    Returns:
        The state of the entity as raw data.

    Note:
        While most default methods in this library work with state objects for
        strong typing, this method is designed to return the raw state value,
        as it is likely overkill to convert it to a state object for simple state value retrieval.
    """
    return self.task_bucket.run_sync(self._api.get_state_value(entity_id))

get_attribute(entity_id: str, attribute: str) -> Any | FalseySentinel

Get a specific attribute of an entity.

Parameters:

Name	Type	Description	Default
entity_id	str	The ID of the entity to get the attribute for.	required
attribute	str	The name of the attribute to retrieve. Can be a dot-separated path for nested attributes.	required

Returns:

Type	Description
Any | FalseySentinel	The value of the specified attribute, or MISSING_VALUE sentinel if the attribute does not exist.

Source code in src/hassette/api/sync.py

def get_attribute(self, entity_id: str, attribute: str) -> Any | FalseySentinel:
    """Get a specific attribute of an entity.

    Args:
        entity_id: The ID of the entity to get the attribute for.
        attribute: The name of the attribute to retrieve. Can be a dot-separated path for nested attributes.

    Returns:
        The value of the specified attribute, or MISSING_VALUE sentinel if the attribute does not exist.
    """
    return self.task_bucket.run_sync(self._api.get_attribute(entity_id, attribute))

get_history(entity_id: str, start_time: PlainDateTime | ZonedDateTime | Date | str, end_time: PlainDateTime | ZonedDateTime | Date | str | None = None, significant_changes_only: bool = False, minimal_response: bool = False, no_attributes: bool = False) -> list[HistoryEntry]

Get the history of a specific entity.

Parameters:

Name	Type	Description	Default
entity_id	str	The ID of the entity to get the history for.	required
start_time	PlainDateTime | ZonedDateTime | Date | str	The start time for the history range.	required
end_time	PlainDateTime | ZonedDateTime | Date | str | None	The end time for the history range.	None
significant_changes_only	bool	Whether to only include significant changes.	False
minimal_response	bool	Whether to request a minimal response.	False
no_attributes	bool	Whether to exclude attributes from the response.	False

Returns:

Type	Description
list[HistoryEntry]	A list of history entries for the specified entity.

Source code in src/hassette/api/sync.py

def get_history(
    self,
    entity_id: str,
    start_time: PlainDateTime | ZonedDateTime | Date | str,
    end_time: PlainDateTime | ZonedDateTime | Date | str | None = None,
    significant_changes_only: bool = False,
    minimal_response: bool = False,
    no_attributes: bool = False,
) -> list[HistoryEntry]:
    """Get the history of a specific entity.

    Args:
        entity_id: The ID of the entity to get the history for.
        start_time: The start time for the history range.
        end_time: The end time for the history range.
        significant_changes_only: Whether to only include significant changes.
        minimal_response: Whether to request a minimal response.
        no_attributes: Whether to exclude attributes from the response.

    Returns:
        A list of history entries for the specified entity.
    """
    return self.task_bucket.run_sync(
        self._api.get_history(
            entity_id, start_time, end_time, significant_changes_only, minimal_response, no_attributes
        )
    )

get_histories(entity_ids: list[str], start_time: PlainDateTime | ZonedDateTime | Date | str, end_time: PlainDateTime | ZonedDateTime | Date | str | None = None, significant_changes_only: bool = False, minimal_response: bool = False, no_attributes: bool = False) -> dict[str, list[HistoryEntry]]

Get the history for multiple entities.

Parameters:

Name	Type	Description	Default
entity_ids	list[str]	The IDs of the entities to get the history for.	required
start_time	PlainDateTime | ZonedDateTime | Date | str	The start time for the history range.	required
end_time	PlainDateTime | ZonedDateTime | Date | str | None	The end time for the history range.	None
significant_changes_only	bool	Whether to only include significant changes.	False
minimal_response	bool	Whether to request a minimal response.	False
no_attributes	bool	Whether to exclude attributes from the response.	False

Returns:

Type	Description
dict[str, list[HistoryEntry]]	A dictionary mapping entity IDs to their respective history entries.

Source code in src/hassette/api/sync.py

def get_histories(
    self,
    entity_ids: list[str],
    start_time: PlainDateTime | ZonedDateTime | Date | str,
    end_time: PlainDateTime | ZonedDateTime | Date | str | None = None,
    significant_changes_only: bool = False,
    minimal_response: bool = False,
    no_attributes: bool = False,
) -> dict[str, list[HistoryEntry]]:
    """Get the history for multiple entities.

    Args:
        entity_ids: The IDs of the entities to get the history for.
        start_time: The start time for the history range.
        end_time: The end time for the history range.
        significant_changes_only: Whether to only include significant changes.
        minimal_response: Whether to request a minimal response.
        no_attributes: Whether to exclude attributes from the response.

    Returns:
        A dictionary mapping entity IDs to their respective history entries.
    """
    return self.task_bucket.run_sync(
        self._api.get_histories(
            entity_ids, start_time, end_time, significant_changes_only, minimal_response, no_attributes
        )
    )

get_logbook(entity_id: str, start_time: PlainDateTime | ZonedDateTime | Date | str, end_time: PlainDateTime | ZonedDateTime | Date | str) -> list[dict[str, Any]]

Get the logbook entries for a specific entity.

Parameters:

Name	Type	Description	Default
entity_id	str	The ID of the entity to get the logbook entries for.	required
start_time	PlainDateTime | ZonedDateTime | Date | str	The start time for the logbook range.	required
end_time	PlainDateTime | ZonedDateTime | Date | str	The end time for the logbook range.	required

Returns:

Type	Description
list[dict[str, Any]]	A list of logbook entries for the specified entity.

Source code in src/hassette/api/sync.py

def get_logbook(
    self,
    entity_id: str,
    start_time: PlainDateTime | ZonedDateTime | Date | str,
    end_time: PlainDateTime | ZonedDateTime | Date | str,
) -> list[dict[str, Any]]:
    """Get the logbook entries for a specific entity.

    Args:
        entity_id: The ID of the entity to get the logbook entries for.
        start_time: The start time for the logbook range.
        end_time: The end time for the logbook range.

    Returns:
        A list of logbook entries for the specified entity.
    """
    return self.task_bucket.run_sync(self._api.get_logbook(entity_id, start_time, end_time))

set_state(entity_id: str | StrEnum, state: Any, attributes: dict[str, Any] | None = None) -> dict

Set the state of a specific entity.

Parameters:

Name	Type	Description	Default
entity_id	str | StrEnum	The ID of the entity to set the state for.	required
state	Any	The new state value to set.	required
attributes	dict[str, Any] | None	Additional attributes to set for the entity.	None

Returns:

Type	Description
dict	The response from Home Assistant after setting the state.

Source code in src/hassette/api/sync.py

def set_state(self, entity_id: str | StrEnum, state: Any, attributes: dict[str, Any] | None = None) -> dict:
    """Set the state of a specific entity.

    Args:
        entity_id: The ID of the entity to set the state for.
        state: The new state value to set.
        attributes: Additional attributes to set for the entity.

    Returns:
        The response from Home Assistant after setting the state.
    """
    return self.task_bucket.run_sync(self._api.set_state(entity_id, state, attributes))

get_camera_image(entity_id: str, timestamp: PlainDateTime | ZonedDateTime | Date | str | None = None) -> bytes

Get the latest camera image for a specific entity.

Parameters:

Name	Type	Description	Default
entity_id	str	The ID of the camera entity to get the image for.	required
timestamp	PlainDateTime | ZonedDateTime | Date | str | None	The timestamp for the image. If None, the latest image is returned.	None

Returns:

Type	Description
bytes	The camera image data.

Source code in src/hassette/api/sync.py

def get_camera_image(
    self, entity_id: str, timestamp: PlainDateTime | ZonedDateTime | Date | str | None = None
) -> bytes:
    """Get the latest camera image for a specific entity.

    Args:
        entity_id: The ID of the camera entity to get the image for.
        timestamp: The timestamp for the image. If None, the latest image is returned.

    Returns:
        The camera image data.
    """
    return self.task_bucket.run_sync(self._api.get_camera_image(entity_id, timestamp))

get_calendars() -> list[dict[str, Any]]

Get the list of calendars.

Source code in src/hassette/api/sync.py

def get_calendars(self) -> list[dict[str, Any]]:
    """Get the list of calendars."""
    return self.task_bucket.run_sync(self._api.get_calendars())

get_calendar_events(calendar_id: str, start_time: PlainDateTime | ZonedDateTime | Date | str, end_time: PlainDateTime | ZonedDateTime | Date | str) -> list[dict[str, Any]]

Get events from a specific calendar.

Parameters:

Name	Type	Description	Default
calendar_id	str	The ID of the calendar to get events from.	required
start_time	PlainDateTime | ZonedDateTime | Date | str	The start time for the event range.	required
end_time	PlainDateTime | ZonedDateTime | Date | str	The end time for the event range.	required

Returns:

Type	Description
list[dict[str, Any]]	A list of calendar events.

Source code in src/hassette/api/sync.py

def get_calendar_events(
    self,
    calendar_id: str,
    start_time: PlainDateTime | ZonedDateTime | Date | str,
    end_time: PlainDateTime | ZonedDateTime | Date | str,
) -> list[dict[str, Any]]:
    """Get events from a specific calendar.

    Args:
        calendar_id: The ID of the calendar to get events from.
        start_time: The start time for the event range.
        end_time: The end time for the event range.

    Returns:
        A list of calendar events.
    """
    return self.task_bucket.run_sync(self._api.get_calendar_events(calendar_id, start_time, end_time))

render_template(template: str, variables: dict[str, Any] | None = None) -> str

Render a template with given variables.

Parameters:

Name	Type	Description	Default
template	str	The template string to render.	required
variables	dict[str, Any] | None	Variables to use in the template.	None

Returns:

Type	Description
str	The rendered template result.

Source code in src/hassette/api/sync.py

def render_template(self, template: str, variables: dict[str, Any] | None = None) -> str:
    """Render a template with given variables.

    Args:
        template: The template string to render.
        variables: Variables to use in the template.

    Returns:
        The rendered template result.
    """
    return self.task_bucket.run_sync(self._api.render_template(template, variables))

delete_entity(entity_id: str) -> None

Delete a specific entity.

Parameters:

Name	Type	Description	Default
entity_id	str	The ID of the entity to delete.	required

Raises:

Type	Description
RuntimeError	If the deletion fails.

Source code in src/hassette/api/sync.py

def delete_entity(self, entity_id: str) -> None:
    """Delete a specific entity.

    Args:
        entity_id: The ID of the entity to delete.

    Raises:
        RuntimeError: If the deletion fails.
    """
    return self.task_bucket.run_sync(self._api.delete_entity(entity_id))