python-library-automation 0.1.16__py3-none-any.whl

automation/listeners/base.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from automation.hub import Hub
+
+class BaseListener:
+    """自动化生命周期监听器"""
+
+    def on_loaded(self, hub: Hub) -> None: pass
+    def on_start(self) -> None: pass
+    def on_stop(self) -> None: pass
+    def on_event_fired(self, event_name: str) -> None: pass
+    def on_trigger_started(self, trigger_name: str) -> None: pass
+    def on_trigger_skipped(self, trigger_name: str) -> None: pass
+    def on_trigger_completed(self, trigger_name: str, elapsed: float) -> None: pass
+    def on_trigger_aborted(self, trigger_name: str, condition_name: str) -> None: pass
+    def on_trigger_error(self, trigger_name: str, error: Exception) -> None: pass
+    def on_condition_checked(self, trigger_name: str, condition_name: str, passed: bool) -> None: pass
+    def on_action_started(self, trigger_name: str, action_name: str, *, params: dict | None = None) -> None: pass
+    def on_action_completed(self, trigger_name: str, action_name: str, elapsed: float, *, params: dict | None = None) -> None: pass
+    def on_action_error(self, trigger_name: str, action_name: str, error: Exception) -> None: pass
+    def on_load_error(self,section: str,instance: str,phase: str,code: str,error: Exception) -> None: pass

automation/listeners/console.py

@@ -0,0 +1,82 @@
+from __future__ import annotations
+import sys
+from .base import BaseListener
+
+class _Ansi:
+    RESET  = "\033[0m"
+    BOLD   = "\033[1m"
+    DIM    = "\033[2m"
+    RED    = "\033[31m"
+    GREEN  = "\033[32m"
+    YELLOW = "\033[33m"
+    CYAN   = "\033[36m"
+
+class ConsoleListener(BaseListener):
+    """默认彩色控制台渲染器"""
+
+    def _write(self, msg: str, prefix: str = "") -> None:
+        line = f"{_Ansi.DIM}[{prefix}]{_Ansi.RESET} {msg}" if prefix else msg
+        sys.stderr.write(line + "\n")
+        sys.stderr.flush()
+
+    def on_start(self) -> None:
+        self._write(f"{_Ansi.DIM}── Assistant started ──{_Ansi.RESET}")
+
+    def on_stop(self) -> None:
+        self._write(f"{_Ansi.DIM}── Assistant stopped ──{_Ansi.RESET}")
+
+    def on_event_fired(self, event_name: str) -> None:
+        self._write(f"{_Ansi.CYAN}{_Ansi.BOLD}⚡ {event_name}{_Ansi.RESET}")
+
+    def on_trigger_started(self, trigger_name: str) -> None:
+        self._write(f"{_Ansi.YELLOW}┌ {trigger_name}{_Ansi.RESET}")
+
+    def on_trigger_skipped(self, trigger_name: str) -> None:
+        self._write(f"{_Ansi.DIM}⏭ {trigger_name} (busy){_Ansi.RESET}")
+
+    def on_trigger_completed(self, trigger_name: str, elapsed: float) -> None:
+        time_str = f" {_Ansi.DIM}({elapsed:.2f}s){_Ansi.RESET}" if elapsed >= 0.005 else ""
+        self._write(
+            f"{_Ansi.YELLOW}└ {trigger_name}{_Ansi.RESET}{time_str}"
+        )
+
+    def on_trigger_aborted(self, trigger_name: str, condition_name: str) -> None:
+        self._write(
+            f"{_Ansi.YELLOW}└ {trigger_name}{_Ansi.RESET}"
+            f" {_Ansi.DIM}aborted by {condition_name}{_Ansi.RESET}"
+        )
+
+    def on_trigger_error(self, trigger_name: str, error: Exception) -> None:
+        self._write(
+            f"{_Ansi.YELLOW}└ {trigger_name}{_Ansi.RESET}"
+            f" {_Ansi.RED}error{_Ansi.RESET}"
+        )
+
+    def on_condition_checked(
+        self, trigger_name: str, condition_name: str, passed: bool
+    ) -> None:
+        if passed:
+            self._write(f"{_Ansi.GREEN}│ ✓ {condition_name}{_Ansi.RESET}")
+        else:
+            self._write(f"{_Ansi.RED}│ ✗ {condition_name}{_Ansi.RESET}")
+
+    def on_action_started(self, trigger_name: str, action_name: str, **_) -> None:
+        self._write(f"│ ▶ {action_name}", prefix=trigger_name)
+        
+    def on_action_completed(self, trigger_name: str, action_name: str, elapsed: float, **_) -> None:
+        time_str = f" {_Ansi.DIM}({elapsed:.2f}s){_Ansi.RESET}" if elapsed >= 0.005 else ""
+        self._write(
+            f"{_Ansi.GREEN}│ ✓ {action_name}{_Ansi.RESET}{time_str}",
+            prefix=trigger_name,
+        )
+        
+    def on_action_error(
+        self, trigger_name: str, action_name: str, error: Exception
+    ) -> None:
+        self._write(f"{_Ansi.RED}│ ✗ {action_name}: {error}{_Ansi.RESET}")
+
+    def on_load_error(self, section, instance, phase, code, error):
+        self._write(
+            f"{_Ansi.RED}✗ {section}.{instance} "
+            f"[{phase}/{code}]: {error}{_Ansi.RESET}"
+        )

