HomeAssistant-API 4.2.2.post1__tar.gz → 5.0.0__tar.gz

{homeassistant_api-4.2.2.post1 → homeassistant_api-5.0.0}/PKG-INFO

@@ -1,61 +1,93 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.3
 Name: HomeAssistant-API
-Version: 4.2.2.post1
+Version: 5.0.0
 Summary: Python Wrapper for Homeassistant's REST API
-Home-page: https://github.com/GrandMoff100/HomeAssistantAPI
 License: GPL-3.0-or-later
 Author: GrandMoff100
 Author-email: minecraftcrusher100@gmail.com
-Requires-Python: >=3.8,<4.0
+Requires-Python: >=3.9,<4.0
 Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.8
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Requires-Dist: aiohttp (>=3.8.1,<4.0.0)
 Requires-Dist: aiohttp-client-cache (>=0.6.1)
-Requires-Dist: pydantic (>=2.0)
+Requires-Dist: pydantic (>=2.0,<2.9)
 Requires-Dist: requests (>=2.27.1,<3.0.0)
 Requires-Dist: requests-cache (>=0.9.2,<0.10.0)
 Requires-Dist: simplejson (>=3.17.6,<4.0.0)
+Requires-Dist: websockets (>=14.1,<15.0)
 Project-URL: Documentation, https://homeassistantapi.readthedocs.io
