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

    async def on_initialize(self) -> None:
        self.mark_ready(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))

    def turn_on(self, entity_id: str | StrEnum, domain: str = "homeassistant", **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 (default: ``"homeassistant"``).
                This calls the generic ``homeassistant.turn_on`` service, which is deprecated
                in Home Assistant 2024.x in favor of domain-specific services. For lights,
                pass ``domain="light"``; for switches, pass ``domain="switch"``."""

        return self.task_bucket.run_sync(self._api.turn_on(entity_id, domain, **data))

    def turn_off(self, entity_id: str | StrEnum, domain: str = "homeassistant"):
        """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 (default: ``"homeassistant"``).
                This calls the generic ``homeassistant.turn_off`` service, which is deprecated
                in Home Assistant 2024.x in favor of domain-specific services. For lights,
                pass ``domain="light"``; for switches, pass ``domain="switch"``."""

        return self.task_bucket.run_sync(self._api.turn_off(entity_id, domain))

    def toggle_service(self, entity_id: str | StrEnum, domain: str = "homeassistant"):
        """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 (default: ``"homeassistant"``).
                This calls the generic ``homeassistant.toggle`` service, which is deprecated
                in Home Assistant 2024.x in favor of domain-specific services. For lights,
                pass ``domain="light"``; for switches, pass ``domain="switch"``."""

        return self.task_bucket.run_sync(self._api.toggle_service(entity_id, domain))

    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_state_value_typed(self, entity_id: str) -> "Any":
        """Get the value of a specific entity's state, converted to the correct type for that state.

        The return type here is Any due to the dynamic nature of this conversion, but the return type
        at runtime will match the expected value type for the specific state class of the 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.

        Raises:
            TypeError: If the model is not a valid StateType subclass.

        Warning:
            For states like `SensorState` the value type in Hassette is `str`, even if the sensor represents a number,
            as we cannot be sure of the actual type without additional context. For these cases, you are responsible
            for converting the string to the desired type."""

        return self.task_bucket.run_sync(self._api.get_state_value_typed(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]:
        """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]:
        """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]:
        """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 | 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))

    def list_input_booleans(self) -> list[InputBooleanRecord]:
        """List all stored input_boolean helpers.

        Returns:
            List of InputBooleanRecord instances representing stored configs."""

        return self.task_bucket.run_sync(self._api.list_input_booleans())

    def create_input_boolean(self, params: CreateInputBooleanParams) -> InputBooleanRecord:
        """Create a new input_boolean helper.

        Args:
            params: Parameters for the new helper.

        Returns:
            The stored record returned by Home Assistant."""

        return self.task_bucket.run_sync(self._api.create_input_boolean(params))

    def update_input_boolean(self, helper_id: str, params: UpdateInputBooleanParams) -> InputBooleanRecord:
        """Update an existing input_boolean helper.

        Args:
            helper_id: The ID of the helper to update.
            params: Fields to update (unset fields are left unchanged).

        Returns:
            The updated stored record."""

        return self.task_bucket.run_sync(self._api.update_input_boolean(helper_id, params))

    def delete_input_boolean(self, helper_id: str) -> None:
        """Delete an input_boolean helper.

        Args:
            helper_id: The ID of the helper to delete."""

        return self.task_bucket.run_sync(self._api.delete_input_boolean(helper_id))

    def list_input_numbers(self) -> list[InputNumberRecord]:
        """List all stored input_number helpers.

        Returns:
            List of InputNumberRecord instances representing stored configs."""

        return self.task_bucket.run_sync(self._api.list_input_numbers())

    def create_input_number(self, params: CreateInputNumberParams) -> InputNumberRecord:
        """Create a new input_number helper.

        Args:
            params: Parameters for the new helper.

        Returns:
            The stored record returned by Home Assistant."""

        return self.task_bucket.run_sync(self._api.create_input_number(params))

    def update_input_number(self, helper_id: str, params: UpdateInputNumberParams) -> InputNumberRecord:
        """Update an existing input_number helper.

        Args:
            helper_id: The ID of the helper to update.
            params: Fields to update (unset fields are left unchanged).

        Returns:
            The updated stored record."""

        return self.task_bucket.run_sync(self._api.update_input_number(helper_id, params))

    def delete_input_number(self, helper_id: str) -> None:
        """Delete an input_number helper.

        Args:
            helper_id: The ID of the helper to delete."""

        return self.task_bucket.run_sync(self._api.delete_input_number(helper_id))

    def list_input_texts(self) -> list[InputTextRecord]:
        """List all stored input_text helpers.

        Returns:
            List of InputTextRecord instances representing stored configs."""

        return self.task_bucket.run_sync(self._api.list_input_texts())

    def create_input_text(self, params: CreateInputTextParams) -> InputTextRecord:
        """Create a new input_text helper.

        Args:
            params: Parameters for the new helper.

        Returns:
            The stored record returned by Home Assistant."""

        return self.task_bucket.run_sync(self._api.create_input_text(params))

    def update_input_text(self, helper_id: str, params: UpdateInputTextParams) -> InputTextRecord:
        """Update an existing input_text helper.

        Args:
            helper_id: The ID of the helper to update.
            params: Fields to update (unset fields are left unchanged).

        Returns:
            The updated stored record."""

        return self.task_bucket.run_sync(self._api.update_input_text(helper_id, params))

    def delete_input_text(self, helper_id: str) -> None:
        """Delete an input_text helper.

        Args:
            helper_id: The ID of the helper to delete."""

        return self.task_bucket.run_sync(self._api.delete_input_text(helper_id))

    def list_input_selects(self) -> list[InputSelectRecord]:
        """List all stored input_select helpers.

        Returns:
            List of InputSelectRecord instances representing stored configs."""

        return self.task_bucket.run_sync(self._api.list_input_selects())

    def create_input_select(self, params: CreateInputSelectParams) -> InputSelectRecord:
        """Create a new input_select helper.

        Args:
            params: Parameters for the new helper.

        Returns:
            The stored record returned by Home Assistant."""

        return self.task_bucket.run_sync(self._api.create_input_select(params))

    def update_input_select(self, helper_id: str, params: UpdateInputSelectParams) -> InputSelectRecord:
        """Update an existing input_select helper.

        Args:
            helper_id: The ID of the helper to update.
            params: Fields to update (unset fields are left unchanged).

        Returns:
            The updated stored record."""

        return self.task_bucket.run_sync(self._api.update_input_select(helper_id, params))

    def delete_input_select(self, helper_id: str) -> None:
        """Delete an input_select helper.

        Args:
            helper_id: The ID of the helper to delete."""

        return self.task_bucket.run_sync(self._api.delete_input_select(helper_id))

    def list_input_datetimes(self) -> list[InputDatetimeRecord]:
        """List all stored input_datetime helpers.

        Returns:
            List of InputDatetimeRecord instances representing stored configs."""

        return self.task_bucket.run_sync(self._api.list_input_datetimes())

    def create_input_datetime(self, params: CreateInputDatetimeParams) -> InputDatetimeRecord:
        """Create a new input_datetime helper.

        Args:
            params: Parameters for the new helper.

        Returns:
            The stored record returned by Home Assistant."""

        return self.task_bucket.run_sync(self._api.create_input_datetime(params))

    def update_input_datetime(self, helper_id: str, params: UpdateInputDatetimeParams) -> InputDatetimeRecord:
        """Update an existing input_datetime helper.

        Args:
            helper_id: The ID of the helper to update.
            params: Fields to update (unset fields are left unchanged).

        Returns:
            The updated stored record."""

        return self.task_bucket.run_sync(self._api.update_input_datetime(helper_id, params))

    def delete_input_datetime(self, helper_id: str) -> None:
        """Delete an input_datetime helper.

        Args:
            helper_id: The ID of the helper to delete."""

        return self.task_bucket.run_sync(self._api.delete_input_datetime(helper_id))

    def list_input_buttons(self) -> list[InputButtonRecord]:
        """List all stored input_button helpers.

        Returns:
            List of InputButtonRecord instances representing stored configs."""

        return self.task_bucket.run_sync(self._api.list_input_buttons())

    def create_input_button(self, params: CreateInputButtonParams) -> InputButtonRecord:
        """Create a new input_button helper.

        Args:
            params: Parameters for the new helper.

        Returns:
            The stored record returned by Home Assistant."""

        return self.task_bucket.run_sync(self._api.create_input_button(params))

    def update_input_button(self, helper_id: str, params: UpdateInputButtonParams) -> InputButtonRecord:
        """Update an existing input_button helper.

        Args:
            helper_id: The ID of the helper to update.
            params: Fields to update (unset fields are left unchanged).

        Returns:
            The updated stored record."""

        return self.task_bucket.run_sync(self._api.update_input_button(helper_id, params))

    def delete_input_button(self, helper_id: str) -> None:
        """Delete an input_button helper.

        Args:
            helper_id: The ID of the helper to delete."""

        return self.task_bucket.run_sync(self._api.delete_input_button(helper_id))

    def list_counters(self) -> list[CounterRecord]:
        """List all stored counter helpers.

        Returns:
            List of CounterRecord instances representing stored configs."""

        return self.task_bucket.run_sync(self._api.list_counters())

    def create_counter(self, params: CreateCounterParams) -> CounterRecord:
        """Create a new counter helper.

        Args:
            params: Parameters for the new helper.

        Returns:
            The stored record returned by Home Assistant."""

        return self.task_bucket.run_sync(self._api.create_counter(params))

    def update_counter(self, helper_id: str, params: UpdateCounterParams) -> CounterRecord:
        """Update an existing counter helper (stored config, not live value).

        Args:
            helper_id: The ID of the helper to update.
            params: Fields to update (unset fields are left unchanged).

        Returns:
            The updated stored record."""

        return self.task_bucket.run_sync(self._api.update_counter(helper_id, params))

    def delete_counter(self, helper_id: str) -> None:
        """Delete a counter helper.

        Args:
            helper_id: The ID of the helper to delete."""

        return self.task_bucket.run_sync(self._api.delete_counter(helper_id))

    def list_timers(self) -> list[TimerRecord]:
        """List all stored timer helpers.

        Returns:
            List of TimerRecord instances representing stored configs."""

        return self.task_bucket.run_sync(self._api.list_timers())

    def create_timer(self, params: CreateTimerParams) -> TimerRecord:
        """Create a new timer helper.

        Args:
            params: Parameters for the new helper.

        Returns:
            The stored record returned by Home Assistant."""

        return self.task_bucket.run_sync(self._api.create_timer(params))

    def update_timer(self, helper_id: str, params: UpdateTimerParams) -> TimerRecord:
        """Update an existing timer helper.

        Args:
            helper_id: The ID of the helper to update.
            params: Fields to update (unset fields are left unchanged).

        Returns:
            The updated stored record."""

        return self.task_bucket.run_sync(self._api.update_timer(helper_id, params))

    def delete_timer(self, helper_id: str) -> None:
        """Delete a timer helper.

        Args:
            helper_id: The ID of the helper to delete."""

        return self.task_bucket.run_sync(self._api.delete_timer(helper_id))

    def increment_counter(self, entity_id: str) -> None:
        """Increment a counter entity's current value (live state, not stored config).

        Args:
            entity_id: The entity ID of the counter (e.g. ``"counter.motion_count"``)."""

        return self.task_bucket.run_sync(self._api.increment_counter(entity_id))

    def decrement_counter(self, entity_id: str) -> None:
        """Decrement a counter entity's current value (live state, not stored config).

        Args:
            entity_id: The entity ID of the counter (e.g. ``"counter.motion_count"``)."""

        return self.task_bucket.run_sync(self._api.decrement_counter(entity_id))

    def reset_counter(self, entity_id: str) -> None:
        """Reset a counter entity's value to its configured initial (live state, not stored config).

        Args:
            entity_id: The entity ID of the counter (e.g. ``"counter.motion_count"``)."""

        return self.task_bucket.run_sync(self._api.reset_counter(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))

