decoy 2.3.0__py3-none-any.whl → 2.5.0__py3-none-any.whl

decoy/next/_internal/verify.py

@@ -0,0 +1,78 @@
+import warnings
+from typing import Any, Callable, Generic, ParamSpec, TypeVar
+
+from .errors import createVerifyError
+from .inspect import bind_args
+from .state import DecoyState
+from .values import (
+    AttributeEvent,
+    CallEvent,
+    Event,
+    EventMatcher,
+    MatchOptions,
+    MockInfo,
+)
+from .warnings import createRedundantVerifyWarning
+
+SpecT = TypeVar("SpecT")
+ParamsT = ParamSpec("ParamsT")
+
+
+class Verify(Generic[SpecT]):
+    """[Verify](./verify.md) how a mock was called."""
+
+    def __init__(
+        self,
+        state: DecoyState,
+        mock: MockInfo,
+        match_options: MatchOptions,
+    ) -> None:
+        self._mock = mock
+        self._state = state
+        self._match_options = match_options
+
+    def _verify(self, expected: Event) -> None:
+        matcher = EventMatcher(expected, self._match_options)
+        result = self._state.use_verification(self._mock, matcher)
+
+        if not result.is_success:
+            raise createVerifyError(
+                self._mock.name,
+                self._match_options,
+                expected,
+                result.mock_events,
+            )
+
+        if result.is_redundant:
+            warnings.warn(
+                createRedundantVerifyWarning(self._mock.name, expected),
+                stacklevel=3,
+            )
+
+    def called_with(
+        self: "Verify[Callable[ParamsT, Any]]",
+        *args: ParamsT.args,
+        **kwargs: ParamsT.kwargs,
+    ) -> None:
+        """Verify that a mock was called."""
+        bound_args = bind_args(
+            signature=self._mock.signature,
+            args=args,
+            kwargs=kwargs,
+            ignore_extra_args=self._match_options.ignore_extra_args,
+        )
+        expected = CallEvent(args=bound_args.args, kwargs=bound_args.kwargs)
+
+        self._verify(expected)
+
+    def set(self, value: SpecT) -> None:
+        """Verify that an [attribute was set](./attributes.md#verify-a-setter)."""
+        expected = AttributeEvent.set(value)
+
+        self._verify(expected)
+
+    def delete(self) -> None:
+        """Verify that an [attribute was deleted](./attributes.md#verify-a-deleter)."""
+        expected = AttributeEvent.delete()
+
+        self._verify(expected)

decoy/next/_internal/warnings.py

@@ -0,0 +1,35 @@
+from ... import warnings
+from .stringify import count, join_lines, stringify_event, stringify_event_list
+from .values import CallEvent, Event
+
+
+def createMiscalledStubWarning(
+    name: str,
+    expected_events: list[Event],
+    actual_event: CallEvent,
+) -> warnings.MiscalledStubWarning:
+    """Create a MiscalledStubWarning."""
+    message = join_lines(
+        "Stub was called but no matching rehearsal found.",
+        f"Found {count(len(expected_events), 'rehearsal')}:",
+        stringify_event_list(name, expected_events),
+        "Found 1 call:",
+        f"1.\t{stringify_event(name, actual_event)}",
+    )
+
+    return warnings.MiscalledStubWarning(message)
+
+
+def createRedundantVerifyWarning(
+    name: str,
+    event: Event,
+) -> warnings.RedundantVerifyWarning:
+    """Create a RedundantVerifyWarning."""
+    message = join_lines(
+        "The same rehearsal was used in both a `when` and a `verify`.",
+        "This is redundant and probably a misuse of the mock.",
+        f"\t{stringify_event(name, event)}",
+        "See https://michael.cousins.io/decoy/usage/errors-and-warnings/#redundantverifywarning",
+    )
+
+    return warnings.RedundantVerifyWarning(message)

decoy/next/_internal/when.py

