Update documentation and docstrings for v2 API surface

- Rewrite usage.rst async section: replace use_async=True/async_ prefix
  pattern with separate AsyncClient and AsyncWebsocketClient classes
- Fix advanced.rst: update caching params (cache_session -> session),
  remove obsolete "disabling caching" section, add use_cache docs
- Fix README.md: update async example to use AsyncClient, remove
  "async not supported" note for WebSocket
- Standardize docstrings across all four client classes: consistent
  voice, correct class references (Entity->AsyncEntity etc.), fix
  "homeassistant" -> "Home Assistant" naming
- Fix minor issues: typos, Python version (3.9->3.11), zuban in
  CONTRIBUTING.rst tooling list

Author: adamlogan73

README.md

@@ -25,25 +25,22 @@ 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")
+    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(...)`).
+All four client classes share the same method names.
+The async clients (`AsyncClient`, `AsyncWebsocketClient`) use `async def` methods that you `await`.
 
 ```py
 import asyncio
-from homeassistant_api import Client
+from homeassistant_api import AsyncClient
 
 async def main():
-    with Client(
+    async with AsyncClient(
         '<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")
+        await client.trigger_service('light', 'turn_on', entity_id="light.living_room")
 
 asyncio.run(main())
 ```
@@ -57,11 +54,9 @@ 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")
+    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

docs/CONTRIBUTING.rst

@@ -37,7 +37,7 @@ Next run in your terminal.
 Step Three: Installing Dependencies
 ======================================
 
-Firstly, you need to have Python 3.9 or newer installed.
+Firstly, you need to have Python 3.11 or newer installed.
 Download the latest Python Version from `here <https://www.python.org/>`__.
 Then you need to install :code:`uv`, a fast Python package manager.
 Checkout the `uv Docs <https://docs.astral.sh/uv/>`__.
@@ -69,7 +69,7 @@ Code Styling Guidelines
 In order to make sure that our code is easy to read, and navigate.
 As well as to stop stupid mistakes like typos, undefined variables, etc.
 We enforce code standards.
-Using the tools, :code:`ruff`, :code:`pytest`, and :code:`docker`, we make make sure that our code quality is top notch, and that are changes work everywhere.
+Using the tools, :code:`ruff`, :code:`zuban`, :code:`pytest`, and :code:`docker`, we make make sure that our code quality is top notch, and that are changes work everywhere.
 You can those tools manually yourself, but they also run automatically when you open a PR.
 
 Merging Your Contributions

docs/advanced.rst

@@ -2,71 +2,74 @@
 Advanced Section
 *******************
 
-Persistent Caching
-********************
+Caching
+**********
+
+By default, caching is **disabled**. You can enable the built-in in-memory cache by passing :code:`use_cache=True`:
+
+.. code-block:: python
 
-Persistent caching is exactly what it means. It makes your requests cache persist or stay around between :py:class:`Client` objects, and between runs, and contexts (:code:`with client:` statements).
-Rather than the default behavior, which is saving the cache to memory or not at all and erasing it after each context and run.
+    from homeassistant_api import Client
 
+    client = Client("<API_URL>", "<TOKEN>", use_cache=True)
 
-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.
+This creates an in-memory cache that expires after 300 seconds.
 
-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.
+Persistent Caching
+********************
 
-You can simply pass them to your client like so.
+If you want your cache to persist between runs (e.g. to a filesystem), you can pass your own custom cached session via the :code:`session` parameter.
+
+Depending on whether you are using a sync or async client you will want to use either :py:class:`requests_cache.CachedSession` or :py:class:`aiohttp_client_cache.session.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 backend options and more.
 
 .. code-block:: python
 
+    from datetime import timedelta
     from homeassistant_api import Client
     from requests_cache import CachedSession
 
     client = Client(
         "<API_URL>",
         "<TOKEN>",
-        cache_session=CachedSession(
+        session=CachedSession(
             backend="filesystem",
-            expire_after=timedelta(minutes=5)
-        )
+            expire_after=timedelta(minutes=5),
+        ),
     )
 
-    # CachedSession is activated by the `with` statement.
     with client:
         # Grab and update some cool entities and services inside your installation.
         ...
 
+.. code-block:: python
+
     # Or an example for async
     import asyncio
-    from homeassistant_api import Client
+    from datetime import timedelta
+    from homeassistant_api import AsyncClient
     from aiohttp_client_cache import CachedSession, FileBackend
 
-    client = Client(
-        "<URL>",
+    client = AsyncClient(
+        "<API_URL>",
         "<TOKEN>",
-        cache_session=CachedSession(
+        session=CachedSession(
             cache=FileBackend(
-                expire_after=timedelta(minutes=5)
-            )
+                expire_after=timedelta(minutes=5),
+            ),
         ),
-        use_async=True
     )
+
     async def main():
         async with client:
             # Grab and update some cool entities and services inside your installation.
             ...
+
     asyncio.run(main())
 
 
 Why the heck is :py:class:`Client` a context manager?
 ********************************************************
 
-The :py:class:`Client` is a context manager because it activates the cache session and pings Home Assistant to make sure its running.
-You might not want this behavior, if you don't then don't use the :code:`with` or :code:`async with` statement.
-You can still use the client without it, but you will have to manually activate the cache session before you use it.
-
-Disabling Caching
-******************
-
-To explicitly disable the default cache you can pass :code:`cache_session=False` or :code:`async_cache_session=False` to :py:class:`Client`'s init method depending on your use case.
-Otherwise the default cache will be used by default when you use :code:`with client:` or :code:`async with client:`.
+The :py:class:`Client` is a context manager because it manages the underlying HTTP session and pings Home Assistant to make sure it's running.
+You don't have to use the context manager — the client works without it — but you'll need to manage the session lifecycle yourself.

docs/index.rst

@@ -30,11 +30,11 @@ 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)
+- 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.
+- Synchronous and asynchronous support for both REST and WebSocket clients.
 - Modular design for intuitive readability.
-- Request caching for more efficient repeative requests.
+- Request caching for more efficient repetitive requests.
 
 Getting Started
 -------------------