feat: add mock method to replace create_decoy, create_decoy_func (#37)

Author: mcous

README.md

@@ -83,11 +83,11 @@ def test_add_todo(decoy: Decoy) -> None:
 
 ### Create a mock
 
-Use `decoy.create_decoy` to create a mock based on some specification. From there, inject the mock into your test subject.
+Use `decoy.mock` to create a mock based on some specification. From there, inject the mock into your test subject.
 
 ```python
 def test_add_todo(decoy: Decoy) -> None:
-    todo_store = decoy.create_decoy(spec=TodoStore)
+    todo_store = decoy.mock(cls=TodoStore)
     subject = TodoAPI(store=todo_store)
     ...
 ```
@@ -101,7 +101,7 @@ Use `decoy.when` to configure your mock's behaviors. For example, you can set th
 ```python
 def test_add_todo(decoy: Decoy) -> None:
     """Adding a todo should create a TodoItem in the TodoStore."""
-    todo_store = decoy.create_decoy(spec=TodoStore)
+    todo_store = decoy.mock(cls=TodoStore)
     subject = TodoAPI(store=todo_store)
 
     decoy.when(
@@ -123,7 +123,7 @@ Use `decoy.verify` to assert that a mock was called in a certain way. This is be
 ```python
 def test_remove_todo(decoy: Decoy) -> None:
     """Removing a todo should remove the item from the TodoStore."""
-    todo_store = decoy.create_decoy(spec=TodoStore)
+    todo_store = decoy.mock(cls=TodoStore)
     subject = TodoAPI(store=todo_store)
 
     subject.remove("abc123")

decoy/__init__.py

@@ -1,6 +1,6 @@
 """Decoy stubbing and spying library."""
 from __future__ import annotations
-from typing import cast, Any, Callable, Generic, Optional
+from typing import Any, Callable, Generic, Optional, cast, overload
 
 from . import matchers, errors, warnings
 from .core import DecoyCore, StubCore
@@ -18,32 +18,58 @@ def __init__(self) -> None:
         """
         self._core = DecoyCore()
 
-    def create_decoy(
+    @overload
+    def mock(self, *, cls: Callable[..., ClassT]) -> ClassT:
+        ...
+
+    @overload
+    def mock(self, *, func: FuncT) -> FuncT:
+        ...
+
+    @overload
+    def mock(self, *, is_async: bool = False) -> Any:
+        ...
+
+    def mock(
         self,
-        spec: Callable[..., ClassT],
         *,
+        cls: Optional[Any] = None,
+        func: Optional[Any] = None,
         is_async: bool = False,
-    ) -> ClassT:
-        """Create a class decoy for `spec`.
+    ) -> Any:
+        """Create a mock.
 
-        See [decoy creation usage guide](../usage/create) for more details.
+        See the [mock creation guide](../usage/create) for more details.
 
         Arguments:
-            spec: A class definition that the decoy should mirror.
-            is_async: Force the returned spy to be asynchronous. In most cases,
-                this argument is unnecessary, since the Spy will use `spec` to
-                determine if a method should be asynchronous.
+            cls: A class definition that the mock should imitate.
+            func: A function definition the mock should imitate.
+            is_async: Force the returned spy to be asynchronous. This argument
+                only applies if you don't use `cls` nor `func`.
 
         Returns:
-            A spy typecast as an instance of `spec`.
+            A spy typecast as the object it's imitating, if any.
 
         Example:
             ```python
             def test_get_something(decoy: Decoy):
-                db = decoy.create_decoy(spec=Database)
+                db = decoy.mock(cls=Database)
                 # ...
             ```
+        """
+        spec = cls or func
+        return self._core.mock(spec=spec, is_async=is_async)
+
+    def create_decoy(
+        self,
+        spec: Callable[..., ClassT],
+        *,
+        is_async: bool = False,
+    ) -> ClassT:
+        """Create a class mock for `spec`.
 
+        !!! warning "Deprecated since v1.6.0"
+            Use [decoy.Decoy.mock][] with the `cls` parameter, instead.
         """
         spy = self._core.mock(spec=spec, is_async=is_async)
         return cast(ClassT, spy)
@@ -54,25 +80,10 @@ def create_decoy_func(
         *,
         is_async: bool = False,
     ) -> FuncT:
-        """Create a function decoy for `spec`.
-
-        See [decoy creation usage guide](../usage/create) for more details.
-
-        Arguments:
-            spec: A function that the decoy should mirror.
-            is_async: Force the returned spy to be asynchronous. In most cases,
-                this argument is unnecessary, since the Spy will use `spec` to
-                determine if the function should be asynchronous.
-
-        Returns:
-            A spy typecast as `spec` function.
+        """Create a function mock for `spec`.
 
