diff --git a/docs/advanced.rst b/docs/advanced.rst index ae6ead6b..4e75aed8 100644 --- a/docs/advanced.rst +++ b/docs/advanced.rst @@ -41,8 +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))) - # CachedSession is activated by the `async with` statement. + client = Client( + "", + "", + cache_session=CachedSession(cache=FileBackend(), + 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. @@ -50,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. @@ -58,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/api.rst b/docs/api.rst index 94e40b27..c347f150 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -3,5 +3,7 @@ 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 diff --git a/docs/usage.rst b/docs/usage.rst index efdccdf6..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") @@ -106,8 +108,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(): @@ -157,6 +159,9 @@ Async Entities # + + + What's Next? ############# 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(