1+ from typing import Any , Callable , overload
2+
3+ from appdaemon .adapi import ADAPI
4+ from appdaemon .adbase import ADBase
5+
6+
7+ class Hass (ADBase , ADAPI ):
8+ def call_service (
9+ self ,
10+ service : str ,
11+ namespace : str | None = None ,
12+ timeout : str | int | float | None = None ,
13+ callback : Callable | None = None ,
14+ hass_timeout : str | int | float | None = None ,
15+ suppress_log_messages : bool = False ,
16+ ** data ,
17+ ) -> Any :
18+ """Calls a Service within AppDaemon.
19+
20+ Services represent specific actions, and are generally registered by plugins or provided by AppDaemon itself.
21+ The app calls the service only by referencing the service with a string in the format ``<domain>/<service>``, so
22+ there is no direct coupling between apps and services. This allows any app to call any service, even ones from
23+ other plugins.
24+
25+ Services often require additional parameters, such as ``entity_id``, which AppDaemon will pass to the service
26+ call as appropriate, if used when calling this function. This allows arbitrary data to be passed to the service
27+ calls.
28+
29+ Apps can also register their own services using their ``self.regsiter_service`` method.
30+
31+ Args:
32+ service (str): The service name in the format `<domain>/<service>`. For example, `light/turn_on`.
33+ namespace (str, optional): It's safe to ignore this parameter in most cases because the default namespace
34+ will be used. However, if a `namespace` is provided, the service call will be made in that namespace. If
35+ there's a plugin associated with that namespace, it will do the service call. If no namespace is given,
36+ AppDaemon will use the app's namespace, which can be set using the ``self.set_namespace`` method. See
37+ the section on `namespaces <APPGUIDE.html#namespaces>`__ for more information.
38+ timeout (str | int | float, optional): The internal AppDaemon timeout for the service call. If no value is
39+ specified, the default timeout is 60s. The default value can be changed using the
40+ ``appdaemon.internal_function_timeout`` config setting.
41+ callback (callable): The non-async callback to be executed when complete. It should accept a single
42+ argument, which will be the result of the service call. This is the recommended method for calling
43+ services which might take a long time to complete. This effectively bypasses the ``timeout`` argument
44+ because it only applies to this function, which will return immediately instead of waiting for the
45+ result if a `callback` is specified.
46+ hass_timeout (str | int | float, optional): Only applicable to the Hass plugin. Sets the amount of time to
47+ wait for a response from Home Assistant. If no value is specified, the default timeout is 10s. The
48+ default value can be changed using the ``ws_timeout`` setting the in the Hass plugin configuration in
49+ ``appdaemon.yaml``. Even if no data is returned from the service call, Home Assistant will still send an
50+ acknowledgement back to AppDaemon, which this timeout applies to. Note that this is separate from the
51+ ``timeout``. If ``timeout`` is shorter than this one, it will trigger before this one does.
52+ suppress_log_messages (bool, optional): Only applicable to the Hass plugin. If this is set to ``True``,
53+ Appdaemon will suppress logging of warnings for service calls to Home Assistant, specifically timeouts
54+ and non OK statuses. Use this flag and set it to ``True`` to supress these log messages if you are
55+ performing your own error checking as described `here <APPGUIDE.html#some-notes-on-service-calls>`__
56+ service_data (dict, optional): Used as an additional dictionary to pass arguments into the ``service_data``
57+ field of the JSON that goes to Home Assistant. This is useful if you have a dictionary that you want to
58+ pass in that has a key like ``target`` which is otherwise used for the ``target`` argument.
59+ **data: Any other keyword arguments get passed to the service call as ``service_data``. Each service takes
60+ different parameters, so this will vary from service to service. For example, most services require
61+ ``entity_id``. The parameters for each service can be found in the actions tab of developer tools in
62+ the Home Assistant web interface.
63+
64+ Returns:
65+ Result of the `call_service` function if any, see
66+ `service call notes <APPGUIDE.html#some-notes-on-service-calls>`__ for more details.
67+
68+ Examples:
69+ HASS
70+ ^^^^
71+
72+ >>> self.call_service("light/turn_on", entity_id="light.office_lamp", color_name="red")
73+ >>> self.call_service("notify/notify", title="Hello", message="Hello World")
74+ >>> events = self.call_service(
75+ "calendar/get_events",
76+ entity_id="calendar.home",
77+ start_date_time="2024-08-25 00:00:00",
78+ end_date_time="2024-08-27 00:00:00",
79+ )["result"]["response"]["calendar.home"]["events"]
80+
81+ MQTT
82+ ^^^^
83+
84+ >>> self.call_service("mqtt/subscribe", topic="homeassistant/living_room/light", qos=2)
85+ >>> self.call_service("mqtt/publish", topic="homeassistant/living_room/light", payload="on")
86+
87+ Utility
88+ ^^^^^^^
89+
90+ It's important that the ``namespace`` arg is set to ``admin`` for these services, as they do not exist
91+ within the default namespace, and apps cannot exist in the ``admin`` namespace. If the namespace is not
92+ specified, calling the method will raise an exception.
93+
94+ >>> self.call_service("app/restart", app="notify_app", namespace="admin")
95+ >>> self.call_service("app/stop", app="lights_app", namespace="admin")
96+ >>> self.call_service("app/reload", namespace="admin")
97+
98+ """
99+ ...
0 commit comments