docs(v3): add v3 preview docs

Author: mcous

codebook.toml

@@ -0,0 +1,6 @@
+words = [
+    "matchers",
+    "mundo",
+    "stubbings",
+    "verden",
+]

docs/usage/matchers.md

@@ -51,7 +51,7 @@ When testing certain APIs, especially callback APIs, it can be helpful to captur
 
 For example, our test subject may register an event listener handler, and we want to test our subject's behavior when the event listener is triggered.
 
-```py
+```python
 import pytest
 from typing import cast, Optional
 from decoy import Decoy, matchers

docs/usage/verify.md

@@ -69,8 +69,8 @@ say_hello = decoy.mock(name="say_hello")
 
 say_hello("foobar")
 
-decoy.verify(matchers.StringMatching("^foo"), times=1)  # passes
-decoy.verify(matchers.StringMatching("^bar"), times=1)  # raises
+decoy.verify(say_hello(matchers.StringMatching("^foo")), times=1)  # passes
+decoy.verify(say_hello(matchers.StringMatching("^bar")), times=1)  # raises
 ```
 
 ## Verifying with async/await

docs/v3/about.md

@@ -0,0 +1,54 @@
+# Decoy v3 Preview
+
+The next major version of Decoy is a ground-up rebuild of the library. In the years since Decoy was first written, the Python typing system has advanced, especially when it comes to typing functions. These advancements, especially the addition of [`ParamSpec`][paramspec], unblocked a much simpler API (as well as internal implementation) for Decoy.
+
+In order to ease the migration to the new API, the v3 API has been added as a preview to the v2 release (starting with `v2.4.0`) as `decoy.next`.
+
+```diff
+- from decoy import Decoy
++ from decoy.next import Decoy
+```
+
+!!! warning
+
+    `decoy.next` is a **preview** and not subject to semver.
+    No major changes are anticipated, but cannot be guaranteed until
+    Decoy v3 is released.
+
+## Setup
+
+In order to use the v3 preview, you must be using:
+
+- `decoy >= 2.4.0`
+- `python >= 3.10`
+
+Then, start trying out the new API!
+
+```diff
+- from decoy import Decoy
++ from decoy.next import Decoy
+
+
++ @pytest.fixture()
++ def decoy() -> collections.abc.Iterator[Decoy]:
++     """Create a Decoy v3 preview instance for testing."""
++     with Decoy.create() as decoy:
++         yield decoy
+
+
+  def test_when(decoy: Decoy) -> None:
+      mock = decoy.mock(cls=SomeClass)
+-     decoy.when(mock.foo("hello")).then_return("world")
++     decoy.when(mock.foo).called_with("hello").then_return("world")
+
+
+   def test_verify(decoy: Decoy) -> None:
+      mock = decoy.mock(cls=SomeClass)
+      mock.foo("hello")
+-     decoy.verify(mock.foo("hello"))
++     decoy.verify(mock.foo).called_with("hello")
+```
+
+See the [migration guide](./migration.md) for more details.
+
+[paramspec]: https://docs.python.org/3/library/typing.html#typing.ParamSpec

docs/v3/api.md

@@ -0,0 +1,9 @@
+# API Reference
+
+!!! warning
+
+    `decoy.next` is a **preview** and not subject to semver.
+    No major changes are anticipated, but cannot be guaranteed until
+    Decoy v3 is released.
+
+::: decoy.next

docs/v3/attributes.md

@@ -0,0 +1,126 @@
+# Mock attributes
+
+Python [property attributes][] provide an interface for creating read-only properties and properties with getters, setters, and deleters. You can use Decoy to stub these properties.
+
+[property attributes]: https://docs.python.org/3/library/functions.html#property
+
+## Default behavior
+
+Unlike mock method calls - which have a default return value of `None` - Decoy's default return value for attribute access is **another mock**. So you don't need to configure anything explicitly if you need a `@property` getter to return another mock; Decoy will do this for you.
+
+```python
+class Child:
+    ...
+
+class Parent:
+    @property
+    def child(self) -> Child:
+        ...
+
+mock_parent = decoy.mock(cls=Parent)
+
+assert isinstance(mock_parent, Dependency)
+assert isinstance(mock_parent.child, Child)
+```
+
+You may also manually set any mock attribute to "opt out" of Decoy for a given attribute. To opt back into Decoy, delete the attribute.
+
+```python
+dep = decoy.mock(cls=Parent)
+
+dep.child = "don't worry about it"
+assert dep.child == "don't worry about it"
+
+del dep.child
+assert isinstance(mock_parent.child, Child)
+```
+
+## Stub property access
+
+### Stub a getter
+
+If you would like to stub a return value for a property that is different than the default behavior, simply use [`When.get`][decoy.next.When.get].
+
+```python
+dependency = decoy.mock(name="dependency")
+
+decoy.when(dependency.some_property).get().then_return(42)
+
+assert dep.some_property == 42
+```
+
+You can also configure any other behavior, like raising an error.
+
+```python
+dependency = decoy.mock(name="dependency")
+
+decoy
+    .when(dependency.some_property)
+    .get()
+    .then_raise(RuntimeError("oh no"))
+
+with pytest.raises(RuntimeError, match="oh no"):
+    dependency.some_property
+```
+
+### Stub a setter or deleter
+
+While you cannot stub a return value for a getter or setter, you can stub a `raise` or a side effect with [`When.set`][decoy.next.When.set] and [`When.delete`][decoy.next.When.delete].
+
+```python
+dependency = decoy.mock(name="dependency")
+
+decoy
+    .when(dependency.some_property)
+    .set(42)
+    .then_raise(RuntimeError("oh no"))
+
+decoy
+    .when(dependency.some_property)
+    .delete()
+    .then_raise(RuntimeError("what a disaster"))
+
+with pytest.raises(RuntimeError, match="oh no"):
+    dependency.some_property = 42
+
+with pytest.raises(RuntimeError, match="what a disaster"):
+    del dependency.some_property
+```
+
+!!! tip
+
+    You cannot use [`then_return`][decoy.Stub.then_return] with attribute setters and deleters, because set and delete expressions do not return a value in Python.
+
+## Verify property access
+
+You can verify calls to property setters and deleters with [`Verify.set`][decoy.next.Verify.set] and [`Verify.delete`][decoy.next.Verify.delete].
+
+!!! tip
+
+    Use this feature sparingly! If you're designing a dependency that triggers a side-effect, consider using a regular method, instead.
+
+    Mocking and verifying property setters and deleters is most useful for testing code that needs to interact with older or legacy dependencies that would be prohibitively expensive to redesign.
+
+### Verify a setter
+
+Use [`Verify.set`][decoy.next.Verify.set] to check that an attribute was set.
+
+```python
+dependency = decoy.mock(name="dependency")
+
+dependency.some_property = 42
+
+decoy.verify(dependency.some_property).set(42)
+```
+
+### Verify a deleter
+
+Use [`Verify.delete`][decoy.next.Verify.delete] to check that an attribute was deleted.
+
+```python
+dependency = decoy.mock(name="dependency")
+
+del dependency.some_property
+
+decoy.verify(dependency.some_property).delete)
+```

docs/v3/context-managers.md

@@ -0,0 +1,76 @@
+# Mock context managers
+
+In Python, `with` statement [context managers][] provide an interface to execute code inside a given "runtime context." This context can define consistent, failsafe setup and teardown behavior. For example, Python's built-in file objects provide a context manager interface to ensure the underlying file resource is opened and closed cleanly, without the caller having to explicitly deal with it:
+
+```python
+with open("hello-world.txt", "r") as f:
+    contents = f.read()
+```
+
+You can use Decoy to mock out your dependencies that provide a context manager interface.
+
+[context managers]: https://docs.python.org/3/reference/datamodel.html#context-managers
+
+## Generator-based context managers
+
+Using the [contextlib][] module, you can [decorate a generator function][] or method to turn its yielded value into a context manager. To mock a generator function context manager, use [`Stub.then_enter_with`][decoy.next.Stub.then_enter_with].
+
+```python
+@contextlib.contextmanager
+def open_config(path: str) -> collections.abc.Iterator[bool]:
+    ...
+
+
+def test_generator_context_manager(decoy: Decoy) -> None:
+    mock_open_config = decoy.mock(func=open_config)
+
+    decoy
+        .when(mock_open_config)
+        .called_with("some_flag")
+        .then_enter_with(True)
+
+    with mock_open_config("some_flag") as result:
+        assert result is True
+```
+
+[contextlib]: https://docs.python.org/3/library/contextlib.html
+[decorate a generator function]: https://docs.python.org/3/library/contextlib.html#contextlib.contextmanager
+
+## Class-based context managers
+
+You can stub out a context manager's `__enter__` and `__exit__` method like any other method.
+
+```python
+def test_context_manager(decoy: Decoy) -> None:
+    subject = decoy.mock(name="cm")
+
+    decoy.when(subject.__enter__).called_with().then_return("hello world")
+
+    with subject as result:
+        assert result == "hello world"
+
+    decoy.verify(subject.__exit__).called_with(None, None, None)
+```
+
+This also works with asynchronous `__aenter__` and `__aexit__`
+
+## Context manager state
+
+You can also configure stubs and verifications to only match calls made while a context manager mock is entered using the `is_entered` option to `called_with`.
+
+| `is_entered` | Matching behavior                                           |
+| ------------ | ----------------------------------------------------------- |
+| `True`       | Only matches calls made between `__enter__` and `__exit__`  |
+| `False`      | Only matches calls made if context manager is _not_ entered |
+| `None`       | Match the call regardless of context manager entry state    |
+
+```python
+decoy
+    .when(subject.read, is_entered=True)
+    .called_with("some_flag")
+    .then_return(True)
+
+decoy
+    .verify(subject.write, is_entered=True)
+    .called_with("some_flag", "new_value")
+```

docs/v3/create.md

@@ -0,0 +1,56 @@
+# Create a mock
+
+Decoy mocks are flexible objects that can be used in place of a class instance or a callable object, like a function. Mocks are created using the [`Decoy.mock`][decoy.next.Decoy.mock] method.
+
+## Default behaviors
+
+Decoy mock objects are flexible, callable proxy objects that simply record interactions made with the object. Accessing any property of the mock will return a child mock, and calling the mock itself or any "method" of the mock will return `None`.
+
+```python
+my_mock = decoy.mock(name="my_mock")
+
+assert my_mock() is None
+assert my_mock.some_method("hello world") is None
+assert my_mock.some_property.some_method("hey") is None
+```
+
+You can configure a mock's behaviors using [decoy.when](./when.md). You can make assertions about how a mock was called using [decoy.verify](./verify.md).
+
+## Mock a class
+
+To mock a class instance, pass the `cls` argument to `decoy.mock`. Decoy will inspect type annotations and method signatures to set a name for use in assertion messages, configure methods as synchronous or asynchronous, and understand function keyword arguments.
+
+```python
+some_dependency = decoy.mock(cls=SomeDependency)
+```
+
+To type checkers, the mock will appear to have the exact same type as the `cls` argument. The mock will also pass `isinstance` checks.
+
+## Mock a function
+
+To mock a function, pass the `func` argument to `decoy.mock`. Decoy will inspect `func` to set a name for use in assertion messages, configure the mock as synchronous or asynchronous, and understand function keyword arguments.
+
+```python
+mock_function = decoy.mock(func=some_function)
+```
+
+To type checkers, the mock will appear to have the exact same type as the `func` argument. The function mock will pass `inspect.signature` checks.
+
+## Creating a mock without a spec
+
+You can call `decoy.mock` without using `cls` or `func`. A spec-less mock is useful for dependency interfaces like callback functions.
+
+When creating a mock without a spec, you must use the `name` argument to give the mock a name to use in assertion messages. You must use the `is_async` argument if the created mock will be used as an asynchronous callable.
+
+```python
+callback = decoy.mock(name="callback")
+async_callback = decoy.mock(name="async_callback", is_async=True)
+```
+
+## Mock an async function or method
+
+If you pass Decoy a `cls` or `func` with asynchronous methods or functions, Decoy will automatically create asynchronous mocks. When creating mocks without `cls` or `func`, you can use the `is_async` option to create an asynchronous mock manually:
+
+```python
+async_mock = decoy.mock(name="async_mock", is_async=True)
+```