python-library-observer 0.1.0__tar.gz

python_library_observer-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+.venv/
+.env
+.pytest_cache/
+config.yaml
+logs/

python_library_observer-0.1.0/PKG-INFO

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

python_library_observer-0.1.0/example.bat

@@ -0,0 +1,11 @@
+@echo off
+cd /d %~dp0
+
+if not exist .venv (
+    python -m venv .venv
+)
+
+call .venv\Scripts\activate.bat
+python -m pip install -e .
+
+python example.py

python_library_observer-0.1.0/example.py

@@ -0,0 +1,57 @@
+from observer import ObserverBus, ObserverContext
+
+bus = ObserverBus()
+
+
+@bus.callback()
+def log_all(ctx: ObserverContext) -> None:
+    print(
+        f"[ALL] {ctx.cls_name}.{ctx.method_name} "
+        f"phase={ctx.phase} args={ctx.args} kwargs={ctx.kwargs}"
+    )
+
+
+@bus.callback(cls_name="Demo", phase="after")
+def log_demo_after(ctx: ObserverContext) -> None:
+    print(
+        f"[DEMO AFTER] {ctx.cls_name}.{ctx.method_name} "
+        f"result={ctx.result} elapsed={ctx.elapsed:.6f}s"
+    )
+
+
+@bus.callback(method_name="ping", phase="after")
+def log_ping(ctx: ObserverContext) -> None:
+    print(f"[PING] result={ctx.result}")
+
+
+@bus.observe()
+class Demo:
+    def add(self, a: int, b: int) -> int:
+        return a + b
+
+    @classmethod
+    def build(cls, name: str) -> "Demo":
+        return cls()
+
+    @staticmethod
+    def ping(msg: str) -> str:
+        return f"pong:{msg}"
+
+
+class ChildDemo(Demo):
+    def sub(self, a: int, b: int) -> int:
+        return a - b
+
+    def add(self, a: int, b: int) -> int:
+        return a + b + 100
+
+
+d = Demo()
+print(d.add(1, 2))
+print(Demo.build("x"))
+print(Demo.ping("hello"))
+
+child = ChildDemo()
+print(child.add(1, 2))
+print(child.sub(5, 3))
+print(ChildDemo.ping("world"))

python_library_observer-0.1.0/observer/__init__.py

@@ -0,0 +1,9 @@
+from .bus import ObserverBus
+from .context import ObserverContext
+from .deractor import observe_methods
+
+__all__ = [
+    "ObserverBus",
+    "ObserverContext",
+    "observe_methods",
+]

python_library_observer-0.1.0/observer/bus.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from threading import RLock
+from typing import Any
+
+from .context import ObserverContext
+
+
+ObserverCallback = Callable[[ObserverContext], None]
+
+
+class ObserverBus:
+    def __init__(self) -> None:
+        self._callbacks: list[tuple[ObserverCallback, dict[str, Any]]] = []
+        self._lock = RLock()
+
+    def subscribe(
+        self,
+        callback: ObserverCallback,
+        **filters: Any,
+    ) -> ObserverCallback:
+        with self._lock:
+            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:
+        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):
+        self._validate_filters(filters)
+
+        def decorator(fn: ObserverCallback) -> ObserverCallback:
+            return self.subscribe(fn, **filters)
+
+        return decorator
+
+    def emit(self, ctx: ObserverContext) -> None:
+        with self._lock:
+            callbacks = tuple(self._callbacks)
+
+        for callback, filters in callbacks:
+            if not self._match_filters(ctx, filters):
+                continue
+
+            try:
+                callback(ctx)
+            except Exception:
+                # 不要让监听器异常影响原始业务调用
+                pass
+
+    def observe(
+        self,
+        *,
+        include_private: bool = False,
+        emit_before: bool = True,
+    ):
+        from .deractor import observe_methods
+
+        return observe_methods(
+            self,
+            include_private=include_private,
+            emit_before=emit_before,
+        )
+
+    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.0/observer/context.py

@@ -0,0 +1,29 @@
+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
+    instance: Any | None
+    owner: Any | None
+    cls: type
+    cls_name: str
+    method_name: str
+    qualname: str
+    method_kind: ObserverKind
+    args: tuple[Any, ...]
+    kwargs: dict[str, Any]
+    result: Any = None
+    error: BaseException | None = None
+    phase: ObserverPhase = "after"
+    is_async: bool = False
+    started_at: float = 0.0
+    ended_at: float = 0.0
+    elapsed: float = 0.0