turn_on(entity_id: str | StrEnum, domain: str = 'homeassistant', **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	The domain to use for the service call (default: "homeassistant"). This calls the generic homeassistant.turn_on service, which is deprecated in Home Assistant 2024.x in favor of domain-specific services. For lights, pass domain="light"; for switches, pass domain="switch".	'homeassistant'

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

def turn_on(self, entity_id: str | StrEnum, domain: str = "homeassistant", **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 (default: ``"homeassistant"``).
            This calls the generic ``homeassistant.turn_on`` service, which is deprecated
            in Home Assistant 2024.x in favor of domain-specific services. For lights,
            pass ``domain="light"``; for switches, pass ``domain="switch"``."""

    return self.task_bucket.run_sync(self._api.turn_on(entity_id, domain, **data))

turn_off(entity_id: str | StrEnum, domain: str = 'homeassistant')

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	The domain to use for the service call (default: "homeassistant"). This calls the generic homeassistant.turn_off service, which is deprecated in Home Assistant 2024.x in favor of domain-specific services. For lights, pass domain="light"; for switches, pass domain="switch".	'homeassistant'

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

def turn_off(self, entity_id: str | StrEnum, domain: str = "homeassistant"):
    """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 (default: ``"homeassistant"``).
            This calls the generic ``homeassistant.turn_off`` service, which is deprecated
            in Home Assistant 2024.x in favor of domain-specific services. For lights,
            pass ``domain="light"``; for switches, pass ``domain="switch"``."""

    return self.task_bucket.run_sync(self._api.turn_off(entity_id, domain))

toggle_service(entity_id: str | StrEnum, domain: str = 'homeassistant')

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	The domain to use for the service call (default: "homeassistant"). This calls the generic homeassistant.toggle service, which is deprecated in Home Assistant 2024.x in favor of domain-specific services. For lights, pass domain="light"; for switches, pass domain="switch".	'homeassistant'

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

def toggle_service(self, entity_id: str | StrEnum, domain: str = "homeassistant"):
    """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 (default: ``"homeassistant"``).
            This calls the generic ``homeassistant.toggle`` service, which is deprecated
            in Home Assistant 2024.x in favor of domain-specific services. For lights,
            pass ``domain="light"``; for switches, pass ``domain="switch"``."""

    return self.task_bucket.run_sync(self._api.toggle_service(entity_id, domain))

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_state_value_typed(entity_id: str) -> Any

Get the value of a specific entity's state, converted to the correct type for that state.

The return type here is Any due to the dynamic nature of this conversion, but the return type at runtime will match the expected value type for the specific state class of the entity.

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 converted to the specified model type.

Raises:

Type	Description
TypeError	If the model is not a valid StateType subclass.

Warning

For states like SensorState the value type in Hassette is str, even if the sensor represents a number, as we cannot be sure of the actual type without additional context. For these cases, you are responsible for converting the string to the desired type.

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

def get_state_value_typed(self, entity_id: str) -> "Any":
    """Get the value of a specific entity's state, converted to the correct type for that state.

    The return type here is Any due to the dynamic nature of this conversion, but the return type
    at runtime will match the expected value type for the specific state class of the 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.

    Raises:
        TypeError: If the model is not a valid StateType subclass.

    Warning:
        For states like `SensorState` the value type in Hassette is `str`, even if the sensor represents a number,
        as we cannot be sure of the actual type without additional context. For these cases, you are responsible
        for converting the string to the desired type."""

    return self.task_bucket.run_sync(self._api.get_state_value_typed(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]

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]	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]:
    """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]

Get the list of calendars.

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

def get_calendars(self) -> list[dict]:
    """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]

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]	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]:
    """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 | None = None) -> str