automation/listeners/instance_schema.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+import json
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from .base import BaseListener
+
+if TYPE_CHECKING:
+    from automation.hub import Hub
+
+
+class InstanceSchemaListener(BaseListener):
+    """加载后输出实例 schema 到文件，展示当前运行时状态"""
+
+    def __init__(self, output_path: str | Path):
+        self._output_path = Path(output_path)
+
+    def on_loaded(self, hub: Hub) -> None:
+        from automation.schema import export_instance_schema
+
+        schema = export_instance_schema(hub)
+        self._output_path.parent.mkdir(parents=True, exist_ok=True)
+        self._output_path.write_text(
+            json.dumps(schema, indent=2, ensure_ascii=False, default=str),
+            encoding="utf-8",
+        )

automation/listeners/record.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+from typing import Literal
+from datetime import datetime
+from pydantic import BaseModel, Field
+
+
+class ConditionRecord(BaseModel):
+    expr: str
+    passed: bool
+
+
+class ActionRecord(BaseModel):
+    action: str
+    params: dict | None = None
+    status: Literal["running", "completed", "error"] = "running"
+    elapsed: float | None = None
+    error: str | None = None
+
+
+class TriggerRecord(BaseModel):
+    trigger: str
+    started_at: datetime = Field(default_factory=datetime.now)
+    finished_at: datetime | None = None
+    status: Literal["running", "completed", "error", "aborted"] = "running"
+    elapsed: float | None = None
+    error: str | None = None
+    aborted_by: str | None = None
+    conditions: list[ConditionRecord] = Field(default_factory=list)
+    actions: list[ActionRecord] = Field(default_factory=list)

automation/listeners/trace.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+from pathlib import Path
+from datetime import datetime
+
+from .base import BaseListener
+from .record import TriggerRecord, ActionRecord, ConditionRecord
+
+
+class TraceListener(BaseListener):
+    """将每次触发的执行记录写入独立 JSON 文件，用于调试回溯"""
+
+    def __init__(self, output_dir: str | Path):
+        self._output_dir = Path(output_dir)
+        self._output_dir.mkdir(parents=True, exist_ok=True)
+        self._pending: dict[str, TriggerRecord] = {}
+
+    def on_trigger_started(self, trigger_name: str) -> None:
+        self._pending[trigger_name] = TriggerRecord(trigger=trigger_name)
+
+    def on_condition_checked(self, trigger_name: str, condition_name: str, passed: bool) -> None:
+        if record := self._pending.get(trigger_name):
+            record.conditions.append(ConditionRecord(expr=condition_name, passed=passed))
+
+    def on_action_started(self, trigger_name: str, action_name: str, *, params: dict | None = None) -> None:
+        if record := self._pending.get(trigger_name):
+            record.actions.append(ActionRecord(action=action_name, params=params))
+
+    def on_action_completed(self, trigger_name: str, action_name: str, elapsed: float, *, params: dict | None = None) -> None:
+        if record := self._pending.get(trigger_name):
+            if record.actions and record.actions[-1].action == action_name:
+                record.actions[-1].status = "completed"
+                record.actions[-1].elapsed = round(elapsed, 4)
+
+    def on_action_error(self, trigger_name: str, action_name: str, error: Exception) -> None:
+        if record := self._pending.get(trigger_name):
+            if record.actions and record.actions[-1].action == action_name:
+                record.actions[-1].status = "error"
+                record.actions[-1].error = str(error)
+
+    def on_trigger_completed(self, trigger_name: str, elapsed: float) -> None:
+        self._flush(trigger_name, "completed", elapsed)
+
+    def on_trigger_error(self, trigger_name: str, error: Exception) -> None:
+        if record := self._pending.get(trigger_name):
+            record.error = str(error)
+        self._flush(trigger_name, "error")
+
+    def on_trigger_aborted(self, trigger_name: str, condition_name: str) -> None:
+        if record := self._pending.get(trigger_name):
+            record.aborted_by = condition_name
+        self._flush(trigger_name, "aborted")
+
+    def _flush(self, trigger_name: str, status: str, elapsed: float | None = None) -> None:
+        record = self._pending.pop(trigger_name, None)
+        if record is None:
+            return
+        record.status = status
+        record.finished_at = datetime.now()
+        if elapsed is not None:
+            record.elapsed = round(elapsed, 4)
+
+        now = datetime.now()
+        trigger_dir = self._output_dir / now.strftime("%Y-%m-%d") / trigger_name
+        trigger_dir.mkdir(parents=True, exist_ok=True)
+        filename = f"{now.strftime('%H-%M-%S-%f')}.json"
+        (trigger_dir / filename).write_text(
+            record.model_dump_json(indent=2),
+            encoding="utf-8",
+        )

