From d115ad81203ae3f7eac682aa040c2e7e5d8cca24 Mon Sep 17 00:00:00 2001
From: Pierre Sassoulas <pierre.sassoulas@gmail.com>
Date: Tue, 4 Jan 2022 21:50:21 +0100
Subject: [PATCH] Add a name and an optional attribute to Formatters

---
 .github/CONTRIBUTING.md                      |  8 ++++++++
 pydocstringformatter/formatting/__init__.py  |  5 ++++-
 pydocstringformatter/formatting/base.py      | 12 ++++++++++++
 pydocstringformatter/formatting/formatter.py |  4 ++++
 tests/test_formatter.py                      | 14 ++++++++++++++
 5 files changed, 42 insertions(+), 1 deletion(-)
 create mode 100644 tests/test_formatter.py

diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
index 7cb3b46f..daf9c447 100644
--- a/.github/CONTRIBUTING.md
+++ b/.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:
diff --git a/pydocstringformatter/formatting/__init__.py b/pydocstringformatter/formatting/__init__.py
index 87e2d52c..f1ba0fe7 100644
--- a/pydocstringformatter/formatting/__init__.py
+++ b/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(),
 ]
diff --git a/pydocstringformatter/formatting/base.py b/pydocstringformatter/formatting/base.py
index 241f5179..9edcbe73 100644
--- a/pydocstringformatter/formatting/base.py
+++ b/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."""
diff --git a/pydocstringformatter/formatting/formatter.py b/pydocstringformatter/formatting/formatter.py
index f1a8668a..56001e6d 100644
--- a/pydocstringformatter/formatting/formatter.py
+++ b/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
diff --git a/tests/test_formatter.py b/tests/test_formatter.py
new file mode 100644
index 00000000..fe4e0e1a
--- /dev/null
+++ b/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)