-        Example:
-            ```python
-            def test_create_something(decoy: Decoy):
-                gen_id = decoy.create_decoy_func(spec=generate_unique_id)
-                # ...
-            ```
+        !!! warning "Deprecated since v1.6.0"
+            Use [decoy.Decoy.mock][] with the `func` parameter, instead.
         """
         spy = self._core.mock(spec=spec, is_async=is_async)
         return cast(FuncT, spy)
@@ -90,7 +101,7 @@ def when(self, _rehearsal_result: ReturnT) -> Stub[ReturnT]:
 
         Example:
             ```python
-            db = decoy.create_decoy(spec=Database)
+            db = decoy.mock(cls=Database)
             decoy.when(db.exists("some-id")).then_return(True)
             ```
 
@@ -119,7 +130,7 @@ def verify(self, *_rehearsal_results: Any, times: Optional[int] = None) -> None:
         Example:
             ```python
             def test_create_something(decoy: Decoy):
-                gen_id = decoy.create_decoy_func(spec=generate_unique_id)
+                gen_id = decoy.mock(func=generate_unique_id)
 
                 # ...
 

docs/usage/create.md

@@ -5,25 +5,36 @@ Decoy can create two kinds of mocks:
 -   Mocks of a class instance
 -   Mocks of a function
 
-## Mocking a class
+Mocks are created using the [decoy.Decoy.mock][] method.
 
-To create a mock class instance, use [decoy.Decoy.create_decoy][]. Decoy will inspect type annotations and method signatures to automatically configure methods as synchronous or asynchronous. Decoy mocks are automatically deep.
+## Mocking a class
 
-To type checkers, the mock will appear to have the exact same type as the `spec` argument. The mock will also pass `isinstance` checks.
+To mock a class instance, pass the `cls` argument to `decoy.mock`. Decoy will inspect type annotations and method signatures to automatically configure methods as synchronous or asynchronous. Decoy mocks are automatically deep.
 
 ```python
 def test_my_thing(decoy: Decoy) -> None:
-    some_dependency = decoy.create_decoy(spec=SomeDependency)
+    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.
+
 ## Mocking a function
 
-To create a mock function, use [decoy.Decoy.create_decoy_func][]. Decoy can inspect a `spec` function signature to automatically configure the function as synchronous or asynchronous. Otherwise, the `is_async` argument can force the mock to be asynchronous.
+To mock a function, pass the `func` argument to `decoy.mock`. Decoy will inspect `func` to automatically configure the function as synchronous or asynchronous.
+
+```python
+def test_my_thing(decoy: Decoy) -> None:
+    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 an anonymous mock
 
-To type checkers, the mock will appear to have the exact same type as the `spec` argument, if used.
+If you use neither `cls` nor `func` when calling `decoy.mock`, you will get an anonymous mock. You can use the `is_async` argument to return an asynchronous mock.
 
 ```python
 def test_my_thing(decoy: Decoy) -> None:
-    mock_function = decoy.create_decoy_func(spec=some_function)
-    free_async_function = decoy.create_decoy_func(is_async=True)
+    anon_function = decoy.mock()
+    async_anon_function = decoy.mock(is_async=True)
 ```

docs/usage/errors-and-warnings.md

@@ -9,7 +9,7 @@ Decoy's job as a mocking library is to provide you, the user, with useful design
 A [decoy.errors.VerifyError][] will be raised if a call to [decoy.Decoy.verify][] does not match the given rehearsal. This is a normal assertion, and means your code under test isn't behaving according to your tests specifications.
 
 ```python
-func = decoy.create_decoy_func()
+func = decoy.mock()
 
 func("hello")
 
@@ -69,8 +69,8 @@ class Subject:
         return result
 
 def test_subject(decoy: Decoy):
-    data_getter = decoy.create_decoy(spec=DataGetter)
-    data_handler = decoy.create_decoy(spec=DataHandler)
+    data_getter = decoy.mock(cls=DataGetter)
+    data_handler = decoy.mock(cls=DataHandler)
     subject = Subject(data_getter=data_getter, data_handler=data_handler)
 
     decoy.when(data_getter.get("data-id")).then_return(42)
@@ -133,8 +133,8 @@ This, however, requires a sizable mentality shift in terms of how you use mocks
 
 ```python
 def test_subject(decoy: Decoy):
-    data_getter = decoy.create_decoy(spec=DataGetter)
-    data_handler = decoy.create_decoy(spec=DataHandler)
+    data_getter = decoy.mock(cls=DataGetter)
+    data_handler = decoy.mock(cls=DataHandler)
     subject = Subject(data_getter=data_getter, data_handler=data_handler)
 
     decoy.when(data_getter.get("data-id")).then_return(42)

docs/usage/matchers.md

@@ -17,7 +17,7 @@ from .logger import Logger
 from .my_thing import MyThing
 
 def test_log_warning(decoy: Decoy):
-    logger = decoy.create_decoy(spec=Logger)
+    logger = decoy.mock(cls=Logger)
 
     subject = MyThing(logger=logger)
 
@@ -46,7 +46,7 @@ from .event_consumer import EventConsumer
 
 
 def test_event_listener(decoy: Decoy):
-    event_source = decoy.create_decoy(spec=EventSource)
+    event_source = decoy.mock(cls=EventSource)
     subject = EventConsumer(event_source=event_source)
     captor = matchers.Captor()
 

docs/usage/verify.md

@@ -22,7 +22,7 @@ The `verify` API uses the same "rehearsal" syntax as the [`when` API](./when).
 
 ```python
 def test_my_thing(decoy: Decoy) -> None:
-    database = decoy.create_decoy(spec=Database)
+    database = decoy.mock(cls=Database)
 
     subject = MyThing(database=database)
     subject.delete_model_by_id("some-id")
@@ -39,7 +39,7 @@ If your dependency uses async/await, simply add `await` to the rehearsal:
 ```python
 @pytest.mark.asyncio
 async def test_my_async_thing(decoy: Decoy) -> None:
-    database = decoy.create_decoy(spec=Database)
+    database = decoy.mock(cls=Database)
 
     subject = MyThing(database=database)
     await subject.delete_model_by_id("some-id")

docs/usage/when.md

@@ -8,7 +8,7 @@ A stub is a mock that is pre-configured to return a result or raise an error if
 
 ```python
 def test_my_thing(decoy: Decoy) -> None:
-    database = decoy.create_decoy(spec=Database)
+    database = decoy.mock(cls=Database)
     subject = MyThing(database=database)
 
     decoy.when(database.get("some-id")).then_return(Model(id="some-id"))
@@ -32,7 +32,7 @@ You can configure your stub to raise an error if called in a certain way:
 
 ```python
 def test_my_thing_when_database_raises(decoy: Decoy) -> None:
-    database = decoy.create_decoy(spec=Database)
+    database = decoy.mock(cls=Database)
     subject = MyThing(database=database)
 
     decoy.when(database.get("foo")).then_raise(KeyError(f"foo does not exist"))
@@ -48,7 +48,7 @@ If your dependency uses async/await, simply add `await` to the rehearsal:
 ```python
 @pytest.mark.asyncio
 async def test_my_async_thing(decoy: Decoy) -> None:
-    database = decoy.create_decoy(spec=Database)
+    database = decoy.mock(cls=Database)
     subject = MyThing(database=database)
 
     decoy.when(await database.get("some-id")).then_return(Model(id="some-id"))

docs/why.md

@@ -177,7 +177,7 @@ def decoy() -> Decoy:
 
 @pytest.fixture
 def mock_database(decoy: Decoy) -> Database:
-    return decoy.create_decoy(spec=Database)
+    return decoy.mock(cls=Database)
 
 @pytest.fixture
 def mock_book() -> Book:
@@ -265,7 +265,7 @@ def decoy() -> Decoy:
 
 @pytest.fixture
 def mock_logger(decoy: Decoy) -> Logger:
-    return decoy.create_decoy(spec=Logger)
+    return decoy.mock(cls=Logger)
 ```
 
 For verification of spies, Decoy doesn't do much except set out to add typechecking.

tests/test_call_handler.py

@@ -11,13 +11,13 @@
 @pytest.fixture
 def call_stack(decoy: Decoy) -> CallStack:
     """Get a mock instance of a CallStack."""
-    return decoy.create_decoy(spec=CallStack)
+    return decoy.mock(cls=CallStack)
 
 
 @pytest.fixture
 def stub_store(decoy: Decoy) -> StubStore:
     """Get a mock instance of a StubStore."""
-    return decoy.create_decoy(spec=StubStore)
+    return decoy.mock(cls=StubStore)
 
 
 @pytest.fixture

tests/test_core.py

@@ -17,37 +17,37 @@
 @pytest.fixture
 def create_spy(decoy: Decoy) -> SpyFactory:
     """Get a mock instance of a create_spy factory function."""
-    return decoy.create_decoy_func(spec=default_create_spy)
+    return decoy.mock(func=default_create_spy)
 
 
 @pytest.fixture
 def call_handler(decoy: Decoy) -> CallHandler:
     """Get a mock instance of a create_spy factory function."""
-    return decoy.create_decoy(spec=CallHandler)
+    return decoy.mock(cls=CallHandler)
 
 
 @pytest.fixture
 def call_stack(decoy: Decoy) -> CallStack:
     """Get a mock instance of a CallStack."""
-    return decoy.create_decoy(spec=CallStack)
+    return decoy.mock(cls=CallStack)
 
 
 @pytest.fixture
 def stub_store(decoy: Decoy) -> StubStore:
     """Get a mock instance of a StubStore."""
-    return decoy.create_decoy(spec=StubStore)
+    return decoy.mock(cls=StubStore)
 
 
 @pytest.fixture
 def verifier(decoy: Decoy) -> Verifier:
     """Get a mock instance of a Verifier."""
-    return decoy.create_decoy(spec=Verifier)
+    return decoy.mock(cls=Verifier)
 
 
 @pytest.fixture
 def warning_checker(decoy: Decoy) -> WarningChecker:
     """Get a mock instance of a Verifier."""
-    return decoy.create_decoy(spec=WarningChecker)
+    return decoy.mock(cls=WarningChecker)
 
 
 @pytest.fixture