Render a template with given variables.

Parameters:

Name	Type	Description	Default
template	str	The template string to render.	required
variables	dict | 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 | 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))

list_input_booleans() -> list[InputBooleanRecord]

List all stored input_boolean helpers.

Returns:

Type	Description
list[InputBooleanRecord]	List of InputBooleanRecord instances representing stored configs.

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

def list_input_booleans(self) -> list[InputBooleanRecord]:
    """List all stored input_boolean helpers.

    Returns:
        List of InputBooleanRecord instances representing stored configs."""

    return self.task_bucket.run_sync(self._api.list_input_booleans())

create_input_boolean(params: CreateInputBooleanParams) -> InputBooleanRecord

Create a new input_boolean helper.

Parameters:

Name	Type	Description	Default
params	CreateInputBooleanParams	Parameters for the new helper.	required

Returns:

Type	Description
InputBooleanRecord	The stored record returned by Home Assistant.

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

def create_input_boolean(self, params: CreateInputBooleanParams) -> InputBooleanRecord:
    """Create a new input_boolean helper.

    Args:
        params: Parameters for the new helper.

    Returns:
        The stored record returned by Home Assistant."""

    return self.task_bucket.run_sync(self._api.create_input_boolean(params))

update_input_boolean(helper_id: str, params: UpdateInputBooleanParams) -> InputBooleanRecord

