Merge pull request #2246 from AppDaemon/typing

Docstrings and Typing

Author: acockburn

appdaemon/adapi.py

@@ -10,12 +10,12 @@
 import sys
 import traceback
 from collections import OrderedDict
-from collections.abc import Iterable
+from collections.abc import AsyncGenerator, Iterable
 from copy import copy
 from functools import partial, reduce, wraps
 from logging import Logger
 from pathlib import Path
-from typing import TYPE_CHECKING, Literal
+from typing import TYPE_CHECKING, Literal, TypeVar
 
 from pydantic import ValidationError
 
@@ -33,6 +33,8 @@
     from .appdaemon import AppDaemon
     from .plugin_management import PluginBase
 
+T = TypeVar("T")
+
 
 class AppManagement:
     """Subsystem container for managing app lifecycles"""
@@ -44,6 +46,7 @@ class AppManagement:
     logger: Logger
     """Standard python logger named ``AppDaemon._app_management``
     """
+    name: str = "_app_management"
     error: Logger
     """Standard python logger named ``Error``
     """
@@ -80,7 +83,7 @@ class AppManagement:
     def __init__(self, ad: "AppDaemon"):
         self.AD = ad
         self.ext = self.AD.config.ext
-        self.logger = ad.logging.get_child("_app_management")
+        self.logger = ad.logging.get_child(self.name)
         self.error = ad.logging.get_error()
         self.diag = ad.logging.get_diag()
         self.filter_files = {}
@@ -468,7 +471,7 @@ async def create_app_object(self, app_name: str) -> None:
         )
 
         if (pin := cfg.pin_thread) and pin >= self.AD.threading.total_threads:
-            raise ade.PinOutofRange()
+            raise ade.PinOutofRange(pin_thread=pin, total_threads=self.AD.threading.total_threads)
         elif (obj := self.objects.get(app_name)) and obj.pin_thread is not None:
             pin = obj.pin_thread
         else:
@@ -538,7 +541,7 @@ async def terminate_sequence(self, name: str) -> bool:
     async def read_all(self, config_files: Iterable[Path] = None) -> AllAppConfig:
         config_files = config_files or self.dependency_manager.config_files
 
-        async def config_model_factory():
+        async def config_model_factory() -> AsyncGenerator[AllAppConfig, None, None]:
             """Creates a generator that sets the config_path of app configs"""
             for path in config_files:
                 @ade.wrap_async(self.error, self.AD.app_dir, "Reading user apps")
@@ -862,7 +865,9 @@ def _process_import_paths(self):
                     self.add_to_import_path(path)
             case 'legacy':
                 for root, subdirs, files in os.walk(self.AD.app_dir):
-                    if utils.is_valid_root_path(root) and root not in sys.path:
+                    base = os.path.basename(root)
+                    valid_root = base != "__pycache__" and not base.startswith(".")
+                    if valid_root and root not in sys.path:
                         self.add_to_import_path(root)
 
     async def _init_dep_manager(self):

appdaemon/app_management.py

@@ -1,5 +1,6 @@
 import ast
 import logging
+from collections.abc import Generator
 from pathlib import Path
 from typing import Iterable
 
@@ -46,6 +47,7 @@ def resolve_relative_import(node: ast.ImportFrom, path: Path):
         for _ in range(levels_to_remove):
             parts.pop(-1)
     else:
+        assert isinstance(node.module, str)
         parts = node.module.split(".")
 
     if node.module:
@@ -64,7 +66,7 @@ def __init__(self, base_exception: Exception, *args: object) -> None:
         self.base_exception = base_exception
 
 
-def get_imports(parsed_module: ast.Module):
+def get_imports(parsed_module: ast.Module) -> Generator[ast.Import | ast.ImportFrom, None, None]:
     yield from (
         n for n in parsed_module.body
         if isinstance(n, (ast.Import, ast.ImportFrom))
@@ -85,7 +87,7 @@ def get_file_deps(file_path: str | Path) -> set[str]:
     with file_path.open("r") as file:
         file_content = file.read()
 
-    def gen_modules():
+    def gen_modules() -> Generator[str, None, None]:
         try:
             mod: ast.Module = ast.parse(file_content, filename=file_path)
         except Exception as e:
@@ -99,7 +101,7 @@ def gen_modules():
                         if node.level:
                             abs_module = resolve_relative_import(node, file_path)
                             yield abs_module
-                        else:
+                        elif isinstance(node.module, str):
                             yield node.module
 
     return set(gen_modules())
@@ -148,7 +150,7 @@ def reverse_graph(graph: dict[str, set[str]]) -> dict[str, set[str]]:
     Returns:
         Graph: A new graph with the direction of all edges reversed.
     """
-    reversed_graph = {n: set() for n in get_all_nodes(graph)}
+    reversed_graph: dict[str, set[str]] = {n: set() for n in get_all_nodes(graph)}
 
     for module, dependencies in graph.items():
         if dependencies:
@@ -159,13 +161,16 @@ def reverse_graph(graph: dict[str, set[str]]) -> dict[str, set[str]]:
 
 
 def find_all_dependents(
-    base_nodes: Iterable[str], reversed_deps: dict[str, set[str]], visited: set[str] = None
-) -> set[str]:
+    base_nodes: Iterable[str],
+    reversed_deps: dict[str, set[str]],
+    visited: set[str] | None = None
+) -> set[str]:  # fmt: skip
     """Recursively find all nodes that depend on the specified base nodes.
 
     Args:
         base_nodes (Iterable[str]): A list or set of base node names to start the search from.
-        reversed_deps (Graph): A dictionary representing the reversed graph where keys are node names and values are sets of nodes that depend on the key node.
+        reversed_deps (Graph): A dictionary representing the reversed graph where keys are node names and values are
+            sets of nodes that depend on the key node.
         visited (set[str], optional): A set of nodes that have already been visited. Defaults to None.
 
     Returns: