decoy 2.2.2__py3-none-any.whl → 2.4.0__py3-none-any.whl

decoy/call_handler.py

@@ -2,9 +2,9 @@
 
 from typing import Any, NamedTuple, Optional
 
-from .spy_log import SpyLog
 from .context_managers import ContextWrapper
-from .spy_events import SpyCall, SpyEvent
+from .spy_events import PropAccessType, SpyCall, SpyEvent, SpyPropAccess
+from .spy_log import SpyLog
 from .stub_store import MISSING, StubStore
 
 
@@ -41,6 +41,11 @@ class CallHandler:
                     *call.payload.args,
                     **call.payload.kwargs,
                 )
+            elif (
+                isinstance(call.payload, SpyPropAccess)
+                and call.payload.access_type == PropAccessType.SET
+            ):
+                return_value = behavior.action(call.payload.value)
             else:
                 return_value = behavior.action()
 

decoy/errors.py

@@ -12,12 +12,7 @@ from .stringify import count, stringify_error_message
 
 
 class MockNameRequiredError(ValueError):
-    """An error raised if a name is not provided for a mock.
-
-    See the [MockNameRequiredError guide][] for more details.
-
-    [MockNameRequiredError guide]: usage/errors-and-warnings.md#mocknamerequirederror
-    """
+    """A name was not provided for a mock."""
 
     @classmethod
     def create(cls) -> "MockNameRequiredError":
@@ -25,17 +20,17 @@ class MockNameRequiredError(ValueError):
         return cls("Mocks without `cls` or `func` require a `name`.")
 
 
+class MockSpecInvalidError(TypeError):
+    """A value passed as a mock spec is not valid."""
+
+
 class MissingRehearsalError(ValueError):
-    """An error raised when a Decoy method is called without rehearsal(s).
+    """A Decoy method was called without rehearsal(s).
 
     This error is raised if you use [`when`][decoy.Decoy.when],
     [`verify`][decoy.Decoy.verify], or [`prop`][decoy.Decoy.prop] incorrectly
     in your tests. When using async/await, this error can be triggered if you
     forget to include `await` with your rehearsal.
-
-    See the [MissingRehearsalError guide][] for more details.
-
-    [MissingRehearsalError guide]: usage/errors-and-warnings.md#missingrehearsalerror
     """
 
     @classmethod
@@ -44,29 +39,28 @@ class MissingRehearsalError(ValueError):
         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.
+    """An asynchronous function was passed to a synchronous mock.
 
     This error is raised if you pass an `async def` function
-    to a synchronous stub's `then_do` method.
-    See the [MockNotAsyncError guide][] for more details.
-
-    [MockNotAsyncError guide]: usage/errors-and-warnings.md#mocknotasyncerror
+    to a synchronous stub's [`then_do`][decoy.Stub.then_do] method.
     """
 
 
-class VerifyError(AssertionError):
-    """An error raised when actual calls do not match rehearsals given to `verify`.
+class SignatureMismatchError(TypeError):
+    """Arguments did not match the signature of the mock."""
 
-    See [spying with verify][] for more details.
 
-    [spying with verify]: usage/verify.md
-
-    Attributes:
-        rehearsals: Rehearsals that were being verified.
-        calls: Actual calls to the mock(s).
-        times: The expected number of calls to the mock, if any.
-    """
+class VerifyError(AssertionError):
+    """A [`Decoy.verify`][decoy.Decoy.verify] assertion failed."""
 
     rehearsals: Sequence[VerifyRehearsal]
     calls: Sequence[SpyEvent]
@@ -100,3 +94,11 @@ class VerifyError(AssertionError):
         result.times = times
 
         return result
+
+
+class VerifyOrderError(VerifyError):
+    """A [`Decoy.verify_order`][decoy.next.Decoy.verify_order] assertion failed."""
+
+
+class NoMatcherValueCapturedError(ValueError):
+    """An error raised if a [decoy.next.Matcher][] has not captured any matching values."""

decoy/matchers.py

@@ -28,16 +28,17 @@ See the [matchers guide][] for more details.
 """
 
 from re import compile as compile_re
-from typing import Any, List, Mapping, Optional, Pattern, Type, TypeVar, cast
-
-__all__ = [
-    "Anything",
-    "Captor",
-    "ErrorMatching",
-    "IsA",
-    "IsNot",
-    "StringMatching",
-]
+from typing import (
+    Any,
+    Generic,
+    List,
+    Mapping,
+    Optional,
+    Pattern,
+    Type,
+    TypeVar,
+    cast,
+)
 
 
 class _AnythingOrNone:
