python-library-automation 0.1.16__tar.gz → 0.3.0__tar.gz

{python_library_automation-0.1.16 → python_library_automation-0.3.0}/.gitignore

@@ -8,4 +8,6 @@ build/
 .env
 .pytest_cache/
 config.yaml
-logs/
+logs/
+.cursor/
+uv.lock

python_library_automation-0.3.0/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: python-library-automation
+Version: 0.3.0
+Requires-Python: >=3.10
+Requires-Dist: python-library-express-evaluator
+Requires-Dist: python-library-observer
+Requires-Dist: python-library-reactive-model
+Requires-Dist: python-library-registry

python_library_automation-0.3.0/automation/__init__.py

@@ -0,0 +1,58 @@
+from automation import assistant
+from automation.assistant import (
+    add_listener,
+    configure_listeners,
+    context,
+    entities,
+    events,
+    load_script_file,
+    reload_automation,
+    run,
+    section,
+    start,
+    stop,
+    triggers,
+)
+from automation.core import (
+    Action,
+    Entity,
+    Event,
+    Trigger,
+    action_registry,
+    catalog_registry,
+    entity_registry,
+    event_registry,
+    instantiate_registered,
+    registered_kind_for,
+    trigger_registry,
+)
+from automation.runtime import Context, get_context
+
+__all__ = [
+    "Action",
+    "Entity",
+    "Event",
+    "Trigger",
+    "Context",
+    "assistant",
+    "add_listener",
+    "configure_listeners",
+    "context",
+    "entities",
+    "events",
+    "triggers",
+    "section",
+    "get_context",
+    "load_script_file",
+    "reload_automation",
+    "run",
+    "start",
+    "stop",
+    "catalog_registry",
+    "action_registry",
+    "entity_registry",
+    "event_registry",
+    "trigger_registry",
+    "instantiate_registered",
+    "registered_kind_for",
+]

python_library_automation-0.3.0/automation/assistant.py

