Merge branch 'dev' into clean-tokens

Author: GrandMoff100

.gitignore

@@ -17,6 +17,9 @@ venv/
 .replit
 .breakpoints
 
+# Informal testing
+main.py
+
 # Cache files
 *.sqlite
 

.readthedocs.yml

@@ -2,14 +2,14 @@ version: 2
 
 # Set the version of Python and other tools you might need
 build:
-  os: ubuntu-20.04
+  os: ubuntu-22.04
   tools:
     python: "3.10"
   jobs:
     pre_create_environment:
       - asdf plugin add poetry
-      - asdf install poetry latest
-      - asdf global poetry latest
+      - asdf install poetry 1.8.3
+      - asdf global poetry 1.8.3
       - poetry export -f requirements.txt --output requirements.txt --with docs
     post_install:
       - pip install -r requirements.txt

.vscode/settings.json

@@ -0,0 +1,7 @@
+{
+    "python.testing.pytestArgs": [
+        "tests"
+    ],
+    "python.testing.unittestEnabled": false,
+    "python.testing.pytestEnabled": true
+}

README.md

@@ -1,35 +1,66 @@
 # 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
 

compose.yml

@@ -1,5 +1,3 @@
-version: "3.9"
-
 services:
   server:
     image: "homeassistant/home-assistant:stable"
@@ -19,6 +17,7 @@ services:
       - server
     environment:
       HOMEASSISTANTAPI_URL: http://server:8123/api
+      HOMEASSISTANTAPI_WS_URL: ws://server:8123/api/websocket
       HOMEASSISTANTAPI_TOKEN: ${HOMEASSISTANTAPI_TOKEN}
       DELAY: 60
 

docs/advanced.rst

@@ -12,7 +12,7 @@ Rather than the default behavior, which is saving the cache to memory or not at
 If you want to persist your requests cache you can pass your own custom cached session to :py:class:`Client`'s init method.
 You can pass a variety of options to your cached session like how fast to expire the cache, where to cache it (the cache backend), and what to do when the cache is expired.
 
-Depending on whether you are using this in an async of sync project you will want to use either :py:class:`aiohttp_client_cache.backends.CachedSession` or :py:class:`requests_cache.CachedSession` respectively.
+Depending on whether you are using this in an async or sync project you will want to use either :py:class:`aiohttp_client_cache.backends.CachedSession` or :py:class:`requests_cache.CachedSession` respectively.
 See the docs for `requests_cache <https://requests-cache.readthedocs.io/en/latest/>`__ and `aiohttp_client_cache <https://aiohttp-client-cache.readthedocs.io/en/latest/>`__ for how to implement these backends, options, and much more.
 
 You can simply pass them to your client like so.

docs/api.rst

@@ -4,4 +4,4 @@ Code Reference
 .. automodule:: homeassistant_api
       :platform: Linux, Windows, MacOS
       :inherited-members:
-      :exclude-members: model_json_schema, model_copy, model_rebuild, model_dump, construct, copy, dict, from_orm, json, parse_file, parse_obj, parse_raw, parse_str, parse_url, schema, schema_json, schema_yaml, schema_yml, to_orm, update_forward_refs, validate, validate_file, validate_obj, validate_raw, validate_str, validate_url, model_validate_strings, model_validate_json, model_validate, model_post_init, model_parametrized_name, model_extra, model_fields_set, model_dump_json, model_construct, model_computed_fields
+      :exclude-members: model_json_schema, model_copy, model_rebuild, model_dump, construct, copy, dict, from_orm, json, parse_file, model_validate, parse_raw, parse_obj, parse_str, parse_url, schema, schema_json, schema_yaml, schema_yml, to_orm, update_forward_refs, validate, validate_file, validate_obj, validate_raw, validate_str, validate_url, model_validate_strings, model_validate_json, model_validate, model_post_init, model_parametrized_name, model_extra, model_fields_set, model_dump_json, model_construct, model_computed_fields

docs/conf.py

@@ -1,4 +1,5 @@
 """Configuration file for the Sphinx documentation builder."""
+
 #
 # This file only contains a selection of the most common options. For a full
 # list see the documentation:
@@ -20,8 +21,8 @@
 # -- Project information -----------------------------------------------------
 
 project = "Homeassistant API"
-copyright = "2024, Nathan Larsen"  # pylint: disable=redefined-builtin
-author = "Nate Larsen"
+copyright = "2023-2025, Nathan Larsen"  # pylint: disable=redefined-builtin
+author = "Nathan Larsen"
 
 # The full version, including alpha/beta/rc tags
 with open("../pyproject.toml") as f:

docs/index.rst

@@ -9,8 +9,8 @@
 Welcome to Homeassistant API!
 =============================
 
-Homeassistant API is a pythonic module that interacts with `Homeassistant's REST API integration <https://developers.home-assistant.io/docs/api/rest>`_.
-You can use it to remotely control your Home Assistant like getting entity states, triggering services, etc.
+Homeassistant API is a pythonic module that interacts with `Homeassistant's REST API integration <https://developers.home-assistant.io/docs/api/rest>`_ and Homeassistant's `Websocket API <https://developers.home-assistant.io/docs/api/websocket>`_.
+You can use it to remotely control your Home Assistant to do things like turn on lights, change the temperature, or listen for when the garage door opens.
 
 Index
 ----------
@@ -30,6 +30,7 @@ Features
 ----------
 
 - Full consumption of the Home Assistant REST API endpoints.
+- Full consumption of the Home Assistant Websocket API (all of the documented commands and some undocumented ones)
 - Convenient Pydantic Models for data validation.
 - Syncrononous and Asynchronous support for integrating with all applications and/or libraries.
 - Modular design for intuitive readability.

