Merge branch 'testing-docs'

Author: jsl12

appdaemon/__main__.py

@@ -17,7 +17,7 @@
 import os
 import signal
 import sys
-from collections.abc import Callable
+from collections.abc import Callable, Generator
 from contextlib import ExitStack, contextmanager
 from logging import Logger
 from pathlib import Path
@@ -271,8 +271,9 @@ def parse_config(args: argparse.Namespace, stop_function: Callable) -> MainConfi
 
 
 class ADMain:
-    """
-    Class to encapsulate all main() functionality.
+    """Main application class for AppDaemon, which contains the parsed CLI arguments, top-level config model, and the async event loop.
+
+    When this class is instantiated, it creates a :py:class:`~appdaemon.dependency_manager.DependencyManager` from the app directory. This causes
     """
 
     AD: AppDaemon
@@ -286,13 +287,13 @@ class ADMain:
     _cleanup_stack: ExitStack
 
     model: MainConfig
+    """Pydantic model of the top-level object for the appdaemon.yaml file."""
     args: argparse.Namespace
 
     stop_time: float = 0.0
     """Stores the value of perf_counter() when self.stop is first called."""
 
-    def __init__(self, args: argparse.Namespace):
-        """Constructor."""
+    def __init__(self, args: argparse.Namespace) -> None:
         self.args = args
         self.http_object = None
         self._cleanup_stack = ExitStack()
@@ -302,7 +303,7 @@ def __init__(self, args: argparse.Namespace):
             self.setup_logging()
             utils.deprecation_warnings(self.model.appdaemon, self.logger)
 
-            # # Create the dependency manager here so that all the initial file reading happens in here
+            # Create the dependency manager here so that all the initial file reading happens in here
             self.dep_manager = DependencyManager.from_app_directory(
                 self.model.appdaemon.app_dir,
                 exclude=self.model.appdaemon.exclude_dirs,
@@ -325,10 +326,10 @@ def __enter__(self):
                 pidfile_path = Path(self.args.pidfile).resolve()
                 self.logger.info("Using pidfile: %s", pidfile_path)
                 pid_file = pid.PidFile(pidfile_path.name, pidfile_path.parent)
-                self.enter_context(pid_file)
+                self._cleanup_stack.enter_context(pid_file)
 
-            self.enter_context(self.loop_context())
-            self.enter_context(self.signal_handlers(self.loop))
+            self._cleanup_stack.enter_context(self.loop_context())
+            self._cleanup_stack.enter_context(self.signal_handlers(self.loop))
             return self
         except Exception as e:
             ade.user_exception_block(self.logger, e, self.model.appdaemon.app_dir, header="ADMain __enter__")
@@ -342,10 +343,6 @@ def add_cleanup(self, cleanup_func, *args, **kwargs):
         """Add a cleanup function to be called on exit."""
         self._cleanup_stack.callback(cleanup_func, *args, **kwargs)
 
-    def enter_context(self, context_manager):
-        """Enter a context manager and ensure it's cleaned up on exit."""
-        return self._cleanup_stack.enter_context(context_manager)
-
     def handle_sig(self, signum: int):
         """Function to handle signals.
 
@@ -366,13 +363,13 @@ def handle_sig(self, signum: int):
             case (signal.SIGINT | signal.SIGTERM) as sig:
                 self.logger.info(f"Received signal: {signal.Signals(sig).name}")
                 self.stop()
-            # case signal.SIGWINCH:
-            #     ... # disregard window changes
-            # case _:
-            #     self.logger.error(f'Unhandled signal: {signal.Signals(signum).name}')
 
     @contextmanager
-    def loop_context(self):
+    def loop_context(self) -> Generator[asyncio.AbstractEventLoop]:
+        """Context manager that creates a new async event loop and cleans it up afterwards.
+
+        Includes the logic to install uvloop if it's enabled.
+        """
         # uvloop needs to be installed outside of self.run_context
         if self.model.appdaemon.uvloop and uvloop is not None:
             uvloop.install()
@@ -410,15 +407,18 @@ def signal_handlers(self, loop: asyncio.AbstractEventLoop):
                     pass
 
     def stop(self):
-        """Called by the signal handler to shut AD down."""
+        """Stop AppDaemon and stop the event loop afterwards."""
         self.stop_time = perf_counter()
         task = self.loop.create_task(self.AD.stop())
         task.add_done_callback(lambda _: self.loop.stop())
 
     def run(self) -> None:
-        """Start AppDaemon up after initial argument parsing."""
-        self.enter_context(self.startup_text())
-        self.enter_context(self.run_context(self.loop))
+        """Start AppDaemon up after initial argument parsing.
+
+        This uses :py:meth:`~asyncio.loop.run_forever` on the event loop to run it indefinitely.
+        """
+        self._cleanup_stack.enter_context(self.startup_text())
+        self._cleanup_stack.enter_context(self.run_context(self.loop))
         self.AD.start()
         self.logger.debug("Running async event loop forever")
         self.loop.run_forever()
@@ -495,17 +495,22 @@ def startup_text(self):
             self.logger.info("AppDaemon main() stopped gracefully in %s", utils.format_timedelta(stop_duration))
 
 
-def main():
+def main() -> None:
+    """Top-level entrypoint for AppDaemon
+
+    Parses the CLI arguments, configures logging, and runs the AppDaemon.
+    """
     args = parse_arguments()
 
+    CLI_LOG_CFG = PRE_LOGGING.copy()
+
     if args.debug is not None:
-        CLI_LOG_CFG = PRE_LOGGING.copy()
         CLI_LOG_CFG["root"]["level"] = args.debug
-        logging.config.dictConfig(CLI_LOG_CFG)
         logger.debug("Configured logging level from command line argument")
 
+    logging.config.dictConfig(CLI_LOG_CFG)
+
     with ADMain(args) as admain:
-        # raise ade.StartupAbortedException()
         admain.run()
 
 

appdaemon/app_management.py

@@ -164,8 +164,15 @@ def valid_apps(self) -> set[str]:
         return self.running_apps | self.loaded_globals
 
     def start(self) -> None:
-        self.logger.debug("Starting the app management subsystem")
+        """Start the app management subsystem, which creates async tasks to
+
+        * Initialize admin entities
+        * Call :meth:`~.check_app_updates`
+        * Fire an ``appd_started`` event in the ``global`` namespace.
+
+        """
         if self.AD.apps_enabled:
+            self.logger.debug("Starting the app management subsystem")
             self.AD.loop.create_task(self.init_admin_entities())
 
             task = self.AD.loop.create_task(
@@ -180,6 +187,10 @@ def start(self) -> None:
             )
 
     async def stop(self) -> None:
+        """Stop the app management subsystem and all the running apps.
+
+        * Calls :py:meth:`~.check_app_updates` with ``UpdateMode.TERMINATE``
+        """
         if self.AD.apps_enabled:
             self.logger.debug("Stopping the app management subsystem")
             await self.check_app_updates(mode=UpdateMode.TERMINATE)
@@ -841,19 +852,31 @@ async def check_app_updates(
 
         Called as part of :meth:`.utility_loop.Utility.loop`
 
-        Update Modes:
-        - NORMAL: Checks for changes and reloads apps as necessary.
-        - INIT: Used during startup trigger processing the import paths and initializing the dependency manager.
-        - TERMINATE: Adds all apps to the set to be terminated.
-        - RELOAD_APPS: Adds all apps and the modules they depend on to the respective reload sets. Used by the app
-            reload service.
-        - PLUGIN_FAILED: Stops all the apps of a plugin that failed.
-        - PLUGIN_RESTART: Restarts all the apps of a plugin that has started again.
-        - TESTING: Testing mode, used during testing to load apps without starting them.
+        NORMAL
+            Checks for changes and reloads apps as necessary.
+
+        INIT
+            Used during startup trigger processing the import paths and initializing the dependency manager.
+
+        TERMINATE
+            Adds all apps to the set to be terminated.
+
+        RELOAD_APPS
+            Adds all apps and the modules they depend on to the respective reload sets. Used by the app reload service.
+
+        PLUGIN_FAILED
+            Stops all the apps of a plugin that failed.
+
+        PLUGIN_RESTART
+            Restarts all the apps of a plugin that has started again.
+
+        TESTING
+            Testing mode, used during testing to load apps without starting them.
 
         Args:
             plugin_ns (str, optional): Namespace of a plugin to restart, if necessary. Defaults to None.
-            mode (UpdateMode, optional): Defaults to UpdateMode.NORMAL.
+            mode (UpdateMode, optional): Defaults to ``UpdateMode.NORMAL``.
+            update_actions (UpdateActions, optional): The update actions to perform. Defaults to None.
         """
         if not self.AD.apps_enabled:
             return