@@ -0,0 +1,113 @@
+from __future__ import annotations
+
+import asyncio
+import logging
+from pathlib import Path
+
+from automation.listener.base import BaseListener
+from automation.listener.events import Loaded, Started, Stopped
+from automation.runtime.bootstrap import load_script, reload_automation, teardown_automation
+from automation.runtime.global_state import (
+    RunState,
+    add_listener,
+    get_context,
+    get_main_loop,
+    get_run_state,
+    set_listeners,
+    set_main_loop,
+    set_run_state,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def context():
+    """进程内唯一的自动化运行时上下文。"""
+
+    return get_context()
+
+
+def entities():
+    return get_context().entities
+
+
+def events():
+    return get_context().events
+
+
+def triggers():
+    return get_context().triggers
+
+
+def section(name: str):
+    return get_context().section(name)
+
+
+async def load_script_file(path: str | Path) -> None:
+    """执行自动化脚本并激活其中注册的实体/事件/触发器。"""
+
+    await load_script(path)
+    get_context().emit(Loaded(get_context()))
+
+
+async def start() -> None:
+    if get_run_state() == RunState.RUNNING:
+        return
+    set_run_state(RunState.RUNNING)
+    ctx = get_context()
+    ctx.stop_event.clear()
+    set_main_loop(asyncio.get_running_loop())
+    ctx.main_loop = get_main_loop()
+    for section_name in ctx.AUTOMATION_SECTIONS:
+        for obj in ctx.section(section_name).values():
+            await obj.run_phase()
+    ctx.emit(Started())
+
+
+async def run() -> None:
+    await start()
+    await get_context().stop_event.wait()
+
+
+async def stop() -> None:
+    if get_run_state() != RunState.RUNNING:
+        return
+    set_run_state(RunState.STOPPED)
+    ctx = get_context()
+    ctx.main_loop = None
+    set_main_loop(None)
+    for section_name in reversed(ctx.AUTOMATION_SECTIONS):
+        for obj in ctx.section(section_name).values():
+            await obj.run_phase(closing=True)
+    ctx.stop_event.set()
+    ctx.emit(Stopped())
+
+
+def configure_listeners(
+    listeners: list[BaseListener] | BaseListener | None = None,
+) -> None:
+    """登记监听器；须在 load_script 或 reload_automation 之前调用。"""
+
+    if listeners is None:
+        set_listeners([])
+        return
+    merged = (
+        [listeners] if isinstance(listeners, BaseListener) else list(listeners)
+    )
+    set_listeners(merged)
+
+
+__all__ = [
+    "context",
+    "entities",
+    "events",
+    "triggers",
+    "section",
+    "configure_listeners",
+    "add_listener",
+    "load_script_file",
+    "reload_automation",
+    "start",
+    "run",
+    "stop",
+]

{python_library_automation-0.1.16 → python_library_automation-0.3.0}/automation/builtins/__init__.py

@@ -3,7 +3,7 @@ import pkgutil
 from pathlib import Path
 
 def _auto_import():
-    """自动导入 builtins 下所有子模块，触发类的注册"""
+    """自动导入 builtins 下所有子模块，完成事件等内置类型的模块级登记。"""
     package_dir = Path(__file__).resolve().parent
     for sub_pkg in package_dir.iterdir():
         if not sub_pkg.is_dir() or sub_pkg.name.startswith("_"):

python_library_automation-0.3.0/automation/builtins/action/__init__.py

@@ -0,0 +1,11 @@
+from automation.builtins.action.call_method import CallMethodAction
+from automation.builtins.action.delay import DelayAction
+from automation.builtins.action.log import LogAction
+from automation.builtins.action.set_attribute import SetAttributeAction
+
+__all__ = [
+    "CallMethodAction",
+    "DelayAction",
+    "LogAction",
+    "SetAttributeAction",
+]

python_library_automation-0.3.0/automation/builtins/action/call_method.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+import inspect
+from typing import Any
+
+from pydantic import Field
+
+from automation.core.action import Action
+from automation.core.renderer import Renderer
+
+
+class CallMethodAction(Action):
+    """调用某实体上的方法。"""
+
+    entity: str = Field(description="实体实例名，对应 context.entities 的键。")
+    method: str = Field(description="实体上的方法名。")
+    args: dict[str, Any] = Field(
+        default_factory=dict,
+        description="传给实体方法的命名参数；字符串值在运行期经渲染器求值。",
+    )
+
+    @property
+    def display_label(self) -> str:
+        return "call_method"
+
+    @property
+    def log_params(self) -> dict[str, Any]:
+        return {"entity": self.entity, "method": self.method, "args": self.args}
+
+    async def execute(self, renderer: Renderer) -> None:
+        entities = self._ctx.entities
+        if self.entity not in entities:
+            raise ValueError(f"Entity {self.entity!r} not found")
+        target = entities[self.entity]
+        if not hasattr(target, self.method):
+            raise ValueError(
+                f"Entity {self.entity!r} has no method {self.method!r}"
+            )
+        fn = getattr(target, self.method)
+        if not callable(fn):
+            raise ValueError(
+                f"Entity {self.entity!r}.{self.method} is not callable"
+            )
+        rendered_args = {
+            key: renderer(value) if isinstance(value, str) else value
+            for key, value in self.args.items()
+        }
+        result = fn(**rendered_args)
+        if inspect.isawaitable(result):
+            await result

python_library_automation-0.3.0/automation/builtins/action/delay.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+import asyncio
+
+from pydantic import Field
+
+from automation.core.action import Action
+from automation.core.renderer import Renderer
+
+
+class DelayAction(Action):
+    """异步等待指定秒数。"""
+
+    seconds: float = Field(default=0.0, description="等待秒数。")
+
+    @property
+    def display_label(self) -> str:
+        return "delay"
+
+    @property
+    def log_params(self) -> dict[str, float]:
+        return {"seconds": self.seconds}
+
+    async def execute(self, renderer: Renderer) -> None:
+        await asyncio.sleep(self.seconds)

python_library_automation-0.3.0/automation/builtins/action/log.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+import logging
+
+from pydantic import Field
+
+from automation.core.action import Action
+from automation.core.renderer import Renderer
+
+logger = logging.getLogger(__name__)
+
+
+class LogAction(Action):
+    """将一条信息写入日志。"""
+
+    info: str = Field(description="日志正文；字符串值在运行期经表达式渲染器求值。")
+
+    @property
+    def display_label(self) -> str:
+        return "log"
+
+    @property
+    def log_params(self) -> dict[str, str]:
+        return {"info": self.info}
+
+    async def execute(self, renderer: Renderer) -> None:
+        text = self.info
+        if "{" in text or "}" in text:
+            text = str(renderer(text))
+        logger.info(text)

python_library_automation-0.3.0/automation/builtins/action/set_attribute.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import Field
+
+from automation.core.action import Action
+from automation.core.renderer import Renderer
+
+
+class SetAttributeAction(Action):
+    """设置某实体上的属性值。"""
+
+    entity: str = Field(description="实体实例名，对应 context.entities 的键。")
+    attribute: str = Field(description="实体上的属性名。")
+    value: Any = Field(description="要写入的值；字符串在运行期经渲染器求值。")
+
+    @property
+    def display_label(self) -> str:
+        return "set_attribute"
+
+    @property
+    def log_params(self) -> dict[str, Any]:
+        return {
+            "entity": self.entity,
+            "attribute": self.attribute,
+            "value": self.value,
+        }
+
+    async def execute(self, renderer: Renderer) -> None:
+        entities = self._ctx.entities
+        if self.entity not in entities:
+            raise ValueError(f"Entity {self.entity!r} not found")
+        target = entities[self.entity]
+        if not hasattr(target, self.attribute):
+            raise ValueError(
+                f"Entity {self.entity!r} has no attribute {self.attribute!r}"
+            )
+        value = self.value
+        if isinstance(value, str):
+            value = renderer(value)
+        setattr(target, self.attribute, value)

python_library_automation-0.3.0/automation/builtins/event/attribute_change.py

@@ -0,0 +1,119 @@
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import ConfigDict, Field, PrivateAttr
+
+from automation.core.base import BaseAutomation, registered_kind_for
+from automation.core.event import EventContext
+from automation.core.registry_catalog import event_registry
+from automation.core.info import AttributeWatchInfo
+
+from .on_call import OnCallEvent
+
+
+class AttributeChangeEventData(EventContext):
+    """由 on_changes 路径触发：结构化字段与并入条件的扁平 data 同源。"""
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    event_name: str = Field(
+        default="",
+        description="激活 fire 时由 Event 填入本事件实例名；构造监听载荷时可省略",
+    )
+    entity: BaseAutomation = Field(description="发生写入的实体实例")
+    attribute: str = Field(description="被写入的属性名")
+    old: Any = Field(description="写入前的取值")
+    new: Any = Field(description="写入后的取值")
+
+    def as_payload(self) -> dict[str, Any]:
+        """转成条件与回调使用的扁平表，实体仍以运行中实例传入。"""
+
+        return {
+            "entity": self.entity,
+            "attribute": self.attribute,
+            "old": self.old,
+            "new": self.new,
+        }
+
+
+def _register_on_change_handlers(ev: Any) -> None:
+    """按 on_changes 将异步 handler 登记到上下文的属性变更链。"""
+
+    for h in ev._attribute_watch_handlers:
+        try:
+            ev._ctx._on_state_changed.remove(h)
+        except ValueError:
+            pass
+    ev._attribute_watch_handlers.clear()
+
+    for watch in ev.on_changes:
+
+        async def handler(
+            entity: Any,
+            attr: str,
+            old: Any,
+            new: Any,
+            *,
+            _w: AttributeWatchInfo = watch,
+            _ev: Any = ev,
+        ) -> None:
+            if _w.entity_type and registered_kind_for(type(entity)) != _w.entity_type:
+                return
+            if _w.entity_name and entity.instance_name != _w.entity_name:
+                return
+            if _w.attribute and attr != _w.attribute:
+                return
+            await _ev.fire(
+                AttributeChangeEventData(
+                    entity=entity,
+                    attribute=attr,
+                    old=old,
+                    new=new,
+                )
+            )
+
+        ev._ctx._on_state_changed.append(handler)
+        ev._attribute_watch_handlers.append(handler)
+
+
+class AttributeWatchEvent(OnCallEvent):
+    """在基类事件之上登记 on_changes，从实体属性变更链触发 fire。"""
+
+    on_changes: list[AttributeWatchInfo] = Field(
+        default_factory=list,
+        description="实体属性变更时按条过滤后触发本事件，空列表则不登记属性监听",
+    )
+    _attribute_watch_handlers: list[Any] = PrivateAttr(default_factory=list)
+
+    async def on_activate(self) -> None:
+        await super().on_activate()
+        _register_on_change_handlers(self)
+
+    async def on_inactive(self) -> None:
+        for h in self._attribute_watch_handlers:
+            try:
+                self._ctx._on_state_changed.remove(h)
+            except ValueError:
+                pass
+        self._attribute_watch_handlers.clear()
+        await super().on_inactive()
+
+    async def fire(
+        self,
+        data: dict[str, Any] | EventContext | AttributeChangeEventData | None = None,
+    ) -> None:
+        """在交给基类前将属性变更载荷展开为与条件求值一致的 data。"""
+
+        if isinstance(data, AttributeChangeEventData):
+            data = data.model_copy(
+                update={
+                    "event_name": self.instance_name,
+                    "data": data.as_payload(),
+                }
+            )
+        await super().fire(data)
+
+
+AttributeWatchEvent.registered_kind = "event"
+event_registry.register("event", AttributeWatchEvent)

python_library_automation-0.3.0/automation/builtins/event/on_call.py

@@ -0,0 +1,105 @@
+from __future__ import annotations
+
+import asyncio
+import logging
+from concurrent.futures import Future as ConcurrentFuture
+from typing import Any
+
+from pydantic import Field, PrivateAttr
+
+from automation.core.base import BaseAutomation, observer_bus
+from automation.core.event import Event
+from automation.core.info import CallInfo
+from automation.core.registry_catalog import event_registry
+
+logger = logging.getLogger(__name__)
+
+
+class OnCallEvent(Event):
+    """在基类事件之上按规格登记方法调用观测，匹配后触发 fire。"""
+
+    on_calls: list[CallInfo] = Field(
+        default_factory=list,
+        description=(
+            "与总线发派匹配的多条调用规格，逐项登记；"
+            "某条方法名为空则该项不挂总线、仅可依赖其它触发路径"
+        ),
+    )
+
+    _on_call_bridges_done: bool = PrivateAttr(default=False)
+
+    async def on_activate(self) -> None:
+        await super().on_activate()
+        _register_on_call_bridges(self)
+
+    async def on_inactive(self) -> None:
+        self._on_call_bridges_done = False
+        await super().on_inactive()
+
+
+def _register_on_call_bridges(ev: OnCallEvent) -> None:
+    """在总线上按本事件的调用规格登记，在匹配到调用后调度 fire。"""
+
+    if ev._on_call_bridges_done:
+        return
+
+    from observer.context import ObserverContext
+
+    for spec in ev.on_calls:
+        if not spec.method_name:
+            continue
+
+        def on_observed_call(
+            obs_ctx: ObserverContext, _spec: CallInfo = spec
+        ) -> None:
+            if obs_ctx.phase != "after":
+                return
+            if _spec.instance_type and obs_ctx.cls_name != _spec.instance_type:
+                return
+            inst = obs_ctx.instance
+            if _spec.instance_name:
+                if not isinstance(inst, BaseAutomation):
+                    return
+                if inst.instance_name != _spec.instance_name:
+                    return
+            else:
+                if inst is None:
+                    return
+                if not isinstance(inst, BaseAutomation) or inst._ctx is not ev._ctx:
+                    return
+            loop = ev._ctx.main_loop
+            if loop is None:
+                logger.warning(
+                    "事件 %s：主循环未就绪，无法在观测回调路径中向主循环调度 fire",
+                    ev.instance_name,
+                )
+                return
+            fut: ConcurrentFuture[Any] = asyncio.run_coroutine_threadsafe(
+                ev.fire(dict(obs_ctx.kwargs)), loop
+            )
+
+            def _on_fire_done(done: ConcurrentFuture[Any]) -> None:
+                exc = done.exception()
+                if exc is not None:
+                    logger.error(
+                        "由观测触发的 fire 失败：%s",
+                        exc,
+                        exc_info=exc,
+                    )
+
+            fut.add_done_callback(_on_fire_done)
+
+        filters: dict[str, Any] = {
+            "phase": "after",
+            "method_name": spec.method_name,
+        }
+        if spec.instance_type:
+            filters["cls_name"] = spec.instance_type
+        observer_bus.subscribe(on_observed_call, **filters)
+        ev._ctx.register_observer_bridge_handler(on_observed_call)
+
+    ev._on_call_bridges_done = True
+
+
+OnCallEvent.registered_kind = "on_call"
+event_registry.register("on_call", OnCallEvent)

python_library_automation-0.3.0/automation/core/__init__.py

@@ -0,0 +1,36 @@
+from .base import BaseAutomation, registered_kind_for
+from .action import Action
+from .entity import Entity
+from .trigger import Trigger
+from .event import Event
+from .registry_catalog import (
+    ACTION_NAMESPACE,
+    ENTITY_NAMESPACE,
+    EVENT_NAMESPACE,
+    TRIGGER_NAMESPACE,
+    action_registry,
+    catalog_registry,
+    entity_registry,
+    event_registry,
+    instantiate_registered,
+    trigger_registry,
+)
+
+__all__ = [
+    "BaseAutomation",
+    "Action",
+    "Entity",
+    "Trigger",
+    "Event",
+    "catalog_registry",
+    "action_registry",
+    "entity_registry",
+    "event_registry",
+    "trigger_registry",
+    "instantiate_registered",
+    "ENTITY_NAMESPACE",
+    "EVENT_NAMESPACE",
+    "TRIGGER_NAMESPACE",
+    "ACTION_NAMESPACE",
+    "registered_kind_for",
+]