python_library_observer-0.1.0/observer/deractor.py

@@ -0,0 +1,353 @@
+from __future__ import annotations
+
+import functools
+import inspect
+import time
+import uuid
+from collections.abc import Callable
+from typing import Any
+
+from .bus import ObserverBus
+from .context import ObserverContext, ObserverKind, ObserverPhase
+
+
+_WRAPPED_FLAG = "__observer_bus_wrapped__"
+_SUBCLASS_HOOK_FLAG = "__observer_bus_subclass_hook_installed__"
+
+
+def observe_methods(
+    bus: ObserverBus,
+    *,
+    include_private: bool = False,
+    emit_before: bool = True,
+):
+    def decorator(cls: type) -> type:
+        _observe_class(
+            cls,
+            bus=bus,
+            include_private=include_private,
+            emit_before=emit_before,
+        )
+        _install_subclass_hook(
+            cls,
+            bus=bus,
+            include_private=include_private,
+            emit_before=emit_before,
+        )
+        return cls
+
+    return decorator
+
+
+def _install_subclass_hook(
+    cls: type,
+    *,
+    bus: ObserverBus,
+    include_private: bool,
+    emit_before: bool,
+) -> None:
+    if cls.__dict__.get(_SUBCLASS_HOOK_FLAG, False):
+        return
+
+    original_init_subclass = cls.__dict__.get("__init_subclass__")
+
+    @classmethod
+    def __init_subclass__(subcls, **kwargs):
+        if original_init_subclass is not None:
+            original_init_subclass.__get__(subcls, subcls)(**kwargs)
+        else:
+            super(cls, subcls).__init_subclass__(**kwargs)
+
+        _observe_class(
+            subcls,
+            bus=bus,
+            include_private=include_private,
+            emit_before=emit_before,
+        )
+        _install_subclass_hook(
+            subcls,
+            bus=bus,
+            include_private=include_private,
+            emit_before=emit_before,
+        )
+
+    setattr(cls, "__init_subclass__", __init_subclass__)
+    setattr(cls, _SUBCLASS_HOOK_FLAG, True)
+
+
+def _observe_class(
+    cls: type,
+    *,
+    bus: ObserverBus,
+    include_private: bool,
+    emit_before: bool,
+) -> None:
+    for name, obj in list(cls.__dict__.items()):
+        if not include_private and name.startswith("_"):
+            continue
+
+        if isinstance(obj, property):
+            continue
+
+        if isinstance(obj, staticmethod):
+            func = obj.__func__
+            if getattr(func, _WRAPPED_FLAG, False):
+                continue
+            wrapped_func = _wrap_function(
+                owner_cls=cls,
+                method_name=name,
+                func=func,
+                bus=bus,
+                method_kind="static",
+                emit_before=emit_before,
+            )
+            setattr(cls, name, staticmethod(wrapped_func))
+            continue
+
+        if isinstance(obj, classmethod):
+            func = obj.__func__
+            if getattr(func, _WRAPPED_FLAG, False):
+                continue
+            wrapped_func = _wrap_function(
+                owner_cls=cls,
+                method_name=name,
+                func=func,
+                bus=bus,
+                method_kind="class",
+                emit_before=emit_before,
+            )
+            setattr(cls, name, classmethod(wrapped_func))
+            continue
+
+        if callable(obj):
+            if getattr(obj, _WRAPPED_FLAG, False):
+                continue
+            wrapped = _wrap_function(
+                owner_cls=cls,
+                method_name=name,
+                func=obj,
+                bus=bus,
+                method_kind="instance",
+                emit_before=emit_before,
+            )
+            setattr(cls, name, wrapped)
+
+
+def _wrap_function(
+    owner_cls: type,
+    method_name: str,
+    func: Callable[..., Any],
+    bus: ObserverBus,
+    method_kind: ObserverKind,
+    emit_before: bool,
+):
+    if inspect.iscoroutinefunction(func):
+        @functools.wraps(func)
+        async def async_wrapper(*args, **kwargs):
+            call_id = uuid.uuid4().hex
+            started = time.perf_counter()
+
+            if emit_before:
+                bus.emit(
+                    _build_context(
+                        owner_cls=owner_cls,
+                        method_name=method_name,
+                        func=func,
+                        method_kind=method_kind,
+                        args=args,
+                        kwargs=kwargs,
+                        phase="before",
+                        is_async=True,
+                        started_at=started,
+                        call_id=call_id,
+                    )
+                )
+
+            try:
+                result = await func(*args, **kwargs)
+            except Exception as error:
+                ended = time.perf_counter()
+                bus.emit(
+                    _build_context(
+                        owner_cls=owner_cls,
+                        method_name=method_name,
+                        func=func,
+                        method_kind=method_kind,
+                        args=args,
+                        kwargs=kwargs,
+                        phase="error",
+                        is_async=True,
+                        started_at=started,
+                        ended_at=ended,
+                        error=error,
+                        call_id=call_id,
+                    )
+                )
+                raise
+
+            ended = time.perf_counter()
+            bus.emit(
+                _build_context(
+                    owner_cls=owner_cls,
+                    method_name=method_name,
+                    func=func,
+                    method_kind=method_kind,
+                    args=args,
+                    kwargs=kwargs,
+                    phase="after",
+                    is_async=True,
+                    started_at=started,
+                    ended_at=ended,
+                    result=result,
+                    call_id=call_id,
+                )
+            )
+            return result
+
+        setattr(async_wrapper, _WRAPPED_FLAG, True)
+        return async_wrapper
+
+    @functools.wraps(func)
+    def sync_wrapper(*args, **kwargs):
+        call_id = uuid.uuid4().hex
+        started = time.perf_counter()
+
+        if emit_before:
+            bus.emit(
+                _build_context(
+                    owner_cls=owner_cls,
+                    method_name=method_name,
+                    func=func,
+                    method_kind=method_kind,
+                    args=args,
+                    kwargs=kwargs,
+                    phase="before",
+                    is_async=False,
+                    started_at=started,
+                    call_id=call_id,
+                )
+            )
+
+        try:
+            result = func(*args, **kwargs)
+        except Exception as error:
+            ended = time.perf_counter()
+            bus.emit(
+                _build_context(
+                    owner_cls=owner_cls,
+                    method_name=method_name,
+                    func=func,
+                    method_kind=method_kind,
+                    args=args,
+                    kwargs=kwargs,
+                    phase="error",
+                    is_async=False,
+                    started_at=started,
+                    ended_at=ended,
+                    error=error,
+                    call_id=call_id,
+                )
+            )
+            raise
+
+        ended = time.perf_counter()
+        bus.emit(
+            _build_context(
+                owner_cls=owner_cls,
+                method_name=method_name,
+                func=func,
+                method_kind=method_kind,
+                args=args,
+                kwargs=kwargs,
+                phase="after",
+                is_async=False,
+                started_at=started,
+                ended_at=ended,
+                result=result,
+                call_id=call_id,
+            )
+        )
+        return result
+
+    setattr(sync_wrapper, _WRAPPED_FLAG, True)
+    return sync_wrapper
+
+
+def _build_context(
+    *,
+    owner_cls: type,
+    method_name: str,
+    func: Callable[..., Any],
+    method_kind: ObserverKind,
+    args: tuple[Any, ...],
+    kwargs: dict[str, Any],
+    phase: ObserverPhase,
+    is_async: bool,
+    started_at: float,
+    call_id: str,
+    ended_at: float | None = None,
+    result: Any = None,
+    error: BaseException | None = None,
+) -> ObserverContext:
+    instance, owner, pure_args = _split_receiver(method_kind, args)
+    actual_cls = _resolve_context_class(
+        owner_cls=owner_cls,
+        method_kind=method_kind,
+        instance=instance,
+        owner=owner,
+    )
+    final_ended_at = ended_at if ended_at is not None else 0.0
+    elapsed = final_ended_at - started_at if ended_at is not None else 0.0
+
+    return ObserverContext(
+        call_id=call_id,
+        instance=instance,
+        owner=owner,
+        cls=actual_cls,
+        cls_name=actual_cls.__name__,
+        method_name=method_name,
+        qualname=func.__qualname__,
+        method_kind=method_kind,
+        args=pure_args,
+        kwargs=dict(kwargs),
+        result=result,
+        error=error,
+        phase=phase,
+        is_async=is_async,
+        started_at=started_at,
+        ended_at=final_ended_at,
+        elapsed=elapsed,
+    )
+
+
+def _split_receiver(
+    method_kind: ObserverKind,
+    args: tuple[Any, ...],
+) -> tuple[Any | None, Any | None, tuple[Any, ...]]:
+    if method_kind == "instance":
+        instance = args[0] if args else None
+        pure_args = args[1:] if args else ()
+        return instance, instance, pure_args
+
+    if method_kind == "class":
+        owner = args[0] if args else None
+        pure_args = args[1:] if args else ()
+        return None, owner, pure_args
+
+    return None, None, args
+
+
+def _resolve_context_class(
+    *,
+    owner_cls: type,
+    method_kind: ObserverKind,
+    instance: Any | None,
+    owner: Any | None,
+) -> type:
+    if method_kind == "instance" and instance is not None:
+        return type(instance)
+
+    if method_kind == "class" and isinstance(owner, type):
+        return owner
+
+    return owner_cls