Update an existing input_boolean helper.

Parameters:

Name	Type	Description	Default
helper_id	str	The ID of the helper to update.	required
params	UpdateInputBooleanParams	Fields to update (unset fields are left unchanged).	required

Returns:

Type	Description
InputBooleanRecord	The updated stored record.

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

def update_input_boolean(self, helper_id: str, params: UpdateInputBooleanParams) -> InputBooleanRecord:
    """Update an existing input_boolean helper.

    Args:
        helper_id: The ID of the helper to update.
        params: Fields to update (unset fields are left unchanged).

    Returns:
        The updated stored record."""

    return self.task_bucket.run_sync(self._api.update_input_boolean(helper_id, params))

delete_input_boolean(helper_id: str) -> None

Delete an input_boolean helper.

Parameters:

Name	Type	Description	Default
helper_id	str	The ID of the helper to delete.	required

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

def delete_input_boolean(self, helper_id: str) -> None:
    """Delete an input_boolean helper.

    Args:
        helper_id: The ID of the helper to delete."""

    return self.task_bucket.run_sync(self._api.delete_input_boolean(helper_id))

list_input_numbers() -> list[InputNumberRecord]

List all stored input_number helpers.

Returns:

Type	Description
list[InputNumberRecord]	List of InputNumberRecord instances representing stored configs.

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

