Merge branch 'dev' of https://github.com/AppDaemon/appdaemon into dev

Author: acockburn

appdaemon/adapi.py

@@ -1802,37 +1802,37 @@ def deregister_service(self, service: str, namespace: str | None = None) -> bool
         return self.AD.services.deregister_service(namespace, *service.split("/"), __name=self.name)
 
     def list_services(self, namespace: str = "global") -> list[dict[str, str]]:
-        """List all services available within AD
-
-        Using this function, an App can request all available services within AD
+        """List all services available within AppDaemon
 
         Args:
-            namespace(str, optional): If a `namespace` is provided, AppDaemon will request
-                the services within the given namespace. On the other hand, if no namespace is given,
-                AppDaemon will use the last specified namespace or the default namespace.
-                To get all services across AD, pass `global`. See the section on `namespaces <APPGUIDE.html#namespaces>`__
-                for a detailed description. In most cases, it is safe to ignore this parameter.
+            namespace(str, optional): If a ``namespace`` is provided, this function will return services only in that
+                namespace. Otherwise, the default value for ``namespace`` is ``global``, which will return services
+                across all namespaces. See the section on `namespaces <APPGUIDE.html#namespaces>`__ for more
+                information.
 
         Returns:
             List of dictionary with keys ``namespace``, ``domain``, and ``service``.
 
         Examples:
-            >>> self.list_services(namespace="global")
+            >>> services = self.list_services()
+
+            >>> services = self.list_services("default")
+
+            >>> services = self.list_services("mqtt")
 
         """
 
         self.logger.debug("list_services: %s", namespace)
-        return self.AD.services.list_services(namespace)  # retrieve services
+        return self.AD.services.list_services(namespace)
 
-    @overload
+    @overload # This overload provides the type hints for the Hass-specific version of this method
     async def call_service(
         self,
         service: str,
         namespace: str | None = None,
-        timeout: int | float | None = None,
-        return_result: bool = True,
+        timeout: str | int | float | None = None,
         callback: Callable | None = None,
-        hass_timeout: float = 10,
+        hass_timeout: str | int | float | None = None,
         suppress_log_messages: bool = False,
         **data,
     ) -> Any: ...
@@ -1842,82 +1842,90 @@ async def call_service(
         self,
         service: str,
         namespace: str | None = None,
-        timeout: int | float | None = None,  # Used by utils.sync_decorator
-        **data: Any | None,
+        timeout: str | int | float | None = None,  # Used by utils.sync_decorator
+        callback: Callable[[Any], Any] | None = None,
+        **data: dict[str, Any] | None,
     ) -> Any:
         """Calls a Service within AppDaemon.
 