appdaemon/appdaemon.py

@@ -381,6 +381,14 @@ def utility_delay(self):
         return self.config.utility_delay
 
     def start(self) -> None:
+        """Start AppDaemon, which also starts all the component subsystems like the scheduler, etc.
+
+        - :meth:`ThreadAsync <appdaemon.thread_async.ThreadAsync.start>`
+        - :meth:`Scheduler <appdaemon.scheduler.Scheduler.start>`
+        - :meth:`Utility <appdaemon.utility_loop.Utility.start>`
+        - :meth:`AppManagement <appdaemon.app_management.AppManagement.start>`
+
+        """
         self.logger.debug("Starting AppDaemon")
         self.thread_async.start()
         self.sched.start()
@@ -390,15 +398,15 @@ def start(self) -> None:
             self.app_management.start()
 
     async def stop(self) -> None:
-        """Called by the signal handler to shut down AppDaemon.
+        """Stop AppDaemon by calling the stop method of the subsystems.
 
-        Also stops (in order):
+        This does not stop the event loop, but waits for all the existings tasks to finish before returning, which has a 3s timeout.
 
-        - :class:`~.app_management.AppManagement`
-        - :class:`~.thread_async.ThreadAsync`
-        - :class:`~.plugin_management.Plugins`
-        - :class:`~.scheduler.Scheduler`
-        - :class:`~.state.State`
+        - :meth:`AppManagement <appdaemon.app_management.AppManagement.stop>`
+        - :meth:`ThreadAsync <appdaemon.thread_async.ThreadAsync.stop>`
+        - :meth:`Plugins <appdaemon.plugin_management.Plugins.stop>`
+        - :meth:`Scheduler <appdaemon.scheduler.Scheduler.stop>`
+        - :meth:`State <appdaemon.state.State.stop>`
         """
         self.logger.info("Stopping AppDaemon")
         self.stopping = True

appdaemon/exceptions.py

@@ -52,7 +52,9 @@ def exception_handler(appdaemon: "AppDaemon", loop: asyncio.AbstractEventLoop, c
 
 
 def user_exception_block(logger: Logger, exception: AppDaemonException, app_dir: Path, header: str | None = None):
-    """Function to generate a user-friendly block of text for an exception. Gets the whole chain of exception causes to decide what to do.
+    """Generate a user-friendly block of text for an exception.
+
+    Gets the whole chain of exception causes to decide what to do.
     """
     width = 75
     spacing = 4

