Add a name and an optional attribute to Formatters (#18)

Author: Pierre-Sassoulas

.github/CONTRIBUTING.md

@@ -1,7 +1,15 @@
 ## Development
 
+### Linting
+
 Use `pre-commit install` to install the pre-commit hook for the repository.
 
+### Creating a new formatter
+
+- 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.
+
 ### Testing
 
 To run all the tests:

pydocstringformatter/formatting/__init__.py

@@ -1,11 +1,14 @@
 __all__ = ["FORMATTERS"]
 
+from typing import List
+
+from pydocstringformatter.formatting.base import Formatter
 from pydocstringformatter.formatting.formatter import (
     BeginningQuotesFormatter,
     ClosingQuotesFormatter,
 )
 
-FORMATTERS = [
+FORMATTERS: List[Formatter] = [
     BeginningQuotesFormatter(),
     ClosingQuotesFormatter(),
 ]

pydocstringformatter/formatting/base.py

@@ -5,6 +5,18 @@
 class Formatter:
     """Base class for docstring formatter."""
 
+    optional = False
+
+    @property
+    @abc.abstractmethod
+    def name(self) -> str:
+        """Name of the Formatter.
+
+        This will be used to create argparse options when added to
+        'pydocstringformatter.formatting.FORMATTERS'. Therefore, it is
+        user-facing and should be chosen carefully.
+        """
+
     @abc.abstractmethod
     def treat_token(self, tokeninfo: tokenize.TokenInfo) -> tokenize.TokenInfo:
         """Return a modified token."""

pydocstringformatter/formatting/formatter.py

@@ -7,6 +7,8 @@
 class BeginningQuotesFormatter(StringFormatter):
     """Fix the position of the opening quotes"""
 
+    name = "beginning-quotes"
+
     def _treat_string(self, tokeninfo: tokenize.TokenInfo) -> str:
         new_string = tokeninfo.string
         if new_string[3] == "\n":
@@ -17,6 +19,8 @@ def _treat_string(self, tokeninfo: tokenize.TokenInfo) -> str:
 class ClosingQuotesFormatter(StringFormatter):
     """Fix the position of the closing quotes"""
 
+    name = "closing-quotes"
+
     def _treat_string(self, tokeninfo: tokenize.TokenInfo) -> str:
         """Fix the position of end quotes for multi-line docstrings"""
         new_string = tokeninfo.string

tests/test_formatter.py

@@ -0,0 +1,14 @@
+from typing import Set
+
+from pydocstringformatter.formatting import FORMATTERS
+
+
+def test_formatter_names() -> None:
+    """Test that each formatter name exists and is unique."""
+    formatter_names: Set[str] = set()
+    for formatter in FORMATTERS:
+        assert formatter.name, "Each formatter should have a name set."
+        assert (
+            formatter.name not in formatter_names
+        ), "Each formatter should have an unique name."
+        formatter_names.add(formatter.name)