python-library-observer 0.1.0__tar.gz → 0.1.3__tar.gz

{python_library_observer-0.1.0 → python_library_observer-0.1.3}/.gitignore

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

{python_library_observer-0.1.0 → python_library_observer-0.1.3}/PKG-INFO

@@ -1,4 +1,4 @@
 Metadata-Version: 2.4
 Name: python-library-observer
-Version: 0.1.0
+Version: 0.1.3
 Requires-Python: >=3.10

python_library_observer-0.1.3/README.md

@@ -0,0 +1,30 @@
+# python-library-observer
+
+## 设计特性
+
+### 同步异步分流
+
+普通函数监听走线程池；`async` 监听走库自带的一条后台事件循环。不必为了观测再自己起一套 asyncio。
+
+### 单次调用记录
+
+被包一层的方法每跑一次，就有一份记录：哪个类、哪个方法、参数、当前是 before / after / 还是出错、大概多久。同一次调用里多段通知共用一个编号，方便对上是不是同一件事。
+
+### 条件订阅
+
+登记监听时可以加条件，例如只在某个类名、方法名或阶段才执行。写了不存在的字段名会直接报错，不会悄悄永远不触发。
+
+### 类级包装
+
+类上套装饰器后，实例方法、`@classmethod`、`@staticmethod` 会多一层包装；`@property` 不动。子类新方法也会自动跟上。
+
+### 关闭与清理
+
+可手动关总线，也可用 `with`。会尽量等正在跑的监听结束，再停线程池和后台事件循环线程。
+
+## 配置
+
+### `max_workers`
+
+| 含义 | 默认 | 说明 |
+| 同步监听最多用几个线程 | 不传就用系统默认 | 回调里如果会卡住（等 IO 等），可以适当调大；别指望无限变快 |

python_library_observer-0.1.0/example.py → python_library_observer-0.1.3/example/demo.py

@@ -1,5 +1,11 @@
+import asyncio
+import logging
+
 from observer import ObserverBus, ObserverContext
 
+
+logging.basicConfig(level=logging.INFO)
+
 bus = ObserverBus()
 
 
@@ -12,7 +18,8 @@ def log_all(ctx: ObserverContext) -> None:
 
 
 @bus.callback(cls_name="Demo", phase="after")