@@ -0,0 +1,136 @@
+from contextlib import AbstractAsyncContextManager, AbstractContextManager
+from typing import (
+    Any,
+    Awaitable,
+    Callable,
+    Generic,
+    NoReturn,
+    ParamSpec,
+    TypeVar,
+    overload,
+)
+
+from .inspect import bind_args, ensure_callable
+from .state import DecoyState
+from .values import (
+    AttributeEvent,
+    Behavior,
+    CallEvent,
+    Event,
+    EventMatcher,
+    MatchOptions,
+    MockInfo,
+)
+
+CallableSpecT = TypeVar("CallableSpecT", covariant=True)
+AttributeSpecT = TypeVar("AttributeSpecT")
+ParamsT = ParamSpec("ParamsT")
+ReturnT = TypeVar("ReturnT")
+ContextValueT = TypeVar("ContextValueT")
+
+
+class Stub(Generic[ParamsT, ReturnT, ContextValueT]):
+    """Configure how a mock behaves [when called](./when.md)."""
+
+    def __init__(
+        self,
+        state: DecoyState,
+        mock: MockInfo,
+        matcher: EventMatcher,
+    ) -> None:
+        self._state = state
+        self._mock = mock
+        self._matcher = matcher
+
+    def then_return(self, *values: ReturnT) -> None:
+        """Mock a return value."""
+        behaviors = [Behavior(return_value=value) for value in values]
+        self._push_behaviors(behaviors)
+
+    def then_enter_with(self, *values: ContextValueT) -> None:
+        """Mock a context manager value for a generator context manager."""
+        behaviors = [Behavior(context=value) for value in values]
+        self._push_behaviors(behaviors)
+
+    def then_raise(self, *errors: Exception) -> None:
+        """Mock a raised exception."""
+        behaviors = [Behavior(error=error) for error in errors]
+        self._push_behaviors(behaviors)
+
+    def then_do(self, *actions: Callable[ParamsT, ReturnT]) -> None:
+        """Trigger a callback function."""
+        behaviors = [
+            Behavior(action=ensure_callable(action, is_async=self._mock.is_async))
+            for action in actions
+        ]
+        self._push_behaviors(behaviors)
+
+    def _push_behaviors(self, behaviors: list[Behavior]) -> None:
+        self._state.push_behaviors(self._mock, self._matcher, behaviors)
+
+
+class When(Generic[CallableSpecT, AttributeSpecT]):
+    """Configure [when a mock is triggered](./when.md)."""
+
+    def __init__(
+        self,
+        state: DecoyState,
+        mock: MockInfo,
+        match_options: MatchOptions,
+    ) -> None:
+        self._state = state
+        self._mock = mock
+        self._match_options = match_options
+
+    @overload
+    def called_with(
+        self: "When[Callable[ParamsT, AbstractAsyncContextManager[ContextValueT] | AbstractContextManager[ContextValueT]], Callable[..., ReturnT]]",
+        *args: ParamsT.args,
+        **kwargs: ParamsT.kwargs,
+    ) -> Stub[ParamsT, ReturnT, ContextValueT]: ...
+
+    @overload
+    def called_with(
+        self: "When[Callable[ParamsT, Awaitable[ReturnT]], Any]",
+        *args: ParamsT.args,
+        **kwargs: ParamsT.kwargs,
+    ) -> Stub[ParamsT, ReturnT | Awaitable[ReturnT], NoReturn]: ...
+
+    @overload
+    def called_with(
+        self: "When[Callable[ParamsT, ReturnT], Any]",
+        *args: ParamsT.args,
+        **kwargs: ParamsT.kwargs,
+    ) -> Stub[ParamsT, ReturnT, NoReturn]: ...
+
+    def called_with(
+        self,
+        *args: Any,
+        **kwargs: Any,
+    ) -> Stub[Any, Any, Any]:
+        """Configure a stub to react to certain passed-in arguments."""
+        bound_args = bind_args(
+            signature=self._mock.signature,
+            args=args,
+            kwargs=kwargs,
+            ignore_extra_args=self._match_options.ignore_extra_args,
+        )
+        event = CallEvent(args=bound_args.args, kwargs=bound_args.kwargs)
+
+        return self._create_stub(event)
+
+    def get(self) -> Stub[[], AttributeSpecT, NoReturn]:
+        """Configure a stub to react to an attribute get."""
+        return self._create_stub(AttributeEvent.get())
+
+    def set(self, value: AttributeSpecT) -> Stub[[AttributeSpecT], None, NoReturn]:
+        """Configure a stub to react to an attribute set."""
+        return self._create_stub(AttributeEvent.set(value))
+
+    def delete(self) -> Stub[[], None, NoReturn]:
+        """Configure a stub to react to an attribute delete."""
+        return self._create_stub(AttributeEvent.delete())
+
+    def _create_stub(self, event: Event) -> Stub[Any, Any, NoReturn]:
+        matcher = EventMatcher(event=event, options=self._match_options)
+        return Stub(self._state, self._mock, matcher)

