pytest-mockrot 0.1.0__py3-none-any.whl

mockrot/__init__.py

@@ -0,0 +1,7 @@
+"""Mockrot: Runtime contract verification to detect rotting mocks in pytest."""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

mockrot/cli.py

@@ -0,0 +1,23 @@
+"""Standalone CLI entry point for Mockrot (delegates to pytest)."""
+
+from __future__ import annotations
+
+import sys
+
+import pytest
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Run pytest with Mockrot enabled by default."""
+    args = list(sys.argv[1:] if argv is None else argv)
+
+    # Ensure --mockrot flag is injected if not explicitly provided
+    has_mockrot_flag = any(arg.startswith("--mockrot") for arg in args)
+    if not has_mockrot_flag:
+        args.insert(0, "--mockrot=warn")
+
+    return int(pytest.main(args))
+
+
+if __name__ == "__main__":
+    sys.exit(main())

mockrot/errors.py

@@ -0,0 +1,19 @@
+"""Exceptions hierarchy for Mockrot."""
+
+from __future__ import annotations
+
+
+class MockrotError(Exception):
+    """Base exception for all Mockrot runtime and configuration errors."""
+
+
+class ContractExtractionError(MockrotError):
+    """Raised when extraction of signature or type hints fails unexpectedly."""
+
+
+class ContractValidationError(MockrotError):
+    """Raised when a mock interaction violates the target contract."""
+
+
+class ConfigurationError(MockrotError):
+    """Raised when Mockrot configuration in pyproject.toml or CLI is invalid."""

mockrot/extractor.py

@@ -0,0 +1,180 @@
+"""Contract extraction layer inspecting signatures and type metadata."""
+
+from __future__ import annotations
+
+import inspect
+import sys
+import weakref
+from typing import Any, get_type_hints
+
+from pydantic import TypeAdapter
+from pydantic.errors import PydanticUserError
+
+from mockrot.models import Contract
+
+# Two-tier cache: WeakKeyDictionary for living objects (zero memory leak),
+# mapping underlying callable -> dict[is_bound, Contract].
+# Fallback to static key (module, qualname, is_bound) for unhashable or non-weakrefable callables.
+_CONTRACT_CACHE: weakref.WeakKeyDictionary[Any, dict[bool, Contract]] = weakref.WeakKeyDictionary()
+_STATIC_CONTRACT_CACHE: dict[tuple[str, str, bool], Contract] = {}
+
+
+def clear_extractor_cache() -> None:
+    """Clear all cached contracts (primarily used for test isolation)."""
+    _CONTRACT_CACHE.clear()
+    _STATIC_CONTRACT_CACHE.clear()
+
+
+def _get_target_qualname(target: Any) -> str:
+    """Build a reliable identifier from target module and qualname."""
+    module = getattr(target, "__module__", "")
+    qualname = getattr(target, "__qualname__", getattr(target, "__name__", str(target)))
+    return f"{module}.{qualname}" if module else qualname
+
+
+def _resolve_type_hints_return(real_fn: Any, globalns: dict[str, Any] | None) -> Any | None:
+    """Attempt resolving return annotation using typing.get_type_hints."""
+    try:
+        hints = get_type_hints(real_fn, globalns=globalns)
+        ret = hints.get("return")
+        if ret is not None and ret is not type(None):
+            return ret
+    except NameError:
+        # Resolve closure or local function annotations by inspecting caller frames
+        try:
+            merged_locals: dict[str, Any] = {}
+            frame = inspect.currentframe()
+            while frame:
+                merged_locals.update(frame.f_locals)
+                frame = frame.f_back
+            hints = get_type_hints(real_fn, globalns=globalns, localns=merged_locals)
+            ret = hints.get("return")
+            if ret is not None and ret is not type(None):
+                return ret
+        except (NameError, TypeError, ValueError):
+            return None
+    except (TypeError, ValueError, AttributeError):
+        return None
+    return None
+
+
+def _resolve_raw_annotations_return(
+    real_fn: Any, underlying: Any, globalns: dict[str, Any] | None
+) -> Any | None:
+    """Fallback resolving return type from raw annotations or string evaluation."""
+    annotations: dict[str, Any] = getattr(real_fn, "__annotations__", {}) or getattr(
+        underlying, "__annotations__", {}
+    )
+    raw_ret = annotations.get("return")
+    if raw_ret is None or raw_ret is type(None) or raw_ret == "None":
+        return None
+
+    if isinstance(raw_ret, str):
+        try:
+            resolved = eval(raw_ret, globalns)
+            if resolved is not None and resolved is not type(None):
+                return resolved
+        except (NameError, TypeError, ValueError, SyntaxError):
+            return None
+        return None
+
+    return raw_ret
+
+
+def _resolve_return_type(
+    real_fn: Any, underlying: Any
+) -> tuple[Any | None, TypeAdapter[Any] | None]:
+    """Resolve return type annotation and compile its Pydantic TypeAdapter."""
+    globalns: dict[str, Any] | None = getattr(underlying, "__globals__", None) or getattr(
+        sys.modules.get(getattr(underlying, "__module__", "")), "__dict__", None
+    )
+
+    ret = _resolve_type_hints_return(real_fn, globalns)
+    if ret is None and underlying is not real_fn:
+        ret = _resolve_type_hints_return(underlying, globalns)
+    if ret is None:
+        ret = _resolve_raw_annotations_return(real_fn, underlying, globalns)
+
+    adapter: TypeAdapter[Any] | None = None
+    if ret is not None:
+        try:
+            adapter = TypeAdapter(ret)
+        except (PydanticUserError, TypeError, ValueError):
+            adapter = None
+
+    return ret, adapter
+
+
+def extract_contract(real_fn: Any) -> Contract:
+    """Extract runtime contract (signature, async status, annotations) from a callable.
+
+    Features two-tier caching to prevent memory leaks and protect against Python
+    id() recycling or non-hashable callables. Distinguishes bound and unbound callables.
+    """
+    if real_fn is None:
+        return Contract(
+            target_name="unknown",
+            is_async=False,
+            has_return_annotation=False,
+            signature=None,
+            return_type=None,
+            return_adapter=None,
+        )
+
+    underlying = getattr(real_fn, "__func__", real_fn)
+    is_bound = hasattr(real_fn, "__self__") and real_fn.__self__ is not None
+
+    # 1. Check caches
+    try:
+        if is_bound in _CONTRACT_CACHE[underlying]:
+            return _CONTRACT_CACHE[underlying][is_bound]
+    except (KeyError, TypeError):
+        key = (
+            getattr(underlying, "__module__", ""),
+            getattr(underlying, "__qualname__", getattr(underlying, "__name__", "")),
+            is_bound,
+        )
+        if key in _STATIC_CONTRACT_CACHE:
+            return _STATIC_CONTRACT_CACHE[key]
+
+    # 2. Extract signature with graceful fallback for C builtins or unsupported callables
+    try:
+        sig = inspect.signature(real_fn)
+    except (ValueError, TypeError):
+        sig = None
+
+    # 3. Determine if coroutine function
+    is_async = inspect.iscoroutinefunction(real_fn) or inspect.iscoroutinefunction(underlying)
+
+    # 4. Extract return type annotation and compile TypeAdapter
+    return_type, return_adapter = _resolve_return_type(real_fn, underlying)
+    has_return = return_type is not None or (
+        sig is not None
+        and sig.return_annotation is not inspect.Signature.empty
+        and sig.return_annotation is not None
+    )
+
+    target_name = _get_target_qualname(real_fn)
+    contract = Contract(
+        target_name=target_name,
+        is_async=is_async,
+        has_return_annotation=has_return,
+        signature=sig,
+        return_type=return_type,
+        return_adapter=return_adapter,
+    )
+
+    # 5. Populate cache
+    try:
+        if underlying not in _CONTRACT_CACHE:
+            _CONTRACT_CACHE[underlying] = {}
+        _CONTRACT_CACHE[underlying][is_bound] = contract
+    except TypeError:
+        key = (
+            getattr(underlying, "__module__", ""),
+            getattr(underlying, "__qualname__", getattr(underlying, "__name__", "")),
+            is_bound,
+        )
+        _STATIC_CONTRACT_CACHE[key] = contract
+
+    return contract

mockrot/interceptor.py

@@ -0,0 +1,418 @@
+"""Transparent mock interception layer for unittest.mock and pytest.MonkeyPatch."""
+
+from __future__ import annotations
+
+import inspect
+import sys
+import threading
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+from unittest import mock
+
+from mockrot.models import MockInteraction, MockSite
+
+try:
+    import _pytest.monkeypatch as _mp
+except ImportError:  # pragma: no cover
+    _mp = None  # type: ignore[assignment]
+
+if TYPE_CHECKING:
+    import _pytest.monkeypatch
+
+# Type alias for listener callback receiving intercepted interactions
+InteractionListener = Callable[[MockInteraction], None]
+
+
+@dataclass
+class _InterceptorState:
+    """Internal state tracking original patch methods and active listener."""
+
+    orig_patch_enter: Callable[..., Any] | None = None
+    orig_monkeypatch_setattr: Callable[..., Any] | None = None
+    listener: InteractionListener | None = None
+    is_installed: bool = False
+
+
+_STATE = _InterceptorState()
+
+# Thread-local storage to prevent reentrant interception loops
+_TLS = threading.local()
+
+
+def _is_active() -> bool:
+    """Return True if currently processing an interception."""
+    return bool(getattr(_TLS, "active", False))
+
+
+def _resolve_mock_site() -> MockSite:
+    """Resolve caller file, line, and test name, skipping internal frameworks."""
+    try:
+        # sys._getframe is used for fast memory-only frame traversal without blocking disk I/O
+        frame = sys._getframe(1)  # pyright: ignore[reportPrivateUsage] - fast frame inspection
+        while frame is not None:
+            fn = frame.f_code.co_filename
+            if any(
+                skip in fn
+                for skip in (
+                    "unittest/mock.py",
+                    "contextlib.py",
+                    "_pytest",
+                    "/mockrot/",
+                    "pluggy",
+                    "pytest_asyncio",
+                )
+            ):
+                frame = frame.f_back
+                continue
+            return MockSite(
+                file_path=fn,
+                line_number=frame.f_lineno,
+                test_name=frame.f_code.co_name,
+            )
+    except (AttributeError, ValueError):
+        pass
+    return MockSite(file_path="unknown", line_number=0, test_name="")
+
+
+def _get_target_name(target: Any, attribute: str | None = None) -> str:
+    """Build a human-readable identifier for the target function or attribute."""
+    if attribute:
+        target_mod = getattr(target, "__module__", "")
+        target_cls = getattr(target, "__name__", "")
+        prefix = (
+            f"{target_mod}.{target_cls}" if target_mod and target_cls else target_cls or target_mod
+        )
+        return f"{prefix}.{attribute}" if prefix else attribute
+
+    module = getattr(target, "__module__", "")
+    qualname = getattr(target, "__qualname__", getattr(target, "__name__", str(target)))
+    return f"{module}.{qualname}" if module else qualname
+
+
+def _wrap_mock_object(mock_obj: Any, orig_target: Any, target_name: str) -> None:
+    """Wrap the _mock_call dispatch of a Mock or AsyncMock instance."""
+    if not hasattr(mock_obj, "_mock_call"):
+        return
+
+    orig_mock_call = mock_obj._mock_call
+    if getattr(orig_mock_call, "__mockrot_wrapped__", False):
+        return
+
+    is_async = isinstance(mock_obj, mock.AsyncMock)
+
+    if is_async:
+
+        async def async_interceptor_wrapper(*args: Any, **kwargs: Any) -> Any:
+            if _is_active() or _STATE.listener is None:
+                return await orig_mock_call(*args, **kwargs)
+
+            _TLS.active = True
+            try:
+                site = _resolve_mock_site()
+                try:
+                    result = await orig_mock_call(*args, **kwargs)
+                except BaseException as exc:
+                    _STATE.listener(
+                        MockInteraction(
+                            site=site,
+                            target_func=orig_target,
+                            target_name=target_name,
+                            args=args,
+                            kwargs=kwargs,
+                            returned_value=None,
+                            raised_exception=exc,
+                            is_async_call=True,
+                        )
+                    )
+                    raise
+                else:
+                    _STATE.listener(
+                        MockInteraction(
+                            site=site,
+                            target_func=orig_target,
+                            target_name=target_name,
+                            args=args,
+                            kwargs=kwargs,
+                            returned_value=result,
+                            raised_exception=None,
+                            is_async_call=True,
+                        )
+                    )
+                    return result
+            finally:
+                _TLS.active = False
+
+        async_interceptor_wrapper.__mockrot_wrapped__ = True  # type: ignore[attr-defined]
+        mock_obj._mock_call = async_interceptor_wrapper
+
+    else:
+
+        def sync_interceptor_wrapper(*args: Any, **kwargs: Any) -> Any:
+            if _is_active() or _STATE.listener is None:
+                return orig_mock_call(*args, **kwargs)
+
+            _TLS.active = True
+            try:
+                site = _resolve_mock_site()
+                try:
+                    result = orig_mock_call(*args, **kwargs)
+                except BaseException as exc:
+                    _STATE.listener(
+                        MockInteraction(
+                            site=site,
+                            target_func=orig_target,
+                            target_name=target_name,
+                            args=args,
+                            kwargs=kwargs,
+                            returned_value=None,
+                            raised_exception=exc,
+                            is_async_call=False,
+                        )
+                    )
+                    raise
+                else:
+                    _STATE.listener(
+                        MockInteraction(
+                            site=site,
+                            target_func=orig_target,
+                            target_name=target_name,
+                            args=args,
+                            kwargs=kwargs,
+                            returned_value=result,
+                            raised_exception=None,
+                            is_async_call=False,
+                        )
+                    )
+                    return result
+            finally:
+                _TLS.active = False
+
+        sync_interceptor_wrapper.__mockrot_wrapped__ = True  # type: ignore[attr-defined]
+        mock_obj._mock_call = sync_interceptor_wrapper
+
+
+def _wrap_plain_callable(func: Any, orig_target: Any, target_name: str) -> Any:
+    """Wrap a non-Mock callable (e.g. lambda or dummy function) with interception."""
+    if getattr(func, "__mockrot_wrapped__", False):
+        return func
+
+    if inspect.iscoroutinefunction(func):
+
+        async def async_callable_wrapper(*args: Any, **kwargs: Any) -> Any:
+            if _is_active() or _STATE.listener is None:
+                return await func(*args, **kwargs)
+
+            _TLS.active = True
+            try:
+                site = _resolve_mock_site()
+                try:
+                    result = await func(*args, **kwargs)
+                except BaseException as exc:
+                    _STATE.listener(
+                        MockInteraction(
+                            site=site,
+                            target_func=orig_target,
+                            target_name=target_name,
+                            args=args,
+                            kwargs=kwargs,
+                            returned_value=None,
+                            raised_exception=exc,
+                            is_async_call=True,
+                        )
+                    )
+                    raise
+                else:
+                    _STATE.listener(
+                        MockInteraction(
+                            site=site,
+                            target_func=orig_target,
+                            target_name=target_name,
+                            args=args,
+                            kwargs=kwargs,
+                            returned_value=result,
+                            raised_exception=None,
+                            is_async_call=True,
+                        )
+                    )
+                    return result
+            finally:
+                _TLS.active = False
+
+        async_callable_wrapper.__mockrot_wrapped__ = True  # type: ignore[attr-defined]
+        return async_callable_wrapper
+
+    def callable_wrapper(*args: Any, **kwargs: Any) -> Any:
+        if _is_active() or _STATE.listener is None:
+            return func(*args, **kwargs)
+
+        _TLS.active = True
+        try:
+            site = _resolve_mock_site()
+            try:
+                result = func(*args, **kwargs)
+            except BaseException as exc:
+                _STATE.listener(
+                    MockInteraction(
+                        site=site,
+                        target_func=orig_target,
+                        target_name=target_name,
+                        args=args,
+                        kwargs=kwargs,
+                        returned_value=None,
+                        raised_exception=exc,
+                        is_async_call=False,
+                    )
+                )
+                raise
+            else:
+                _STATE.listener(
+                    MockInteraction(
+                        site=site,
+                        target_func=orig_target,
+                        target_name=target_name,
+                        args=args,
+                        kwargs=kwargs,
+                        returned_value=result,
+                        raised_exception=None,
+                        is_async_call=False,
+                    )
+                )
+                return result
+        finally:
+            _TLS.active = False
+
+    callable_wrapper.__mockrot_wrapped__ = True  # type: ignore[attr-defined]
+    return callable_wrapper
+
+
+def _patched_enter(patch_self: Any) -> Any:
+    """Intercept unittest.mock._patch.__enter__ to wrap created mocks transparently."""
+    if _STATE.orig_patch_enter is None:
+        return patch_self  # pragma: no cover
+
+    mock_obj = _STATE.orig_patch_enter(patch_self)
+
+    try:
+        orig_target = getattr(patch_self, "temp_original", None)
+        attr_name = getattr(patch_self, "attribute", "")
+        target_obj = getattr(patch_self, "target", None)
+        target_name = _get_target_name(target_obj, attr_name)
+
+        if callable(orig_target) and hasattr(mock_obj, "_mock_call"):
+            _wrap_mock_object(mock_obj, orig_target, target_name)
+    except Exception:  # noqa: BLE001
+        # Invariant 1: fail-safe, never crash user tests on internal interception failure
+        pass
+
+    return mock_obj
+
+
+def _is_runner_internal_caller() -> bool:
+    """Return True if caller of monkeypatch is an internal test runner or plugin."""
+    try:
+        caller = sys._getframe(2)  # pyright: ignore[reportPrivateUsage] - caller inspection
+        caller_fn = caller.f_code.co_filename
+        return any(skip in caller_fn for skip in ("pytest_asyncio", "_pytest", "pluggy"))
+    except (AttributeError, ValueError):
+        return False
+
+
+def _wrap_dotted_monkeypatch(target: str, value: Any) -> Any:
+    """Wrap replacement mock or callable when monkeypatch uses dotted target string."""
+    if "." not in target:
+        return value
+    mod_name, attr = target.rsplit(".", 1)
+    try:
+        mod = sys.modules.get(mod_name) or __import__(mod_name, fromlist=[attr])
+        orig_target = getattr(mod, attr, None)
+        if hasattr(value, "_mock_call"):
+            _wrap_mock_object(value, orig_target, target)
+        elif callable(value) and callable(orig_target):
+            return _wrap_plain_callable(value, orig_target, target)
+    except Exception:  # noqa: BLE001
+        pass
+    return value
+
+
+def _patched_monkeypatch_setattr(
+    self: _pytest.monkeypatch.MonkeyPatch,
+    target: str | object,
+    name: object | str = mock.DEFAULT,
+    value: object = mock.DEFAULT,
+    raising: bool = True,
+) -> None:
+    """Intercept pytest.MonkeyPatch.setattr to wrap replacement callables or mocks."""
+    if _STATE.orig_monkeypatch_setattr is None:
+        return  # pragma: no cover
+
+    if _is_active():
+        _STATE.orig_monkeypatch_setattr(self, target, name, value, raising=raising)
+        return
+
+    _TLS.active = True
+    try:
+        if _is_runner_internal_caller():
+            if value is mock.DEFAULT:
+                _STATE.orig_monkeypatch_setattr(self, target, name, raising=raising)
+            else:
+                _STATE.orig_monkeypatch_setattr(self, target, name, value, raising=raising)
+            return
+
+        if value is mock.DEFAULT:
+            real_name = _wrap_dotted_monkeypatch(target, name) if isinstance(target, str) else name
+            _STATE.orig_monkeypatch_setattr(self, target, real_name, raising=raising)
+            return
+
+        if isinstance(name, str):
+            orig_target = getattr(target, name, None)
+            target_name = _get_target_name(target, name)
+            if hasattr(value, "_mock_call"):
+                _wrap_mock_object(value, orig_target, target_name)
+            elif callable(value) and callable(orig_target):
+                value = _wrap_plain_callable(value, orig_target, target_name)
+
+        _STATE.orig_monkeypatch_setattr(self, target, name, value, raising=raising)
+    finally:
+        _TLS.active = False
+
+
+def is_interceptor_installed() -> bool:
+    """Return True if mockrot interceptor is actively installed."""
+    return _STATE.is_installed
+
+
+def install_interceptor(listener: InteractionListener) -> None:
+    """Install interception hooks on unittest.mock._patch and MonkeyPatch.setattr."""
+    _STATE.listener = listener
+    if _STATE.is_installed:
+        return
+
+    patch_cls: Any = mock._patch  # pyright: ignore[reportPrivateUsage]  # Wrap unittest.mock._patch.__enter__
+    _STATE.orig_patch_enter = patch_cls.__enter__
+    patch_cls.__enter__ = _patched_enter
+
+    if _mp is not None and hasattr(_mp, "MonkeyPatch"):
+        _STATE.orig_monkeypatch_setattr = _mp.MonkeyPatch.setattr
+        _mp.MonkeyPatch.setattr = _patched_monkeypatch_setattr  # type: ignore[assignment]
+
+    _STATE.is_installed = True
+
+
+def uninstall_interceptor() -> None:
+    """Restore original patch methods idempotently."""
+    if not _STATE.is_installed:
+        return
+
+    if _STATE.orig_patch_enter is not None:
+        patch_cls: Any = mock._patch  # pyright: ignore[reportPrivateUsage]  # Restore original _patch.__enter__
+        patch_cls.__enter__ = _STATE.orig_patch_enter
+        _STATE.orig_patch_enter = None
+
+    if _STATE.orig_monkeypatch_setattr is not None:
+        if _mp is not None and hasattr(_mp, "MonkeyPatch"):
+            _mp.MonkeyPatch.setattr = _STATE.orig_monkeypatch_setattr  # type: ignore[assignment]
+        _STATE.orig_monkeypatch_setattr = None
+
+    _STATE.listener = None
+    _STATE.is_installed = False