From 159b8658c1015102be554e3817bcad0814aa978b Mon Sep 17 00:00:00 2001 From: Nate Date: Fri, 2 Dec 2022 18:17:40 -0600 Subject: [PATCH 1/4] Readd ineherited members to the docs --- docs/api.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/api.rst b/docs/api.rst index 94e40b27..93a4f983 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -3,5 +3,6 @@ Code Reference .. automodule:: homeassistant_api :platform: Linux, Windows, MacOS + :inherited-members: From fbd39d2c5d41c2e9cd9d241990159cb0d3083b42 Mon Sep 17 00:00:00 2001 From: Nate Date: Fri, 2 Dec 2022 19:32:21 -0600 Subject: [PATCH 2/4] Add pydantic method exclusions --- docs/api.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/api.rst b/docs/api.rst index 93a4f983..c347f150 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -4,5 +4,6 @@ Code Reference .. automodule:: homeassistant_api :platform: Linux, Windows, MacOS :inherited-members: + :exclude-members: 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 From 0586d9b58ab2486af55cc707eca9fd6970d5f559 Mon Sep 17 00:00:00 2001 From: Nate Date: Fri, 2 Dec 2022 19:32:42 -0600 Subject: [PATCH 3/4] Add use_async keywords to examples --- docs/advanced.rst | 8 +++++++- docs/usage.rst | 4 ++-- homeassistant_api/rawclient.py | 4 ++-- 3 files changed, 11 insertions(+), 5 deletions(-) diff --git a/docs/advanced.rst b/docs/advanced.rst index ae6ead6b..7a47af4d 100644 --- a/docs/advanced.rst +++ b/docs/advanced.rst @@ -41,7 +41,13 @@ You can simply pass them to your client like so. from homeassistant_api import Client from aiohttp_client_cache import CachedSession, FileBackend - client = Client("", "", cache_session=CachedSession(cache=FileBackend(), expire_after=timedelta(minutes=5))) + client = Client( + "", + "", + cache_session=CachedSession(cache=FileBackend(), + expire_after=timedelta(minutes=5)), + use_async=True + ) # CachedSession is activated by the `async with` statement. async def main(): async with client: diff --git a/docs/usage.rst b/docs/usage.rst index efdccdf6..f4bb2a01 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -106,8 +106,8 @@ Async Services import asyncio from homeassistant_api import Client - # Initialize client like usual - client = Client(url, token) + # Initialize client like usual, except with the :code:`use_async` keyword. + client = Client(url, token, use_async=True) async def main(): diff --git a/homeassistant_api/rawclient.py b/homeassistant_api/rawclient.py index 55364b21..4e1c4af3 100644 --- a/homeassistant_api/rawclient.py +++ b/homeassistant_api/rawclient.py @@ -236,7 +236,7 @@ def get_entity( # Services and domain methods def get_domains(self) -> Dict[str, Domain]: - """Fetches all :py:class:`Service`s from the API.""" + """Fetches all :py:class:`Service` 's from the API.""" data = self.request("services") domains = map( lambda json: Domain.from_json(json, client=cast(Client, self)), @@ -245,7 +245,7 @@ def get_domains(self) -> Dict[str, Domain]: return {domain.domain_id: domain for domain in domains} def get_domain(self, domain_id: str) -> Optional[Domain]: - """Fetches all services under a particular domain.""" + """Fetches all :py:class:`Service`'s under a particular service :py:class:`Domain`.""" return self.get_domains().get(domain_id) def trigger_service( From 4b714d778e188a7259e5ab5fddc6e2a6cb4af8e6 Mon Sep 17 00:00:00 2001 From: Nate Date: Fri, 2 Dec 2022 19:45:07 -0600 Subject: [PATCH 4/4] Explain the context manager functionality --- docs/advanced.rst | 17 +++++++++++++++-- docs/usage.rst | 5 +++++ 2 files changed, 20 insertions(+), 2 deletions(-) diff --git a/docs/advanced.rst b/docs/advanced.rst index 7a47af4d..4e75aed8 100644 --- a/docs/advanced.rst +++ b/docs/advanced.rst @@ -48,7 +48,6 @@ You can simply pass them to your client like so. expire_after=timedelta(minutes=5)), use_async=True ) - # CachedSession is activated by the `async with` statement. async def main(): async with client: # Grab and update some cool entities and services inside your installation. @@ -56,6 +55,20 @@ You can simply pass them to your client like so. 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:`. + + Response Processing ********************** Home Assistant API uses functions called processors. @@ -64,7 +77,7 @@ These functions take a Response object as a parameter and return the python data How To Register Response Processors (Converters) ================================================== -To register a response processor you need to import the Processing class and then implement the decorator. +To register a response processor you need to import the :py:class:`Processing` class and then implement the decorator. .. code-block:: python diff --git a/docs/usage.rst b/docs/usage.rst index f4bb2a01..f786600a 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -42,6 +42,8 @@ The most commonly used features of this library include triggering services and client = Client("https://foobarhomeassistant.duckdns.org:8123/api", "mylongtokenpasswordthingyfoobar") # In order to activate the requests session you to use the Client context manager like so. + # Using it as a context manager will automatically close the session when you're done with it. + # But also will *ping* your Home Assistant instance to make sure it's running. with client: while True: sun = client.get_entity(entity_id="sun.sun") @@ -157,6 +159,9 @@ Async Entities # + + + What's Next? #############