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

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:
@@ -361,12 +362,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 +396,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 +416,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.
-
-    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.
+    """Match anything, capturing its value for further assertions.
 
-    !!! 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.2.2.dist-info → decoy-2.3.0.dist-info}/METADATA

@@ -1,18 +1,17 @@
 Metadata-Version: 2.4
 Name: decoy
-Version: 2.2.2
+Version: 2.3.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
+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/
@@ -30,7 +29,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 +43,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 +163,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.dist-info → decoy-2.3.0.dist-info}/RECORD

@@ -3,7 +3,7 @@ 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=TFa3ZLewXPxhuUy_YDktzJWMfdOgfz4jq2TQ9oa6hwk,11298
+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
@@ -18,8 +18,7 @@ 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.2.2.dist-info/METADATA,sha256=hKPZiHbc6RDbYOJ9iwIZ0wvRhrOn3UYxPSCAqABg9Tc,6855
-decoy-2.2.2.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
-decoy-2.2.2.dist-info/entry_points.txt,sha256=P2wF8zdthEM-3Yo32kxHDhZDjbW6AE489HPWqnvPLOU,38
-decoy-2.2.2.dist-info/licenses/LICENSE,sha256=Rxi19kHgqakAsJNG1jMuORmgKx9bI8Pcu_gtzFkhflQ,1078
-decoy-2.2.2.dist-info/RECORD,,
+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,,

decoy-2.3.0.dist-info/WHEEL

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

decoy-2.3.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[pytest11]
+decoy = decoy.pytest_plugin
+

decoy-2.2.2.dist-info/WHEEL

@@ -1,4 +0,0 @@
-Wheel-Version: 1.0
-Generator: poetry-core 2.2.1
-Root-Is-Purelib: true
-Tag: py3-none-any

decoy-2.2.2.dist-info/entry_points.txt

@@ -1,3 +0,0 @@
-[pytest11]
-decoy=decoy.pytest_plugin
-

decoy-2.2.2.dist-info/licenses/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2020-2023, Michael Cousins
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.