appdaemon/scheduler.py

@@ -33,6 +33,8 @@
 
 
 class Scheduler:
+    """AppDaemon subsystem to manage internal scheduling, calculate the times of sun-based events, and parse datetime
+    strings."""
     AD: "AppDaemon"
     logger: Logger
     error: Logger
@@ -42,7 +44,6 @@ class Scheduler:
 
     name: str = "_scheduler"
     active_event: asyncio.Event
-    stopping: bool = False
     loop_task: asyncio.Task[None]
 
     def __init__(self, ad: "AppDaemon"):
@@ -68,7 +69,10 @@ def __init__(self, ad: "AppDaemon"):
         # Setup sun
         self.init_sun()
 
-    def start(self):
+    def start(self) -> None:
+        """Starts the scheduler, which creates the the async task for :py:meth:`~appdaemon.scheduler.Scheduler.loop` and
+        adds some cleanup callbacks using the Python-native :py:meth:`~asyncio.Task.add_done_callback`.
+        """
         def _set_inactive(task: asyncio.Task[None]) -> None:
             """
             Callback to set the scheduler as inactive when the loop task is done.
@@ -92,13 +96,14 @@ def _shutdown_message(task: asyncio.Task[None]) -> None:
         self.loop_task.add_done_callback(_set_inactive)
         self.loop_task.add_done_callback(_shutdown_message)
 
-    def stop(self):
+    def stop(self) -> None:
+        """Stops the scheduler by cancelling the task for :py:meth:`~appdaemon.scheduler.Scheduler.loop`"""
         self.loop_task.cancel()
         self.logger.debug("Scheduler loop task was cancelled")
 
     @property
     def active(self) -> bool:
-        """Return whether the scheduler is active."""
+        """Whether the core scheduler loop is running."""
         return self.active_event.is_set()
 
     @active.setter
@@ -110,7 +115,7 @@ def active(self, value: bool) -> None:
 
     @property
     def realtime(self) -> bool:
-        """Return whether the scheduler is running in real time."""
+        """Whether the scheduler is running in real time (timewarp == 1)."""
         return self.AD.real_time
 
     async def _init_loop(self):
@@ -533,6 +538,7 @@ def get_next_dst_offset(self, base, limit):
         return limit
 
     async def loop(self):  # noqa: C901
+        """Core scheduler loop, which processes scheduled callbacks and sleeping between them."""
         self.logger.debug("Starting scheduler loop()")
         await self._init_loop()
 

appdaemon/services.py

@@ -13,14 +13,23 @@
 
 
 class ServiceCallback(Protocol):
-    def __call__(self, result: Any) -> None: ...
+    """Simple :py:class:`~typing.Protocol` for callbacks for service results."""
+    def __call__(self, result: Any) -> None:
+        """Required form of the callback function for a service result."""
 
 
 class Services:
     """Subsystem container for handling services
 
     Attributes:
         AD: Reference to the AppDaemon container object
+        services: AppDaemon's internal service registry, which is a set of nested dicts, organized like this:
+
+            * Namespace
+            * Domain
+            * Service name
+            * Service Info
+        services_lock: Re-entrant lock for preventing the service dict from being read and modified at the same time.
     """
 
     AD: "AppDaemon"
@@ -38,7 +47,8 @@ class Services:
         ]
     ] = {}
     services_lock: threading.RLock = threading.RLock()
-    app_registered_services: defaultdict[str, set[str]] = defaultdict(set)
+    app_registered_services: defaultdict[str, set[str]] = defaultdict(set)  # TODO: remove this
+
 
     def __init__(self, ad: "AppDaemon"):
         self.AD = ad