Build out AAA01 code examples in docs, fix Python version docs (#201)

* WIP add problematic and correct code examples

* Add good example of pytest.raises() and update example README

* Build out problematic code / correct code for AAA01

* Fix supported Python versions docs, add Black issue #200

* Update CHANGELOG

* Extend Changelog to contain markers for types of changes

CHANGELOG.rst

@@ -7,24 +7,55 @@ The format is based on `Keep a Changelog
 <http://keepachangelog.com/en/1.0.0/>`_ and this project adheres to `Semantic
 Versioning <http://semver.org/spec/v2.0.0.html>`_.
 
+Additional markers for types of change copied from ``README``:
+
+* 🎈: Features. Public facing changes to functionality.
+
+* 📕: Documentation. Public facing changes to documentation, but no
+  functionality changes.
+
+* ⛏️: Internal refactors. Internal technical changes with no downstream changes
+  to features.
 
 Unreleased_
 -----------
 
 See also `latest documentation
 <https://flake8-aaa.readthedocs.io/en/latest/#__unreleased_marker__>`_.
 
+Added
+.....
+
+* 📕 Extended Changelog entries to include markers indicating focus. `Pull #201
+  <https://github.com/jamescooke/flake8-aaa/pull/201>`_
+
 Changed
 .......
 
-* CI system (GitHub Actions) adjusted to install pinned requirements from
+* ⛏️ CI system (GitHub Actions) adjusted to install pinned requirements from
   ``ci.txt`` rather than un-pinned / rolling requirements at "action time".
-  `#197 <https://github.com/jamescooke/flake8-aaa/pull/197>`_ . Also:
+  `Pull #197 <https://github.com/jamescooke/flake8-aaa/pull/197>`_ . Also:
 
   - Pinned Ubuntu GHA image to ``ubuntu-22.04``
 
   - Fixed ``tox.ini`` config to use ``allowlist_externals``.
 
+* 📕 Documentation for error ``AAA01`` no Act block found in test expanded to
+  contain problematic code / correct code examples. Progress on `Issue #149
+  <https://github.com/jamescooke/flake8-aaa/issues/149>`_, `pull #201
+  <https://github.com/jamescooke/flake8-aaa/pull/201>`_.
+
+Fixed
+.....
+
+* 📕 Added missing Python 3.6 compatibility notes missing from ``v0.12.2``
+  `documentation
+  <https://flake8-aaa.readthedocs.io/en/v0.12.2/compatibility.html>`_. `Pull
+  #201 <https://github.com/jamescooke/flake8-aaa/pull/201>`_.
+
+* 📕 Supported Python version list updated: remove 3.6 and add 3.10. `Pull #201
+  <https://github.com/jamescooke/flake8-aaa/pull/201>`_.
+
 
 0.12.2_ - 2022/01/02
 --------------------

README.rst

@@ -261,7 +261,7 @@ Flake8-AAA works with:
 
 * Mypy and type-annotated code.
 
-* Latest versions of Python 3 (3.6, 3.7, 3.8 and 3.9).
+* Latest versions of Python 3 (3.7, 3.8, 3.9 and 3.10).
 
 Further reading:
 

docs/commands.rst

@@ -12,7 +12,7 @@ Explicitly marking blocks
 One can set the act block explicitly using the ``# act`` comment. This is
 necessary when there is no assignment possible.
 
-See :ref:`AAA01: no Act block found in test - Resolution <aaa01-resolution>`.
+See :ref:`AAA01: no Act block found in test - Correct code 2 <aaa01-correct-code-2>`.
 
 
 Disabling Flake8-AAA selectively

docs/compatibility.rst

@@ -10,29 +10,11 @@ Python
 Works with Python 3.
 
 Flake8-AAA is fully compatible and tested against the latest versions of Python
-3. Currently that's 3.6, 3.7, 3.8 and 3.9.
+3. Currently that's 3.7, 3.8, 3.9 and 3.10.
 
-The following versions of Python are no longer supported:
-
-Python 3.5
-..........
-
-Python 3.5 was supported up to ``v0.7.2``
+.. admonition:: See also...
 
-  * `v0.7.2 on PyPI <https://pypi.org/project/flake8-aaa/0.7.2/>`_
-  * `v0.7.2 Documentation <https://flake8-aaa.readthedocs.io/en/v0.7.2/>`_
-  * `Github v0.7.2 tag
-    <https://github.com/jamescooke/flake8-aaa/releases/tag/v0.7.2>`_
-
-Python 2
-........
-
-Python 2 was supported up to ``v0.4.0``
-
-  * `v0.4.0 on PyPI <https://pypi.org/project/flake8-aaa/0.4.0/>`_
-  * `v0.4.0 Documentation <https://flake8-aaa.readthedocs.io/en/v0.4.0/>`_
-  * `Github v0.4.0 tag
-    <https://github.com/jamescooke/flake8-aaa/releases/tag/v0.4.0>`_
+    :ref:`Previously supported Python versions <previous-python-versions>`.
 
 Flake8
 ------
@@ -44,12 +26,17 @@ specified in ``setup.py`` because users may only want to use the command line
 interface.
 
 Check that Flake8-AAA was installed correctly by asking ``flake8`` for its
-version signature::
+version signature:
+
+.. code-block:: shell
+
+    flake8 --version
+
+.. code-block::
 
-    $ flake8 --version
-    3.8.2 (aaa: 0.10.0, mccabe: 0.6.1, pycodestyle: 2.6.0, pyflakes: 2.2.0) CPython 3.6.10 on Linux
+    4.0.1 (aaa: 0.12.2, mccabe: 0.6.1, pycodestyle: 2.8.0, pyflakes: 2.4.0) CPython 3.10.1 on Linux
 
-The ``aaa: 0.10.0`` part of that output tells you Flake8 found this plugin.
+The ``aaa: 0.12.2`` part of that output tells you Flake8 found this plugin.
 
 Yapf
 ----
@@ -73,6 +60,12 @@ directory
 These tests are formatted with the latest version of Black in default mode.
 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>`_.
+
 Pytest
 ------
 
@@ -89,4 +82,42 @@ Python unittest style is supported.
 
 To pin this compatibility we include unittest-style tests in the `examples/good
 directory
-<https://github.com/jamescooke/flake8-aaa/tree/master/examples/good>`_ -
+<https://github.com/jamescooke/flake8-aaa/tree/master/examples/good>`_.
+
+.. _previous-python-versions:
+
+Previous Python versions
+------------------------
+
+The following versions of Python are no longer supported:
+
+Python 3.6
+..........
+
+Python 3.6 was supported up to ``v0.12.1``
+
+* `v0.12.1 on PyPI <https://pypi.org/project/flake8-aaa/0.12.1/>`_
+* `v0.12.1 Documentation <https://flake8-aaa.readthedocs.io/en/v0.12.1/>`_
+* `Github v0.12.1 tag
+  <https://github.com/jamescooke/flake8-aaa/releases/tag/v0.12.1>`_
+
+
+Python 3.5
+..........
+
+Python 3.5 was supported up to ``v0.7.2``
+
+* `v0.7.2 on PyPI <https://pypi.org/project/flake8-aaa/0.7.2/>`_
+* `v0.7.2 Documentation <https://flake8-aaa.readthedocs.io/en/v0.7.2/>`_
+* `Github v0.7.2 tag
+  <https://github.com/jamescooke/flake8-aaa/releases/tag/v0.7.2>`_
+
+Python 2
+........
+
+Python 2 was supported up to ``v0.4.0``
+
+* `v0.4.0 on PyPI <https://pypi.org/project/flake8-aaa/0.4.0/>`_
+* `v0.4.0 Documentation <https://flake8-aaa.readthedocs.io/en/v0.4.0/>`_
+* `Github v0.4.0 tag
+  <https://github.com/jamescooke/flake8-aaa/releases/tag/v0.4.0>`_

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

@@ -1,50 +1,90 @@
 AAA01: no Act block found in test
----------------------------------
+=================================
 
 An Act block is usually a line like ``result =`` or a check that an exception
-is raised. Flake8-AAA could not find an Act block in the indicated test
-function.
+is raised. When Flake8-AAA raises ``AAA01`` it could not find an Act block in
+the indicated test function.
 
-.. _aaa01-resolution:
+Problematic code
+................
 
-Resolution
-..........
+.. code-block:: python
+
+    def test_some_text() -> None:
+        some = 'some'
+        text = 'text'
 
-Add an Act block to the test or mark a line that should be considered the
-action.
+        some_text = f'{some}_{text}'
 
-Even if the result of a test action is ``None``, assign that result and
-pin it with a test:
+        assert some_text == 'some_text'
 
 .. code-block:: python
 
-    result = action()
+    from pytest import raises
+
+    def test() -> None:
+        with raises(IndexError):
+            list()[0]
 
-    assert result is None
+Correct code 1
+..............
 
-However, if your action's ``None`` return value is type-hinted ``action() ->
-None``, then ``mypy`` will complain if you try to assign a result. In this
-case, or any other where a you can not assign a ``result``, then mark the end
-of the line considered the Act block with ``# act`` (case insensitive):
+Use ``result =`` assignment to indicate the action in the test:
 
 .. code-block:: python
 
-    data['new_key'] = 1  # act
+    def test_some_text() -> None:
+        some = 'some'
+        text = 'text'
+
+        result = f'{some}_{some}'
+
+        assert result == 'some_text'
 
-If the action spans multiple lines, then it can be marked with ``# act`` on the
-first or last line. Both of the following will work:
+Ensure all Pytest context managers are in the ``pytest`` namespace - use
+``pytest.raises()`` not just ``raises()``:
 
 .. code-block:: python
 
-    validate_row(  # act
-        {"total_number_of_users": "1", "number_of_new_users": "0"},
-        ["total_number_of_users", "number_of_new_users"],
-    )
+    import pytest
+
+    def test() -> None:
+        with pytest.raises(IndexError):
+            list()[0]
+
+.. _aaa01-correct-code-2:
+
+Correct code 2
+..............
+
+Alternatively, mark your Act block with the ``# act`` hint to indicate the
+action in the test. This can be useful for scenarios where a result can not be
+assigned, such as tests on functions that return ``None``.
+
+.. code-block:: python
+
+    def test_some_text() -> None:
+        some = 'some'
+        text = 'text'
+
+        some_text = f'{some}_{text}'  # act
+
+        assert some_text == 'some_text'
+
+.. code-block:: python
+
+    from pytest import raises
+
+    def test() -> None:
+        with raises(IndexError):
+            list()[0]  # act
+
+Rationale
+.........
 
-    validate_row(
-        {"total_number_of_users": "1", "number_of_new_users": "0"},
-        ["total_number_of_users", "number_of_new_users"],
-    )  # act
+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.

examples/good/README.rst

@@ -10,13 +10,11 @@ AAA-style test.
 Valid tests
 -----------
 
-The goal is that all tests in both good and bad examples will target features
-of the Python 3 standard library. They will all be executable with a vanilla
-install of ``pytest``. Currently only the ``with`` statement examples support
-this.
+All good and bad tests are intended to work on Python 3 stdlib. They are tested
+with vanilla ``pytest`` to ensure they pass in the ``examples`` environment.
 
 Testing Flake8-AAA
 ------------------
 
-To prevent false negatives our test suite runs Flake8-AAA against this
-directory and checks no linting errors are raised.
+To prevent false negatives our test suite runs Flake8-AAA against all test
+modules in this directory and checks no linting errors are raised.

examples/good/test_with_statement.py

@@ -3,6 +3,16 @@
 
 import pytest
 
+# --- Pytest context managers ---
+
+
+def test_pytest_raises() -> None:
+    with pytest.raises(IndexError):
+        list()[0]
+
+
+# --- Use of context managers in tests ---
+
 
 def test_simple(hello_world_path) -> None:
     """