-def log_demo_after(ctx: ObserverContext) -> None:
+async def log_demo_after(ctx: ObserverContext) -> None:
+    await asyncio.sleep(0.01)
     print(
         f"[DEMO AFTER] {ctx.cls_name}.{ctx.method_name} "
         f"result={ctx.result} elapsed={ctx.elapsed:.6f}s"
@@ -24,6 +31,11 @@ def log_ping(ctx: ObserverContext) -> None:
     print(f"[PING] result={ctx.result}")
 
 
+@bus.callback(method_name="add", phase="after")
+def broken_callback(ctx: ObserverContext) -> None:
+    raise RuntimeError("callback boom")
+
+
 @bus.observe()
 class Demo:
     def add(self, a: int, b: int) -> int:
@@ -37,6 +49,10 @@ class Demo:
     def ping(msg: str) -> str:
         return f"pong:{msg}"
 
+    async def async_add(self, a: int, b: int) -> int:
+        await asyncio.sleep(0.01)
+        return a + b
+
 
 class ChildDemo(Demo):
     def sub(self, a: int, b: int) -> int:
@@ -46,12 +62,18 @@ class ChildDemo(Demo):
         return a + b + 100
 
 
-d = Demo()
-print(d.add(1, 2))
-print(Demo.build("x"))
-print(Demo.ping("hello"))
+async def main() -> None:
+    d = Demo()
+    print(d.add(1, 2))
+    print(Demo.build("x"))
+    print(Demo.ping("hello"))
+    print(await d.async_add(3, 4))
+
+    child = ChildDemo()
+    print(child.add(1, 2))
+    print(child.sub(5, 3))
+    print(ChildDemo.ping("world"))
+
 
-child = ChildDemo()
-print(child.add(1, 2))
-print(child.sub(5, 3))
-print(ChildDemo.ping("world"))
+asyncio.run(main())
+bus.close(wait=True)

python_library_observer-0.1.3/observer/bus.py

@@ -0,0 +1,293 @@
+from __future__ import annotations
+
+import asyncio
+import concurrent.futures
+import inspect
+import logging
+from collections.abc import Awaitable, Callable
+from threading import Event, RLock, Thread
+from typing import Any, TypeVar
+
+from .context import ObserverContext
+
+
+T = TypeVar("T")
+
+logger = logging.getLogger(__name__)
+
+ObserverSyncCallback = Callable[[ObserverContext], None]
+ObserverAsyncCallback = Callable[[ObserverContext], Awaitable[None]]
+ObserverCallback = Callable[[ObserverContext], object]
+
+
+class ObserverBus:
+    """承载订阅、派发与收尾观测总线。
+
+    在独立线程池中执行同步回调，在自建事件循环线程上调度协程回调；与业务线程解耦。
+    """
+
+    def __init__(self, *, max_workers: int | None = None) -> None:
+        """创建总线并启动后台执行设施。
+
+        Args:
+            max_workers: 同步回调所用线程池的最大工作线程数；未指定时由标准库采用默认策略。
+        """
+        self._callbacks: list[tuple[ObserverCallback, dict[str, Any]]] = []
+        self._pending: set[concurrent.futures.Future[Any]] = set()
+        self._lock = RLock()
+        self._closed = False
+
+        self._executor = concurrent.futures.ThreadPoolExecutor(
+            max_workers=max_workers,
+            thread_name_prefix="observer-callback",
+        )
+
+        self._loop = asyncio.new_event_loop()
+        self._loop_ready = Event()
+        self._loop_thread = Thread(
+            target=self._run_event_loop,
+            name="observer-async-loop",
+            daemon=True,
+        )
+        self._loop_thread.start()
+        self._loop_ready.wait()
+
+    def subscribe(
+        self,
+        callback: ObserverCallback,
+        **filters: Any,
+    ) -> ObserverCallback:
+        """注册监听，在派发上下文与附带条件一致时触发。
+
+        Args:
+            callback: 同步函数、协程函数，或协程可调用实例；入参为当前派发快照。
+            **filters: 与快照各槽位逐项相等的匹配条件；留空表示每次派发都考虑该回调。
+
+        Returns:
+            传入的监听对象，便于链式注册或稍后取消订阅。
+
+        Raises:
+            RuntimeError: 总线已关闭后仍尝试注册。
+            ValueError: 匹配条件里出现了快照中不存在的字段名。
+        """
+        self._validate_filters(filters)
+
+        with self._lock:
+            if self._closed:
+                raise RuntimeError("observer bus is closed")
+
+            exists = any(
+                registered_callback is callback and registered_filters == filters
+                for registered_callback, registered_filters in self._callbacks
+            )
+            if not exists:
+                self._callbacks.append((callback, dict(filters)))
+        return callback
+
+    def unsubscribe(self, callback: ObserverCallback) -> None:
+        """按对象身份移除此前注册过的监听，与注册时使用的过滤条件无关。
+
+        Args:
+            callback: 与订阅时传入的同一可调用对象。
+        """
+        with self._lock:
+            self._callbacks = [
+                (registered_callback, registered_filters)
+                for registered_callback, registered_filters in self._callbacks
+                if registered_callback is not callback
+            ]
+
+    def callback(self, **filters: Any):
+        """返回用于声明式注册监听的装饰器工厂。
+
+        Args:
+            **filters: 与订阅接口相同的匹配条件；非法字段名在装饰器应用时即校验。
+
+        Returns:
+            接收可调用对象并完成注册的装饰器。
+
+        Raises:
+            ValueError: 匹配条件里出现了快照中不存在的字段名。
+        """
+        self._validate_filters(filters)
+
+        def decorator(fn: ObserverCallback) -> ObserverCallback:
+            return self.subscribe(fn, **filters)
+
+        return decorator
+
+    def emit(self, ctx: ObserverContext) -> None:
+        """向当前所有监听异步投递一份上下文快照；总线已关闭时静默忽略。
+
+        Args:
+            ctx: 本次派发携带的快照，监听侧按匹配条件决定是否执行。
+        """
+        with self._lock:
+            if self._closed:
+                return
+            callbacks = tuple(self._callbacks)
+
+        for callback, filters in callbacks:
+            if not self._match_filters(ctx, filters):
+                continue
+            self._submit_callback(callback, ctx)
+
+    def observe(
+        self,
+        *,
+        include_private: bool = False,
+        emit_before: bool = True,
+    ) -> Callable[[type[T]], type[T]]:
+        """返回类装饰器，为被装饰类的方法挂上与当前总线关联的观测包装。
+
+        Args:
+            include_private: 为真时下划线开头的方法也会被包装。
+            emit_before: 为真时在目标方法体执行前额外派发切入阶段快照。
+
+        Returns:
+            接收类型对象并原地改写其可调用成员的类装饰器。
+        """
+        from .deractor import observe_methods
+
+        return observe_methods(
+            self,
+            include_private=include_private,
+            emit_before=emit_before,
+        )
+
+    def close(self, *, wait: bool = True, timeout: float | None = None) -> None:
+        """停止接受新订阅并尽量结束在途回调。
+
+        Args:
+            wait: 为真时先等待已提交任务结束再关停执行设施。
+            timeout: 等待在途同步任务或后台线程结束的上限秒数；与标准库等待语义一致。
+        """
+        with self._lock:
+            if self._closed:
+                return
+            self._closed = True
+            pending = tuple(self._pending)
+
+        if wait and pending:
+            concurrent.futures.wait(pending, timeout=timeout)
+
+        self._executor.shutdown(wait=wait, cancel_futures=not wait)
+
+        if not self._loop.is_closed():
+            self._loop.call_soon_threadsafe(self._loop.stop)
+
+        join_timeout = timeout if timeout is not None else (None if wait else 0.0)
+        self._loop_thread.join(join_timeout)
+
+    def __enter__(self) -> ObserverBus:
+        """进入上下文管理作用域时返回自身。"""
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> None:
+        """离开上下文管理作用域时按同步等待策略关闭总线。
+
+        Args:
+            exc_type: 离开作用域时未处理异常的型别；无异常时为 None。
+            exc: 异常实例或 None。
+            tb: 对应回溯或 None。
+        """
+        self.close(wait=True)
+
+    def _submit_callback(self, callback: ObserverCallback, ctx: ObserverContext) -> None:
+        if self._is_async_callback(callback):
+            future = asyncio.run_coroutine_threadsafe(
+                self._run_async_callback(callback, ctx),
+                self._loop,
+            )
+        else:
+            future = self._executor.submit(callback, ctx)
+
+        self._track_future(callback, future)
+
+    def _track_future(
+        self,
+        callback: ObserverCallback,
+        future: concurrent.futures.Future[Any],
+    ) -> None:
+        with self._lock:
+            if self._closed:
+                future.cancel()
+                return
+            self._pending.add(future)
+
+        future.add_done_callback(
+            lambda done_future: self._on_future_done(callback, done_future)
+        )
+
+    def _on_future_done(
+        self,
+        callback: ObserverCallback,
+        future: concurrent.futures.Future[Any],
+    ) -> None:
+        with self._lock:
+            self._pending.discard(future)
+
+        try:
+            future.result()
+        except concurrent.futures.CancelledError:
+            return
+        except Exception:
+            logger.exception(
+                "observer callback failed: %s",
+                self._callback_name(callback),
+            )
+
+    def _run_event_loop(self) -> None:
+        asyncio.set_event_loop(self._loop)
+        self._loop_ready.set()
+
+        try:
+            self._loop.run_forever()
+        finally:
+            pending = asyncio.all_tasks(self._loop)
+            for task in pending:
+                task.cancel()
+
+            if pending:
+                self._loop.run_until_complete(
+                    asyncio.gather(*pending, return_exceptions=True)
+                )
+
+            self._loop.run_until_complete(self._loop.shutdown_asyncgens())
+            self._loop.close()
+
+    async def _run_async_callback(
+        self,
+        callback: ObserverCallback,
+        ctx: ObserverContext,
+    ) -> None:
+        result = callback(ctx)
+        if inspect.isawaitable(result):
+            await result
+
+    def _is_async_callback(self, callback: ObserverCallback) -> bool:
+        if inspect.iscoroutinefunction(callback):
+            return True
+
+        call = getattr(callback, "__call__", None)
+        if call is not None and inspect.iscoroutinefunction(call):
+            return True
+
+        return False
+
+    def _callback_name(self, callback: ObserverCallback) -> str:
+        return getattr(callback, "__qualname__", getattr(callback, "__name__", repr(callback)))
+
+    def _match_filters(self, ctx: ObserverContext, filters: dict[str, Any]) -> bool:
+        for key, expected in filters.items():
+            if getattr(ctx, key) != expected:
+                return False
+        return True
+
+    def _validate_filters(self, filters: dict[str, Any]) -> None:
+        valid_keys = set(ObserverContext.__dataclass_fields__.keys())
+        invalid_keys = [key for key in filters if key not in valid_keys]
+        if invalid_keys:
+            raise ValueError(
+                f"invalid callback filters: {', '.join(sorted(invalid_keys))}"
+            )

python_library_observer-0.1.3/observer/context.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Literal
+
+
+ObserverPhase = Literal["before", "after", "error"]
+ObserverKind = Literal["instance", "class", "static"]
+
+
+@dataclass(slots=True)
+class ObserverContext:
+    """一次方法被观测时，某一时刻要交给监听者的信息包。"""
+
+    # 标识与归属
+    call_id: str
+    """同一次调用共用的编号，before/after/error 对得上"""
+    instance: Any | None
+    """实例方法里的 self；不是实例方法则为空"""
+    owner: Any | None
+    """类方法里的类；其它情况多为空"""
+    cls: type
+    """当作哪个类来记；实例上一般是真实类型"""
+    cls_name: str
+    """类名，用来过滤、打印"""
+    method_name: str
+    """方法短名，用来过滤"""
+    qualname: str
+    """带类前缀的方法名"""
+    method_kind: ObserverKind
+    """实例 / 类方法 / 静态"""
+    # 载荷
+    args: tuple[Any, ...]
+    """位置参数（已去掉 self/cls 这类接收者）"""
+    kwargs: dict[str, Any]
+    """关键字参数"""
+    result: Any = None
+    """正常返回时的结果；还没执行完可能没有"""
+    error: BaseException | None = None
+    """出错时的异常；没出错为空"""
+    # 阶段与时间
+    phase: ObserverPhase = "after"
+    """before、after、error 三选一"""
+    is_async: bool = False
+    """是不是 async 方法"""
+    started_at: float = 0.0
+    """开始时刻（性能计数器）"""
+    ended_at: float = 0.0
+    """结束时刻；刚开始还没结束可能是 0"""
+    elapsed: float = 0.0
+    """这段调用花了多少秒"""

{python_library_observer-0.1.0 → python_library_observer-0.1.3}/observer/deractor.py

@@ -5,11 +5,12 @@ import inspect
 import time
 import uuid
 from collections.abc import Callable
-from typing import Any
+from typing import Any, TypeVar
 
 from .bus import ObserverBus
-from .context import ObserverContext, ObserverKind, ObserverPhase
 
+T = TypeVar("T")
+from .context import ObserverContext, ObserverKind, ObserverPhase
 
 _WRAPPED_FLAG = "__observer_bus_wrapped__"
 _SUBCLASS_HOOK_FLAG = "__observer_bus_subclass_hook_installed__"
@@ -20,8 +21,18 @@ def observe_methods(
     *,
     include_private: bool = False,
     emit_before: bool = True,
-):
-    def decorator(cls: type) -> type:
+) -> Callable[[type[T]], type[T]]:
+    """返回类装饰器，为指定类型及其子类挂上与总线关联的方法级观测。
+
+    Args:
+        bus: 用于派发各阶段快照的总线实例。
+        include_private: 为真时下划线开头的方法也会被包装。
+        emit_before: 为真时在目标方法体执行前派发切入阶段快照。
+
+    Returns:
+        接收类型对象并原地改写其可调用成员的类装饰器。
+    """
+    def decorator(cls: type[T]) -> type[T]:
         _observe_class(
             cls,
             bus=bus,

{python_library_observer-0.1.0 → python_library_observer-0.1.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "python-library-observer"
-version = "0.1.0"
+version = "0.1.3"
 requires-python = ">=3.10"
 dependencies = []