Extend recognition of Pytest context managers: add deprecated_call() and warns() (#199)

* Add examples for namespaced context manager use

* Rename ActNodeType from pytest_raises to pytest_context_manager

* Soften node analysis function to make space for other pytest CMs

* Extend recognition of Pytest CMs: include deprecated_call() and warns()

* Update CHANGELOG

* Tweak docs

* Improve py versions and black error notes
* Move error codes up 1 place in the toc - put them above test discovery
internals.
* Clean up CM list in AAA01 doc.

* Add pytest CM good examples from @lyz-code

* Clean up Changelog entry: just log new example for CM

Author: jamescooke

CHANGELOG.rst

@@ -29,6 +29,16 @@ Added
 * 📕 Extended Changelog entries to include markers indicating focus. `Pull #201
   <https://github.com/jamescooke/flake8-aaa/pull/201>`_
 
+* 🎈 Support for Pytest context managers ``pytest.warns()`` and
+  ``pytest.deprecated_call()``. `Issue #196
+  <https://github.com/jamescooke/flake8-aaa/issues/196>`_, `pull #199
+  <https://github.com/jamescooke/flake8-aaa/pull/199>`_.
+
+* ⛏️ "Bad" example added for scenario where manager will only be found if it is
+  in the ``pytest`` namespace. To be compatible with Flake8-AAA tests need to
+  ``import pytest`` and not ``from pytest import raises``. `Pull #199
+  <https://github.com/jamescooke/flake8-aaa/pull/199>`_.
+
 Changed
 .......
 

docs/compatibility.rst

@@ -14,7 +14,9 @@ Flake8-AAA is fully compatible and tested against the latest versions of Python
 
 .. admonition:: See also...
 
-    :ref:`Previously supported Python versions <previous-python-versions>`.
+    See :ref:`full list of previously supported Python versions
+    <previous-python-versions>` for links to the last supported packages and
+    documentation.
 
 Flake8
 ------
@@ -62,9 +64,10 @@ They are then checked to pass Flake8-AAA's linting.
 
 .. note::
 
-    We are aware that new management of blank lines released in Black
-    ``23.1.0`` cause ``AAA03`` errors to be raised and this is tracked `in
-    issue #200 <https://github.com/jamescooke/flake8-aaa/issues/200>`_.
+    Black version ``23.1.0`` changed how it managed blank lines by default.
+    This change causes Flake8-AAA to raise ``AAA03`` errors on tests that
+    contain context managers and are formatted with Black. See `issue #200
+    <https://github.com/jamescooke/flake8-aaa/issues/200>`_.
 
 Pytest
 ------

docs/error_codes/AAA01-no-act-block-found-in-test.rst

@@ -86,5 +86,7 @@ The Act block carries out a single action on an object so it's important that
 Flake8-AAA can clearly distinguish which line or lines make up the Act block in
 every test.
 
-Code blocks wrapped in ``pytest.raises()`` and ``unittest.assertRaises()``
-context managers are recognised as Act blocks.
+Flake8-AAA recognises code blocks wrapped in Pytest context managers like
+``pytest.raises()`` as Act blocks.
+
+It also recognises unittest's ``assertRaises()`` blocks as Act blocks.

docs/index.rst

@@ -17,7 +17,7 @@ Continue here for more detail about using Flake8-AAA.
     :caption: Contents
 
     compatibility
-    discovery
     error_codes/all
+    discovery
     commands
     release_checklist

examples/bad/bad_expected.out

@@ -1,5 +1,7 @@
 examples/bad/test.py:4:1: AAA01 no Act block found in test
 examples/bad/test_aaa01.py:8:1: AAA01 no Act block found in test
+examples/bad/test_aaa01_cm_import.py:11:1: AAA01 no Act block found in test
+examples/bad/test_aaa01_cm_import.py:18:1: AAA01 no Act block found in test
 examples/bad/test_aaa03.py:10:9: AAA03 expected 1 blank line before Act block, found none
 examples/bad/test_aaa03.py:3:5: AAA03 expected 1 blank line before Act block, found none
 examples/bad/test_aaa03_04.py:10:5: AAA04 expected 1 blank line before Assert block, found none

examples/bad/test_aaa01_cm_import.py

@@ -0,0 +1,20 @@
+"""
+Failure of AAA01: when pytest context managers are not imported "in" pytest,
+then they can't be found
+"""
+
+# Unusual import of raises and warns: docs / convention uses `import pytest` so
+# preserves namespace.
+from pytest import raises, warns
+
+
+def test_imported() -> None:
+    one_stuff = [1]
+
+    with raises(IndexError):
+        one_stuff[1]
+
+
+def test_warns() -> None:
+    with warns(UserWarning, match="yamlfix/pull/182"):
+        pass

examples/good/test_with_statement.py

@@ -1,4 +1,5 @@
 import io
+import warnings
 from typing import Generator, List
 
 import pytest
@@ -11,6 +12,16 @@ def test_pytest_raises() -> None:
         list()[0]
 
 
+def test_deprecation_warning():
+    with pytest.deprecated_call():
+        warnings.warn("deprecate warning", DeprecationWarning)
+
+
+def test_user_warning():
+    with pytest.warns(UserWarning):
+        warnings.warn("my warning", UserWarning)
+
+
 # --- Use of context managers in tests ---
 
 

src/flake8_aaa/act_node.py

@@ -5,7 +5,7 @@
 from .helpers import (
     get_first_token,
     get_last_token,
-    node_is_pytest_raises,
+    node_is_pytest_context_manager,
     node_is_result_assignment,
     node_is_unittest_raises,
 )
@@ -56,8 +56,8 @@ def build(cls: Type[AN], node: ast.stmt) -> List[AN]:
         """
         if node_is_result_assignment(node):
             return [cls(node, ActNodeType.result_assignment)]
-        if node_is_pytest_raises(node):
-            return [cls(node, ActNodeType.pytest_raises)]
+        if node_is_pytest_context_manager(node):
+            return [cls(node, ActNodeType.pytest_context_manager)]
         if node_is_unittest_raises(node):
             return [cls(node, ActNodeType.unittest_raises)]
 

src/flake8_aaa/helpers.py

@@ -77,16 +77,28 @@ def node_is_result_assignment(node: ast.AST) -> bool:
     return False
 
 
-def node_is_pytest_raises(node: ast.AST) -> bool:
+cm_exp = re.compile(r'^\s*with\ pytest\.(raises|deprecated_call|warns)\(')
+
+
+def node_is_pytest_context_manager(node: ast.AST) -> bool:
     """
+    Identify node as being one of the Pytest context managers used to catch
+    exceptions and warnings.
+
+    Pytest's context managers as of 7.2 are:
+
+    * pytest.raises()
+    * pytest.deprecated_call()
+    * pytest.warns()
+
     Args:
         node: An ``ast`` node, augmented with ASTTokens
 
     Returns:
         bool: ``node`` corresponds to a With node where the context manager is
-        ``pytest.raises``.
+            a Pytest context manager.
     """
-    return isinstance(node, ast.With) and get_first_token(node).line.strip().startswith('with pytest.raises')
+    return isinstance(node, ast.With) and bool(cm_exp.match(get_first_token(node).line))
 
 
 def node_is_unittest_raises(node: ast.AST) -> bool:

src/flake8_aaa/types.py

@@ -4,7 +4,7 @@
     'ActNodeType',
     (
         'marked_act '  # Marked with "# act"
-        'pytest_raises '  # Wrapped in "pytest.raises" context manager.
+        'pytest_context_manager '  # Pytest context manager e.g. "pytest.raises"
         'result_assignment '  # Simple "result = "
         'unittest_raises '  # Wrapped in unittest's "assertRaises" context manager.
     ),