Add automatically generated options

Author: Pierre-Sassoulas

.github/CONTRIBUTING.md

@@ -8,8 +8,10 @@ Use `pre-commit install` to install the pre-commit hook for the repository.
 
 - Implement a Formatter by inheriting from `pydocstringformatter.formatting.Formatter`
 - Add your new formatter to `pydocstringformatter.formatting.FORMATTERS`
-- Choose a proper name because this will be user-facing: the name will be used for
-  options of the CLI.
+- Write a clear docstring because this will be user-facing: it's what will be seen in
+  the help message for the formatters command line option.
+- Choose a proper name because this will be user-facing: the name will be used to turn
+  the checker on and off via the command line or config files.
 
 ### Testing
 

pydocstringformatter/run.py

@@ -9,13 +9,15 @@
 from typing import List, Union
 
 from pydocstringformatter import __version__, formatting, utils
+from pydocstringformatter.formatting import FORMATTERS
 
 
 class _Run:
     """Main class that represent a run of the program."""
 
     def __init__(self, argv: Union[List[str], None]) -> None:
         self.arg_parser = utils._register_arguments(__version__)
+        utils._register_arguments_formatters(self.arg_parser, FORMATTERS)
         self.config = argparse.Namespace()
 
         if argv := argv or sys.argv[1:]:
@@ -47,9 +49,11 @@ def _format_file(self, filename: Path) -> bool:
         for index, tokeninfo in enumerate(tokens):
             new_tokeninfo = tokeninfo
 
+            formatter_options = vars(self.config)
             if utils._is_docstring(new_tokeninfo, tokens[index - 1]):
                 for formatter in formatting.FORMATTERS:
-                    new_tokeninfo = formatter.treat_token(new_tokeninfo)
+                    if formatter_options[formatter.name]:
+                        new_tokeninfo = formatter.treat_token(new_tokeninfo)
             changed_tokens.append(new_tokeninfo)
 
             if tokeninfo != new_tokeninfo:

pydocstringformatter/utils/__init__.py

@@ -2,6 +2,7 @@
     _parse_command_line_arguments,
     _parse_toml_file,
     _register_arguments,
+    _register_arguments_formatters,
 )
 from pydocstringformatter.utils.exceptions import (
     ParsingError,
@@ -22,6 +23,7 @@
     "ParsingError",
     "PydocstringFormatterError",
     "_register_arguments",
+    "_register_arguments_formatters",
     "TomlParsingError",
     "_print_to_console",
 ]

pydocstringformatter/utils/argument_parsing.py

@@ -4,6 +4,7 @@
 
 import tomli
 
+from pydocstringformatter.formatting.base import Formatter
 from pydocstringformatter.utils.exceptions import TomlParsingError, UnrecognizedOption
 
 OPTIONS_TYPES = {"write": "store_true"}
@@ -36,7 +37,26 @@ def _register_arguments(version: str) -> argparse.ArgumentParser:
         version=version,
         help="Show version number and exit",
     )
+    return parser
+
 
+def _register_arguments_formatters(
+    parser: argparse.ArgumentParser, formatters: List[Formatter]
+) -> argparse.ArgumentParser:
+    """Register a list of formatters, so they can all be deactivated or activated."""
+    for formatter in formatters:
+        name = formatter.name
+        help_text = f"ctivate the {name} formatter"
+        parser.add_argument(
+            f"--{name}",
+            action="store_true",
+            dest=name,
+            default=not formatter.optional,
+            help=f"A{help_text} : {formatter.__doc__}",
+        )
+        parser.add_argument(
+            f"--no-{name}", action="store_false", dest=name, help=f"Dea{help_text}"
+        )
     return parser
 
 

tests/test_run.py

@@ -2,19 +2,26 @@
 import os
 import sys
 from pathlib import Path
+from typing import List
+from unittest.mock import patch
 
 import pytest
 
 import pydocstringformatter
+from pydocstringformatter.formatting import FORMATTERS
 
 
 def test_no_arguments(capsys: pytest.CaptureFixture[str]) -> None:
     """Test that we warn when no arguments are provided"""
     sys.argv = ["pydocstringformatter"]
     pydocstringformatter.run_docstring_formatter()
-    output = capsys.readouterr()
-    assert output.out.startswith("usage: pydocstringformatter [-h]")
-    assert not output.err
+    out, err = capsys.readouterr()
+    assert out.startswith("usage: pydocstringformatter [-h]")
+    assert "--beginning-quotes" in out
+    assert "Activate the beginning-quotes formatter" in out
+    assert "--no-beginning-quotes" in out
+    assert "Deactivate the beginning-quotes formatter" in out
+    assert not err
 
 
 def test_sys_agv_as_arguments(
@@ -106,3 +113,33 @@ def test_output_message_two_files(
 """
     )
     assert not output.err
+
+
+@pytest.mark.parametrize(
+    "args,should_format",
+    [
+        [[f"--no-{f.name}" for f in FORMATTERS], False],
+        [[f"--{f.name}" for f in FORMATTERS], True],
+    ],
+)
+def test_optional_checker(
+    args: List[str],
+    should_format: bool,
+    capsys: pytest.CaptureFixture[str],
+    tmp_path: Path,
+) -> None:
+    """Test that optional check are activated or not depending on options."""
+    bad_docstring = tmp_path / "bad_docstring.py"
+    bad_docstring.write_text(f'"""{"a" * 120}\n{"b" * 120}"""')
+    with patch.object(sys, "argv", ["pydocstringformatter", str(bad_docstring)] + args):
+        pydocstringformatter.run_docstring_formatter()
+    out, err = capsys.readouterr()
+    assert not err
+    if should_format:
+        msg = "Nothing was modified, but all formatters are activated."
+        assert "Nothing to do!" not in out
+        expected = ["---", "@@", "+++"]
+        assert all(e in out for e in expected), msg
+    else:
+        msg = "Something was modified, but all formatter are deactivated."
+        assert "Nothing to do!" in out, msg