decoy 2.2.2__tar.gz → 2.4.0__tar.gz

{decoy-2.2.2 → decoy-2.4.0}/PKG-INFO

@@ -1,23 +1,23 @@
 Metadata-Version: 2.4
 Name: decoy
-Version: 2.2.2
+Version: 2.4.0
 Summary: Opinionated mocking library for Python
-License-Expression: MIT
-License-File: LICENSE
 Author: Michael Cousins
-Author-email: michael@cousins.io>
-Requires-Python: >=3.7
+Author-email: Michael Cousins <michael@cousins.io>>
+License-Expression: MIT
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
 Classifier: Operating System :: OS Independent
 Classifier: Topic :: Software Development :: Testing
 Classifier: Topic :: Software Development :: Testing :: Mocking
 Classifier: Typing :: Typed
-Project-URL: Changelog, https://github.com/mcous/decoy/releases
-Project-URL: Documentation, https://michael.cousins.io/decoy/
+Requires-Dist: typing-extensions>=4.10.0 ; python_full_version >= '3.10' and python_full_version < '3.13'
+Requires-Python: >=3.7
 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">
@@ -30,7 +30,7 @@ Description-Content-Type: text/markdown
         <a title="Code Coverage" href="https://app.codecov.io/gh/mcous/decoy/"><img src="https://img.shields.io/codecov/c/github/mcous/decoy?style=flat-square"></a>
         <a title="License" href="https://github.com/mcous/decoy/blob/main/LICENSE"><img src="https://img.shields.io/github/license/mcous/decoy?style=flat-square"></a>
         <a title="PyPI Version"href="https://pypi.org/project/decoy/"><img src="https://img.shields.io/pypi/v/decoy?style=flat-square"></a>
-        <a title="Supported Python Versions" href="https://pypi.org/project/decoy/"><img src="https://img.shields.io/pypi/pyversions/decoy?style=flat-square"></a>
+        <a title="Supported Python Versions" href="https://pypi.org/project/decoy/"><img src="https://img.shields.io/python/required-version-toml?style=flat-square&tomlFilePath=https%3A%2F%2Fraw.githubusercontent.com%2Fmcous%2Fdecoy%2Fmain%2Fpyproject.toml"></a>
     </p>
     <p>
         <a href="https://michael.cousins.io/decoy/" class="decoy-hidden">Usage guide and documentation</a>
@@ -44,14 +44,7 @@ Decoy mocks are **async/await** and **type-checking** friendly. Decoy is heavily
 ## Install
 
 ```bash
-# pip
 pip install decoy
-
-# poetry
-poetry add --dev decoy
-
-# pipenv
-pipenv install --dev decoy
 ```
 
 ## Setup
@@ -171,4 +164,3 @@ See [spying with verify][] for more details.
 [creating mocks]: https://michael.cousins.io/decoy/usage/create/
 [stubbing with when]: https://michael.cousins.io/decoy/usage/when/
 [spying with verify]: https://michael.cousins.io/decoy/usage/verify/
-

{decoy-2.2.2 → decoy-2.4.0}/README.md

@@ -8,7 +8,7 @@
         <a title="Code Coverage" href="https://app.codecov.io/gh/mcous/decoy/"><img src="https://img.shields.io/codecov/c/github/mcous/decoy?style=flat-square"></a>
         <a title="License" href="https://github.com/mcous/decoy/blob/main/LICENSE"><img src="https://img.shields.io/github/license/mcous/decoy?style=flat-square"></a>
         <a title="PyPI Version"href="https://pypi.org/project/decoy/"><img src="https://img.shields.io/pypi/v/decoy?style=flat-square"></a>
-        <a title="Supported Python Versions" href="https://pypi.org/project/decoy/"><img src="https://img.shields.io/pypi/pyversions/decoy?style=flat-square"></a>
+        <a title="Supported Python Versions" href="https://pypi.org/project/decoy/"><img src="https://img.shields.io/python/required-version-toml?style=flat-square&tomlFilePath=https%3A%2F%2Fraw.githubusercontent.com%2Fmcous%2Fdecoy%2Fmain%2Fpyproject.toml"></a>
     </p>
     <p>
         <a href="https://michael.cousins.io/decoy/" class="decoy-hidden">Usage guide and documentation</a>
@@ -22,14 +22,7 @@ Decoy mocks are **async/await** and **type-checking** friendly. Decoy is heavily
 ## Install
 
 ```bash
-# pip
 pip install decoy
-
-# poetry
-poetry add --dev decoy
-
-# pipenv
-pipenv install --dev decoy
 ```
 
 ## Setup

{decoy-2.2.2 → decoy-2.4.0}/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-2.2.2 → decoy-2.4.0}/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-2.2.2 → decoy-2.4.0}/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-2.4.0/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-2.4.0/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
+    )