def list_input_numbers(self) -> list[InputNumberRecord]:
    """List all stored input_number helpers.

    Returns:
        List of InputNumberRecord instances representing stored configs."""

    return self.task_bucket.run_sync(self._api.list_input_numbers())

create_input_number(params: CreateInputNumberParams) -> InputNumberRecord

Create a new input_number helper.

Parameters:

Name	Type	Description	Default
params	CreateInputNumberParams	Parameters for the new helper.	required

Returns:

Type	Description
InputNumberRecord	The stored record returned by Home Assistant.

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

def create_input_number(self, params: CreateInputNumberParams) -> InputNumberRecord:
    """Create a new input_number helper.

    Args:
        params: Parameters for the new helper.

    Returns:
        The stored record returned by Home Assistant."""

    return self.task_bucket.run_sync(self._api.create_input_number(params))

update_input_number(helper_id: str, params: UpdateInputNumberParams) -> InputNumberRecord

Update an existing input_number helper.

Parameters:

Name	Type	Description	Default
helper_id	str	The ID of the helper to update.	required
params	UpdateInputNumberParams	Fields to update (unset fields are left unchanged).	required

Returns:

Type	Description
InputNumberRecord	The updated stored record.

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

def update_input_number(self, helper_id: str, params: UpdateInputNumberParams) -> InputNumberRecord:
    """Update an existing input_number helper.

    Args:
        helper_id: The ID of the helper to update.
        params: Fields to update (unset fields are left unchanged).

    Returns:
        The updated stored record."""

    return self.task_bucket.run_sync(self._api.update_input_number(helper_id, params))

delete_input_number(helper_id: str) -> None

Delete an input_number helper.

Parameters:

Name	Type	Description	Default
helper_id	str	The ID of the helper to delete.	required

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

def delete_input_number(self, helper_id: str) -> None:
    """Delete an input_number helper.

    Args:
        helper_id: The ID of the helper to delete."""

    return self.task_bucket.run_sync(self._api.delete_input_number(helper_id))

list_input_texts() -> list[InputTextRecord]

List all stored input_text helpers.

Returns:

Type	Description
list[InputTextRecord]	List of InputTextRecord instances representing stored configs.

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

def list_input_texts(self) -> list[InputTextRecord]:
    """List all stored input_text helpers.

    Returns:
        List of InputTextRecord instances representing stored configs."""

    return self.task_bucket.run_sync(self._api.list_input_texts())

create_input_text(params: CreateInputTextParams) -> InputTextRecord

Create a new input_text helper.

Parameters:

Name	Type	Description	Default
params	CreateInputTextParams	Parameters for the new helper.	required

Returns:

Type	Description
InputTextRecord	The stored record returned by Home Assistant.

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

def create_input_text(self, params: CreateInputTextParams) -> InputTextRecord:
    """Create a new input_text helper.

    Args:
        params: Parameters for the new helper.

    Returns:
        The stored record returned by Home Assistant."""

    return self.task_bucket.run_sync(self._api.create_input_text(params))

update_input_text(helper_id: str, params: UpdateInputTextParams) -> InputTextRecord

Update an existing input_text helper.

Parameters:

Name	Type	Description	Default
helper_id	str	The ID of the helper to update.	required
params	UpdateInputTextParams	Fields to update (unset fields are left unchanged).	required

Returns:

Type	Description
InputTextRecord	The updated stored record.

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