-        This function can call any service and provide any required parameters.
-        By default, there are standard services that can be called within AD. Other
-        services that can be called, are dependent on the plugin used, or those registered
-        by individual apps using the `register_service` api.
-        In a future release, all available services can be found using AD's Admin UI.
-        For `listed services`, the part before the first period is the ``domain``,
-        and the part after is the `service name`. For instance, `light/turn_on`
-        has a domain of `light` and a service name of `turn_on`.
-
-        The default behaviour of the call service api is not to wait for any result, typically
-        known as "fire and forget". If it is required to get the results of the call, keywords
-        "return_result" or "callback" can be added.
-
-        Args:
-            service (str): The service name.
-            namespace(str, optional): If a `namespace` is provided, AppDaemon will change
-                the state of the given entity in the given namespace. On the other hand,
-                if no namespace is given, AppDaemon will use the last specified namespace
-                or the default namespace. See the section on `namespaces <APPGUIDE.html#namespaces>`__
-                for a detailed description. In most cases, it is safe to ignore this parameter.
-            return_result(str, option): If `return_result` is provided and set to `True` AD will attempt
-                to wait for the result, and return it after execution. In the case of Home Assistant calls that do not
-                return values this may seem pointless, but it does force the call to be synchronous with respect to Home Assistant
-                whcih can in turn highlight slow performing services if they timeout or trigger thread warnings.
-            callback: The non-async callback to be executed when complete.
-            hass_timeout (Home Assistant Specific): time in seconds to wait for Home Assistant's
-                response for this specific service call. If not specified defaults to the value of
-                the ``q_timeout`` parameter in the HASS plugin configuration, which itself defaults
-                to 30 seconds. See `Some Notes on Service Calls <APPGUIDE.html#some-notes-on-service-calls>`__
-            suppress_log_messages (Home Assistant Specific, False): if set to ``True`` Appdaemon will suppress
-                logging of warnings for service calls to Home Assistant, specifically timeouts and
-                non OK statuses. Use this flag and set it to ``True`` to supress these log messages
-                if you are performing your own error checking as described
-                `here <APPGUIDE.html#some-notes-on-service-calls>`__
-            **data: Each service has different parameter requirements. This argument
-                allows you to specify a comma-separated list of keyword value pairs, e.g.,
-                `entity_id = light.office_1`. These parameters will be different for
-                every service and can be discovered using the developer tools. Most all
-                service calls require an ``entity_id``.
-
-        Returns:
-            Result of the `call_service` function if any, see `service call notes <APPGUIDE.html#some-notes-on-service-calls>`__ for more details.
+        Services represent specific actions, and are generally registered by plugins or provided by AppDaemon itself.
+        The app calls the service only by referencing the service with a string in the format ``<domain>/<service>``, so
+        there is no direct coupling between apps and services. This allows any app to call any service, even ones from
+        other plugins.
+
+        Services often require additional parameters, such as ``entity_id``, which AppDaemon will pass to the service
+        call as appropriate, if used when calling this function. This allows arbitrary data to be passed to the service
+        calls.
+
+        Apps can also register their own services using their ``self.regsiter_service`` method.
+
+        Args:
+            service (str): The service name in the format `<domain>/<service>`. For example, `light/turn_on`.
+            namespace (str, optional): It's safe to ignore this parameter in most cases because the default namespace
+                will be used. However, if a `namespace` is provided, the service call will be made in that namespace. If
+                there's a plugin associated with that namespace, it will do the service call. If no namespace is given,
+                AppDaemon will use the app's namespace, which can be set using the ``self.set_namespace`` method. See
+                the section on `namespaces <APPGUIDE.html#namespaces>`__ for more information.
+            timeout (str | int | float, optional): The internal AppDaemon timeout for the service call. If no value is
+                specified, the default timeout is 60s. The default value can be changed using the
+                ``appdaemon.internal_function_timeout`` config setting.
+            callback (callable): The non-async callback to be executed when complete. It should accept a single
+                argument, which will be the result of the service call. This is the recommended method for calling
+                services which might take a long time to complete. This effectively bypasses the ``timeout`` argument
+                because it only applies to this function, which will return immediately instead of waiting for the
+                result if a `callback` is specified.
+            hass_timeout (str | int | float, optional): Only applicable to the Hass plugin. Sets the amount of time to
+                wait for a response from Home Assistant. If no value is specified, the default timeout is 10s. The
+                default value can be changed using the ``ws_timeout`` setting the in the Hass plugin configuration in
+                ``appdaemon.yaml``. Even if no data is returned from the service call, Home Assistant will still send an
+                acknowledgement back to AppDaemon, which this timeout applies to. Note that this is separate from the
+                ``timeout``. If ``timeout`` is shorter than this one, it will trigger before this one does.
+            suppress_log_messages (bool, optional): Only applicable to the Hass plugin. If this is set to ``True``,
+                Appdaemon will suppress logging of warnings for service calls to Home Assistant, specifically timeouts
+                and non OK statuses. Use this flag and set it to ``True`` to supress these log messages if you are
+                performing your own error checking as described `here <APPGUIDE.html#some-notes-on-service-calls>`__
+            service_data (dict, optional): Used as an additional dictionary to pass arguments into the ``service_data``
+                field of the JSON that goes to Home Assistant. This is useful if you have a dictionary that you want to
+                pass in that has a key like ``target`` which is otherwise used for the ``target`` argument.
+            **data: Any other keyword arguments get passed to the service call as ``service_data``. Each service takes
+                different parameters, so this will vary from service to service. For example, most services require
+                ``entity_id``. The parameters for each service can be found in the actions tab of developer tools in
+                the Home Assistant web interface.
+
+        Returns:
+            Result of the `call_service` function if any, see
+            `service call notes <APPGUIDE.html#some-notes-on-service-calls>`__ for more details.
 
         Examples:
             HASS