+Project-URL: Homepage, https://github.com/GrandMoff100/HomeAssistantAPI
 Project-URL: Repository, https://github.com/GrandMoff100/HomeAssistantAPI
 Description-Content-Type: text/markdown
 
 # HomeassistantAPI
 
 [![Code Coverage](https://img.shields.io/codecov/c/github/GrandMoff100/HomeAssistantAPI/dev?style=for-the-badge&token=SJFC3HX5R1)](https://codecov.io/gh/GrandMoff100/HomeAssistantAPI)
-[![PyPI - Downloads](https://img.shields.io/pypi/dm/HomeAssistant-API?style=for-the-badge)](https://pypi.org/project/homeassistant_api)
+[![PyPI - Downloads](https://img.shields.io/pypi/dm/HomeAssistant-API?style=for-the-badge)](https://pypistats.org/packages/homeassistant-api)
 ![GitHub commits since latest release (by date including pre-releases)](https://img.shields.io/github/commits-since/GrandMoff100/HomeassistantAPI/latest/dev?include_prereleases&style=for-the-badge)
 [![Read the Docs (version)](https://img.shields.io/readthedocs/homeassistantapi?style=for-the-badge)](https://homeassistantapi.readthedocs.io/en/latest/?badge=latest)
 [![GitHub release (latest by date)](https://img.shields.io/github/v/release/GrandMoff100/HomeassistantAPI?style=for-the-badge)](https://github.com/GrandMoff100/HomeassistantAPI/releases)
 
 <a href="https://home-assistant.io">
-    <img src="https://github.com/GrandMoff100/HomeAssistantAPI/blob/7edb4e6298d37bda19c08b807613c6d351788491/docs/images/homeassistant-logo.png?raw=true" width="60%">
+    <img src="https://github.com/GrandMoff100/HomeAssistantAPI/blob/7edb4e6298d37bda19c08b807613c6d351788491/docs/images/homeassistant-logo.png?raw=true" width="80%">
 </a>
 
-## Python wrapper for Homeassistant's [REST API](https://developers.home-assistant.io/docs/api/rest/)
+## Python wrapper for Homeassistant's [Websocket API](https://developers.home-assistant.io/docs/api/websocket/) and [REST API](https://developers.home-assistant.io/docs/api/rest/)
 
-Here is a quick example.
+> Note: As of [this comment](https://github.com/home-assistant/architecture/discussions/1074#discussioncomment-9196867) the REST API is not getting any new features or endpoints.
+> However, it is not going to be deprecated according to [this comment](https://github.com/home-assistant/developers.home-assistant/pull/2150#pullrequestreview-2017433583)
+> But it is recommended to use the Websocket API for new integrations.
+
+### REST API Examples
 
 ```py
 from homeassistant_api import Client
 
 with Client(
-    '<API Server URL>',
+    '<API Server URL>', # i.e. 'http://homeassistant.local:8123/api/'
     '<Your Long Lived Access-Token>'
 ) as client:
+    light = client.trigger_service('light', 'turn_on', entity_id="light.living_room")
+```
+
+All the methods also support async/await!
+Just prefix the method with `async_` and pass the `use_async=True` argument to the `Client` constructor.
+Then you can use the methods as coroutines
+(i.e. `await light.async_turn_on(...)`).
+
+```py
+import asyncio
+from homeassistant_api import Client
 
-    light = client.get_domain("light")
+async def main():
+    with Client(
+        '<REST API Server URL>', # i.e. 'http://homeassistant.local:8123/api/'
+        '<Your Long Lived Access-Token>',
+        use_async=True
+    ) as client:
+    light = await client.async_trigger_service('light', 'turn_on', entity_id="light.living_room")
 
-    light.turn_on(entity_id="light.living_room_lamp")
+asyncio.run(main())
 ```
 
-All the methods also support async!
-Just prefix the method with `async_`
-(i.e. `await light.async_turn_on(...)`).
+### Websocket API Example
+
+```py
+from homeassistant_api import WebsocketClient
+
+with WebsocketClient(
+    '<WS API Server URL>', # i.e. 'ws://homeassistant.local:8123/api/websocket'
+    '<Your Long Lived Access-Token>'
+) as ws_client:
+    light = ws_client.trigger_service('light', 'turn_on', entity_id="light.living_room")
+```
+
+> Note: The Websocket API is not yet supported in async/await mode.
 
 ## Documentation
 

homeassistant_api-5.0.0/README.md

@@ -0,0 +1,78 @@
+# HomeassistantAPI
+
+[![Code Coverage](https://img.shields.io/codecov/c/github/GrandMoff100/HomeAssistantAPI/dev?style=for-the-badge&token=SJFC3HX5R1)](https://codecov.io/gh/GrandMoff100/HomeAssistantAPI)
+[![PyPI - Downloads](https://img.shields.io/pypi/dm/HomeAssistant-API?style=for-the-badge)](https://pypistats.org/packages/homeassistant-api)
+![GitHub commits since latest release (by date including pre-releases)](https://img.shields.io/github/commits-since/GrandMoff100/HomeassistantAPI/latest/dev?include_prereleases&style=for-the-badge)
+[![Read the Docs (version)](https://img.shields.io/readthedocs/homeassistantapi?style=for-the-badge)](https://homeassistantapi.readthedocs.io/en/latest/?badge=latest)
+[![GitHub release (latest by date)](https://img.shields.io/github/v/release/GrandMoff100/HomeassistantAPI?style=for-the-badge)](https://github.com/GrandMoff100/HomeassistantAPI/releases)
+
+<a href="https://home-assistant.io">
+    <img src="https://github.com/GrandMoff100/HomeAssistantAPI/blob/7edb4e6298d37bda19c08b807613c6d351788491/docs/images/homeassistant-logo.png?raw=true" width="80%">
+</a>
+
+## Python wrapper for Homeassistant's [Websocket API](https://developers.home-assistant.io/docs/api/websocket/) and [REST API](https://developers.home-assistant.io/docs/api/rest/)
+
+> Note: As of [this comment](https://github.com/home-assistant/architecture/discussions/1074#discussioncomment-9196867) the REST API is not getting any new features or endpoints.
+> However, it is not going to be deprecated according to [this comment](https://github.com/home-assistant/developers.home-assistant/pull/2150#pullrequestreview-2017433583)
+> But it is recommended to use the Websocket API for new integrations.
+
+### REST API Examples
+
+```py
+from homeassistant_api import Client
+
+with Client(
+    '<API Server URL>', # i.e. 'http://homeassistant.local:8123/api/'
+    '<Your Long Lived Access-Token>'
+) as client:
+    light = client.trigger_service('light', 'turn_on', entity_id="light.living_room")
+```
+
+All the methods also support async/await!
+Just prefix the method with `async_` and pass the `use_async=True` argument to the `Client` constructor.
+Then you can use the methods as coroutines
+(i.e. `await light.async_turn_on(...)`).
+
+```py
+import asyncio
+from homeassistant_api import Client
+
+async def main():
+    with Client(
+        '<REST API Server URL>', # i.e. 'http://homeassistant.local:8123/api/'
+        '<Your Long Lived Access-Token>',
+        use_async=True
+    ) as client:
+    light = await client.async_trigger_service('light', 'turn_on', entity_id="light.living_room")
+
+asyncio.run(main())
+```
+
+### Websocket API Example
+
+```py
+from homeassistant_api import WebsocketClient
+
+with WebsocketClient(
+    '<WS API Server URL>', # i.e. 'ws://homeassistant.local:8123/api/websocket'
+    '<Your Long Lived Access-Token>'
+) as ws_client:
+    light = ws_client.trigger_service('light', 'turn_on', entity_id="light.living_room")
+```
+
+> Note: The Websocket API is not yet supported in async/await mode.
+
+## Documentation
+
+All documentation, API reference, contribution guidelines and pretty much everything else
+you'd want to know is on our readthedocs site [here](https://homeassistantapi.readthedocs.io)
+
+If there is something missing, open an issue and let us know! Thanks!
+
+Go make some cool stuff! Maybe come back and tell us about it in a
+[discussion](https://github.com/GrandMoff100/HomeAssistantAPI/discussions)?
+We'd love to hear about how you use our library!!
+
+## License
+
+This project is under the GNU GPLv3 license, as defined by the Free Software Foundation.

homeassistant_api-5.0.0/homeassistant_api/__init__.py

@@ -0,0 +1,48 @@
+"""Interact with your Homeassistant Instance remotely."""
+
+__all__ = (
+    "Client",
+    "State",
+    "Context",
+    "Domain",
+    "Service",
+    "Group",
+    "Entity",
+    "History",
+    "Event",
+    "LogbookEntry",
+    "WebsocketClient",
+    "AuthInvalid",
+    "AuthOk",
+    "AuthRequired",
+    "ResultResponse",
+    "ErrorResponse",
+    "PingResponse",
+    "EventResponse",
+)
+
+from .client import Client
+from .models.domains import Domain, Service
+from .models.entity import Entity, Group
+from .models.events import Event
+from .models.history import History
+from .models.logbook import LogbookEntry
+from .models.states import Context, State
+from .models.websocket import (
+    AuthInvalid,
+    AuthOk,
+    AuthRequired,
+    ErrorResponse,
+    EventResponse,
+    PingResponse,
+    ResultResponse,
+)
+from .websocket import WebsocketClient
+
+Domain.model_rebuild()
+Entity.model_rebuild()
+Event.model_rebuild()
+Group.model_rebuild()
+History.model_rebuild()
+Service.model_rebuild()
+State.model_rebuild()

{homeassistant_api-4.2.2.post1 → homeassistant_api-5.0.0}/homeassistant_api/client.py

@@ -1,5 +1,7 @@
 """Module containing the primary Client class."""
+
 import logging
+import urllib.parse as urlparse
 from typing import Any
 
 from .rawasyncclient import RawAsyncClient
@@ -21,12 +23,22 @@ class Client(RawClient, RawAsyncClient):
 
     def __init__(
         self,
-        *args: Any,
+        api_url: str,
+        token: str,
         use_async: bool = False,
         verify_ssl: bool = True,
-        **kwargs: Any
+        **kwargs: Any,
     ) -> None:
-        if use_async:
-            RawAsyncClient.__init__(self, *args, verify_ssl=verify_ssl, **kwargs)
+        parsed = urlparse.urlparse(api_url)
+
+        if parsed.scheme in {"http", "https"}:
+            if use_async:
+                RawAsyncClient.__init__(
+                    self, api_url, token, verify_ssl=verify_ssl, **kwargs
+                )
+            else:
+                RawClient.__init__(
+                    self, api_url, token, verify_ssl=verify_ssl, **kwargs
+                )
         else:
-            RawClient.__init__(self, *args, verify_ssl=verify_ssl, **kwargs)
+            raise ValueError(f"Unknown scheme {parsed.scheme} in {api_url}")

{homeassistant_api-4.2.2.post1 → homeassistant_api-5.0.0}/homeassistant_api/errors.py

@@ -1,9 +1,9 @@
 """Module for custom error classes"""
 
-from typing import Union
+from typing import Optional, Union
 
 
-class HomeassistantAPIError(BaseException):
+class HomeassistantAPIError(Exception):
     """Base class for custom errors"""
 
 
@@ -55,8 +55,8 @@ class InternalServerError(HomeassistantAPIError):
 class UnauthorizedError(HomeassistantAPIError):
     """Error raised when an invalid token in used to authenticate with homeassistant."""
 
-    def __init__(self) -> None:
-        super().__init__("Invalid authentication token")
+    def __init__(self, message: Optional[str] = None) -> None:
+        super().__init__(message or "Invalid authentication token")
 
 
 class EndpointNotFoundError(HomeassistantAPIError):
@@ -84,3 +84,11 @@ class UnexpectedStatusCodeError(ResponseError):
 
     def __init__(self, status_code: int) -> None:
         super().__init__(f"Response has unexpected status code: {status_code!r}")
+
+
+class WebsocketError(HomeassistantAPIError):
+    """Error raised when an issue occurs with the websocket connection."""
+
+
+class ReceivingError(WebsocketError):
+    """Error raised when an issue occurs when receiving a message from the websocket server."""

{homeassistant_api-4.2.2.post1 → homeassistant_api-5.0.0}/homeassistant_api/models/__init__.py

@@ -1,4 +1,5 @@
 """The Model objects for the entire library."""
+
 from .base import BaseModel
 from .domains import Domain, Service, ServiceField
 from .entity import Entity, Group

{homeassistant_api-4.2.2.post1 → homeassistant_api-5.0.0}/homeassistant_api/models/base.py

@@ -3,16 +3,18 @@
 from datetime import datetime
 from typing import Annotated
 
-from pydantic import ConfigDict, BaseModel as PydanticBaseModel, PlainSerializer
-
+from pydantic import BaseModel as PydanticBaseModel
+from pydantic import ConfigDict, PlainSerializer
 
 DatetimeIsoField = Annotated[
-    datetime, PlainSerializer(lambda x: x.isoformat(), return_type=str, when_used='json')
+    datetime,
+    PlainSerializer(lambda x: x.isoformat(), return_type=str, when_used="json"),
 ]
 
 
 class BaseModel(PydanticBaseModel):
     """Base model that all Library Models inherit from."""
+
     model_config = ConfigDict(
         arbitrary_types_allowed=True,
         validate_assignment=True,

{homeassistant_api-4.2.2.post1 → homeassistant_api-5.0.0}/homeassistant_api/models/domains.py

@@ -1,27 +1,35 @@
 """File for Service and Domain data models"""
+
 import gc
 import inspect
 from typing import TYPE_CHECKING, Any, Coroutine, Dict, Optional, Tuple, Union, cast
 
 from pydantic import Field
 
+from homeassistant_api.errors import RequestError
+
 from .base import BaseModel
 from .states import State
 
 if TYPE_CHECKING:
-    from homeassistant_api import Client
+    from homeassistant_api import Client, WebsocketClient
 
 
 class Domain(BaseModel):
     """Model representing the domain that services belong to."""
 
-    def __init__(self, *args, _client: Optional["Client"] = None, **kwargs) -> None:
+    def __init__(
+        self,
+        *args,
+        _client: Optional[Union["Client", "WebsocketClient"]] = None,
+        **kwargs,
+    ) -> None:
         super().__init__(*args, **kwargs)
         if _client is None:
             raise ValueError("No client passed.")
         object.__setattr__(self, "_client", _client)
 
-    _client: "Client"
+    _client: Union["Client", "WebsocketClient"]
     domain_id: str = Field(
         ...,
         description="The name of the domain that services belong to. "
@@ -33,12 +41,12 @@ class Domain(BaseModel):
     )
 
     @classmethod
-    def from_json(cls, json: Dict[str, Any], client: "Client") -> "Domain":
+    def from_json(
+        cls, json: Dict[str, Any], client: Union["Client", "WebsocketClient"]
+    ) -> "Domain":
         """Constructs Domain and Service models from json data."""
         if "domain" not in json or "services" not in json:
-            raise ValueError(
-                "Missing services or attribute attribute in json argument."
-            )
+            raise ValueError("Missing services or domain attribute in json argument.")
         domain = cls(domain_id=cast(str, json.get("domain")), _client=client)
         services = json.get("services")
         assert isinstance(services, dict)
@@ -67,7 +75,13 @@ class Domain(BaseModel):
         """Allows services accessible as attributes"""
         if attr in self.services:
             return self.get_service(attr)
-        return super().__getattribute__(attr)
+        try:
+            return super().__getattribute__(attr)
+        except AttributeError as err:
+            try:
+                return object.__getattribute__(self, attr)
+            except AttributeError as e:
+                raise e from err
 
 
 class ServiceField(BaseModel):
@@ -89,33 +103,75 @@ class Service(BaseModel):
     description: Optional[str] = None
     fields: Optional[Dict[str, ServiceField]] = None
 
-    def trigger(self, **service_data) -> Tuple[State, ...]:
+    def trigger(self, entity_id: Optional[str] = None, **service_data) -> Union[
+        Tuple[State, ...],
+        Tuple[Tuple[State, ...], Dict[str, Any]],
+        dict[str, Any],
+        None,
+    ]:
         """Triggers the service associated with this object."""
-        return self.domain._client.trigger_service(
-            self.domain.domain_id,
-            self.service_id,
-            **service_data,
-        )
+        if entity_id is not None:
+            service_data["entity_id"] = entity_id
+        try:
+            return self.domain._client.trigger_service_with_response(
+                self.domain.domain_id,
+                self.service_id,
+                **service_data,
+            )
+        except RequestError:
+            return self.domain._client.trigger_service(
+                self.domain.domain_id,
+                self.service_id,
+                **service_data,
+            )
 
-    async def async_trigger(self, **service_data) -> Tuple[State, ...]:
+    async def async_trigger(
+        self, entity_id: Optional[str] = None, **service_data
+    ) -> Union[Tuple[State, ...], Tuple[Tuple[State, ...], Dict[str, Any]]]:
         """Triggers the service associated with this object."""
-        return await self.domain._client.async_trigger_service(
-            self.domain.domain_id,
-            self.service_id,
-            **service_data,
-        )
+        if entity_id is not None:
+            service_data["entity_id"] = entity_id
 
-    def __call__(
-        self, **service_data
-    ) -> Union[Tuple[State, ...], Coroutine[Any, Any, Tuple[State, ...]]]:
-        """Triggers the service associated with this object."""
+        from homeassistant_api import WebsocketClient  # prevent circular import
+
+        if isinstance(self.domain._client, WebsocketClient):
+            raise NotImplementedError(
+                "WebsocketClient does not support async/await syntax."
+            )
+        try:
+            return await self.domain._client.async_trigger_service_with_response(
+                self.domain.domain_id,
+                self.service_id,
+                **service_data,
+            )
+        except RequestError:
+            return await self.domain._client.async_trigger_service(
+                self.domain.domain_id,
+                self.service_id,
+                **service_data,
+            )
+
+    def __call__(self, entity_id: Optional[str] = None, **service_data) -> Union[
+        Union[
+            Tuple[State, ...],
+            Tuple[Tuple[State, ...], Dict[str, Any]],
+            dict[str, Any],
+            None,
+        ],
+        Coroutine[
+            Any, Any, Union[Tuple[State, ...], Tuple[Tuple[State, ...], Dict[str, Any]]]
+        ],
+    ]:
+        """
+        Triggers the service associated with this object.
+        """
         assert (frame := inspect.currentframe()) is not None
         assert (parent_frame := frame.f_back) is not None
         try:
             if inspect.iscoroutinefunction(
                 caller := gc.get_referrers(parent_frame.f_code)[0]
             ) or inspect.iscoroutine(caller):
-                return self.async_trigger(**service_data)
+                return self.async_trigger(entity_id=entity_id, **service_data)
         except IndexError:  # pragma: no cover
             pass
-        return self.trigger(**service_data)
+        return self.trigger(entity_id=entity_id, **service_data)

{homeassistant_api-4.2.2.post1 → homeassistant_api-5.0.0}/homeassistant_api/models/history.py

@@ -1,4 +1,5 @@
 """Module for the History model."""
+
 from typing import Tuple
 
 from pydantic import Field

{homeassistant_api-4.2.2.post1 → homeassistant_api-5.0.0}/homeassistant_api/models/logbook.py

@@ -1,4 +1,5 @@
 """Module for the Logbook Entry model."""
+
 from typing import Optional
 
 from pydantic import Field

{homeassistant_api-4.2.2.post1 → homeassistant_api-5.0.0}/homeassistant_api/models/states.py

@@ -1,4 +1,5 @@
 """Module for the Entity State model."""
+
 from datetime import datetime
 from typing import Any, Dict, Optional
 
@@ -11,9 +12,22 @@ class Context(BaseModel):
     """Model for entity state contexts."""
 
     id: str = Field(
-        max_length=128,
+        max_length=128,  # arbitrary limit
         description="Unique string identifying the context.",
     )
+    parent_id: Optional[str] = Field(
+        max_length=128,
+        description="Unique string identifying the parent context.",
+    )
+    user_id: Optional[str] = Field(
+        max_length=128,
+        description="Unique string identifying the user.",
+    )
+
+    @classmethod
+    def from_json(cls, json: Dict[str, Any]) -> "Context":
+        """Constructs Context model from json data"""
+        return cls.model_validate(json)
 
 
 class State(BaseModel):

homeassistant_api-5.0.0/homeassistant_api/models/websocket.py

@@ -0,0 +1,97 @@
+"""A module defining the responses we expect from the websocket API."""
+
+from typing import Any, Literal, Optional, Union
+
+from .base import BaseModel
+from .states import Context, DatetimeIsoField
+
+__all__ = (
+    "AuthRequired",
+    "AuthOk",
+    "AuthInvalid",
+    "PingResponse",
+    "ErrorResponse",
+    "ResultResponse",
+    "EventResponse",
+)
+
+
+class AuthRequired(BaseModel):
+    type: Literal["auth_required"]
+    ha_version: str
+
+
+class AuthOk(BaseModel):
+    type: Literal["auth_ok"]
+    ha_version: str
+
+
+class AuthInvalid(BaseModel):
+    type: Literal["auth_invalid"]
+    message: str
+
+
+class PingResponse(BaseModel):
+    """Ping websocket response model."""
+
+    id: int
+    type: Literal["pong"]
+    start: int  # added by the client, nanoseconds
+    end: Optional[int] = None  # added by the client, nanoseconds
+
+
+class Error(BaseModel):
+    code: str
+    message: str
+
+
+class ErrorResponse(BaseModel):
+    """Error websocket response model."""
+
+    id: int
+    success: Literal[False]
+    type: Literal["result"]
+    error: Error
+
+
+class ResultResponse(BaseModel):
+    """Result websocket response model."""
+
+    id: int
+    success: Literal[True]
+    type: Literal["result"]
+    result: Optional[Any]
+
+
+class FiredEvent(BaseModel):
+    """A model to parse the `event` key of fired event websocket responses."""
+
+    event_type: str
+    data: dict[str, Any]
+
+    origin: Literal["LOCAL", "REMOTE"]
+    # REMOTE if another API client or webhook fired the event
+    # LOCAL if Home Assistant (or the auth token we used) fired the event
+
+    time_fired: DatetimeIsoField  # datetime.datetime
+    context: Optional[Context]
+
+
+class TemplateEvent(BaseModel):
+    result: str
+    listeners: dict[str, Any]
+
+
+class FiredTrigger(BaseModel):
+    """A model to parse the `trigger` key of fired event websocket responses."""
+
+    context: Optional[Context]
+    variables: dict[str, Any]
+
+
+class EventResponse(BaseModel):
+    """A model to parse the response of a fired event websocket response."""
+
+    id: int
+    type: Literal["event"]
+    event: Union[FiredEvent, FiredTrigger, TemplateEvent]