haanim 0.2.0__py3-none-any.whl

haanim/__init__.py

@@ -0,0 +1,166 @@
+"""HAAnim: Python automations for Home Assistant.
+
+This package holds the automation engine and the test harness
+(``haanim.testing``). The Home Assistant integration in
+``custom_components/haanim`` is the glue that connects the engine to a running
+instance. Importing this package does not import Home Assistant.
+
+It also carries the type information for what an automation imports::
+
+    from haanim import haa, action, on_state, StateEvent
+
+Inside Home Assistant, and inside the test harness, each automation gets these
+names from the interpreter, bound to that automation. Here they are the same
+classes and decorators, so editors and type checkers see the real signatures.
+``haa``, ``hass`` and ``logging`` belong to a running automation and exist here
+for type checking only.
+"""
+
+from typing import TYPE_CHECKING, Any
+
+from haanim.const import ActionMode
+from haanim.engine.card import HAAnimCard
+from haanim.engine.card_elements import (
+    BadgeElement,
+    ButtonElement,
+    CardElement,
+    CardLayout,
+    CardRow,
+    EntityElement,
+    GaugeElement,
+    GraphElement,
+    HtmlElement,
+    IconElement,
+    ImageElement,
+    TextElement,
+    ValueElement,
+)
+from haanim.engine.decorators import (
+    action,
+    on_cron,
+    on_event,
+    on_interval,
+    on_state,
+    on_time,
+    shutdown,
+    startup,
+)
+from haanim.engine.errors import (
+    PUBLIC_ERRORS,
+    ActionCancelledError,
+    ActionDroppedError,
+    ActionNotFoundError,
+    ActionTimeOutError,
+    AutomationAlreadyRunningError,
+    AutomationDisabledError,
+    AutomationNotLoadedError,
+    AutomationNotRunningError,
+    AutomationSecurityError,
+    AutomationSyntaxError,
+    HAAnimError,
+    NonExistingAutomationError,
+    NonExistingEntityError,
+    NonExistingServiceError,
+    PoolExhaustedError,
+    QueueFullError,
+)
+from haanim.engine.haanim_api import HAAnim, HAAnimAutomationProxy, HAAnimServiceCall, HAAnimServiceProxy
+from haanim.engine.logging_wrapper import LoggerWrapper
+from haanim.entity import HAAnimEntity
+from haanim.events import (
+    ActionEvent,
+    AutomationEvent,
+    CronEvent,
+    EventTriggerEvent,
+    IntervalEvent,
+    ManualEvent,
+    StateEvent,
+    TimeEvent,
+)
+
+__version__ = "0.2.0"
+
+RUNTIME_ONLY = ("haa", "hass", "logging")
+"""Names an automation imports that exist only while it runs: the interpreter supplies them."""
+
+if TYPE_CHECKING:
+    haa: HAAnim
+    hass: Any
+    logging: LoggerWrapper
+
+
+def __getattr__(name: str) -> Any:
+    """Explain why a name of a running automation is not here."""
+    if name in RUNTIME_ONLY:
+        raise AttributeError(
+            f"'{name}' exists only inside a running automation: Home Assistant and the test harness "
+            "(haanim.testing.AutomationHarness) supply it to each automation they load"
+        )
+    raise AttributeError(f"module 'haanim' has no attribute '{name}'")
+
+
+__all__ = [
+    "__version__",
+    # The API object and what it hands out
+    "haa",
+    "hass",
+    "logging",
+    "HAAnim",
+    "HAAnimAutomationProxy",
+    "HAAnimCard",
+    "CardElement",
+    "CardLayout",
+    "CardRow",
+    "TextElement",
+    "HtmlElement",
+    "ImageElement",
+    "ValueElement",
+    "EntityElement",
+    "IconElement",
+    "GaugeElement",
+    "BadgeElement",
+    "GraphElement",
+    "ButtonElement",
+    "HAAnimEntity",
+    "HAAnimServiceCall",
+    "HAAnimServiceProxy",
+    "LoggerWrapper",
+    "RUNTIME_ONLY",
+    # Decorators
+    "action",
+    "startup",
+    "shutdown",
+    "on_time",
+    "on_interval",
+    "on_cron",
+    "on_event",
+    "on_state",
+    "ActionMode",
+    # Events
+    "ActionEvent",
+    "TimeEvent",
+    "IntervalEvent",
+    "CronEvent",
+    "StateEvent",
+    "EventTriggerEvent",
+    "ManualEvent",
+    "AutomationEvent",
+    # Errors
+    "PUBLIC_ERRORS",
+    "HAAnimError",
+    "AutomationSyntaxError",
+    "AutomationSecurityError",
+    "NonExistingAutomationError",
+    "AutomationNotLoadedError",
+    "AutomationNotRunningError",
+    "AutomationAlreadyRunningError",
+    "AutomationDisabledError",
+    "ActionNotFoundError",
+    "ActionDroppedError",
+    "QueueFullError",
+    "PoolExhaustedError",
+    "ActionTimeOutError",
+    "ActionCancelledError",
+    "NonExistingEntityError",
+    "NonExistingServiceError",
+]