def update_input_text(self, helper_id: str, params: UpdateInputTextParams) -> InputTextRecord:
    """Update an existing input_text helper.

    Args:
        helper_id: The ID of the helper to update.
        params: Fields to update (unset fields are left unchanged).

    Returns:
        The updated stored record."""

    return self.task_bucket.run_sync(self._api.update_input_text(helper_id, params))

delete_input_text(helper_id: str) -> None

Delete an input_text helper.

Parameters:

Name	Type	Description	Default
helper_id	str	The ID of the helper to delete.	required

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

def delete_input_text(self, helper_id: str) -> None:
    """Delete an input_text helper.

    Args:
        helper_id: The ID of the helper to delete."""

    return self.task_bucket.run_sync(self._api.delete_input_text(helper_id))

list_input_selects() -> list[InputSelectRecord]

List all stored input_select helpers.

Returns:

Type	Description
list[InputSelectRecord]	List of InputSelectRecord instances representing stored configs.

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

def list_input_selects(self) -> list[InputSelectRecord]:
    """List all stored input_select helpers.

    Returns:
        List of InputSelectRecord instances representing stored configs."""

    return self.task_bucket.run_sync(self._api.list_input_selects())

create_input_select(params: CreateInputSelectParams) -> InputSelectRecord

Create a new input_select helper.

Parameters:

Name	Type	Description	Default
params	CreateInputSelectParams	Parameters for the new helper.	required

Returns:

Type	Description
InputSelectRecord	The stored record returned by Home Assistant.

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

def create_input_select(self, params: CreateInputSelectParams) -> InputSelectRecord:
    """Create a new input_select helper.

    Args:
        params: Parameters for the new helper.

    Returns:
        The stored record returned by Home Assistant."""

    return self.task_bucket.run_sync(self._api.create_input_select(params))

update_input_select(helper_id: str, params: UpdateInputSelectParams) -> InputSelectRecord

Update an existing input_select helper.

Parameters:

Name	Type	Description	Default
helper_id	str	The ID of the helper to update.	required
params	UpdateInputSelectParams	Fields to update (unset fields are left unchanged).	required

Returns:

Type	Description
InputSelectRecord	The updated stored record.

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

def update_input_select(self, helper_id: str, params: UpdateInputSelectParams) -> InputSelectRecord:
    """Update an existing input_select helper.

    Args:
        helper_id: The ID of the helper to update.
        params: Fields to update (unset fields are left unchanged).

    Returns:
        The updated stored record."""

    return self.task_bucket.run_sync(self._api.update_input_select(helper_id, params))

delete_input_select(helper_id: str) -> None

Delete an input_select helper.

Parameters:

Name	Type	Description	Default
helper_id	str	The ID of the helper to delete.	required

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

def delete_input_select(self, helper_id: str) -> None:
    """Delete an input_select helper.

    Args:
        helper_id: The ID of the helper to delete."""

    return self.task_bucket.run_sync(self._api.delete_input_select(helper_id))

list_input_datetimes() -> list[InputDatetimeRecord]

List all stored input_datetime helpers.

Returns:

Type	Description
list[InputDatetimeRecord]	List of InputDatetimeRecord instances representing stored configs.

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

def list_input_datetimes(self) -> list[InputDatetimeRecord]:
    """List all stored input_datetime helpers.

    Returns:
        List of InputDatetimeRecord instances representing stored configs."""

    return self.task_bucket.run_sync(self._api.list_input_datetimes())

create_input_datetime(params: CreateInputDatetimeParams) -> InputDatetimeRecord

Create a new input_datetime helper.

Parameters:

Name	Type	Description	Default
params	CreateInputDatetimeParams	Parameters for the new helper.	required

Returns:

Type	Description
InputDatetimeRecord	The stored record returned by Home Assistant.

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

def create_input_datetime(self, params: CreateInputDatetimeParams) -> InputDatetimeRecord:
    """Create a new input_datetime helper.

    Args:
        params: Parameters for the new helper.

    Returns:
        The stored record returned by Home Assistant."""

    return self.task_bucket.run_sync(self._api.create_input_datetime(params))

update_input_datetime(helper_id: str, params: UpdateInputDatetimeParams) -> InputDatetimeRecord

Update an existing input_datetime helper.

Parameters:

Name	Type	Description	Default
helper_id	str	The ID of the helper to update.	required
params	UpdateInputDatetimeParams	Fields to update (unset fields are left unchanged).	required

Returns:

Type	Description
InputDatetimeRecord	The updated stored record.

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