automation/listeners/type_schema.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+import json
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from .base import BaseListener
+
+if TYPE_CHECKING:
+    from automation.hub import Hub
+
+
+class TypeSchemaListener(BaseListener):
+    """加载后输出类型 schema 到文件，告诉用户怎么写配置"""
+
+    def __init__(self, output_path: str | Path):
+        self._output_path = Path(output_path)
+
+    def on_loaded(self, hub: Hub) -> None:
+        from automation.schema import export_type_schema
+
+        schema = export_type_schema()
+        self._output_path.parent.mkdir(parents=True, exist_ok=True)
+        self._output_path.write_text(
+            json.dumps(schema, indent=2, ensure_ascii=False, default=str),
+            encoding="utf-8",
+        )

automation/loader.py

@@ -0,0 +1,131 @@
+import logging
+from typing import Any
+from .hub import Hub
+from .core.entity import entity_registry
+from .core.event import event_registry
+from .core.trigger import trigger_registry
+from .core.composite_action import CompositeAction
+from .errors import ConfigLoadError, LoadPhase, LoadErrorCode
+
+logger = logging.getLogger(__name__)
+
+SECTION_TO_REGISTRIES = {
+    "entities": entity_registry,
+    "events": event_registry,
+    "triggers": trigger_registry,
+}
+
+DEFAULT_TYPES: dict[str, str] = {
+    "triggers": "trigger",
+}
+
+
+def build_section(section_name, section_data):
+    registry = SECTION_TO_REGISTRIES[section_name]
+    default_type = DEFAULT_TYPES.get(section_name)
+    result = {}
+    for name, spec in section_data.items():
+        spec = dict(spec)
+        type_name = spec.pop("type", default_type)
+        if type_name is None:
+            raise ConfigLoadError(
+                section=section_name, instance=name,
+                phase=LoadPhase.BUILD, code=LoadErrorCode.MISSING_TYPE,
+            )
+        try:
+            cls = registry.get(type_name)
+        except KeyError as e:
+            raise ConfigLoadError(
+                section=section_name, instance=name,
+                phase=LoadPhase.BUILD, code=LoadErrorCode.UNKNOWN_TYPE,
+                cause=e,
+            ) from e
+        try:
+            result[name] = cls(instance_name=name, **spec)
+        except Exception as e:
+            raise ConfigLoadError(
+                section=section_name, instance=name,
+                phase=LoadPhase.BUILD, code=LoadErrorCode.INVALID_CONFIG,
+                cause=e,
+            ) from e
+    return result
+
+
+def build_actions(
+    section_data: dict[str, dict[str, Any]]
+) -> dict[str, CompositeAction]:
+    result = {}
+    for name, spec in section_data.items():
+        spec = dict(spec)
+        params = spec.get("params", {})
+        conditions = spec.get("conditions", [])
+        action_specs = spec.get("actions", [])
+        if not action_specs:
+            raise ValueError(
+                f"actions.{name} must have at least one child action"
+            )
+        result[name] = CompositeAction(
+            name=name,
+            params=params,
+            conditions=conditions,
+            action_specs=action_specs,
+        )
+    return result
+
+
+async def load(hub: Hub, config: dict[str, Any]) -> None:
+    built: dict[str, dict[str, Any]] = {}
+    for section_name in hub.AUTOMATION_SECTIONS:
+        data = config.get(section_name, {})
+        built[section_name] = build_section(section_name, data)
+
+    built_actions = build_actions(config.get("actions", {}))
+
+    old_config = hub.config
+    old_sections = {
+        name: getattr(hub, name) for name in hub.AUTOMATION_SECTIONS
+    }
+    old_actions = hub.actions
+
+    hub.config = config
+    for section_name, items in built.items():
+        setattr(hub, section_name, items)
+    hub.actions = built_actions
+
+    activated: list[tuple[str, str]] = []
+    try:
+        for section_name in hub.AUTOMATION_SECTIONS:
+            for obj in hub.section(section_name).values():
+                obj._hub = hub
+                try:
+                    await obj.on_validate(hub)
+                except ConfigLoadError:
+                    raise
+                except Exception as e:
+                    err = ConfigLoadError(
+                        section=section_name, instance=obj.instance_name,
+                        phase=LoadPhase.VALIDATE,
+                        code=LoadErrorCode.VALIDATION_FAILED, cause=e,
+                    )
+                    hub.notify("on_load_error", section_name,
+                                obj.instance_name, err.phase, err.code, e)
+                    raise err from e
+
+        for composite in hub.actions.values():
+            composite.validate(hub)
+
+        for section_name in hub.AUTOMATION_SECTIONS:
+            for name, obj in hub.section(section_name).items():
+                await obj.on_activate(hub)
+                activated.append((section_name, name))
+    except Exception:
+        for sec, n in reversed(activated):
+            try:
+                await hub.section(sec)[n].on_stop()
+            except Exception:
+                logger.exception("Cleanup failed for %s.%s", sec, n)
+        hub.config = old_config
+        for section_name, items in old_sections.items():
+            setattr(hub, section_name, items)
+        hub.actions = old_actions
+        raise