@@ -177,14 +178,11 @@ class _HasAttributes:
 
     def __eq__(self, target: object) -> bool:
         """Return true if target matches all given attributes."""
-        is_match = True
         for attr_name, value in self._attributes.items():
-            if is_match:
-                is_match = (
-                    hasattr(target, attr_name) and getattr(target, attr_name) == value
-                )
+            if not hasattr(target, attr_name) or getattr(target, attr_name) != value:
+                return False
 
-        return is_match
+        return True
 
     def __repr__(self) -> str:
         """Return a string representation of the matcher."""
@@ -218,16 +216,14 @@ class _DictMatching:
 
     def __eq__(self, target: object) -> bool:
         """Return true if target matches all given keys/values."""
-        is_match = True
-
         for key, value in self._values.items():
-            if is_match:
-                try:
-                    is_match = key in target and target[key] == value  # type: ignore[index,operator]
-                except TypeError:
-                    is_match = False
+            try:
+                if key not in target or target[key] != value:  # type: ignore[index,operator]
+                    return False
+            except TypeError:
+                return False
 
-        return is_match
+        return True
 
     def __repr__(self) -> str:
         """Return a string representation of the matcher."""
@@ -318,10 +314,12 @@ def StringMatching(match: str) -> str:
 class _ErrorMatching:
     _error_type: Type[BaseException]
     _string_matcher: Optional[_StringMatching]
+    _match: Optional[str]
 
     def __init__(self, error: Type[BaseException], match: Optional[str] = None) -> None:
         """Initialize with the Exception type and optional message matcher."""
         self._error_type = error
+        self._match = match
         self._string_matcher = _StringMatching(match) if match is not None else None
 
     def __eq__(self, target: object) -> bool:
@@ -337,9 +335,7 @@ class _ErrorMatching:
 
     def __repr__(self) -> str:
         """Return a string representation of the matcher."""
-        return (
-            f"<ErrorMatching {self._error_type.__name__} match={self._string_matcher}>"
-        )
+        return f"<ErrorMatching {self._error_type.__name__} match={self._match!r}>"
 
 
 ErrorT = TypeVar("ErrorT", bound=BaseException)
@@ -361,12 +357,32 @@ def ErrorMatching(error: Type[ErrorT], match: Optional[str] = None) -> ErrorT:
     return cast(ErrorT, _ErrorMatching(error, match))
 
 
-class _Captor:
+CapturedT = TypeVar("CapturedT")
+
+
+class ValueCaptor(Generic[CapturedT]):
+    """Match anything, capturing its value for further assertions.
+
+    Compare against the `matcher` property to capture a value.
+    The last captured value is available via `captor.value`,
+    while all captured values are stored in `captor.values`.
+
+    !!! example
+        ```python
+        captor = ValueCaptor[str]()
+        assert "foobar" == captor.matcher
+        print(captor.value)  # "foobar"
+        print(captor.values)  # ["foobar"]
+        ```
+    """
+
+    _values: List[object]
+
     def __init__(self) -> None:
-        self._values: List[Any] = []
+        self._values = []
 
     def __eq__(self, target: object) -> bool:
-        """Capture compared value, always returning True."""
+        """Captors are always "equal" to a given target."""
         self._values.append(target)
         return True
 
@@ -375,11 +391,19 @@ class _Captor:
         return "<Captor>"
 
     @property
-    def value(self) -> Any:
-        """Get the captured value.
+    def matcher(self) -> CapturedT:
+        """Match anything, capturing its value.
+
+        This method exists as a type-checking convenience.
+        """
+        return cast(CapturedT, self)
+
+    @property
+    def value(self) -> object:
+        """The latest captured value.
 
         Raises:
-            AssertionError: if no value was captured.
+            AssertionError: no value has been captured.
         """
         if len(self._values) == 0:
             raise AssertionError("No value captured by captor.")
@@ -387,24 +411,15 @@ class _Captor:
         return self._values[-1]
 
     @property
-    def values(self) -> List[Any]:
-        """Get all captured values."""
+    def values(self) -> List[object]:
+        """All captured values."""
         return self._values
 
 
 def Captor() -> Any:
-    """Match anything, capturing its value.
+    """Match anything, capturing its value for further assertions.
 
-    The last captured value will be set to `captor.value`. All captured
-    values will be placed in the `captor.values` list, which can be
-    helpful if a captor needs to be triggered multiple times.
-
-    !!! example
-        ```python
-        captor = Captor()
-        assert "foobar" == captor
-        print(captor.value)  # "foobar"
-        print(captor.values)  # ["foobar"]
-        ```
+    !!! tip
+        Prefer [decoy.matchers.ValueCaptor][], which has better type annotations.
     """
-    return _Captor()
+    return ValueCaptor()

