python-library-observer 0.1.0__py3-none-any.whl → 0.1.3__py3-none-any.whl

observer/bus.py

@@ -1,26 +1,81 @@
 from __future__ import annotations
 
-from collections.abc import Callable
-from threading import RLock
-from typing import Any
+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
 
 
-ObserverCallback = Callable[[ObserverContext], None]
+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) -> None:
+    """承载订阅、派发与收尾观测总线。
+
+    在独立线程池中执行同步回调，在自建事件循环线程上调度协程回调；与业务线程解耦。
+    """
+
+    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
@@ -30,6 +85,11 @@ class ObserverBus:
         return callback
 
     def unsubscribe(self, callback: ObserverCallback) -> None:
+        """按对象身份移除此前注册过的监听，与注册时使用的过滤条件无关。
+
+        Args:
+            callback: 与订阅时传入的同一可调用对象。
+        """
         with self._lock:
             self._callbacks = [
                 (registered_callback, registered_filters)
@@ -38,6 +98,17 @@ class ObserverBus:
             ]
 
     def callback(self, **filters: Any):
+        """返回用于声明式注册监听的装饰器工厂。
+
+        Args:
+            **filters: 与订阅接口相同的匹配条件；非法字段名在装饰器应用时即校验。
+
+        Returns:
+            接收可调用对象并完成注册的装饰器。
+
+        Raises:
+            ValueError: 匹配条件里出现了快照中不存在的字段名。
+        """
         self._validate_filters(filters)
 
         def decorator(fn: ObserverCallback) -> ObserverCallback:
@@ -46,25 +117,36 @@ class ObserverBus:
         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
-
-            try:
-                callback(ctx)
-            except Exception:
-                # 不要让监听器异常影响原始业务调用
-                pass
+            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(
@@ -73,6 +155,129 @@ class ObserverBus:
             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:

observer/context.py

@@ -10,20 +10,42 @@ 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
-    elapsed: float = 0.0
+    """结束时刻；刚开始还没结束可能是 0"""
+    elapsed: float = 0.0
+    """这段调用花了多少秒"""

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.dist-info → python_library_observer-0.1.3.dist-info}/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,7 @@
+observer/__init__.py,sha256=BQHsdXKbTkLzwH_9Hols36mGACKQaiAN3JcwmbPT3xY,191
+observer/bus.py,sha256=oroVy2Ks50jy7JWd9LMt3ZcX5koMVxaHneuxucDuTJ8,10123
+observer/context.py,sha256=fQ12HGAlAtMWH-GyuHCoUDgCUnmu0xJH7iJRLcmSuwY,1694
+observer/deractor.py,sha256=MTWTHqn1ylQmHzpcLksZUQGFXVtasXQ3ZHfsSr-7ioU,10730
+python_library_observer-0.1.3.dist-info/METADATA,sha256=MoIOlN1S6_zU4equOLXKgGS_TVkAR2gYgSBDIZh9J2E,91
+python_library_observer-0.1.3.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+python_library_observer-0.1.3.dist-info/RECORD,,

python_library_observer-0.1.0.dist-info/RECORD

@@ -1,7 +0,0 @@
-observer/__init__.py,sha256=BQHsdXKbTkLzwH_9Hols36mGACKQaiAN3JcwmbPT3xY,191
-observer/bus.py,sha256=VqoHzuPPCPPdoT1NwTlTfXMxeaNsU68ZPOu1Y-jnvqA,2784
-observer/context.py,sha256=-PmeYuT7wi-SlUjxTOZJMrETJIHsa_3aeEHJz8mzqyI,706
-observer/deractor.py,sha256=maBrHvvHlMWb4LgWKzRgpgZKopyXDumV-bX0093Pfa4,10225
-python_library_observer-0.1.0.dist-info/METADATA,sha256=pMKdq2oOlxgZYeQ3nURipN45QYou75AOIAJ06AZWBCA,91
-python_library_observer-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
-python_library_observer-0.1.0.dist-info/RECORD,,