Modernize the caching docs

Author: GrandMoff100

docs/advanced.rst

@@ -5,24 +5,37 @@ Advanced Section
 Caching
 **********
 
-By default, caching is **disabled**. You can enable the built-in in-memory cache by passing :code:`use_cache=True`:
+The packaged :py:class:`Client` and :py:class:`AsyncClient` do not come with any built-in caching.
+A convenient option is to use the :py:class:`niquests_cache.session.CachedSession` or :py:class:`niquests_cache.session.AsyncCachedSession` classes from the `niquests_cache` library.
+
 
 .. code-block:: python
 
     from homeassistant_api import Client
 
-    client = Client("<API_URL>", "<TOKEN>", use_cache=True)
+    from niquests_cache.session import CachedSession
+    from niquests_cache.backend import MemoryBackend
+
+    client = Client("<API_URL>", "<TOKEN>", session=CachedSession(backend=MemoryBackend(), expire_after=300))
+
+.. code-block:: python
+    from homeassistant_api import AsyncClient
+
+    from niquests_cache.session import AsyncCachedSession
+    from niquests_cache.backend import MemoryBackend
+
+    client = AsyncClient("<API_URL>", "<TOKEN>", session=AsyncCachedSession(backend=MemoryBackend(), expire_after=300))
+
+
+This creates an in-memory cache that expires after 300 seconds. You can adjust the `expire_after` value to fit your needs or set it to `-1` to disable expiration.
+For more information on the available caching options, see the `niquests_cache <https://niquests-cache.readthedocs.io/en/stable/>` documentation.
 
-This creates an in-memory cache that expires after 300 seconds.
 
 Persistent Caching
 ********************
 
 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:`niquests_cache.session.CachedSession` or :py:class:`niquests_cache.session.AsyncCachedSession` respectively.
-See the docs for `niquests_cache <https://niquests-cache.readthedocs.io/en/stable/#example-usage>`__ for backend options and more.
-
 .. code-block:: python
 
     from datetime import timedelta
@@ -32,7 +45,7 @@ See the docs for `niquests_cache <https://niquests-cache.readthedocs.io/en/stabl
     client = Client(
         "<API_URL>",
         "<TOKEN>",
-        session=CachedSession(cache_name=Path('.cache') / 'http'),  # defaults to sqlite cache
+        session=CachedSession(cache_name=Path('.cache') / 'http'),  # by default uses sqlite backend
     )
 
     with client:

docs/conf.py

@@ -15,7 +15,6 @@
 import re
 import sys
 
-
 sys.path.insert(0, os.path.abspath("../"))
 sys.path.append(os.path.abspath("extensions"))
 
@@ -129,15 +128,11 @@
             "model_construct",
             "model_computed_fields",
         ]
-    )
+    ),
 }
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3", None),
     "homeassistant_api": ("https://homeassistantapi.readthedocs.io/en/stable", None),
     "niquests": ("https://niquests.readthedocs.io/en/stable", None),
-    "niquests-cache": ("https://niquests-cache.readthedocs.io/en/stable/", None)
+    "niquests-cache": ("https://niquests-cache.readthedocs.io/en/stable/", None),
 }
-
-autodoc_type_aliases = {
-    "JsonValue": "typing.Any",
-}

docs/extensions/resourcelinks.py

@@ -5,10 +5,8 @@
 from typing import Any
 
 import sphinx
-from docutils import nodes
-from docutils import utils
-from docutils.nodes import Node
-from docutils.nodes import system_message
+from docutils import nodes, utils
+from docutils.nodes import Node, system_message
 from docutils.parsers.rst.states import Inliner
 from sphinx.application import Sphinx
 from sphinx.util.nodes import split_explicit_title

homeassistant_api/models/domains.py

@@ -26,11 +26,11 @@
 
 __all__ = (
     "AsyncDomain",
+    "AsyncService",
     "BaseDomain",
-    "Domain",
     "BaseService",
-    "AsyncService",
-    "Service"
+    "Domain",
+    "Service",
 )
 
 

tests/test_client.py

@@ -9,47 +9,55 @@
 from homeassistant_api import WebsocketClient
 from homeassistant_api.baseclient import BaseClient
 
+HA_URL = os.environ.get("HOMEASSISTANTAPI_URL", "http://localhost:8123/api")
+HA_WS_URL = os.environ.get(
+    "HOMEASSISTANTAPI_WS_URL",
+    "ws://localhost:8123/api/websocket",
+)
+HA_TOKEN = os.environ.get("HOMEASSISTANTAPI_TOKEN", "")
+
 
 def test_custom_session(nimax_session: niquests.Session) -> None:
     with Client(
-        os.environ.get("HOMEASSISTANTAPI_URL", "http://localhost:8123/api"),
-        os.environ.get("HOMEASSISTANTAPI_TOKEN", ""),
+        HA_URL,
+        HA_TOKEN,
         session=nimax_session,
     ):
         pass
 
 
 def test_default_session(nimax_session: niquests.Session) -> None:  # noqa: ARG001
     with Client(
-        os.environ.get("HOMEASSISTANTAPI_URL", "http://localhost:8123/api"),
-        os.environ.get("HOMEASSISTANTAPI_TOKEN", ""),
+        HA_URL,
+        HA_TOKEN,
     ):
         pass
 
 
 async def test_custom_async_session(nimax_async_session: niquests.AsyncSession) -> None:
     async with AsyncClient(
-        os.environ.get("HOMEASSISTANTAPI_URL", "http://localhost:8123/api"),
-        os.environ.get("HOMEASSISTANTAPI_TOKEN", ""),
+        HA_URL,
+        HA_TOKEN,
         session=nimax_async_session,
     ):
         pass
 
 
 async def test_default_async_session(
-    nimax_async_session: niquests.AsyncSession,  # noqa: ARG001
+    nimax_async_session: niquests.AsyncSession,
 ) -> None:
     async with AsyncClient(
-        os.environ.get("HOMEASSISTANTAPI_URL", "http://localhost:8123/api"),
-        os.environ.get("HOMEASSISTANTAPI_TOKEN", ""),
+        HA_URL,
+        HA_TOKEN,
+        session=nimax_async_session,
     ):
         pass
 
 
 def test_websocket_client_ping(nimax_session: niquests.Session) -> None:
     with WebsocketClient(
-        os.environ.get("HOMEASSISTANTAPI_WS_URL", "ws://localhost:8123/api/websocket"),
-        os.environ.get("HOMEASSISTANTAPI_TOKEN", ""),
+        HA_WS_URL,
+        HA_TOKEN,
         session=nimax_session,
     ) as client:
         assert client.ping_latency() > 0
@@ -59,8 +67,8 @@ async def test_async_websocket_client_ping(
     nimax_async_session: niquests.AsyncSession,
 ) -> None:
     async with AsyncWebsocketClient(
-        os.environ.get("HOMEASSISTANTAPI_WS_URL", "ws://localhost:8123/api/websocket"),
-        os.environ.get("HOMEASSISTANTAPI_TOKEN", ""),
+        HA_WS_URL,
+        HA_TOKEN,
         session=nimax_async_session,
     ) as client:
         assert (await client.ping_latency()) > 0