Add Websocket "config entries" methods (#213)

* Add from_json to BaseModel to reduce duplicated code

* Fix Websocket Error model by not requiring translation keys

* Add method to get non-user flows in progress

* Add disable/enable config entry methods

* Add ignore flow method

* Add method to get a filtered list of config entries

* Add get entry subentry method

* Add delete subentry method

* Fix typing

* Add Websocket endpoints to docstrings

* Add config_entries subscribe method

* Add testing

* Add from_json to BaseModel to reduce duplicated code

* Add method to get non-user flows in progress

* Add disable/enable config entry methods

* Add ignore flow method

* Add method to get a filtered list of config entries

* Add get entry subentry method

* Add delete subentry method

* Fix typing

* Add Websocket endpoints to docstrings

* Add config_entries subscribe method

* Add testing

* add missing testing.
Some updates to dependencies and conftest were also required.
Updated ruff version did formatting slightly different in a few files.

* update ruff commands in github cicd pipeline

* Update Python build_from version  and fix websocket client fixture type

* Fix test coverage for logbook and entity history tests

Use sun.red_sun entity for logbook tests (sun.sun has no logbook entries).
Replace for/else raise pattern with direct assertions in history tests.

---------

Co-authored-by: Nathan Larsen <minecraftcrusher100@gmail.com>
Co-authored-by: Adam Logan <adamlogan73@gmail.com>
Co-authored-by: Nate <nlarsen23.student@gmail.com>

Author: 3 people

.github/workflows/test-suite.yml

@@ -32,8 +32,10 @@ jobs:
         run: |
           pip install poetry
           poetry install --with styling
-      - name: Run Ruff
-        run: poetry run ruff homeassistant_api
+      - name: Run Ruff format
+        run: poetry run ruff format homeassistant_api
+      - name: Run Ruff linting
+        run: poetry run ruff check homeassistant_api
       - name: Run MyPy
         run: poetry run mypy homeassistant_api --show-error-codes
 

.pre-commit-config.yaml

@@ -10,7 +10,9 @@ repos:
     hooks:
       - id: trailing-whitespace
     rev: "v4.1.0"
-  - repo: https://github.com/charliermarsh/ruff-pre-commit
-    rev: 'v0.0.209'
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: 'v0.15.6'
     hooks:
-      - id: ruff
+      - id: ruff-format
+      - id: ruff-check
+      - id: ruff-format

compose.yml

@@ -9,7 +9,7 @@ services:
     build:
       context: .
       args:
-        BUILD_FROM: "python:3.9"
+        BUILD_FROM: "python:3.13"
     image: homeassistant-tests:latest
     volumes:
       - ./volumes/coverage:/app/coverage:rw

homeassistant_api/models/__init__.py

@@ -1,6 +1,21 @@
 """The Model objects for the entire library."""
 
 from .base import BaseModel
+from .config_entries import (
+    ConfigEntry,
+    ConfigEntryChange,
+    ConfigEntryDisabler,
+    ConfigEntryEvent,
+    ConfigEntryState,
+    ConfigFlowContext,
+    ConfigSubEntry,
+    DisableEnableResult,
+    DiscoveryKey,
+    FlowContext,
+    FlowResult,
+    FlowResultType,
+    IntegrationTypes,
+)
 from .domains import Domain, Service, ServiceField
 from .entity import Entity, Group
 from .events import Event
@@ -21,4 +36,17 @@
     "History",
     "LogbookEntry",
     "State",
+    "DisableEnableResult",
+    "DiscoveryKey",
+    "FlowContext",
+    "ConfigFlowContext",
+    "FlowResult",
+    "FlowResultType",
+    "IntegrationTypes",
+    "ConfigEntryDisabler",
+    "ConfigEntryState",
+    "ConfigEntry",
+    "ConfigSubEntry",
+    "ConfigEntryChange",
+    "ConfigEntryEvent",
 )

homeassistant_api/models/base.py

@@ -1,10 +1,13 @@
 """Module for Global Base Model Configuration inheritance."""
 
 from datetime import datetime
-from typing import Annotated
+from typing import Annotated, Any, Union
 
 from pydantic import BaseModel as PydanticBaseModel
 from pydantic import ConfigDict, PlainSerializer
+from typing_extensions import Self
+
+from homeassistant_api.utils import JSONType
 
 __all__ = (
     "BaseModel",
@@ -25,3 +28,9 @@ class BaseModel(PydanticBaseModel):
         validate_assignment=True,
         protected_namespaces=(),
     )
+
+    # TODO: Any being accepted is not ideal. Narrow it down.
+    @classmethod
+    def from_json(cls, json: Union[dict[str, JSONType], Any, None]) -> Self:
+        """Constructs Self model from json data"""
+        return cls.model_validate(json)

