Merge pull request #1438 from Odianosen25/entity-class-docs

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)
 

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,63 @@ 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
 ~~~~~