decoy/pytest_plugin.py

@@ -5,21 +5,32 @@ fixture without modifying any other pytest behavior. Its usage is optional
 but highly recommended.
 """
 
-from typing import Iterable
+from typing import TYPE_CHECKING, Iterable, Union, get_type_hints
 
 import pytest
 
 from decoy import Decoy
 
+if TYPE_CHECKING:
+    from decoy.next import Decoy as DecoyNext
+
 
 @pytest.fixture()
-def decoy() -> Iterable[Decoy]:
+def decoy(
+    request: pytest.FixtureRequest,
+) -> "Iterable[Union[Decoy, DecoyNext]]":
     """Get a [decoy.Decoy][] container and [reset it][decoy.Decoy.reset] after the test.
 
     This function is function-scoped [pytest fixture][] that will be
     automatically inserted by the plugin.
 
+    !!! tip
+
+        This fixture will automatically opt-into the [v3 preview API][v3-preview]
+        if annotated with `decoy.next.Decoy`.
+
     [pytest fixture]: https://docs.pytest.org/en/latest/how-to/fixtures.html
+    [v3-preview]: ./v3/about.md
 
     !!! example
         ```python
@@ -28,6 +39,20 @@ def decoy() -> Iterable[Decoy]:
             # ...
         ```
     """
-    decoy = Decoy()
-    yield decoy
-    decoy.reset()
+    try:
+        decoy_hint = get_type_hints(request.function).get("decoy")
+        is_next = decoy_hint.__module__.startswith("decoy.next")
+
+    # purely defensive, probably won't ever raise
+    except Exception:  # pragma: no cover
+        is_next = False
+
+    if is_next:
+        from decoy.next import Decoy as DecoyNext
+
+        with DecoyNext.create() as decoy_next:
+            yield decoy_next
+    else:
+        decoy = Decoy()
+        yield decoy
+        decoy.reset()

decoy/spy.py

@@ -10,7 +10,7 @@ from typing import Any, ContextManager, Dict, Optional, Type, Union, cast, overl
 
 from .call_handler import CallHandler
 from .spy_core import SpyCore
-from .spy_events import SpyCall, SpyEvent, SpyPropAccess, PropAccessType
+from .spy_events import PropAccessType, SpyCall, SpyEvent, SpyPropAccess
 
 
 class BaseSpy(ContextManager[Any]):

{decoy-2.3.0.dist-info → decoy-2.5.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: decoy
-Version: 2.3.0
+Version: 2.5.0
 Summary: Opinionated mocking library for Python
 Author: Michael Cousins
 Author-email: Michael Cousins <michael@cousins.io>>
@@ -11,12 +11,13 @@ Classifier: Operating System :: OS Independent
 Classifier: Topic :: Software Development :: Testing
 Classifier: Topic :: Software Development :: Testing :: Mocking
 Classifier: Typing :: Typed
+Requires-Dist: typing-extensions>=4.10.0 ; python_full_version >= '3.10' and python_full_version < '3.13'
 Requires-Python: >=3.7
-Project-URL: Changelog, https://github.com/mcous/decoy/releases
-Project-URL: Documentation, https://michael.cousins.io/decoy/
 Project-URL: Homepage, https://michael.cousins.io/decoy/
-Project-URL: Issues, https://github.com/mcous/decoy/issues
+Project-URL: Documentation, https://michael.cousins.io/decoy/
 Project-URL: Repository, https://github.com/mcous/decoy
+Project-URL: Issues, https://github.com/mcous/decoy/issues
+Project-URL: Changelog, https://github.com/mcous/decoy/releases
 Description-Content-Type: text/markdown
 
 <div align="center">

decoy-2.5.0.dist-info/RECORD

@@ -0,0 +1,38 @@
+decoy/__init__.py,sha256=v3LUyAxuxFrO2M4Iw0VRX0IM6axFMxPmtgIbBemmwj8,11232
+decoy/call_handler.py,sha256=3MixA4pQs4k_2osq1ug19rXXMafzLECGSZLhltSMoo0,1767
+decoy/context_managers.py,sha256=oYsH99ZPmkaCcqjCrOWInueO5ympHm_ICWmbpFoQzqA,1287
+decoy/core.py,sha256=0YsQFnL4Kw_oDX7jRgOVLw9BGsnNdekymQCd1aq-4sQ,5830
+decoy/errors.py,sha256=3vadsAYM-xpoT_lpgiSJbemtjvomWslC9qLfn6FKQpo,2993
+decoy/matchers.py,sha256=Y55oOJww3mhuCsGn9wzUsVMVw0IzxBAMuaSYwtWgOm4,11630
+decoy/mypy/__init__.py,sha256=GdJCf-gXpYB4SBr-Rm8zCLZQxAUuLjPyUieIWgLmdwA,86
+decoy/mypy/plugin.py,sha256=nCfo4XpDxBRDsInDsvCe6h8t7-1OV0ZCJzIJqTsAU0I,1359
+decoy/next/__init__.py,sha256=RqW1Ry5FIw1nptiEqW9W15u1qCySn_ioTRRdu38GFEk,405
+decoy/next/_internal/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+decoy/next/_internal/compare.py,sha256=ab9YY3Y4vJhwfw-Kfg-SHGvsaCkZZbmadSI5cJ4j7x8,4173
+decoy/next/_internal/decoy.py,sha256=Mt8cgRVOofwmT0qP4eReUaTvSPFv765MeOCWP9VIR3M,6995
+decoy/next/_internal/errors.py,sha256=E3gUBWY6O-fWt77YJG67bUpOPkV8ktql8VrnZv7UE6Q,3026
+decoy/next/_internal/inspect.py,sha256=LPbm_3ub621KEr6KO1ODhPhbAyxgYnI8qVM2_jmayz8,6698
+decoy/next/_internal/matcher.py,sha256=UDgPgfBfBM7x67AxBFRrm545U634s6YGcc3QsDTCh2M,9141
+decoy/next/_internal/mock.py,sha256=CQrx3nvGFEJSs-r0VNFyHvojtrajFNIT4nQL3_jz9aM,6558
+decoy/next/_internal/state.py,sha256=kFZweF02aG9yGByPa0gtjrheHQRVdFMJwgi19vj5g7o,8247
+decoy/next/_internal/stringify.py,sha256=jQIi9ma7lO2m-Qc-eIth793KnBg7OTRuwr2fg-Q1h-A,2533
+decoy/next/_internal/values.py,sha256=W5yUnDgVNsTfM5qdvc2JZaZKMZ0yC8WES3WIDNZM_WY,1871
+decoy/next/_internal/verify.py,sha256=CEgb7Di-uJskObO2hIycvCgTLixVd4BYCZvHkTvWXRc,2203
+decoy/next/_internal/warnings.py,sha256=59T3hs3x2AcGp6jAUEEbq2pLgFMKO2QatE-1ep0Tlxg,1182
+decoy/next/_internal/when.py,sha256=WtV2U_LIvGbkYgo8CfocUxo3ZDjdlnbV8gtUp6lmBSU,4376
+decoy/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+decoy/pytest_plugin.py,sha256=y_5soxLEGJXo_EmPXcpw_axLcyStgVROkU-SDaVYCEM,1611
+decoy/spy.py,sha256=G3rEHAx2yWQaucOs8fQoB-Hap8vejPrzYcxBca6XbeQ,7581
+decoy/spy_core.py,sha256=b3PTgCkYnijT08ak_iRUKnA95FnmspSRmT8cs_YtjtM,7965
+decoy/spy_events.py,sha256=PFTfkgN7CVWfbVoSSUMSaCSxfRrUMd7U419iwQ1Xofg,2383
+decoy/spy_log.py,sha256=5JcjcH7zHrn12jp7xyrs_UWY7ATcWJkQ4v9oCR_Cclg,3929
+decoy/stringify.py,sha256=6JA2VA9eK-4AtwSSZPnMYT8ucW7EMpGdbTXokbOpgOg,2240
+decoy/stub_store.py,sha256=tVqKOW65NjotVdDhDDXpLfwagKHypMS4WMob71RYk1c,1744
+decoy/types.py,sha256=LXzky6T0RXvS53NoPpVgCi3KVV6KCyB6EvnBl0NaKug,404
+decoy/verifier.py,sha256=3ZVqaUJPjaNM9Nue3FK6Zzj15qWskX2CEQXoe_yjUEs,1586
+decoy/warning_checker.py,sha256=OOkcrr_I98Pzs3o9UUNgaihJDHwNiu1LlcEK9hi5ZFs,3577
+decoy/warnings.py,sha256=DLdX1ABPk6QvhJWt5s98uR7rCQFQdJJjSPPXRSX0nXA,3203
+decoy-2.5.0.dist-info/WHEEL,sha256=iHtWm8nRfs0VRdCYVXocAWFW8ppjHL-uTJkAdZJKOBM,80
+decoy-2.5.0.dist-info/entry_points.txt,sha256=En3V0KZt-83nTeWFpVB5KTotgxuUETePl7HesB81W64,40
+decoy-2.5.0.dist-info/METADATA,sha256=s_d-w2xrobK880yLspMDWUQ78cXP2QIJBcwetW-jX0Y,6980
+decoy-2.5.0.dist-info/RECORD,,

{decoy-2.3.0.dist-info → decoy-2.5.0.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: uv 0.9.22
+Generator: uv 0.9.30
 Root-Is-Purelib: true
-Tag: py3-none-any
+Tag: py3-none-any

decoy-2.3.0.dist-info/RECORD

@@ -1,24 +0,0 @@
-decoy/__init__.py,sha256=v3LUyAxuxFrO2M4Iw0VRX0IM6axFMxPmtgIbBemmwj8,11232
-decoy/call_handler.py,sha256=fuhWr9VAnh0FUvbfWw11fpdQ_GCUE3Hah-EXvdk3gGw,1512
-decoy/context_managers.py,sha256=oYsH99ZPmkaCcqjCrOWInueO5ympHm_ICWmbpFoQzqA,1287
-decoy/core.py,sha256=0YsQFnL4Kw_oDX7jRgOVLw9BGsnNdekymQCd1aq-4sQ,5830
-decoy/errors.py,sha256=mmUAOoQQyXhCLjMcf_3bHMz3PjU7bingIU6sC3hk2B4,3119
-decoy/matchers.py,sha256=2zO0F4tbxvLeRlm9BMIAQr_nxX5PBKA4CRJ5Hy5eukU,11724
-decoy/mypy/__init__.py,sha256=GdJCf-gXpYB4SBr-Rm8zCLZQxAUuLjPyUieIWgLmdwA,86
-decoy/mypy/plugin.py,sha256=nCfo4XpDxBRDsInDsvCe6h8t7-1OV0ZCJzIJqTsAU0I,1359
-decoy/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-decoy/pytest_plugin.py,sha256=muiWN6zwQPD-AaL4YH6usp-25P4EYjrROTx6wdLE9hM,853
-decoy/spy.py,sha256=cxlwDFxd2dcTb6vFJJGc0B3IuFCPJs2cgVMeB0qNXW4,7581
-decoy/spy_core.py,sha256=b3PTgCkYnijT08ak_iRUKnA95FnmspSRmT8cs_YtjtM,7965
-decoy/spy_events.py,sha256=PFTfkgN7CVWfbVoSSUMSaCSxfRrUMd7U419iwQ1Xofg,2383
-decoy/spy_log.py,sha256=5JcjcH7zHrn12jp7xyrs_UWY7ATcWJkQ4v9oCR_Cclg,3929
-decoy/stringify.py,sha256=6JA2VA9eK-4AtwSSZPnMYT8ucW7EMpGdbTXokbOpgOg,2240
-decoy/stub_store.py,sha256=tVqKOW65NjotVdDhDDXpLfwagKHypMS4WMob71RYk1c,1744
-decoy/types.py,sha256=LXzky6T0RXvS53NoPpVgCi3KVV6KCyB6EvnBl0NaKug,404
-decoy/verifier.py,sha256=3ZVqaUJPjaNM9Nue3FK6Zzj15qWskX2CEQXoe_yjUEs,1586
-decoy/warning_checker.py,sha256=OOkcrr_I98Pzs3o9UUNgaihJDHwNiu1LlcEK9hi5ZFs,3577
-decoy/warnings.py,sha256=DLdX1ABPk6QvhJWt5s98uR7rCQFQdJJjSPPXRSX0nXA,3203
-decoy-2.3.0.dist-info/WHEEL,sha256=KSLUh82mDPEPk0Bx0ScXlWL64bc8KmzIPNcpQZFV-6E,79
-decoy-2.3.0.dist-info/entry_points.txt,sha256=En3V0KZt-83nTeWFpVB5KTotgxuUETePl7HesB81W64,40
-decoy-2.3.0.dist-info/METADATA,sha256=3QTINwIfutMyuMNSY0m7TFMHA8Kt5Bl-ijDIqD1I7jA,6874
-decoy-2.3.0.dist-info/RECORD,,