From ec184fad999d0890959914a9f290ae4027ed5db8 Mon Sep 17 00:00:00 2001 From: Odianosen Date: Sat, 1 Jan 2022 08:17:10 +0000 Subject: [PATCH 1/3] Added documentation for entity class --- appdaemon/entity.py | 43 ++++++++++++++++++++++++---- docs/AD_API_REFERENCE.rst | 60 ++++++++++++++++++++++++++++++++++++--- 2 files changed, 94 insertions(+), 9 deletions(-) diff --git a/appdaemon/entity.py b/appdaemon/entity.py index fc5828c08..9de307e5d 100644 --- a/appdaemon/entity.py +++ b/appdaemon/entity.py @@ -349,7 +349,33 @@ async def wait_state( duration: Union[int, float] = 0, timeout: Union[int, float] = None, ) -> None: - """Used to wait for the state of an entity's attribute""" + """Used to wait for the state of an entity's attribute + + This API call is only functional within an async function. It should be noted that when instanciated, + the api checks immediately if its already on the required state, and if it is, it will continue. + + Args: + state (Any): The state to wait for, for the entity to be in before continuing + attribute (str): The entity's attribute to use, if not using the entity's state + duration (int|float): How long the state is to hold, before continuing + timeout (int|float): How long to wait for the state to be achieved, before timing out. + When it times out, a appdaemon.exceptions.TimeOutException is raised + + Returns: + None + + Examples: + >>> from appdaemon.exceptions import TimeOutException + >>> + >>> async def run_my_sequence(self): + >>> sequence_object = self.get_entity("sequence.run_the_thing") + >>> await sequence_object.call_service("run") + >>> try: + >>> await sequence_object.wait_state("idle", timeout=30) # wait for it to completely run + >>> except TimeOutException: + >>> pass # didn't complete on time + + """ wait_id = uuid.uuid4().hex async_event = asyncio.Event() @@ -397,7 +423,14 @@ def entity_api(cls, logger: Logger, ad: AppDaemon, name: str, namespace: str, en @utils.sync_wrapper async def copy(self, copy: bool = True) -> dict: - """Gets the complete state of the entity within AD.""" + """Gets the complete state of the entity within AD. + + This is essentially a helper function, to get all data about an entity + + Args: + copy(bool): If set to False, it will not make a deep copy of the entity. + This can help with speed of accessing the data + """ return await self.get_state(attribute="all", copy=copy, default={}) @@ -417,19 +450,19 @@ async def is_state(self, state: Any) -> bool: @utils.sync_wrapper async def turn_on(self, **kwargs: Optional[Any]) -> Any: - """Used to turn the entity ON if supported""" + """Generic function, used to turn the entity ON if supported""" return await self.call_service("turn_on", **kwargs) @utils.sync_wrapper async def turn_off(self, **kwargs: Optional[Any]) -> Any: - """Used to turn the entity OFF if supported""" + """Generic function, used to turn the entity OFF if supported""" return await self.call_service("turn_off", **kwargs) @utils.sync_wrapper async def toggle(self, **kwargs: Optional[Any]) -> Any: - """Used to toggle the entity ON/OFF if supported""" + """Generic function, used to toggle the entity ON/OFF if supported""" return await self.call_service("toggle", **kwargs) diff --git a/docs/AD_API_REFERENCE.rst b/docs/AD_API_REFERENCE.rst index 19a58dea4..a833ea201 100644 --- a/docs/AD_API_REFERENCE.rst +++ b/docs/AD_API_REFERENCE.rst @@ -8,14 +8,13 @@ by the ``get_ad_api()`` call: .. code:: python import adbase as ad - import adapi as adapi class Test(ad.ADBase): - def initialize(self): + def initialize(self): - adbase = self.get_ad_api() - handle = self.adbase.run_in(callback, 20) + self.adapi = self.get_ad_api() + handle = self.adapi.run_in(callback, 20) These calls are documented below. @@ -32,9 +31,62 @@ To create apps based on just the AppDaemon base API, use some code like the foll def initialize(self): +Entity Class +------------ + +As manipulating entities is a core center point of writing automation apps, easy access and manipulation of entities is very important. +AppDaemon supports the ability to access entities as class in their own right, via the api call ``get_entity(entity)``. +When this is done, the returned object allows to maximise the OOP nature of python while working with entities. +for example: + +..code:: python + import adbase as ad + + class TestApp(ad.ADBase): + + def initialize(self): + + self.adapi = self.get_ad_api() + self.adapi.run_in(self.callback, 20) + + # get light entity class + self.kitchen_light = self.adapi.get_entity("light.kitchen_ceiling_light", namespace="hass") + + def callback(self, kwargs): + if self.kitchen_ceiling_light.is_state("off"): + self.kitchen_ceiling_light.turn_on(brightness=200) + Reference --------- +Entity API +~~~~~~~~~~ +.. autofunction:: appdaemon.entity.Entity.add +.. autofunction:: appdaemon.entity.Entity.call_service +.. autofunction:: appdaemon.entity.Entity.copy +.. autofunction:: appdaemon.entity.Entity.exists +.. autofunction:: appdaemon.entity.Entity.get_state +.. autofunction:: appdaemon.entity.Entity.listen_state +.. autofunction:: appdaemon.entity.Entity.is_state +.. autofunction:: appdaemon.entity.Entity.set_namespace +.. autofunction:: appdaemon.entity.Entity.set_state +.. autofunction:: appdaemon.entity.Entity.toggle +.. autofunction:: appdaemon.entity.Entity.turn_off +.. autofunction:: appdaemon.entity.Entity.turn_on +.. autofunction:: appdaemon.entity.Entity.wait_state + +In addition to the above, there are a couple of propery attributes the Entity class supports +- entity_id +- namespace +- domain +- entity_name +- state +- attributes +- friendly_name +- last_changed +- last_changed_seconds + + State ~~~~~ From 4550ac3dd8c7a2a66d2bea8f5b35c9c98378a6ca Mon Sep 17 00:00:00 2001 From: Odianosen Date: Sat, 1 Jan 2022 08:18:59 +0000 Subject: [PATCH 2/3] Fix --- docs/AD_API_REFERENCE.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/AD_API_REFERENCE.rst b/docs/AD_API_REFERENCE.rst index a833ea201..9d4724864 100644 --- a/docs/AD_API_REFERENCE.rst +++ b/docs/AD_API_REFERENCE.rst @@ -40,6 +40,7 @@ When this is done, the returned object allows to maximise the OOP nature of pyth for example: ..code:: python + import adbase as ad class TestApp(ad.ADBase): From 67987e429e47493db949829bba4a1156d4ce0b88 Mon Sep 17 00:00:00 2001 From: Odianosen Date: Sat, 1 Jan 2022 08:22:13 +0000 Subject: [PATCH 3/3] Fix code --- docs/AD_API_REFERENCE.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/AD_API_REFERENCE.rst b/docs/AD_API_REFERENCE.rst index 9d4724864..3557b6851 100644 --- a/docs/AD_API_REFERENCE.rst +++ b/docs/AD_API_REFERENCE.rst @@ -39,7 +39,7 @@ AppDaemon supports the ability to access entities as class in their own right, v When this is done, the returned object allows to maximise the OOP nature of python while working with entities. for example: -..code:: python +.. code:: python import adbase as ad