def update_input_datetime(self, helper_id: str, params: UpdateInputDatetimeParams) -> InputDatetimeRecord:
    """Update an existing input_datetime helper.

    Args:
        helper_id: The ID of the helper to update.
        params: Fields to update (unset fields are left unchanged).

    Returns:
        The updated stored record."""

    return self.task_bucket.run_sync(self._api.update_input_datetime(helper_id, params))

delete_input_datetime(helper_id: str) -> None

Delete an input_datetime helper.

Parameters:

Name	Type	Description	Default
helper_id	str	The ID of the helper to delete.	required

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

def delete_input_datetime(self, helper_id: str) -> None:
    """Delete an input_datetime helper.

    Args:
        helper_id: The ID of the helper to delete."""

    return self.task_bucket.run_sync(self._api.delete_input_datetime(helper_id))

list_input_buttons() -> list[InputButtonRecord]

List all stored input_button helpers.

Returns:

Type	Description
list[InputButtonRecord]	List of InputButtonRecord instances representing stored configs.

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

def list_input_buttons(self) -> list[InputButtonRecord]:
    """List all stored input_button helpers.

    Returns:
        List of InputButtonRecord instances representing stored configs."""

    return self.task_bucket.run_sync(self._api.list_input_buttons())

create_input_button(params: CreateInputButtonParams) -> InputButtonRecord

Create a new input_button helper.

Parameters:

Name	Type	Description	Default
params	CreateInputButtonParams	Parameters for the new helper.	required

Returns:

Type	Description
InputButtonRecord	The stored record returned by Home Assistant.

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

def create_input_button(self, params: CreateInputButtonParams) -> InputButtonRecord:
    """Create a new input_button helper.

    Args:
        params: Parameters for the new helper.

    Returns:
        The stored record returned by Home Assistant."""

    return self.task_bucket.run_sync(self._api.create_input_button(params))

update_input_button(helper_id: str, params: UpdateInputButtonParams) -> InputButtonRecord

Update an existing input_button helper.

Parameters:

Name	Type	Description	Default
helper_id	str	The ID of the helper to update.	required
params	UpdateInputButtonParams	Fields to update (unset fields are left unchanged).	required

Returns:

Type	Description
InputButtonRecord	The updated stored record.

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

def update_input_button(self, helper_id: str, params: UpdateInputButtonParams) -> InputButtonRecord:
    """Update an existing input_button helper.

    Args:
        helper_id: The ID of the helper to update.
        params: Fields to update (unset fields are left unchanged).

    Returns:
        The updated stored record."""

    return self.task_bucket.run_sync(self._api.update_input_button(helper_id, params))

delete_input_button(helper_id: str) -> None

Delete an input_button helper.

Parameters:

Name	Type	Description	Default
helper_id	str	The ID of the helper to delete.	required

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

def delete_input_button(self, helper_id: str) -> None:
    """Delete an input_button helper.

    Args:
        helper_id: The ID of the helper to delete."""

    return self.task_bucket.run_sync(self._api.delete_input_button(helper_id))

list_counters() -> list[CounterRecord]

List all stored counter helpers.

Returns:

Type	Description
list[CounterRecord]	List of CounterRecord instances representing stored configs.

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

def list_counters(self) -> list[CounterRecord]:
    """List all stored counter helpers.

    Returns:
        List of CounterRecord instances representing stored configs."""

    return self.task_bucket.run_sync(self._api.list_counters())

create_counter(params: CreateCounterParams) -> CounterRecord

Create a new counter helper.

Parameters:

Name	Type	Description	Default
params	CreateCounterParams	Parameters for the new helper.	required

Returns:

Type	Description
CounterRecord	The stored record returned by Home Assistant.

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

def create_counter(self, params: CreateCounterParams) -> CounterRecord:
    """Create a new counter helper.

    Args:
        params: Parameters for the new helper.

    Returns:
        The stored record returned by Home Assistant."""

    return self.task_bucket.run_sync(self._api.create_counter(params))

update_counter(helper_id: str, params: UpdateCounterParams) -> CounterRecord

Update an existing counter helper (stored config, not live value).

Parameters:

Name	Type	Description	Default
helper_id	str	The ID of the helper to update.	required
params	UpdateCounterParams	Fields to update (unset fields are left unchanged).	required

Returns:

Type	Description
CounterRecord	The updated stored record.

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

