Merge pull request #1463 from Odianosen25/dev

appdaemon/entity.py

@@ -35,7 +35,9 @@ def __init__(self, logger: Logger, ad: AppDaemon, name: str, namespace: str, ent
         self._async_events = {}
 
     def set_namespace(self, namespace: str) -> None:
-        """Sets a new namespace for the App to use from that point forward.
+        """Sets a new namespace for the Entity to use from that point forward.
+        It should be noted that when this function is used, a different entity will be referenced.
+        Since each entity is tied to a certain namespace, at every point in time.
 
         Args:
             namespace (str): Name of the new namespace
@@ -44,7 +46,12 @@ def set_namespace(self, namespace: str) -> None:
             None.
 
         Examples:
-            >>> self.set_namespace("hass1")
+            >>> # access entity in Hass namespace
+            >>> self.my_enitity = self.get_entity("light.living_room")
+            >>> # want to copy the same entity into another namespace
+            >>> entity_data = self.my_enitity.copy()
+            >>> self.my_enitity.set_namespace("my_namespace")
+            >>> self.my_enitity.set_state(**entity_data)
 
         """
         self._namespace = namespace
@@ -374,7 +381,7 @@ async def wait_state(
             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
+                                When it times out, a appdaemon.exceptions.TimeOutException is raised
 
         Returns:
             None
@@ -475,7 +482,11 @@ async def is_state(self, state: Any) -> bool:
 
     @utils.sync_wrapper
     async def turn_on(self, **kwargs: Optional[Any]) -> Any:
-        """Generic function, used to turn the entity ON if supported
+        """Generic helper function, used to turn the entity ON if supported.
+        This function will attempt to call the `turn_on` service if registered,
+        either by an app or plugin within the entity's namespace. So therefore its
+        only functional, if the service `turn_on` exists within the namespace the
+        entity is operating in.
 
         Keyword Args:
             **kwargs: Turn_on services depending on the namespace functioning within
@@ -489,7 +500,11 @@ async def turn_on(self, **kwargs: Optional[Any]) -> Any:
 
     @utils.sync_wrapper
     async def turn_off(self, **kwargs: Optional[Any]) -> Any:
-        """Generic function, used to turn the entity OFF if supported
+        """Generic function, used to turn the entity OFF if supported.
+        This function will attempt to call the `turn_off` service if registered,
+        either by an app or plugin within the entity's namespace. So therefore its
+        only functional, if the service `turn_off` exists within the namespace the
+        entity is operating in.
 
         Keyword Args:
             **kwargs: Turn_off services depending on the namespace functioning within
@@ -503,7 +518,11 @@ async def turn_off(self, **kwargs: Optional[Any]) -> Any:
 
     @utils.sync_wrapper
     async def toggle(self, **kwargs: Optional[Any]) -> Any:
-        """Generic function, used to toggle the entity ON/OFF if supported
+        """Generic function, used to toggle the entity ON/OFF if supported.
+        This function will attempt to call the `toggle` service if registered,
+        either by an app or plugin within the entity's namespace. So therefore its
+        only functional, if the service `toggle` exists within the namespace the
+        entity is operating in.
 
         Keyword Args:
             **kwargs: Toggle services depending on the namespace functioning within

docs/AD_API_REFERENCE.rst

@@ -35,8 +35,10 @@ 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.
+AppDaemon supports the ability to access entities as class objects in their own right, via the api call ``get_entity(entity)``.
+This AD does by creating an object which links to the given entity within a specified namespace per app, using an `Entity` class which can be used within the app.
+When this is done, the returned object allows to maximise the OOP nature of python while working with entities. AD will do this,
+even if the entity doesn't actually exist in AD at that point in time. If this is the case, the returned object can be used to add the entity.
 for example:
 
 .. code:: python
@@ -76,16 +78,16 @@ Entity API
 .. 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
+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