decoy/next/__init__.py

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

decoy/next/_internal/compare.py

@@ -0,0 +1,138 @@
+from .values import (
+    AttributeEvent,
+    AttributeEventType,
+    BehaviorEntry,
+    CallEvent,
+    Event,
+    EventEntry,
+    EventMatcher,
+    EventState,
+    MockInfo,
+    VerificationEntry,
+)
+
+
+def is_event_from_mock(event_entry: EventEntry, mock: MockInfo) -> bool:
+    return mock.id == event_entry.mock.id
+
+
+def is_verifiable_mock_event(event_entry: EventEntry, mock: MockInfo) -> bool:
+    return is_event_from_mock(event_entry, mock) and (
+        isinstance(event_entry.event, CallEvent)
+        or event_entry.event.type != AttributeEventType.GET
+    )
+
+
+def is_matching_behavior(
+    event_entry: EventEntry,
+    behavior_entry: BehaviorEntry,
+) -> bool:
+    return is_event_from_mock(
+        event_entry,
+        behavior_entry.mock,
+    ) and is_matching_event(
+        event_entry,
+        behavior_entry.matcher,
+    )
+
+
+def is_matching_event(event_entry: EventEntry, matcher: EventMatcher) -> bool:
+    event_matches = _match_event(event_entry.event, matcher)
+    state_matches = _match_state(event_entry.state, matcher)
+
+    return event_matches and state_matches
+
+
+def is_matching_count(usage_count: int, matcher: EventMatcher) -> bool:
+    return matcher.options.times is None or usage_count < matcher.options.times
+
+
+def is_successful_verify(verification: VerificationEntry) -> bool:
+    if verification.matcher.options.times is not None:
+        return len(verification.matching_events) == verification.matcher.options.times
+
+    return len(verification.matching_events) > 0
+
+
+def is_successful_verify_order(verifications: list[VerificationEntry]) -> bool:
+    matching_events: list[tuple[EventEntry, VerificationEntry]] = []
+    verification_index = 0
+    event_index = 0
+
+    for verification in verifications:
+        for matching_event in verification.matching_events:
+            matching_events.append((matching_event, verification))
+
+    matching_events.sort(key=lambda e: e[0].order)
+
+    while event_index < len(matching_events) and verification_index < len(
+        verifications
+    ):
+        _, event_verification = matching_events[event_index]
+        expected_verification = verifications[verification_index]
+        expected_times = expected_verification.matcher.options.times
+        remaining_events = len(matching_events) - event_index
+
+        if event_verification is expected_verification:
+            verification_index += 1
+
+            if expected_times is None or expected_times == 1:
+                event_index += 1
+            else:
+                for times_index in range(1, expected_times):
+                    _, later_verification = matching_events[event_index + times_index]
+                    if later_verification is not expected_verification:
+                        return False
+
+                event_index += expected_times
+
+        elif remaining_events >= len(verifications) and verification_index > 0:
+            verification_index = 0
+        else:
+            return False
+
+    return True
+
+
+def is_redundant_verify(
+    verification: VerificationEntry,
+    behaviors: list[BehaviorEntry],
+) -> bool:
+    return any(
+        behavior
+        for behavior in behaviors
+        if verification.mock.id == behavior.mock.id
+        and verification.matcher.options == behavior.matcher.options
+        and _match_event(verification.matcher.event, behavior.matcher)
+    )
+
+
+def _match_event(event: Event, matcher: EventMatcher) -> bool:
+    if (
+        matcher.options.ignore_extra_args is False
+        or isinstance(event, AttributeEvent)
+        or isinstance(matcher.event, AttributeEvent)
+    ):
+        return event == matcher.event
+
+    try:
+        args_match = all(
+            value == event.args[i] for i, value in enumerate(matcher.event.args)
+        )
+        kwargs_match = all(
+            value == event.kwargs[key] for key, value in matcher.event.kwargs.items()
+        )
+
+        return args_match and kwargs_match
+
+    except (IndexError, KeyError):
+        pass
+
+    return False
+
+
+def _match_state(event_state: EventState, matcher: EventMatcher) -> bool:
+    return (
+        matcher.options.is_entered is None
+        or event_state.is_entered == matcher.options.is_entered
+    )

decoy/next/_internal/decoy.py

@@ -0,0 +1,231 @@
+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](./create.md) for more details.
+
+        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 [`when` 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.
+
+        Raises:
+            NotAMockError: `mock` is invalid.
+
+        !!! 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:
+            mock_info = self._state.peek_last_attribute_mock(mock)
+
+        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. See the [`verify` 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.
+            NotAMockError: `mock` is invalid.
+
+        !!! 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()