feat(spy): add inspect.signature and repr support (#35)

Closes #29, closes #30

Author: mcous

decoy/spy.py

@@ -4,7 +4,8 @@
 [unittest.mock library](https://docs.python.org/3/library/unittest.mock.html).
 """
 from __future__ import annotations
-from inspect import isclass, iscoroutinefunction
+from inspect import isclass, iscoroutinefunction, isfunction, signature
+from functools import partial
 from typing import get_type_hints, Any, Callable, Dict, NamedTuple, Optional, Tuple
 
 
@@ -39,6 +40,7 @@ class SpyConfig(NamedTuple):
     handle_call: CallHandler
     spec: Optional[Any] = None
     name: Optional[str] = None
+    module_name: Optional[str] = None
     is_async: bool = False
 
 
@@ -54,13 +56,25 @@ def __init__(
         handle_call: CallHandler,
         spec: Optional[Any] = None,
         name: Optional[str] = None,
+        module_name: Optional[str] = None,
     ) -> None:
         """Initialize a BaseSpy from a call handler and an optional spec object."""
-        self._name = name or (spec.__name__ if spec is not None else "spy")
         self._spec = spec
         self._handle_call: CallHandler = handle_call
         self._spy_children: Dict[str, BaseSpy] = {}
 
+        self._name = name or (spec.__name__ if spec is not None else "spy")
+        self._module_name = module_name
+
+        if module_name is None and spec is not None and hasattr(spec, "__module__"):
+            self._module_name = spec.__module__
+
+        # ensure spy can pass inspect.signature checks
+        try:
+            self.__signature__ = signature(spec)  # type: ignore[arg-type]
+        except Exception:
+            pass
+
     @property  # type: ignore[misc]
     def __class__(self) -> Any:
         """Ensure Spy can pass `instanceof` checks."""
@@ -69,15 +83,29 @@ def __class__(self) -> Any:
 
         return type(self)
 
+    def __repr__(self) -> str:
+        """Get a helpful string representation of the spy."""
+        name = self._name
+        if self._module_name:
+            name = f"{self._module_name}.{name}"
+
+        return f"<Decoy mock of {name}>" if self._spec else "<Decoy spy function>"
+
     def __getattr__(self, name: str) -> Any:
         """Get a property of the spy.
 
         Lazily constructs child spies, basing them on type hints if available.
         """
+        # do not attempt to mock magic methods
+        if name.startswith("__") and name.endswith("__"):
+            return super().__getattribute__(name)
+
+        # return previously constructed (and cached) child spies
         if name in self._spy_children:
             return self._spy_children[name]
 
         child_spec = None
+        child_is_async = False
 
         if isclass(self._spec):
             try:
@@ -98,12 +126,21 @@ def __getattr__(self, name: str) -> Any:
         if isinstance(child_spec, property):
             hints = get_type_hints(child_spec.fget)
             child_spec = hints.get("return")
+        elif isclass(self._spec) and isfunction(child_spec):
+            # `iscoroutinefunction` does not work for `partial` on Python < 3.8
+            # check before we wrap it
+            child_is_async = iscoroutinefunction(child_spec)
+            # consume the `self` argument of the method to ensure proper
+            # signature reporting by wrapping it in a partial
+            child_spec = partial(child_spec, None)  # type: ignore[arg-type]
 
         spy = create_spy(
             config=SpyConfig(
                 handle_call=self._handle_call,
                 spec=child_spec,
                 name=f"{self._name}.{name}",
+                module_name=self._module_name,
+                is_async=child_is_async,
             ),
         )
 
@@ -137,7 +174,12 @@ def create_spy(config: SpyConfig) -> Any:
     Functions and classes passed to `spec` will be inspected (and have any type
     annotations inspected) to ensure `AsyncSpy`'s are returned where necessary.
     """
-    handle_call, spec, name, is_async = config
+    handle_call, spec, name, module_name, is_async = config
     _SpyCls = AsyncSpy if iscoroutinefunction(spec) or is_async is True else Spy
 
-    return _SpyCls(handle_call=handle_call, spec=spec, name=name)
+    return _SpyCls(
+        handle_call=handle_call,
+        spec=spec,
+        name=name,
+        module_name=module_name,
+    )

tests/common.py

@@ -47,7 +47,8 @@ async def do_the_thing(self, flag: bool) -> None:
         ...
 
 
-def noop(*args: Any, **kwargs: Any) -> Any:
+# NOTE: these `Any`s are forward references for call signature testing purposes
+def noop(*args: "Any", **kwargs: "Any") -> "Any":
     """No-op."""
     pass
 

tests/test_spy.py

@@ -1,10 +1,12 @@
 """Tests for spy creation."""
 import pytest
+import inspect
 from typing import Any
 
 from decoy.spy import create_spy, AsyncSpy, SpyConfig, SpyCall
 
 from .common import (
+    noop,
     some_func,
     some_async_func,
     SomeClass,
@@ -294,3 +296,40 @@ def _handle_call(call: Any) -> int:
         sync_spy(),
         await async_spy(),
     ] == [1, 2, 3, 4]
+
+
+def test_spy_passes_instance_of() -> None:
+    """A spy should pass instanceof checks."""
+    spy = create_spy(SpyConfig(spec=SomeClass, handle_call=noop))
+
+    assert isinstance(spy, SomeClass)
+
+
+def test_spy_matches_signature() -> None:
+    """It should pass `inspect.signature` checks."""
+    class_spy = create_spy(SpyConfig(spec=SomeClass, handle_call=noop))
+    actual_instance = SomeClass()
+    assert inspect.signature(class_spy) == inspect.signature(SomeClass)
+    assert inspect.signature(class_spy.foo) == inspect.signature(actual_instance.foo)
+    assert inspect.signature(class_spy.bar) == inspect.signature(actual_instance.bar)
+    assert inspect.signature(class_spy.do_the_thing) == inspect.signature(
+        actual_instance.do_the_thing
+    )
+
+    func_spy = create_spy(SpyConfig(spec=some_func, handle_call=noop))
+    assert inspect.signature(func_spy) == inspect.signature(some_func)
+
+    spy = create_spy(SpyConfig(handle_call=noop))
+    assert inspect.signature(spy) == inspect.signature(noop)
+
+
+def test_spy_repr() -> None:
+    """It should have an informative repr."""
+    class_spy = create_spy(SpyConfig(spec=SomeClass, handle_call=noop))
+    func_spy = create_spy(SpyConfig(spec=some_func, handle_call=noop))
+    spy = create_spy(SpyConfig(handle_call=noop))
+
+    assert repr(class_spy) == "<Decoy mock of tests.common.SomeClass>"
+    assert repr(class_spy.foo) == "<Decoy mock of tests.common.SomeClass.foo>"
+    assert repr(func_spy) == "<Decoy mock of tests.common.some_func>"
+    assert repr(spy) == "<Decoy spy function>"