Add an external formatter API to be able to launch Run with custom formatters

pydocstringformatter/formatting/__init__.py

@@ -1,4 +1,4 @@
-__all__ = ["FORMATTERS"]
+__all__ = ["FORMATTERS", "Formatter"]
 
 from typing import List
 

pydocstringformatter/run.py

@@ -6,23 +6,28 @@
 import sys
 import tokenize
 from pathlib import Path
-from typing import List, Union
+from typing import List, Optional, Union
 
 from pydocstringformatter import __version__, formatting, utils
 
 
 class _Run:
     """Main class that represent a run of the program."""
 
-    def __init__(self, argv: Union[List[str], None]) -> None:
+    def __init__(
+        self,
+        argv: Union[List[str], None],
+        formatters: Optional[List[formatting.Formatter]] = None,
+    ) -> None:
+        if formatters is None:
+            formatters = formatting.FORMATTERS
+        self.formatters = formatters
         self.arg_parser = utils._register_arguments(__version__)
-        utils._register_arguments_formatters(self.arg_parser, formatting.FORMATTERS)
+        utils._register_arguments_formatters(self.arg_parser, self.formatters)
         self.config = argparse.Namespace()
 
         if argv := argv or sys.argv[1:]:
-            utils._parse_options(
-                self.arg_parser, self.config, argv, formatting.FORMATTERS
-            )
+            utils._parse_options(self.arg_parser, self.config, argv, self.formatters)
             self._check_files(self.config.files)
         else:
             self.arg_parser.print_help()

tests/test_run.py

@@ -2,12 +2,14 @@
 import os
 import sys
 from pathlib import Path
+from tokenize import TokenInfo
 from typing import List
 
 import pytest
 
 import pydocstringformatter
-from pydocstringformatter.formatting import FORMATTERS
+from pydocstringformatter.formatting import FORMATTERS, Formatter
+from pydocstringformatter.run import _Run
 
 
 def test_no_arguments(capsys: pytest.CaptureFixture[str]) -> None:
@@ -116,6 +118,28 @@ def test_output_message_two_files(
     assert not output.err
 
 
+def test_optional_formatter(capsys: pytest.CaptureFixture[str]) -> None:
+    """If a Formatter is optional we handle that in _load_default_formatter."""
+
+    class OptionalFormatter(Formatter):
+        """Non-optional docstring."""
+
+        optional = True
+        name = "optional-formatter"
+
+        def treat_token(self, tokeninfo: TokenInfo) -> TokenInfo:
+            """This does nothing"""
+            return tokeninfo
+
+    with pytest.raises(SystemExit):
+        _Run(argv=["--help"], formatters=[OptionalFormatter()])
+    out, err = capsys.readouterr()
+    assert not err
+    assert "--optional-formatter" in out
+    assert "optional docstring." in out
+    assert "--no-optional-formatter" in out
+
+
 @pytest.mark.parametrize(
     "args,should_format",
     [