haanim/const.py

@@ -0,0 +1,141 @@
+"""Constants for the HAAnim engine."""
+
+from enum import Enum
+from typing import Final
+
+__all__ = [
+    # Enums
+    "ActionMode",
+    # Trigger kinds
+    "TRIGGER_TIME",
+    "TRIGGER_INTERVAL",
+    "TRIGGER_CRON",
+    "TRIGGER_EVENT",
+    "TRIGGER_STATE",
+    # Constraint kinds
+    "CONSTRAINT_TIME",
+    "CONSTRAINT_STATE",
+    # Host events
+    "EVENT_HOST_STARTED",
+    "EVENT_ACTION_ERROR",
+    # Defaults
+    "DEFAULT_ACTION_QUEUE_SIZE",
+    "DEFAULT_ACTION_TIMEOUT",
+    "DEFAULT_MAX_CONCURRENT_ACTIONS",
+    "DEFAULT_WORKER_SHUTDOWN_TIMEOUT",
+    "DEFAULT_STARTUP_TIMEOUT",
+    "DEFAULT_SHUTDOWN_TIMEOUT",
+    "DEFAULT_STOP_GRACE_PERIOD",
+    "DEFAULT_IMPORT_ALLOWLIST",
+    # Security
+    "RESTRICTED_BUILTINS",
+    "DISABLED_MODULE_MEMBERS",
+    "DISABLED_LOOP_MEMBERS",
+    "LOOP_GETTERS",
+]
+
+
+class ActionMode(Enum):
+    """Action execution modes for handling concurrent calls.
+
+    DROP: Drop new action request if already executing.
+    QUEUE: Queue action request to execute sequentially.
+    CANCEL: Cancel current action and start new execution.
+    """
+
+    DROP = "drop"
+    QUEUE = "queue"
+    CANCEL = "cancel"
+
+
+# The kinds of trigger; each is attached with the decorator ``on_<kind>``
+TRIGGER_TIME: Final = "time"
+TRIGGER_INTERVAL: Final = "interval"
+TRIGGER_CRON: Final = "cron"
+TRIGGER_EVENT: Final = "event"
+TRIGGER_STATE: Final = "state"
+
+# The kinds of constraint a trigger can carry
+CONSTRAINT_TIME: Final = "time"
+CONSTRAINT_STATE: Final = "state"
+
+# Event the host fires once it has finished starting
+EVENT_HOST_STARTED: Final = "homeassistant_started"
+
+# Fired when an action called by a trigger fails (see "Trigger Functions Are Actions" in the design)
+EVENT_ACTION_ERROR: Final = "haanim_action_error"
+
+# Default action settings
+DEFAULT_ACTION_QUEUE_SIZE: Final = 100
+DEFAULT_ACTION_TIMEOUT: Final = 0  # 0 = no timeout
+DEFAULT_MAX_CONCURRENT_ACTIONS: Final = 20
+DEFAULT_WORKER_SHUTDOWN_TIMEOUT: Final = 0.2  # 200ms
+
+# Modules an automation can import by default (see "Imports" in the design).
+# "hass" and "haanim" are supplied by the engine; the rest are standard modules.
+DEFAULT_IMPORT_ALLOWLIST: Final[list[str]] = [
+    "asyncio",
+    "datetime",
+    "json",
+    "logging",
+    "math",
+    "random",
+    "re",
+    "time",
+    "typing",
+    "collections",
+    "functools",
+    "itertools",
+    "operator",
+    "statistics",
+    "decimal",
+    "fractions",
+    "enum",
+    "dataclasses",
+    "html",
+    "hass",
+    "haanim",
+]
+
+# Builtins that are not available in automations
+RESTRICTED_BUILTINS: Final[set[str]] = {
+    "eval",
+    "exec",
+    "compile",
+    "__import__",
+    "open",
+    "input",
+    "breakpoint",
+    "globals",
+    "locals",
+}
+
+# Members of allowed modules that block the event loop or leave it, with what to use instead
+DISABLED_MODULE_MEMBERS: Final[dict[str, dict[str, str]]] = {
+    "time": {
+        "sleep": "use 'await haa.sleep()'",
+    },
+    "asyncio": {
+        "run": "automations already run on the event loop",
+        "new_event_loop": "automations run on Home Assistant's event loop",
+        "set_event_loop": "automations run on Home Assistant's event loop",
+        "to_thread": "automations do not use threads",
+        "create_subprocess_exec": "automations cannot start processes",
+        "create_subprocess_shell": "automations cannot start processes",
+    },
+}
+
+# Methods of the event loop that are disabled for the same reason
+DISABLED_LOOP_MEMBERS: Final[dict[str, str]] = {
+    "run_forever": "the event loop is already running",
+    "run_until_complete": "the event loop is already running; use 'await'",
+    "run_in_executor": "automations do not use threads",
+}
+
+# Functions of asyncio that return the event loop
+LOOP_GETTERS: Final[set[str]] = {"get_event_loop", "get_running_loop"}
+
+# Lifecycle time limits, in seconds (see "Automation Lifecycle" in the design)
+DEFAULT_STARTUP_TIMEOUT: Final = 30.0
+DEFAULT_SHUTDOWN_TIMEOUT: Final = 10.0
+DEFAULT_STOP_GRACE_PERIOD: Final = 0.5

haanim/engine/__init__.py

@@ -0,0 +1,34 @@
+"""AST-based Python automation execution engine for HAAnim.
+
+This package provides a restricted Python execution environment using
+AST (Abstract Syntax Tree) evaluation instead of exec/eval.
+"""
+
+from __future__ import annotations
+
+from haanim.engine.ast_evaluator import AstEvaluator
+from haanim.engine.errors import (
+    HAAnimError,
+    AutomationRuntimeError,
+    AutomationSecurityError,
+    AutomationSyntaxError,
+)
+from haanim.engine.eval_function import EvalFunction, ReturnValue
+from haanim.engine.import_controller import ImportController
+from haanim.engine.safe_builtins import SafeBuiltins
+from haanim.engine.symbol_table import SymbolTable
+
+__all__ = [
+    # Error types
+    "HAAnimError",
+    "AutomationRuntimeError",
+    "AutomationSecurityError",
+    "AutomationSyntaxError",
+    # Core components
+    "AstEvaluator",
+    "EvalFunction",
+    "ImportController",
+    "ReturnValue",
+    "SafeBuiltins",
+    "SymbolTable",
+]