homeassistant_api/models/config_entries.py

@@ -0,0 +1,158 @@
+"""File for models used in responses from config entries."""
+
+import asyncio
+from enum import Enum
+from typing import Any, Container, Dict, Optional, Tuple, Union
+
+from .base import BaseModel
+
+
+class FlowResultType(Enum):
+    """Result type for a data entry flow."""
+
+    FORM = "form"
+    CREATE_ENTRY = "create_entry"
+    ABORT = "abort"
+    EXTERNAL_STEP = "external"
+    EXTERNAL_STEP_DONE = "external_done"
+    SHOW_PROGRESS = "progress"
+    SHOW_PROGRESS_DONE = "progress_done"
+    MENU = "menu"
+
+
+class DiscoveryKey(BaseModel):
+    """Serializable discovery key."""
+
+    domain: str
+    key: Union[str, Tuple[str, ...]]
+    version: int
+
+
+class FlowContext(BaseModel):
+    """Base flow context"""
+
+    show_advanced_options: Union[bool, None] = None
+    source: str
+
+
+class ConfigFlowContext(FlowContext):
+    """Context for config flow."""
+
+    alternative_domain: Optional[str] = None
+    configuration_url: Optional[str] = None
+    confirm_only: Optional[bool] = None
+    discovery_key: DiscoveryKey
+    entry_id: Optional[str] = None
+    title_placeholders: Optional[Dict[str, str]] = None
+    unique_id: Optional[str] = None
+
+
+class FlowResult(BaseModel):
+    """Base flow result ."""
+
+    context: ConfigFlowContext
+    data_schema: Optional[Any] = None
+    data: Optional[Dict[str, Any]] = None
+    description_placeholders: Optional[Dict[str, str]] = None
+    description: Optional[str] = None
+    errors: Optional[Dict[str, str]] = None
+    extra: Optional[str] = None
+    flow_id: str
+    handler: str
+    last_step: Optional[bool] = None
+    menu_options: Optional[Container[str]] = None
+    preview: Optional[str] = None
+    progress_action: Optional[str] = None
+    progress_task: Optional[asyncio.Task[Any]] = None
+    reason: Optional[str] = None
+    required: Optional[bool] = None
+    result: Optional[Any] = None
+    step_id: Optional[str] = None
+    title: Optional[str] = None
+    translation_domain: Optional[str] = None
+    type: Optional[FlowResultType] = None
+    url: Optional[str] = None
+
+
+class DisableEnableResult(BaseModel):
+    """Result from a disable/enable config entry call."""
+
+    require_restart: bool
+
+
+class IntegrationTypes(Enum):
+    """Types of integrations."""
+
+    ENTITY = "entity"
+    DEVICE = "device"
+    HARDWARE = "hardware"
+    HELPER = "helper"
+    HUB = "hub"
+    SERVICE = "service"
+    SYSTEM = "system"
+    VIRTUAL = "virtual"
+
+
+class ConfigEntryState(str, Enum):
+    """Config entry state."""
+
+    LOADED = "loaded"
+    SETUP_ERROR = "setup_error"
+    MIGRATION_ERROR = "migration_error"
+    SETUP_RETRY = "setup_retry"
+    NOT_LOADED = "not_loaded"
+    FAILED_UNLOAD = "failed_unload"
+    SETUP_IN_PROGRESS = "setup_in_progress"
+    UNLOAD_IN_PROGRESS = "unload_in_progress"
+
+
+class ConfigEntryDisabler(Enum):
+    """What disabled a config entry."""
+
+    USER = "user"
+
+
+class ConfigEntry(BaseModel):
+    """A configuration entry. This is the model that Home Assistant returns, but not what is used internally."""
+
+    created_at: float
+    entry_id: str
+    domain: str
+    modified_at: float
+    title: str
+    source: str
+    state: ConfigEntryState
+    supports_options: bool
+    supports_remove_device: bool
+    supports_unload: bool
+    supports_reconfigure: bool
+    supported_subentry_types: Dict[str, Dict[str, bool]]
+    pref_disable_new_entities: bool
+    pref_disable_polling: bool
+    disabled_by: Optional[ConfigEntryDisabler]
+    reason: Optional[str]
+    error_reason_translation_key: Optional[str]
+    error_reason_translation_placeholders: Optional[Dict[str, Any]]
+    num_subentries: int
+
+
+class ConfigSubEntry(BaseModel):
+    """A configuration sub-entry. This is the model that Home Assistant returns, but not what is used internally."""
+
+    subentry_id: str
+    subentry_type: str
+    title: str
+    unique_id: Optional[str]
+
+
+class ConfigEntryChange(str, Enum):
+    """What was changed in a config entry."""
+
+    ADDED = "added"
+    REMOVED = "removed"
+    UPDATED = "updated"
+
+
+class ConfigEntryEvent(BaseModel):
+    type: Optional[ConfigEntryChange]
+    entry: ConfigEntry

homeassistant_api/models/domains.py

@@ -18,6 +18,7 @@
 )
 
 from pydantic import Field
+from typing_extensions import Self, override
 
 from homeassistant_api.errors import RequestError
 from homeassistant_api.utils import JSONType
@@ -55,7 +56,14 @@ def __init__(
     )
 
     @classmethod
-    def from_json(
+    @override
+    def from_json(cls, json: Union[dict[str, JSONType], Any, None], **kwargs) -> Self:
+        raise ValueError(
+            f"`{cls.__name__}` does not support `from_json()`. Use `from_json_with_client()`"
+        )
+
+    @classmethod
+    def from_json_with_client(
         cls, json: Dict[str, JSONType], client: Union["Client", "WebsocketClient"]
     ) -> "Domain":
         """Constructs Domain and Service models from json data."""
@@ -375,9 +383,9 @@ class ServiceFieldSelectorObject(BaseModel):
 class ServiceFieldSelectorQRCode(BaseModel):
     data: str
     scale: Optional[Union[int, float]] = None
-    error_correction_level: Optional[ServiceFieldSelectorQRCodeErrorCorrectionLevel] = (
-        None
-    )
+    error_correction_level: Optional[
+        ServiceFieldSelectorQRCodeErrorCorrectionLevel
+    ] = None
     center_image: Optional[str] = None
 
 
@@ -582,7 +590,9 @@ class Service(BaseModel):
     target: Optional[ServiceFieldSelectorTarget] = None
     response: Optional[ServiceResponse] = None
 
-    def trigger(self, **service_data) -> Union[
+    def trigger(
+        self, **service_data
+    ) -> Union[
         Tuple[State, ...],
         Tuple[Tuple[State, ...], dict[str, JSONType]],
         dict[str, JSONType],
@@ -625,7 +635,9 @@ async def async_trigger(
                 **service_data,
             )
 
-    def __call__(self, **service_data) -> Union[
+    def __call__(
+        self, **service_data
+    ) -> Union[
         Union[
             Tuple[State, ...],
             Tuple[Tuple[State, ...], dict[str, JSONType]],

homeassistant_api/models/events.py

@@ -1,8 +1,9 @@
 """Event Model File"""
 
-from typing import TYPE_CHECKING, Optional
-
+from typing import TYPE_CHECKING, Any, Optional, Union
+from typing_extensions import Self
 from pydantic import Field
+from typing_extensions import override
 
 from homeassistant_api.utils import JSONType
 
@@ -40,6 +41,15 @@ async def async_fire(self, **event_data) -> str:
         return await self._client.async_fire_event(self.event, **event_data)
 
     @classmethod
-    def from_json(cls, json: dict[str, JSONType], client: "Client") -> "Event":
+    @override
+    def from_json(cls, json: Union[dict[str, JSONType], Any, None], **kwargs) -> Self:
+        raise ValueError(
+            f"`{cls.__name__}` does not support `from_json()`. Use `from_json_with_client()`"
+        )
+
+    @classmethod
+    def from_json_with_client(
+        cls, json: dict[str, JSONType], client: "Client"
+    ) -> "Event":
         """Constructs Event model from json data"""
         return cls(**json, _client=client)

homeassistant_api/models/states.py

@@ -30,11 +30,6 @@ class Context(BaseModel):
         description="Unique string identifying the user.",
     )
 
-    @classmethod
-    def from_json(cls, json: dict[str, JSONType]) -> "Context":
-        """Constructs Context model from json data"""
-        return cls.model_validate(json)
-
 
 class State(BaseModel):
     """A model representing a state of an entity."""
@@ -61,8 +56,3 @@ class State(BaseModel):
     context: Optional[Context] = Field(
         None, description="Provides information about the context of the state."
     )
-
-    @classmethod
-    def from_json(cls, json: dict[str, JSONType]) -> "State":
-        """Constructs State model from json data"""
-        return cls.model_validate(json)

homeassistant_api/models/websocket.py

@@ -1,10 +1,11 @@
 """A module defining the responses we expect from the websocket API."""
 
-from typing import Any, Literal, Optional, Union
+from typing import Any, List, Literal, Optional, Union
 
 from homeassistant_api.utils import JSONType
 
 from .base import BaseModel, DatetimeIsoField
+from .config_entries import ConfigEntryEvent
 from .states import Context
 
 __all__ = (
@@ -99,4 +100,4 @@ class EventResponse(BaseModel):
 
     id: int
     type: Literal["event"]
-    event: Union[FiredEvent, FiredTrigger, TemplateEvent]
+    event: Union[FiredEvent, FiredTrigger, TemplateEvent, List[ConfigEntryEvent]]