Add new --aaa-act-block-style option with default behaviour (#213)

* Add faker to test requirements

* Add helper for flattening list of allowed values

* Add exception for handling bad config: UnexpectedConfigValue

* Improve typing on classmethods on Config and ActBlockStyle

* Remove default_config fixture and use Config.default_options() instead

* Pass act_block_style setting to Function.mark_act() method

* Pass act_block_style from Function to Block when building Act block

* Split command / control doc, add options doc page

* Adjust make docs recipe to use tox

* Update docs: add options / config page, split out directives page

* Fix lint: remove empty list from test and pass directly

* Bump GHA step versions, set devpi server as default for pip in tox

* Add type hint for Faker fixture in tests

* Expand meta plugin tox envs to add a run with a cmd line option

* Add tox env for testing config, split out dogfood env

* Adjust examples so they run with default flake8 config

* Bump example requirements for mypy bug

* Update CHANGELOG

.github/workflows/build.yml

@@ -14,10 +14,10 @@ jobs:
 
     steps:
 
-    - uses: actions/checkout@v1
+    - uses: actions/checkout@v3
 
     - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v2
+      uses: actions/setup-python@v3
       with:
         python-version: ${{ matrix.python-version }}
 
@@ -27,4 +27,5 @@ jobs:
         pip install --requirement requirements/ci.txt
 
     - name: Test with tox
-      run: tox
+      # Set pip index URL to override devpi server default on local
+      run: PIP_INDEX_URL=https://pypi.org/simple tox

CHANGELOG.rst

@@ -23,6 +23,33 @@ Unreleased_
 See also `latest documentation
 <https://flake8-aaa.readthedocs.io/en/latest/#__unreleased_marker__>`_.
 
+Added
+.....
+
+* ⛏️ New ``--aaa-act-block-style`` option added with corresponding
+  ``aaa_act_block_style`` config value. Only default behaviour supported at
+  this stage, but makes room to fix the `Black formatting problems in issue
+  #200 <https://github.com/jamescooke/flake8-AAA/issues/200>`_.
+
+* 📕 New "Options and configuration" page added to documentation to support
+  `issue #200 <https://github.com/jamescooke/flake8-AAA/issues/200>`_.
+
+* ⛏️ New tox configuration added ``PIP_INDEX_URL`` pointed at locally running
+  `devpi server instance <https://github.com/devpi/devpi>`_.
+
+* ⛏️ Faker added to test requirements to generate random data.
+
+Changed
+.......
+
+* 📕 Previous documentation page "Controlling Flake8-AAA" contained information
+  on both code directives (``# noqa``, etc) and how to use the command line
+  tool. These have been split into two separate pages: "Directives" and
+  "Command line".
+
+* ⛏️ Documentation can be built locally with ``make docs`` recipe, but this has
+  been adjusted to call tox.
+
 0.14.0_ - 2023/03/01
 --------------------
 
@@ -33,7 +60,7 @@ Added
   <https://github.com/jamescooke/flake8-aaa/pull/204>`_ fixes `issue #185
   <https://github.com/jamescooke/flake8-aaa/issues/185>`_.
 
-* 📕: AAA06 hash comment resolution added to docs. `Pull #208
+* 📕 AAA06 hash comment resolution added to docs. `Pull #208
   <https://github.com/jamescooke/flake8-aaa/pull/208>`_ fixes `issue #193
   <https://github.com/jamescooke/flake8-aaa/issues/193>`_.
 

Makefile

@@ -44,7 +44,7 @@ lintexamplespy38:
 
 .PHONY: docs
 docs:
-	$(MAKE) -C docs html
+	tox r -e py310-docs
 
 .PHONY: cmd
 cmd:
@@ -73,7 +73,7 @@ signature:
 
 .PHONY: clean
 clean:
-	rm -rf dist build .tox .pytest_cache src/flake8_aaa.egg-info
+	rm -rf dist build .tox .pytest_cache src/flake8_aaa.egg-info docs/_build/
 	find . -name '*.pyc' -delete
 
 .PHONY: sdist

configs/explicit_default.ini

@@ -0,0 +1,2 @@
+[flake8]
+aaa_act_block_style = default

docs/commands.rst → docs/command_line.rst

@@ -1,52 +1,13 @@
-Controlling Flake8-AAA
-======================
-
-In code
--------
-
-Flake8-AAA can be controlled using some special comments in your test code.
-
-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 - Correct code 2 <aaa01-correct-code-2>`.
-
-
-Disabling Flake8-AAA selectively
-................................
-
-When invoked via Flake8, Flake8 will filter any errors raised when lines are
-marked with the ``# noqa`` syntax. You can turn off all errors from Flake8-AAA
-by marking a line with ``# noqa: AAA`` and other Flake8 errors will still be
-returned.
-
-If you just want to ignore a particular error, then you can use the more
-specific code and indicate the exact error to be ignored. For example, to
-ignore the check for a space before the Act block, we can mark the Act block
-with ``# noqa: AAA03``::
-
-    def test():
-        x = 1
-        result = x + 1  # noqa: AAA03
-
-        assert result == 2
-
-
-.. _command-line:
-
 Command line
-------------
+============
 
 Flake8-AAA has a simple command line interface to assist with development and
 debugging. Its goal is to show the state of analysed test functions, which
 lines are considered to be parts of which blocks and any errors that have been
 found.
 
 Invocation, output and return value
-...................................
+-----------------------------------
 
 With Flake8-AAA installed, it can be called as a Python module::
 
@@ -121,10 +82,10 @@ in a test suite, ``find`` should be used:
     find tests -name '*.py' | xargs -n 1 python -m flake8_aaa
 
 
-noqa and command line
-.....................
+Directives and command line
+---------------------------
 
-The ``# noqa`` comment marker works slightly differently when Flake8-AAA is
+The ``# noqa`` directive comment marker works slightly differently when Flake8-AAA is
 called on the command line rather than invoked through ``flake8``. When called
 on the command line, to skip linting a test function, mark the function
 definition with ``# noqa`` on the same line as the ``def``.
@@ -140,7 +101,7 @@ For example::
 .. _line-markers:
 
 Line markers
-............
+------------
 
 Each test found in the passed file is displayed. Each line is annotated with
 its line number in the file and a marker to show how Flake8-AAA classified that

docs/directives.rst

@@ -0,0 +1,32 @@
+Directives
+==========
+
+Flake8-AAA can be controlled using some special directives in the form of
+comments in your test code.
+
+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 - Correct code 2 <aaa01-correct-code-2>`.
+
+Disabling Flake8-AAA selectively
+--------------------------------
+
+When invoked via Flake8, Flake8 will filter any errors raised when lines are
+marked with the ``# noqa`` syntax. You can turn off all errors from Flake8-AAA
+by marking a line with ``# noqa: AAA`` and other Flake8 errors will still be
+returned.
+
+If you just want to ignore a particular error, then you can use the more
+specific code and indicate the exact error to be ignored. For example, to
+ignore the check for a space before the Act block, we can mark the Act block
+with ``# noqa: AAA03``::
+
+    def test():
+        x = 1
+        result = x + 1  # noqa: AAA03
+
+        assert result == 2

docs/error_codes/AAA99-collision-when-marking-this-line.rst

@@ -1,16 +1,16 @@
 AAA99: collision when marking this line as NEW_CODE, was already OLD_CODE
--------------------------------------------------------------------------
+=========================================================================
 
 This is an error code that is raised when Flake8 tries to mark a single line as
 occupied by two different types of block. It *should* never happen. The values
 for ``NEW_CODE`` and ``OLD_CODE`` are from the list of :ref:`line-markers`.
 
 Resolution
-..........
+----------
 
 Please open a `new issue
 <https://github.com/jamescooke/flake8-aaa/issues/new>`_ containing the output
-for the failing test as generated by the :ref:`command-line` tool.
+for the failing test as generated by the :doc:`../command_line` tool.
 
 You could hack around with your test to see if you can get it to work while
 waiting for someone to reply to your issue. If you're able to adjust the test

docs/index.rst

@@ -18,6 +18,8 @@ Continue here for more detail about using Flake8-AAA.
 
     compatibility
     error_codes/all
+    options
+    directives
     discovery
-    commands
+    command_line
     release_checklist

docs/options.rst

@@ -0,0 +1,53 @@
+Options and configuration
+=========================
+
+Flake8 can be invoked with ``--`` options *and* can read values from project
+configuration files.
+
+All names of Flake8-AAA's options and configuration values are prefixed with
+"aaa". E.g. ``--aaa-act-block-style``.
+
+Act block style
+---------------
+
+Command line flag
+    ``--aaa-act-block-style``
+
+Configuration option
+    ``aaa_act_block_style``
+
+The Act block style option adjusts how Flake8-AAA builds the Act block from the
+Act node.
+
+The allowed value is "default".
+
+In default mode the Act block is the single Act node, best demonstrated by
+example:
+
+.. code-block:: python
+
+    result = do_thing()
+
+Or...
+
+.. code-block:: python
+
+    with pytest.raises(ValueError):
+        do_thing()
+
+The important feature of default Act blocks is that they do not contain any
+context managers other than pytest or unittest ones.
+
+.. code-block:: python
+
+    def test_with():
+        a_class = AClass()
+        with freeze_time("2021-02-02 12:00:02"): 
+
+            result = a_class.action('test')
+
+        assert result == 'test'
+
+In the example above, Flake8-AAA considers the ``with freeze_time()`` context
+manager to be in the Arrange block. It therefore expects a blank line between
+it and the ``result =`` Act block.

examples/good/black/noqa/test_01.py

@@ -1,6 +1,13 @@
-def test_specific():  # noqa: AAA01
+import pathlib
+
+
+def test_specific() -> None:  # noqa: AAA01
     assert 1 + 1 == 2
 
 
-def test_multi_line_args_specific(math_fixture, *args, **kwargs):  # noqa: AAA01
+def test_multi_line_args_specific(  # noqa: AAA01
+    tmp_path: pathlib.Path,
+    *args,
+    **kwargs,
+) -> None:
     assert 1 + 1 == 2

examples/good/black/test_comments.py

@@ -28,7 +28,8 @@ def test_ignore_typing() -> None:
 
 
 # Example from docs:
-# mark the end of the line considered the Act block with ``# act`` (case insensitive)
+# mark the end of the line considered the Act block with ``# act`` (case
+# insensitive)
 def test_Act() -> None:
     """
     Reverse shopping list operates in place
@@ -77,7 +78,12 @@ def test_mark_last_line() -> None:
         ]
     )  # act
 
-    assert shopping == ["apples", "bananas", "cabbages", ["dill", "eggs", "fennel"]]
+    assert shopping == [
+        "apples",
+        "bananas",
+        "cabbages",
+        ["dill", "eggs", "fennel"],
+    ]
 
 
 # Comments are OK in Arrange and Assert.

examples/good/black/test_django_fakery_factories.py

@@ -41,7 +41,9 @@ def test_default(self):
                 with transaction.atomic():
                     UserFactory()
 
-        self.assertEqual(self.user_model.objects.count(), expected_num_created - 1)
+        self.assertEqual(
+            self.user_model.objects.count(), expected_num_created - 1
+        )  # A comment to make black wrap
         self.assertIn("unique", str(cm.exception).lower())
         for u in self.user_model.objects.all():
             u.full_clean()

examples/good/noqa/test_01.py

@@ -1,10 +1,13 @@
-def test_specific():  # noqa: AAA01
+import pathlib
+
+
+def test_specific() -> None:  # noqa: AAA01
     assert 1 + 1 == 2
 
 
 def test_multi_line_args_specific(  # noqa: AAA01
-    math_fixture,
+    tmp_path: pathlib.Path,
     *args,
-    **kwargs
-):
+    **kwargs,
+) -> None:
     assert 1 + 1 == 2

examples/good/test_comments.py

@@ -28,7 +28,8 @@ def test_ignore_typing() -> None:
 
 
 # Example from docs:
-# mark the end of the line considered the Act block with ``# act`` (case insensitive)
+# mark the end of the line considered the Act block with ``# act`` (case
+# insensitive)
 def test_Act() -> None:
     """
     Reverse shopping list operates in place
@@ -75,7 +76,12 @@ def test_mark_last_line() -> None:
         'fennel',
     ])  # act
 
-    assert shopping == ['apples', 'bananas', 'cabbages', ['dill', 'eggs', 'fennel']]
+    assert shopping == [
+        'apples',
+        'bananas',
+        'cabbages',
+        ['dill', 'eggs', 'fennel'],
+    ]
 
 
 # Comments are OK in Arrange and Assert.

examples/good/test_django_fakery_factories.py

@@ -42,7 +42,10 @@ def test_default(self):
                 with transaction.atomic():
                     UserFactory()
 
-        self.assertEqual(self.user_model.objects.count(), expected_num_created - 1)
+        self.assertEqual(
+            self.user_model.objects.count(),
+            expected_num_created - 1,
+        )
         self.assertIn('unique', str(cm.exception).lower())
         for u in self.user_model.objects.all():
             u.full_clean()

examples/good/test_with_statement_unittest.py

@@ -6,7 +6,7 @@
 class Test(unittest.TestCase):
 
     def setUp(self):
-        self.hello_world_path = pathlib.Path(__file__).parent.parent / 'data' / 'hello_world.txt'
+        self.hello_world_path = pathlib.Path(__file__).parent.parent / 'data' / 'hello_world.txt'  # noqa: E501
 
     def test_assert_raises_in_block(self):
         """