feat: add decoy.next preview API

Author: mcous

decoy/errors.py

@@ -25,6 +25,10 @@ def create(cls) -> "MockNameRequiredError":
         return cls("Mocks without `cls` or `func` require a `name`.")
 
 
+class MockSpecInvalidError(TypeError):
+    """An value passed as a mock spec is not valid."""
+
+
 class MissingRehearsalError(ValueError):
     """An error raised when a Decoy method is called without rehearsal(s).
 
@@ -44,6 +48,14 @@ def create(cls) -> "MissingRehearsalError":
         return cls("Rehearsal not found.")
 
 
+class NotAMockError(TypeError):
+    """A Decoy method was called without a mock."""
+
+
+class ThenDoActionNotCallableError(TypeError):
+    """A value passed to `then_do` is not callable."""
+
+
 class MockNotAsyncError(TypeError):
     """An error raised when an asynchronous function is used with a synchronous mock.
 
@@ -55,6 +67,10 @@ class MockNotAsyncError(TypeError):
     """
 
 
+class SignatureMismatchError(TypeError):
+    """Arguments did not match the signature of the mock."""
+
+
 class VerifyError(AssertionError):
     """An error raised when actual calls do not match rehearsals given to `verify`.
 
@@ -100,3 +116,12 @@ def create(
         result.times = times
 
         return result
+
+
+class VerifyOrderError(VerifyError):
+    """An error raised when the order of calls do not match expectations.
+
+    See [spying with verify][] for more details.
+
+    [spying with verify]: usage/verify.md
+    """

decoy/next/__init__.py

@@ -0,0 +1,19 @@
+"""Decoy mocking library.
+
+Use Decoy to create stubs and spies
+to isolate your code under test.
+"""
+
+from ._internal.decoy import Decoy
+from ._internal.mock import AsyncMock, Mock
+from ._internal.verify import Verify
+from ._internal.when import Stub, When
+
+__all__ = [
+    "AsyncMock",
+    "Decoy",
+    "Mock",
+    "Stub",
+    "Verify",
+    "When",
+]

decoy/next/_internal/__init__.py

@@ -0,0 +1,230 @@
+import collections.abc
+import contextlib
+from typing import Any, Callable, Literal, TypeVar, overload
+
+from .errors import createNotAMockError, createVerifyOrderError
+from .inspect import (
+    ensure_spec,
+    ensure_spec_name,
+    get_spec_module_name,
+    is_async_callable,
+)
+from .mock import AsyncMock, Mock, create_mock, ensure_mock
+from .state import DecoyState
+from .values import MatchOptions
+from .verify import Verify
+from .when import When
+
+ClassT = TypeVar("ClassT")
+FuncT = TypeVar("FuncT", bound=Callable[..., Any])
+SpecT = TypeVar("SpecT")
+
+
+class Decoy:
+    """Decoy mock factory and state container.
+
+    Use the `create` context manager to create a new Decoy instance
+    and reset it after your test.
+    If you use the [`decoy` pytest fixture][decoy.pytest_plugin.decoy],
+    this is done automatically.
+
+    See the [setup guide][] for more details.
+
+    !!! example
+        ```python
+        with Decoy.create() as decoy:
+            ...
+        ```
+
+    [setup guide]: ../index.md#setup
+    """
+
+    @classmethod
+    @contextlib.contextmanager
+    def create(cls) -> collections.abc.Iterator["Decoy"]:
+        """Create a Decoy instance for testing that will reset after usage.
+
+        This method is used by the [pytest plugin][decoy.pytest_plugin].
+        """
+        decoy = cls()
+        try:
+            yield decoy
+        finally:
+            decoy.reset()
+
+    def __init__(self) -> None:
+        self._state = DecoyState()
+
+    @overload
+    def mock(self, *, cls: Callable[..., ClassT]) -> ClassT: ...
+
+    @overload
+    def mock(self, *, func: FuncT) -> FuncT: ...
+
+    @overload
+    def mock(self, *, name: str, is_async: Literal[True]) -> AsyncMock: ...
+
+    @overload
+    def mock(self, *, name: str, is_async: bool = False) -> Mock: ...
+
+    def mock(
+        self,
+        *,
+        cls: Callable[..., ClassT] | None = None,
+        func: FuncT | None = None,
+        name: str | None = None,
+        is_async: bool = False,
+    ) -> ClassT | FuncT | AsyncMock | Mock:
+        """Create a mock. See the [mock creation guide][] for more details.
+
+        [mock creation guide]: ./create.md
+
+        Arguments:
+            cls: A class definition that the mock should imitate.
+            func: A function definition the mock should imitate.
+            name: A name to use for the mock. If you do not use
+                `cls` or `func`, you must add a `name`.
+            is_async: Force the returned mock to be asynchronous. This argument
+                only applies if you don't use `cls` nor `func`.
+
+        Returns:
+            A mock typecast as the object it's imitating, if any.
+
+        !!! example
+            ```python
+            def test_get_something(decoy: Decoy):
+                db = decoy.mock(cls=Database)
+                # ...
+            ```
+        """
+        spec = ensure_spec(cls, func)
+        name = ensure_spec_name(spec, name)
+        parent_name = get_spec_module_name(spec)
+        is_async = is_async_callable(spec, is_async)
+
+        return create_mock(
+            spec=spec,
+            name=name,
+            parent_name=parent_name,
+            is_async=is_async,
+            state=self._state,
+        )
+
+    def when(
+        self,
+        mock: SpecT,
+        *,
+        times: int | None = None,
+        ignore_extra_args: bool = False,
+        is_entered: bool | None = None,
+    ) -> When[SpecT, SpecT]:
+        """Configure a mock as a stub.
+
+        See [stubbing usage guide](when.md) for more details.
+
+        Arguments:
+            mock: The mock to configure.
+            times: Limit the number of times the behavior is triggered.
+            ignore_extra_args: Only partially match arguments.
+            is_entered: Limit the behavior to when the mock is entered using `with`.
+
+        Returns:
+            A stub interface to configure matching arguments.
+
+        !!! example
+            ```python
+            db = decoy.mock(cls=Database)
+            decoy.when(db.exists).called_with("some-id").then_return(True)
+            ```
+        """
+        mock_info = ensure_mock(mock)
+        match_options = MatchOptions(times, ignore_extra_args, is_entered)
+
+        if not mock_info:
+            raise createNotAMockError("when", mock)
+
+        return When(self._state, mock_info, match_options)
+
+    def verify(
+        self,
+        mock: SpecT,
+        *,
+        times: int | None = None,
+        ignore_extra_args: bool = False,
+        is_entered: bool | None = None,
+    ) -> Verify[SpecT]:
+        """Verify a mock was called in a particular manner.
+
+        See [verification usage guide](verify.md) for more details.
+
+        Arguments:
+            mock: The mock to verify.
+            times: Limit the number of times the call is expected.
+            ignore_extra_args: Only partially match arguments.
+            is_entered: Verify call happens when the mock is entered using `with`.
+
+        Raises:
+            VerifyError: The verification was not satisfied.
+
+        !!! example
+            ```python
+            def test_create_something(decoy: Decoy):
+                gen_id = decoy.mock(func=generate_unique_id)
+
+                # ...
+
+                decoy.verify(gen_id).called_with("model-prefix_")
+            ```
+        """
+        mock_info = ensure_mock(mock)
+        match_options = MatchOptions(times, ignore_extra_args, is_entered)
+
+        if not mock_info:
+            mock_info = self._state.peek_last_attribute_mock(mock)
+
+        if not mock_info:
+            raise createNotAMockError("verify", mock)
+
+        return Verify(
+            self._state,
+            mock_info,
+            match_options,
+        )
+
+    @contextlib.contextmanager
+    def verify_order(self) -> collections.abc.Iterator[None]:
+        """Verify a sequence of interactions.
+
+        All verifications in the sequence must be individually satisfied
+        before the sequence is checked.
+
+        See [verification usage guide](verify.md) for more details.
+
+        Raises:
+            VerifyOrderError: The sequence was not satisfied.
+
+        !!! example
+            ```python
+            def test_greet(decoy: Decoy):
+                verify_greeting = decoy.mock(name="verify_greeting")
+                greet = decoy.mock(name="greet")
+
+                # ...
+
+                with decoy.verify_order():
+                    decoy.verify(verify_greeting).called_with("hello world")
+                    decoy.verify(greet).called_with("hello world")
+            ```
+        """
+        with self._state.verify_order() as verify_order_result:
+            yield
+
+        if not verify_order_result.is_success:
+            raise createVerifyOrderError(
+                verify_order_result.verifications,
+                verify_order_result.all_events,
+            )
+
+    def reset(self) -> None:
+        """Reset the decoy instance."""
+        self._state.reset()

decoy/next/_internal/decoy.py

@@ -0,0 +1,97 @@
+from typing import Literal
+
+from ... import errors
+from .stringify import (
+    count,
+    join_lines,
+    stringify_event,
+    stringify_event_entry_list,
+    stringify_event_list,
+    stringify_verification_list,
+)
+from .values import Event, EventEntry, MatchOptions, VerificationEntry
+
+
+def createMockNameRequiredError() -> errors.MockNameRequiredError:
+    """Create a MockNameRequiredError."""
+    return errors.MockNameRequiredError(
+        "Mocks without `cls` or `func` require a `name`."
+    )
+
+
+def createMockSpecInvalidError(
+    argument_name: Literal["func", "cls"],
+) -> errors.MockSpecInvalidError:
+    """Create a MockSpecInvalidError."""
+    expected_type = "function" if argument_name == "func" else "class"
+
+    return errors.MockSpecInvalidError(
+        f"{argument_name} value must be a {expected_type}"
+    )
+
+
+def createNotAMockError(method_name: str, actual_value: object) -> errors.NotAMockError:
+    """Create a NotAMockError."""
+    return errors.NotAMockError(
+        f"`Decoy.{method_name}` must be called with a mock, but got: {actual_value}"
+    )
+
+
+def createThenDoActionNotCallableError() -> errors.ThenDoActionNotCallableError:
+    """Create a ThenDoActionNotCallableError."""
+    return errors.ThenDoActionNotCallableError(
+        "Value passed to `then_do` must be callable."
+    )
+
+
+def createMockNotAsyncError() -> errors.MockNotAsyncError:
+    """Create a MockNotAsyncError."""
+    return errors.MockNotAsyncError(
+        "Synchronous mock cannot use an asynchronous callable in `then_do`."
+    )
+
+
+def createSignatureMismatchError(
+    source: TypeError | ValueError,
+) -> errors.SignatureMismatchError:
+    """Create a SignatureMismatchError."""
+    return errors.SignatureMismatchError(source)
+
+
+def createVerifyError(
+    mock_name: str,
+    match_options: MatchOptions,
+    expected: Event,
+    all_events: list[EventEntry],
+) -> errors.VerifyError:
+    """Create a VerifyError."""
+    if match_options.times is not None:
+        heading = f"Expected exactly {count(match_options.times, 'call')}:"
+    else:
+        heading = "Expected at least 1 call:"
+
+    message = join_lines(
+        heading,
+        f"1.\t{stringify_event(mock_name, expected)}",
+        (
+            f"Found {count(len(all_events), 'call')}{'.' if len(all_events) == 0 else ':'}"
+        ),
+        stringify_event_list(mock_name, [entry.event for entry in all_events]),
+    )
+
+    return errors.VerifyError(message)
+
+
+def createVerifyOrderError(
+    verifications: list[VerificationEntry],
+    all_events: list[EventEntry],
+) -> errors.VerifyOrderError:
+    """Create a VerifyOrderError."""
+    message = join_lines(
+        "Expected call sequence:",
+        stringify_verification_list(verifications),
+        f"Found {len(all_events)} calls:",
+        stringify_event_entry_list(all_events),
+    )
+
+    return errors.VerifyOrderError(message)