+            ^^^^
 
-            >>> self.call_service("light/turn_on", entity_id = "light.office_lamp", color_name = "red")
-            >>> self.call_service("notify/notify", title = "Hello", message = "Hello World")
-            >>> self.call_service(
+            >>> self.call_service("light/turn_on", entity_id="light.office_lamp", color_name="red")
+            >>> self.call_service("notify/notify", title="Hello", message="Hello World")
+            >>> events = self.call_service(
                     "calendar/get_events",
                     entity_id="calendar.home",
                     start_date_time="2024-08-25 00:00:00",
                     end_date_time="2024-08-27 00:00:00",
-                    return_result=True,
-                    hass_timeout=10
-                )
+                )["result]["response"]["calendar.home"]["events"]
 
             MQTT
+            ^^^^
 
-            >>> call_service("mqtt/subscribe", topic="homeassistant/living_room/light", qos=2)
-            >>> call_service("mqtt/publish", topic="homeassistant/living_room/light", payload="on")
+            >>> self.call_service("mqtt/subscribe", topic="homeassistant/living_room/light", qos=2)
+            >>> self.call_service("mqtt/publish", topic="homeassistant/living_room/light", payload="on")
 
             Utility
+            ^^^^^^^
+
+            It's important that the ``namespace`` arg is set to ``admin`` for these services, as they do not exist
+            within the default namespace, and apps cannot exist in the ``admin`` namespace. If the namespace is not
+            specified, calling the method will raise an exception.
 
-            >>> call_service("app/restart", app="notify_app", namespace="appdaemon")
-            >>> call_service("app/stop", app="lights_app", namespace="appdaemon")
-            >>> call_service("app/reload", namespace="appdaemon")
+            >>> self.call_service("app/restart", app="notify_app", namespace="admin")
+            >>> self.call_service("app/stop", app="lights_app", namespace="admin")
+            >>> self.call_service("app/reload", namespace="admin")
 
-            For Utility, it is important that the `namespace` arg is set to ``appdaemon``
-            as no app can work within that `namespace`. If namespace is not specified,
-            calling this function will raise an error.
         """
         self.logger.debug("call_service: %s, %s", service, data)
         self._check_service(service)
@@ -1932,7 +1940,18 @@ async def call_service(
                     for e in eid:
                         self._check_entity(namespace, e)
 
-        return await self.AD.services.call_service(namespace, *service.split("/", 2), name=self.name, data=data)
+        domain, service_name = service.split("/", 2)
+        coro = self.AD.services.call_service(
+            namespace=namespace,
+            domain=domain,
+            service=service_name,
+            data=data
+        )
+        if callback is None:
+            return await coro
+        else:
+            task = self.AD.loop.create_task(coro)
+            task.add_done_callback(lambda f: callback(f.result()))
 
     # Sequences
 

appdaemon/app_management.py

@@ -488,10 +488,10 @@ async def create_app_object(self, app_name: str) -> None:
                 class_name
             )
 
-        if utils.count_positional_arguments(app_class.__init__) != 3:
-            raise ade.BadClassSignature(class_name)
-
         new_obj = app_class(self.AD, cfg)
+        assert isinstance(getattr(new_obj, "AD", None), type(self.AD)), 'App objects need to have a reference to the AppDaemon object'
+        assert isinstance(getattr(new_obj, "config_model", None), AppConfig), 'App objects need to have a reference to their config model'
+
         self.objects[app_name] = ManagedObject(
             type="app",
             object=new_obj,

appdaemon/appdaemon.py

@@ -228,10 +228,6 @@ def exclude_dirs(self):
     def import_paths(self):
         return self.config.import_paths
 
-    @property
-    def internal_function_timeout(self):
-        return self.config.internal_function_timeout
-
     @property
     def invalid_config_warnings(self):
         return self.config.invalid_config_warnings

appdaemon/entity.py

@@ -358,7 +358,12 @@ async def call_service(self, service: str, namespace: str | None = None, **kwarg
         namespace = namespace or self.namespace
         kwargs["entity_id"] = self.entity_id
         self.logger.debug("call_service: %s/%s, %s", self.domain, service, kwargs)
-        return await self.AD.services.call_service(namespace, self.domain, service, self.name, kwargs)
+        return await self.AD.services.call_service(
+            namespace=namespace,
+            domain=self.domain,
+            service=service,
+            data=kwargs
+        )  # fmt: skip
 
     async def wait_state(
         self,

appdaemon/exceptions.py

@@ -44,7 +44,7 @@ def exception_handler(appdaemon: "AppDaemon", loop: asyncio.AbstractEventLoop, c
     """Handler to attach to the main event loop as a backstop for any async exception"""
     user_exception_block(
         logging.getLogger('Error'),
-        context['exception'],
+        context.get('exception'),
         appdaemon.app_dir,
         header='Unhandled exception in event loop'
     )

appdaemon/http.py

@@ -691,7 +691,12 @@ async def call_service(self, request):
 
             self.logger.debug("call_service() args = %s", args)
 
-            res = await self.AD.services.call_service(namespace, domain, service, args)
+            res = await self.AD.services.call_service(
+                namespace=namespace,
+                domain=domain,
+                service=service,
+                data=args
+            )  # fmt: skip
             return web.json_response({"response": res}, status=200, dumps=utils.convert_json)
 
         except Exception:

appdaemon/models/config/appdaemon.py

@@ -9,13 +9,13 @@
 from pytz.tzinfo import BaseTzInfo
 from typing_extensions import deprecated
 
+from appdaemon import utils
 from appdaemon.models.config.http import CoercedPath
 
 from ...models.config.plugin import HASSConfig, MQTTConfig
 from ...version import __version__
 from .misc import FilterConfig, NamespaceConfig
 
-
 def plugin_discriminator(plugin):
     if isinstance(plugin, dict):
         return plugin["type"].lower()
@@ -67,7 +67,10 @@ class AppDaemonConfig(BaseModel, extra="allow"):
     admin_delay: int = 1
     plugin_performance_update: int = 10
     """How often in seconds to update the admin entities with the plugin performance data"""
-    max_utility_skew: timedelta = Field(default_factory=lambda: timedelta(seconds=2), before_validator=lambda v: timedelta(seconds=v))
+    max_utility_skew: Annotated[
+        timedelta,
+        BeforeValidator(utils.convert_timedelta)
+    ] = Field(default_factory=lambda: timedelta(seconds=2))
     check_app_updates_profile: bool = False
     production_mode: bool = False
     invalid_config_warnings: bool = True
@@ -76,7 +79,12 @@ class AppDaemonConfig(BaseModel, extra="allow"):
     qsize_warning_threshold: int = 50
     qsize_warning_step: int = 60
     qsize_warning_iterations: int = 10
-    internal_function_timeout: int = 60
+    internal_function_timeout: Annotated[
+        timedelta,
+        BeforeValidator(utils.convert_timedelta)
+    ] = Field(default_factory=lambda: timedelta(seconds=60))
+    """Timeout for internal function calls. This determines how long apps can wait in their thread for an async function
+    to complete in the main thread."""
     use_dictionary_unpacking: Annotated[bool, deprecated("This option is no longer necessary")] = False
     uvloop: bool = False
     use_stream: bool = False

appdaemon/models/config/plugin.py

@@ -10,6 +10,8 @@
 
 from .common import CoercedPath
 
+from appdaemon import utils
+
 
 class PluginConfig(BaseModel, extra="allow"):
     type: str
@@ -93,7 +95,12 @@ class HASSConfig(PluginConfig):
     cert_verify: bool | None = None
     commtype: str = "WS"
     q_timeout: int = 30
-    return_result: bool | None = None
+    ws_timeout: Annotated[
+        timedelta,
+        BeforeValidator(utils.convert_timedelta)
+    ] = Field(default_factory=lambda: timedelta(seconds=10))
+    """Default timeout for waiting for responses from the websocket connection"""
+    # return_result: bool | None = None
     suppress_log_messages: bool = False
     retry_secs: int = 5
     services_sleep_time: int = 60