docs/usage.rst

@@ -6,20 +6,19 @@ Usage
 The Basics...
 #################
 
-This library is centered around the :py:class:`Client` class.
+This library is centered around the :py:class:`Client` and :py:class:`WebsocketClient` classes.
 Once you have have your api base url and Long Lived Access Token from Home Assistant we can start to do stuff.
-The rest of this guide assumes you have the :py:class:`Client` saved to a :code:`client` variable.
+The rest of this guide assumes you have the :py:class:`Client` saved to a :code:`client` variable or a :py:class:`WebsocketClient` saved to a :code:`ws_client` variable.
 Most of these examples require some integrations to be setup inside Home Assistant for the examples to actually work.
 The most commonly used features of this library include triggering services and getting and modifying entity states.
 
-
 .. code-block:: python
     :linenos:
 
     import os
     from homeassistant_api import Client
 
-    URL = '<API BASE URL>'
+    URL = '<API BASE URL>'  # Example: 'https://foobarhomeassistant.duckdns.org:8123/api'
     TOKEN = '<LONG LIVED ACCESS TOKEN>'
 
     # Assigns the Client object to a variable and checks if it's running.
@@ -31,6 +30,18 @@ The most commonly used features of this library include triggering services and
     # Triggers the light.turn_on service on the entity `light.my_living_room_light`
 
 
+.. code-block:: python
+    :linenos:
+
+    from homeassistant_api import WebsocketClient
+
+    WS_URL = '<WS API BASE URL>'  # Example: 'https://foobarhomeassistant.duckdns.org:8123/api/websocket'
+    TOKEN = '<LONG LIVED ACCESS TOKEN>'
+
+    with WebsocketClient(WS_URL, TOKEN) as ws_client:  # opens a websocket connection to Home Assistant
+        print(ws_client.render_template("{{ states('sensor.my_sensor') }}"))
+
+
 .. code-block:: python
    :linenos:
 
@@ -66,6 +77,15 @@ Services
 
     changed_states = light.toggle(entity_id="light.light_bulb_1")
 
+.. code-block:: python
+
+    climate = ws_client.get_domain("climate")
+
+    print(climate.services)
+    # {'set_temperature': Service(service_id='set_temperature', name='Set temperature', description='Set the target temperature for a climate entity.\n', ...
+
+    changed_states = climate.set_temperature(entity_id="climate.my_thermostat", temperature=72)
+
 Entities
 *************
 
@@ -95,12 +115,15 @@ Entities
     door.set_state(State(state="My new state", attributes={"open_height": "5ft"}))
     # <State "My new state" entity_id="cover.garage_door">
 
+    ## All of these methods can be used with the WebsocketClient as well [except for set_state because the WS API doesn't support it :((( ].
 
 Using Client with :code:`async`/:code:`await`
 *************************************************
 Are you wondering if you can use :code:`homeassistant_api` using Python's :code:`async`/:code:`await` syntax?
 Good news! You can!
 
+(You can't use the WebsocketClient with :code:`async`/:code:`await` yet because we haven't implemented it yet.)
+
 Async Services
 ********************
 .. code-block:: python
@@ -159,8 +182,67 @@ Async Entities
     # <State "My new state" entity_id="cover.garage_door">
 
 
+Using Events (Listening and Firing)
+*****************************************
+
+.. code-block:: python
+
+    from homeassistant_api import WebsocketClient
+
+    WS_URL = '<WS API BASE URL>'  # Example: 'https://foobarhomeassistant.duckdns.org:8123/api/websocket'
+    TOKEN = '<LONG LIVED ACCESS TOKEN>'
 
+    with WebsocketClient(WS_URL, TOKEN) as ws_client:
+        with ws_client.listen_events() as events:
+            for event in events:
+                print(event)
+        
+        # Or if you want to listen for a specific event type until dinner time.
+        with ws_client.listen_events('state_changed') as events:
+            for event in events:
+                print(event)
+                if event.data.entity_id == 'myalarmclock.dinner_time' and event.data.new_state.state == 'now':
+                    break
+
+        # Or if you want to listen for just 10 events.
+        with ws_client.listen_events("my_event") as events:
+            for _, event in zip(range(10), events):
+                print(event)
+        
+        # Alternatively for just one event.
+        with ws_client.listen_events("my_event") as events:
+            event = next(events)
+            print(event)
+
+        # Now to fire an event.
+        ws_client.fire_event("my_event", my_arg="my_value")
+
+
+Listening for Triggers
+**************************
 
+.. code-block:: python
+
+    from homeassistant_api import WebsocketClient
+
+    with WebsocketClient(WS_URL, TOKEN) as ws_client:
+        with ws_client.listen_triggers() as triggers:  # see WebsocketClient.listen_triggers for more info.
+            for trigger in triggers:
+                print(trigger)
+        
+        # Another more specific example, listening for event triggers.
+        with ws_client.listen_triggers("event", event_type="my_event") as triggers:
+            ws_client.fire_event("my_event", my_arg="my_value")
+
+            for trigger in triggers:
+                print(trigger.variables.my_arg)  # This is the value of my_arg from the event fired above.
+
+        # Another one, listening for time triggers.
+        future = ws_client.get_rendered_template(
+            "{{ (now() + timedelta(seconds=1)).strftime('%H:%M:%S') }}"
+        )
+        with ws_client.listen_trigger("time", at=future) as triggers:  # `at` can be HH:MM or HH:MM:SS
+            print(next(triggers))
 
 What's Next?
 #############