def update_counter(self, helper_id: str, params: UpdateCounterParams) -> CounterRecord:
    """Update an existing counter helper (stored config, not live value).

    Args:
        helper_id: The ID of the helper to update.
        params: Fields to update (unset fields are left unchanged).

    Returns:
        The updated stored record."""

    return self.task_bucket.run_sync(self._api.update_counter(helper_id, params))

delete_counter(helper_id: str) -> None

Delete a counter helper.

Parameters:

Name	Type	Description	Default
helper_id	str	The ID of the helper to delete.	required

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

def delete_counter(self, helper_id: str) -> None:
    """Delete a counter helper.

    Args:
        helper_id: The ID of the helper to delete."""

    return self.task_bucket.run_sync(self._api.delete_counter(helper_id))

list_timers() -> list[TimerRecord]

List all stored timer helpers.

Returns:

Type	Description
list[TimerRecord]	List of TimerRecord instances representing stored configs.

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

def list_timers(self) -> list[TimerRecord]:
    """List all stored timer helpers.

    Returns:
        List of TimerRecord instances representing stored configs."""

    return self.task_bucket.run_sync(self._api.list_timers())

create_timer(params: CreateTimerParams) -> TimerRecord

Create a new timer helper.

Parameters:

Name	Type	Description	Default
params	CreateTimerParams	Parameters for the new helper.	required

Returns:

Type	Description
TimerRecord	The stored record returned by Home Assistant.

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

def create_timer(self, params: CreateTimerParams) -> TimerRecord:
    """Create a new timer helper.

    Args:
        params: Parameters for the new helper.

    Returns:
        The stored record returned by Home Assistant."""

    return self.task_bucket.run_sync(self._api.create_timer(params))

update_timer(helper_id: str, params: UpdateTimerParams) -> TimerRecord

Update an existing timer helper.

Parameters:

Name	Type	Description	Default
helper_id	str	The ID of the helper to update.	required
params	UpdateTimerParams	Fields to update (unset fields are left unchanged).	required

Returns:

Type	Description
TimerRecord	The updated stored record.

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

def update_timer(self, helper_id: str, params: UpdateTimerParams) -> TimerRecord:
    """Update an existing timer helper.

    Args:
        helper_id: The ID of the helper to update.
        params: Fields to update (unset fields are left unchanged).

    Returns:
        The updated stored record."""

    return self.task_bucket.run_sync(self._api.update_timer(helper_id, params))

delete_timer(helper_id: str) -> None

Delete a timer helper.

Parameters:

Name	Type	Description	Default
helper_id	str	The ID of the helper to delete.	required

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

def delete_timer(self, helper_id: str) -> None:
    """Delete a timer helper.

    Args:
        helper_id: The ID of the helper to delete."""

    return self.task_bucket.run_sync(self._api.delete_timer(helper_id))

increment_counter(entity_id: str) -> None

Increment a counter entity's current value (live state, not stored config).

Parameters:

Name	Type	Description	Default
entity_id	str	The entity ID of the counter (e.g. "counter.motion_count").	required

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

def increment_counter(self, entity_id: str) -> None:
    """Increment a counter entity's current value (live state, not stored config).

    Args:
        entity_id: The entity ID of the counter (e.g. ``"counter.motion_count"``)."""

    return self.task_bucket.run_sync(self._api.increment_counter(entity_id))

decrement_counter(entity_id: str) -> None

Decrement a counter entity's current value (live state, not stored config).

Parameters:

Name	Type	Description	Default
entity_id	str	The entity ID of the counter (e.g. "counter.motion_count").	required

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

def decrement_counter(self, entity_id: str) -> None:
    """Decrement a counter entity's current value (live state, not stored config).

    Args:
        entity_id: The entity ID of the counter (e.g. ``"counter.motion_count"``)."""

    return self.task_bucket.run_sync(self._api.decrement_counter(entity_id))

reset_counter(entity_id: str) -> None

Reset a counter entity's value to its configured initial (live state, not stored config).

Parameters:

Name	Type	Description	Default
entity_id	str	The entity ID of the counter (e.g. "counter.motion_count").	required

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

def reset_counter(self, entity_id: str) -> None:
    """Reset a counter entity's value to its configured initial (live state, not stored config).

    Args:
        entity_id: The entity ID of the counter (e.g. ``"counter.motion_count"``)."""

    return self.task_bucket.run_sync(self._api.reset_counter(entity_id))