python_library_observer-0.1.0/pyproject.toml

@@ -0,0 +1,12 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "python-library-observer"
+version = "0.1.0"
+requires-python = ">=3.10"
+dependencies = []
+
+[tool.hatch.build.targets.wheel]
+packages = ["observer"]

python_library_observer-0.1.0/test.bat

@@ -0,0 +1,10 @@
+@echo off
+cd /d %~dp0
+
+if not exist .venv (
+    python -m venv .venv
+)
+
+call .venv\Scripts\activate.bat
+python -m pip install -e .
+python -m unittest discover -s tests -p "test_*.py"

python_library_observer-0.1.0/tests/test_observer.py

@@ -0,0 +1,562 @@
+from __future__ import annotations
+
+import asyncio
+import unittest
+from typing import Any
+
+from observer import ObserverBus, ObserverContext, observe_methods
+
+
+class ObserverBusTests(unittest.TestCase):
+    def test_subscribe_invokes_on_emit(self) -> None:
+        bus = ObserverBus()
+        seen: list[str] = []
+
+        def cb(ctx: ObserverContext) -> None:
+            seen.append(ctx.phase)
+
+        bus.subscribe(cb)
+        ctx = ObserverContext(
+            call_id="1",
+            instance=None,
+            owner=None,
+            cls=object,
+            cls_name="object",
+            method_name="m",
+            qualname="m",
+            method_kind="static",
+            args=(),
+            kwargs={},
+            phase="after",
+        )
+        bus.emit(ctx)
+        self.assertEqual(seen, ["after"])
+
+    def test_subscribe_returns_callback(self) -> None:
+        bus = ObserverBus()
+
+        def cb(ctx: ObserverContext) -> None:
+            pass
+
+        self.assertIs(bus.subscribe(cb), cb)
+
+    def test_duplicate_subscribe_same_filters_is_idempotent(self) -> None:
+        bus = ObserverBus()
+        count = 0
+
+        def cb(ctx: ObserverContext) -> None:
+            nonlocal count
+            count += 1
+
+        bus.subscribe(cb, phase="after")
+        bus.subscribe(cb, phase="after")
+        bus.emit(
+            ObserverContext(
+                call_id="1",
+                instance=None,
+                owner=None,
+                cls=object,
+                cls_name="object",
+                method_name="m",
+                qualname="m",
+                method_kind="static",
+                args=(),
+                kwargs={},
+                phase="after",
+            )
+        )
+        self.assertEqual(count, 1)
+
+    def test_same_callback_different_filters_both_fire(self) -> None:
+        bus = ObserverBus()
+        phases: list[str] = []
+
+        def cb(ctx: ObserverContext) -> None:
+            phases.append(ctx.phase)
+
+        bus.subscribe(cb, phase="before")
+        bus.subscribe(cb, phase="after")
+        bus.emit(
+            ObserverContext(
+                call_id="1",
+                instance=None,
+                owner=None,
+                cls=object,
+                cls_name="object",
+                method_name="m",
+                qualname="m",
+                method_kind="static",
+                args=(),
+                kwargs={},
+                phase="before",
+            )
+        )
+        bus.emit(
+            ObserverContext(
+                call_id="2",
+                instance=None,
+                owner=None,
+                cls=object,
+                cls_name="object",
+                method_name="m",
+                qualname="m",
+                method_kind="static",
+                args=(),
+                kwargs={},
+                phase="after",
+            )
+        )
+        self.assertEqual(phases, ["before", "after"])
+
+    def test_unsubscribe_removes_callback(self) -> None:
+        bus = ObserverBus()
+        seen: list[int] = []
+
+        def cb(ctx: ObserverContext) -> None:
+            seen.append(1)
+
+        bus.subscribe(cb)
+        bus.unsubscribe(cb)
+        bus.emit(
+            ObserverContext(
+                call_id="1",
+                instance=None,
+                owner=None,
+                cls=object,
+                cls_name="object",
+                method_name="m",
+                qualname="m",
+                method_kind="static",
+                args=(),
+                kwargs={},
+            )
+        )
+        self.assertEqual(seen, [])
+
+    def test_callback_decorator_registers(self) -> None:
+        bus = ObserverBus()
+        seen: list[str] = []
+
+        @bus.callback(phase="after", cls_name="Svc")
+        def cb(ctx: ObserverContext) -> None:
+            seen.append(ctx.method_name)
+
+        bus.emit(
+            ObserverContext(
+                call_id="1",
+                instance=None,
+                owner=None,
+                cls=type("Svc", (), {}),
+                cls_name="Svc",
+                method_name="run",
+                qualname="Svc.run",
+                method_kind="instance",
+                args=(),
+                kwargs={},
+                phase="after",
+            )
+        )
+        self.assertEqual(seen, ["run"])
+
+    def test_callback_multiple_filters_all_must_match(self) -> None:
+        bus = ObserverBus()
+        seen: list[int] = []
+
+        @bus.callback(phase="after", method_name="run")
+        def cb(_: ObserverContext) -> None:
+            seen.append(1)
+
+        bus.emit(
+            ObserverContext(
+                call_id="1",
+                instance=None,
+                owner=None,
+                cls=object,
+                cls_name="object",
+                method_name="other",
+                qualname="object.other",
+                method_kind="static",
+                args=(),
+                kwargs={},
+                phase="after",
+            )
+        )
+        self.assertEqual(seen, [])
+
+        bus.emit(
+            ObserverContext(
+                call_id="2",
+                instance=None,
+                owner=None,
+                cls=object,
+                cls_name="object",
+                method_name="run",
+                qualname="object.run",
+                method_kind="static",
+                args=(),
+                kwargs={},
+                phase="after",
+            )
+        )
+        self.assertEqual(seen, [1])
+
+    def test_callback_decorator_rejects_invalid_filter_keys(self) -> None:
+        bus = ObserverBus()
+
+        with self.assertRaises(ValueError) as ar:
+            @bus.callback(not_a_context_field=1)
+            def cb(ctx: ObserverContext) -> None:
+                pass
+
+        self.assertIn("invalid callback filters", str(ar.exception))
+
+    def test_emit_listener_exception_does_not_propagate(self) -> None:
+        bus = ObserverBus()
+
+        def bad(_: ObserverContext) -> None:
+            raise RuntimeError("boom")
+
+        bus.subscribe(bad)
+
+        ctx = ObserverContext(
+            call_id="1",
+            instance=None,
+            owner=None,
+            cls=object,
+            cls_name="object",
+            method_name="m",
+            qualname="m",
+            method_kind="static",
+            args=(),
+            kwargs={},
+        )
+        bus.emit(ctx)
+
+    def test_emit_order_matches_subscription_order(self) -> None:
+        bus = ObserverBus()
+        order: list[int] = []
+
+        def first(_: ObserverContext) -> None:
+            order.append(1)
+
+        def second(_: ObserverContext) -> None:
+            order.append(2)
+
+        bus.subscribe(first)
+        bus.subscribe(second)
+        bus.emit(
+            ObserverContext(
+                call_id="1",
+                instance=None,
+                owner=None,
+                cls=object,
+                cls_name="object",
+                method_name="m",
+                qualname="m",
+                method_kind="static",
+                args=(),
+                kwargs={},
+            )
+        )
+        self.assertEqual(order, [1, 2])
+
+
+class ObserveMethodsTests(unittest.TestCase):
+    def test_instance_method_emits_before_and_after(self) -> None:
+        bus = ObserverBus()
+        phases: list[str] = []
+
+        bus.subscribe(lambda ctx: phases.append(ctx.phase))
+
+        @observe_methods(bus)
+        class Svc:
+            def add(self, a: int, b: int) -> int:
+                return a + b
+
+        self.assertEqual(Svc().add(1, 2), 3)
+        self.assertEqual(phases, ["before", "after"])
+
+    def test_emit_before_false_skips_before_phase(self) -> None:
+        bus = ObserverBus()
+        phases: list[str] = []
+
+        bus.subscribe(lambda ctx: phases.append(ctx.phase))
+
+        @observe_methods(bus, emit_before=False)
+        class Svc:
+            def add(self, a: int, b: int) -> int:
+                return a + b
+
+        self.assertEqual(Svc().add(1, 2), 3)
+        self.assertEqual(phases, ["after"])
+
+    def test_same_call_id_across_phases_for_sync_call(self) -> None:
+        bus = ObserverBus()
+        ids: list[str] = []
+
+        bus.subscribe(lambda ctx: ids.append(ctx.call_id))
+
+        @observe_methods(bus)
+        class Svc:
+            def add(self, a: int, b: int) -> int:
+                return a + b
+
+        Svc().add(1, 2)
+        self.assertEqual(len(ids), 2)
+        self.assertEqual(ids[0], ids[1])
+
+    def test_error_phase_then_exception_reraised(self) -> None:
+        bus = ObserverBus()
+        phases: list[str] = []
+
+        bus.subscribe(lambda ctx: phases.append(ctx.phase))
+
+        @observe_methods(bus)
+        class Svc:
+            def boom(self) -> None:
+                raise ValueError("x")
+
+        with self.assertRaises(ValueError):
+            Svc().boom()
+
+        self.assertEqual(phases, ["before", "error"])
+
+    def test_classmethod_context_owner_and_pure_args(self) -> None:
+        bus = ObserverBus()
+        snapshots: list[tuple[Any, Any, tuple[Any, ...]]] = []
+
+        def capture(ctx: ObserverContext) -> None:
+            if ctx.phase == "after":
+                snapshots.append((ctx.instance, ctx.owner, ctx.args))
+
+        bus.subscribe(capture)
+
+        @observe_methods(bus)
+        class Svc:
+            @classmethod
+            def build(cls, name: str) -> Svc:
+                return cls()
+
+        inst = Svc.build("n")
+        self.assertIsInstance(inst, Svc)
+        self.assertEqual(len(snapshots), 1)
+        instance, owner, args = snapshots[0]
+        self.assertIsNone(instance)
+        self.assertIs(owner, Svc)
+        self.assertEqual(args, ("n",))
+
+    def test_staticmethod_context(self) -> None:
+        bus = ObserverBus()
+        kinds: list[str] = []
+        owners: list[Any] = []
+
+        def capture(ctx: ObserverContext) -> None:
+            if ctx.phase == "after":
+                kinds.append(ctx.method_kind)
+                owners.append(ctx.owner)
+
+        bus.subscribe(capture)
+
+        @observe_methods(bus)
+        class Svc:
+            @staticmethod
+            def ping(msg: str) -> str:
+                return msg
+
+        self.assertEqual(Svc.ping("hi"), "hi")
+        self.assertEqual(kinds, ["static"])
+        self.assertIsNone(owners[0])
+
+    def test_property_not_wrapped(self) -> None:
+        bus = ObserverBus()
+
+        @observe_methods(bus)
+        class Svc:
+            @property
+            def x(self) -> int:
+                return 1
+
+        self.assertIsInstance(Svc.x, property)
+
+    def test_private_method_skipped_by_default(self) -> None:
+        bus = ObserverBus()
+        method_names: list[str] = []
+
+        bus.subscribe(lambda ctx: method_names.append(ctx.method_name))
+
+        @observe_methods(bus)
+        class Svc:
+            def _hidden(self) -> int:
+                return 2
+
+            def ok(self) -> int:
+                return self._hidden()
+
+        self.assertEqual(Svc().ok(), 2)
+        self.assertEqual(method_names, ["ok", "ok"])
+        self.assertNotIn("_hidden", method_names)
+
+    def test_include_private_wraps_dunder_named_callable(self) -> None:
+        bus = ObserverBus()
+        method_names: list[str] = []
+
+        bus.subscribe(lambda ctx: method_names.append(ctx.method_name))
+
+        @observe_methods(bus, include_private=True)
+        class Svc:
+            def _hidden(self) -> int:
+                return 7
+
+        self.assertEqual(Svc()._hidden(), 7)
+        self.assertIn("_hidden", method_names)
+
+    def test_subclass_methods_observed(self) -> None:
+        bus = ObserverBus()
+        names: list[str] = []
+
+        bus.subscribe(lambda ctx: names.append(ctx.method_name) if ctx.phase == "after" else None)
+
+        @observe_methods(bus)
+        class Base:
+            def a(self) -> int:
+                return 1
+
+        class Child(Base):
+            def b(self) -> int:
+                return 2
+
+        self.assertEqual(Child().a(), 1)
+        self.assertEqual(Child().b(), 2)
+        self.assertIn("a", names)
+        self.assertIn("b", names)
+
+    def test_instance_context_cls_is_runtime_type(self) -> None:
+        bus = ObserverBus()
+        cls_names: list[str] = []
+
+        bus.subscribe(
+            lambda ctx: cls_names.append(ctx.cls_name) if ctx.phase == "after" else None
+        )
+
+        @observe_methods(bus)
+        class Base:
+            def tag(self) -> str:
+                return "base"
+
+        class Child(Base):
+            def tag(self) -> str:
+                return "child"
+
+        self.assertEqual(Base().tag(), "base")
+        self.assertEqual(Child().tag(), "child")
+        self.assertEqual(cls_names, ["Base", "Child"])
+
+    def test_double_decorate_does_not_double_wrap(self) -> None:
+        bus = ObserverBus()
+        phases: list[str] = []
+
+        bus.subscribe(lambda ctx: phases.append(ctx.phase))
+
+        @observe_methods(bus)
+        @observe_methods(bus)
+        class Svc:
+            def run(self) -> int:
+                return 1
+
+        self.assertEqual(Svc().run(), 1)
+        self.assertEqual(phases, ["before", "after"])
+
+    def test_bus_observe_delegates_to_observe_methods(self) -> None:
+        bus = ObserverBus()
+        phases: list[str] = []
+
+        bus.subscribe(lambda ctx: phases.append(ctx.phase))
+
+        @bus.observe()
+        class Svc:
+            def run(self) -> int:
+                return 5
+
+        self.assertEqual(Svc().run(), 5)
+        self.assertEqual(phases, ["before", "after"])
+
+
+class AsyncObserveMethodsTests(unittest.TestCase):
+    def test_async_instance_method_phases(self) -> None:
+        bus = ObserverBus()
+        phases: list[str] = []
+
+        bus.subscribe(lambda ctx: phases.append(ctx.phase))
+
+        @observe_methods(bus)
+        class Svc:
+            async def fetch(self, n: int) -> int:
+                await asyncio.sleep(0)
+                return n * 2
+
+        async def main() -> int:
+            return await Svc().fetch(3)
+
+        self.assertEqual(asyncio.run(main()), 6)
+        self.assertEqual(phases, ["before", "after"])
+
+    def test_async_error_phase(self) -> None:
+        bus = ObserverBus()
+        phases: list[str] = []
+
+        bus.subscribe(lambda ctx: phases.append(ctx.phase))
+
+        @observe_methods(bus)
+        class Svc:
+            async def boom(self) -> None:
+                raise OSError("async")
+
+        async def main() -> None:
+            await Svc().boom()
+
+        with self.assertRaises(OSError):
+            asyncio.run(main())
+
+        self.assertEqual(phases, ["before", "error"])
+
+    def test_async_emit_before_false(self) -> None:
+        bus = ObserverBus()
+        phases: list[str] = []
+
+        bus.subscribe(lambda ctx: phases.append(ctx.phase))
+
+        @observe_methods(bus, emit_before=False)
+        class Svc:
+            async def fetch(self) -> int:
+                return 9
+
+        async def main() -> int:
+            return await Svc().fetch()
+
+        self.assertEqual(asyncio.run(main()), 9)
+        self.assertEqual(phases, ["after"])
+
+
+class InitSubclassChainTests(unittest.TestCase):
+    def test_preserves_existing_init_subclass(self) -> None:
+        bus = ObserverBus()
+        log: list[str] = []
+
+        class Base:
+            def __init_subclass__(cls, **kwargs: Any) -> None:
+                super().__init_subclass__(**kwargs)
+                log.append("base_hook")
+
+        @observe_methods(bus)
+        class Observed(Base):
+            def run(self) -> None:
+                pass
+
+        class Child(Observed):
+            pass
+
+        self.assertIn("base_hook", log)
+
+
+if __name__ == "__main__":
+    unittest.main()