Closes #672

Author: sobolevn

docs/pages/contrib/pytest_plugins.rst

@@ -40,8 +40,9 @@ It tests that containers do handle error track.
 .. code:: python
 
   from returns.result import Failure, Success
+  from returns.contrib.pytest import ReturnsAsserts
 
-  def test_my_container(returns):
+  def test_my_container(returns: ReturnsAsserts):
       assert not returns.is_error_handled(Failure(1))
       assert returns.is_error_handled(
           Failure(1).lash(lambda _: Success('default value')),
@@ -79,6 +80,7 @@ created and looking for the desired function.
 .. code:: python
 
   >>> from returns.result import Result, Success, Failure
+  >>> from returns.contrib.pytest import ReturnsAsserts
 
   >>> returns_fixture = getfixture('returns')
 
@@ -87,11 +89,15 @@ created and looking for the desired function.
   ...         return Success(int(arg))
   ...     return Failure('"{0}" is not a number'.format(arg))
 
-  >>> def test_if_failure_is_created_at_convert_function(returns):
+  >>> def test_if_failure_is_created_at_convert_function(
+  ...     returns: ReturnsAsserts,
+  ... ):
   ...     with returns.has_trace(Failure, desired_function):
   ...         Success('not a number').bind(desired_function)
 
-  >>> def test_if_success_is_created_at_convert_function(returns):
+  >>> def test_if_success_is_created_at_convert_function(
+  ...     returns: ReturnsAsserts,
+  ... ):
   ...     with returns.has_trace(Success, desired_function):
   ...         Success('42').bind(desired_function)
 

returns/contrib/pytest/__init__.py

@@ -0,0 +1 @@
+from returns.contrib.pytest.plugin import ReturnsAsserts as ReturnsAsserts

returns/contrib/pytest/plugin.py

@@ -9,7 +9,8 @@
 from typing_extensions import Final, final
 
 if TYPE_CHECKING:
-    from returns.interfaces.specific.result import ResultBasedN
+    from returns.interfaces.failable import FailableN
+    from returns.interfaces.specific.result import ResultLikeN
 
 _ERROR_FIELD: Final = '_error_handled'
 _ERROR_HANDLERS: Final = (
@@ -21,46 +22,32 @@
 )
 
 _FunctionType = TypeVar('_FunctionType', bound=Callable)
-_ResultCallableType = TypeVar(
-    '_ResultCallableType', bound=Callable[..., 'ResultBasedN'],
+_ReturnsResultType = TypeVar(
+    '_ReturnsResultType', bound=Callable[..., 'ResultLikeN'],
 )
 
 
-def pytest_configure(config) -> None:
-    """
-    Hook to be executed on import.
-
-    We use it define custom markers.
-    """
-    config.addinivalue_line(
-        'markers',
-        """
-        returns_lawful: all tests under `check_all_laws` is marked this way,
-        use `-m "not returns_lawful"` to skip them.
-        """,
-    )
-
-
-class _DesiredFunctionFound(RuntimeError):
-    """Exception to raise when expected function is found."""
-
-
 @final
-class _ReturnsAsserts(object):
+class ReturnsAsserts(object):
     """Class with helpers assertions to check containers."""
 
     __slots__ = ()
 
-    def is_error_handled(self, container) -> bool:
+    def is_error_handled(self, container: 'FailableN') -> bool:
         """Ensures that container has its error handled in the end."""
         return bool(getattr(container, _ERROR_FIELD, False))
 
     @contextmanager
     def has_trace(
         self,
-        trace_type: _ResultCallableType,
+        trace_type: _ReturnsResultType,
         function_to_search: _FunctionType,
     ) -> Iterator[None]:
+        """
+        Ensures that a given function was called during execution.
+
+        Use it to determine where the failure happened.
+        """
         old_tracer = sys.gettrace()
         sys.settrace(partial(_trace_function, trace_type, function_to_search))
 
@@ -76,6 +63,27 @@ def has_trace(
             sys.settrace(old_tracer)
 
 
+@pytest.fixture(scope='session')
+def returns(_patch_containers) -> ReturnsAsserts:  # noqa: WPS442
+    """Returns our own class with helpers assertions to check containers."""
+    return ReturnsAsserts()
+
+
+def pytest_configure(config) -> None:
+    """
+    Hook to be executed on import.
+
+    We use it define custom markers.
+    """
+    config.addinivalue_line(
+        'markers',
+        """
+        returns_lawful: all tests under `check_all_laws` is marked this way,
+        use `-m "not returns_lawful"` to skip them.
+        """,
+    )
+
+
 @pytest.fixture(scope='session')
 def _patch_containers() -> None:
     """
@@ -92,12 +100,6 @@ def _patch_containers() -> None:
     _patch_error_handling(_ERRORS_COPIERS, _PatchedContainer.copy_handler)
 
 
-@pytest.fixture(scope='session')
-def returns(_patch_containers) -> _ReturnsAsserts:  # noqa: WPS442
-    """Returns our own class with helpers assertions to check containers."""
-    return _ReturnsAsserts()
-
-
 def _patch_error_handling(methods, patch_handler) -> None:
     for container in _PatchedContainer.containers_to_patch():
         for method in methods:
@@ -107,7 +109,7 @@ def _patch_error_handling(methods, patch_handler) -> None:
 
 
 def _trace_function(
-    trace_type: _ResultCallableType,
+    trace_type: _ReturnsResultType,
     function_to_search: _FunctionType,
     frame: FrameType,
     event: str,
@@ -192,3 +194,7 @@ def factory(self, *args, **kwargs):
                 )
                 return original_result
         return wraps(original)(factory)
+
+
+class _DesiredFunctionFound(RuntimeError):
+    """Exception to raise when expected function is found."""

setup.cfg

@@ -69,6 +69,7 @@ per-file-ignores =
   returns/_internal/futures/*.py: WPS204, WPS433, WPS437
   # We allow a lot of durty hacks in our plugins:
   returns/contrib/mypy/*.py: S101, WPS201
+  returns/contrib/pytest/__init__.py: F401
   returns/contrib/pytest/plugin.py: WPS201, WPS430, WPS437, WPS609
   returns/contrib/hypothesis/*.py: WPS437, WPS609
   # TODO: remove after [email protected]

tests/test_contrib/test_pytest/test_plugin_has_trace.py

@@ -1,5 +1,6 @@
 import pytest
 
+from returns.contrib.pytest import ReturnsAsserts
 from returns.io import IOFailure, IOSuccess
 from returns.result import Failure, Success
 
@@ -20,7 +21,7 @@ def _create_container_function_intermediate(container_type, container_value):
     IOSuccess,
     IOFailure,
 ])
-def test_has_trace1(container_type, returns):
+def test_has_trace1(container_type, returns: ReturnsAsserts):
     """Test if our plugin will identify the container creation correctly."""
     with returns.has_trace(container_type, _create_container_function):
         _create_container_function(container_type, 1)  # type: ignore
@@ -32,7 +33,7 @@ def test_has_trace1(container_type, returns):
     IOSuccess,
     IOFailure,
 ])
-def test_has_trace2(container_type, returns):
+def test_has_trace2(container_type, returns: ReturnsAsserts):
     """Test if our plugin will identify the container creation correctly."""
     with returns.has_trace(container_type, _create_container_function):
         _create_container_function_intermediate(  # type: ignore
@@ -46,7 +47,7 @@ def test_has_trace2(container_type, returns):
     (IOSuccess, IOFailure),
     (IOFailure, IOSuccess),
 ])
-def test_failed_has_trace1(desired_type, wrong_type, returns):
+def test_failed_has_trace1(desired_type, wrong_type, returns: ReturnsAsserts):
     """Test if our plugin will identify the conainter was not created."""
     with pytest.raises(pytest.fail.Exception):  # noqa: PT012
         with returns.has_trace(desired_type, _create_container_function):
@@ -59,7 +60,7 @@ def test_failed_has_trace1(desired_type, wrong_type, returns):
     (IOSuccess, IOFailure),
     (IOFailure, IOSuccess),
 ])
-def test_failed_has_trace2(desired_type, wrong_type, returns):
+def test_failed_has_trace2(desired_type, wrong_type, returns: ReturnsAsserts):
     """Test if our plugin will identify the conainter was not created."""
     with pytest.raises(pytest.fail.Exception):  # noqa: PT012
         with returns.has_trace(desired_type, _create_container_function):