feat: add mypy plugin (#6)

Closes #5

Author: mcous

README.md

@@ -36,9 +36,7 @@ pip install decoy
 poetry add --dev decoy
 ```
 
-## Usage
-
-### Setup
+## Setup
 
 You'll want to create a test fixture to reset Decoy state between each test run. In [pytest][], you can do this by using a fixture to create a new Decoy instance for every test.
 
@@ -57,6 +55,25 @@ Why is this important? The `Decoy` container tracks every fake that is created d
 
 [pytest]: https://docs.pytest.org/
 
+### Mypy Setup
+
+Decoy's rehearsal syntax can be a bit confusing to [mypy][] if the mock in question is supposed to return `None`. Normally, [mypy will complain][] if you try to use a `None`-returning expression as a value, because this is almost always a mistake.
+
+In Decoy, however, it's an intentional part of the API and _not_ a mistake. To suppress these errors, Decoy provides a mypy plugin that you should add to your configuration file:
+
+```ini
+# mypi.ini
+
+# ...
+plugins = decoy.mypy
+# ...
+```
+
+[mypy]: https://mypy.readthedocs.io/
+[mypy will complain]: https://mypy.readthedocs.io/en/stable/error_code_list.html#check-that-called-function-returns-a-value-func-returns-value
+
+## Usage
+
 ### Stubbing
 
 A stub is a an object used in a test that is pre-configured to return a result or raise an error if called according to a specification. In Decoy, you specify a stub's call expectations with a "rehearsal", which is simply a call to the stub inside of a `decoy.when` wrapper.
@@ -127,6 +144,16 @@ Stubbing and verification of a decoy are **mutually exclusive** within a test. I
 -   The assertions are redundant
 -   The dependency is doing too much based on its input (e.g. side-effecting _and_ calculating complex data) and should be refactored
 
+### Usage with async/await
+
+Decoy supports async/await out of the box! Pass your async function or class with async methods to `spec` in `decoy.create_decoy_func` or `decoy.create_decoy`, respectively, and Decoy will figure out the rest.
+
+When writing rehearsals on async functions and methods, remember to include the `await` with your rehearsal call:
+
+```py
+decoy.when(await mock_db.get_by_id("some-id")).then_return(mock_item)
+```
+
 ### Matchers
 
 Sometimes, when you're stubbing or verifying calls (or really when you're doing any sort of equality assertion in a test), you need to loosen a given assertion. For example, you may want to assert that a dependency is called with a string, but you don't care about the full contents of that string.

decoy/mypy.py

@@ -0,0 +1,39 @@
+"""Decoy mypy plugin."""
+from typing import Callable, Optional, Type as ClassType
+
+from mypy.errorcodes import FUNC_RETURNS_VALUE
+from mypy.plugin import Plugin, MethodContext
+from mypy.types import Type
+
+
+class DecoyPlugin(Plugin):
+    """A mypy plugin to remove otherwise valid errors from rehearsals."""
+
+    def get_method_hook(
+        self, fullname: str
+    ) -> Optional[Callable[[MethodContext], Type]]:
+        """Remove any func-returns-value errors inside `when` or `verify` calls."""
+        if fullname in {"decoy.Decoy.verify", "decoy.Decoy.when"}:
+            return self._handle_decoy_call
+
+        return None
+
+    def _handle_decoy_call(self, ctx: MethodContext) -> Type:
+        errors_list = ctx.api.msg.errors.error_info_map.get(ctx.api.path, [])
+        rehearsal_call_args = ctx.args[0] if len(ctx.args) > 0 else []
+
+        for err in errors_list:
+            for arg in rehearsal_call_args:
+                if (
+                    err.code == FUNC_RETURNS_VALUE
+                    and arg.line == err.line
+                    and arg.column == err.column
+                ):
+                    errors_list.remove(err)
+
+        return ctx.default_return_type
+
+
+def plugin(version: str) -> ClassType[DecoyPlugin]:
+    """Get the DecoyPlugin class definition."""
+    return DecoyPlugin

mkdocs.yml

@@ -1,8 +1,10 @@
 site_name: Decoy
 site_description: "Opinionated, typed stubbing and verification library for Python."
+site_author: "Mike Cousins"
 site_url: "https://mike.cousins.io/decoy/"
 repo_url: "https://github.com/mcous/decoy"
 repo_name: "mcous/decoy"
+edit_uri: "blob/main/docs/"
 
 nav:
     - User Guide: index.md
@@ -14,6 +16,8 @@ theme:
     name: "material"
     palette:
         scheme: preference
+    features:
+        - navigation.instant
 
 plugins:
     - search

mypy.ini

@@ -2,3 +2,4 @@
 files = decoy,tests
 strict = True
 show_error_codes = True
+plugins = decoy.mypy

poetry.lock

@@ -32,10 +32,12 @@ mkdocstrings = "^0.13.6"
 mypy = "^0.790"
 pytest = "^6.1.2"
 pytest-asyncio = "^0.14.0"
+pytest-mypy-plugins = "^1.6.1"
 pytest-xdist = "^2.1.0"
 
 [tool.pytest.ini_options]
-addopts = "--color=yes"
+addopts = "--color=yes --mypy-ini-file=mypy.ini"
+
 [build-system]
 requires = ["poetry>=0.12"]
 build-backend = "poetry.masonry.api"

pyproject.toml

@@ -73,7 +73,7 @@ def test_call_no_return_method_then_verify(decoy: Decoy) -> None:
 
     stub.do_the_thing(True)
 
-    decoy.verify(stub.do_the_thing(True))  # type: ignore[func-returns-value]
+    decoy.verify(stub.do_the_thing(True))
 
     with pytest.raises(AssertionError):
-        decoy.verify(stub.do_the_thing(False))  # type: ignore[func-returns-value]
+        decoy.verify(stub.do_the_thing(False))

tests/test_verify.py

@@ -0,0 +1,42 @@
+# mypy plugin tests
+
+- case: does_not_suppress_func_returns_value
+  main: |
+      def noop() -> None:
+          pass
+
+      value = noop()
+  out: |
+      main:4: error: "noop" does not return a value  [func-returns-value]
+
+- case: suppresses_func_returns_value_in_when
+  main: |
+      from decoy import Decoy
+
+      def noop() -> None:
+          pass
+
+      decoy = Decoy()
+      stub = decoy.when(noop())
+
+- case: suppresses_func_returns_value_in_verify
+  main: |
+      from decoy import Decoy
+
+      def noop() -> None:
+          pass
+
+      decoy = Decoy()
+      decoy.verify(noop())
+
+- case: does_not_suppress_other_errors
+  main: |
+      from decoy import Decoy
+
+      def do_thing() -> int:
+          return 42
+
+      decoy = Decoy()
+      stub = decoy.when(do_thing("hello"))
+  out: |
+      main:7: error: Too many arguments for "do_thing"  [call-arg]

tests/typing/test_mypy_plugin.yml

@@ -0,0 +1,59 @@
+# typing tests
+
+- case: class_decoy_mimics_type
+  main: |
+      from decoy import Decoy
+
+      class Dependency():
+          def do_thing(self, input: str) -> int:
+              return 42
+
+      decoy = Decoy()
+      fake = decoy.create_decoy(spec=Dependency)
+      reveal_type(fake)
+  out: |
+      main:9: note: Revealed type is 'main.Dependency*'
+
+- case: function_decoy_mimics_type
+  main: |
+      from decoy import Decoy
+
+      def do_thing(input: str) -> int:
+          return 42
+
+      decoy = Decoy()
+      fake = decoy.create_decoy_func(spec=do_thing)
+      reveal_type(fake)
+  out: |
+      main:8: note: Revealed type is 'def (input: builtins.str) -> builtins.int'
+
+- case: class_stub_mimics_return_type
+  main: |
+      from decoy import Decoy
+
+      class Dependency():
+          def do_thing(self, input: str) -> int:
+              return 42
+
+      decoy = Decoy()
+      fake = decoy.create_decoy(spec=Dependency)
+
+      decoy.when(fake.do_thing("hello")).then_return(42)
+      decoy.when(fake.do_thing("goodbye")).then_return("wrong-type")
+  out: |
+      main:11: error: Argument 1 to "then_return" of "Stub" has incompatible type "str"; expected "int"  [arg-type]
+
+- case: function_stub_mimics_return_type
+  main: |
+      from decoy import Decoy
+
+      def do_thing(input: str) -> int:
+          return 42
+
+      decoy = Decoy()
+      fake = decoy.create_decoy_func(spec=do_thing)
+
+      decoy.when(fake("hello")).then_return(42)
+      decoy.when(fake("goodbye")).then_return("wrong-type")
+  out: |
+      main:10: error: Argument 1 to "then_return" of "Stub" has incompatible type "str"; expected "int"  [arg-type]