Add formatter of final period for single line docstrings and summaries

Author: DanielNoord

README.md

@@ -66,7 +66,7 @@ multi-line docstring
 """
 ```
 
-**PEP 256: _The closing quotes are on the same line as the opening quotes_**
+**PEP 257: _The closing quotes are on the same line as the opening quotes_**
 
 For consistency this rule also gets applied to multi-line docstrings
 
@@ -93,6 +93,28 @@ multi-line docstring
 """
 ```
 
+**PEP 257: _The docstring is a phrase ending in a period & Multi-line docstrings consist
+of a summary line just like a one-line docstring_**
+
+```python
+# Bad
+"""My docstring"""
+
+"""Summary
+
+My docstring
+"""
+
+
+# Good
+"""My docstring."""
+
+"""Summary.
+
+My docstring
+"""
+```
+
 ## Development
 
 For development and contributing guidelines please see

pydocstringformatter/formatting/__init__.py

@@ -6,9 +6,11 @@
 from pydocstringformatter.formatting.formatter import (
     BeginningQuotesFormatter,
     ClosingQuotesFormatter,
+    FinalPeriodFormatter,
 )
 
 FORMATTERS: List[Formatter] = [
     BeginningQuotesFormatter(),
     ClosingQuotesFormatter(),
+    FinalPeriodFormatter(),
 ]

pydocstringformatter/formatting/formatter.py

@@ -37,3 +37,32 @@ def _treat_string(self, tokeninfo: tokenize.TokenInfo) -> str:
         elif len(split_string) == 2 and split_string[-1] == good_end:
             new_string = "\n".join(split_string[:-1]) + tokeninfo.string[0] * 3
         return new_string
+
+
+class FinalPeriodFormatter(StringFormatter):
+    """Add a period to the end of single line docstrings and summaries."""
+
+    name = "final-period"
+
+    def _treat_string(self, tokeninfo: tokenize.TokenInfo) -> str:
+        """Add a period to the end of single-line docstrings and summaries."""
+        # Handle single line docstrings
+        if not tokeninfo.string.count("\n"):
+            if tokeninfo.string[-4] != ".":
+                return tokeninfo.string[:-3] + "." + tokeninfo.string[-3:]
+        # Handle multi-line docstrings
+        else:
+            first_linebreak = tokeninfo.string.index("\n")
+            # If first linebreak is followed by another we're dealing with a summary
+            if tokeninfo.string[tokeninfo.string.index("\n") + 1] == "\n":
+                if tokeninfo.string[first_linebreak - 1] != ".":
+                    return (
+                        tokeninfo.string[:first_linebreak]
+                        + "."
+                        + tokeninfo.string[first_linebreak:]
+                    )
+            # pylint: disable=fixme
+            # TODO: Handle multi-line docstrings that do not have a summary
+            # This is obviously dependent on whether 'pydocstringformatter' will
+            # start enforcing summaries :)
+        return tokeninfo.string

tests/data/format/final_period/class_docstring.py

@@ -0,0 +1,29 @@
+class MyClass:
+    """Docstring"""
+
+    class InnerClass:
+        """Docstring"""
+
+
+class MyClass:
+    """A multi-line
+    docstring
+    """
+
+    class InnerClass:
+        """A multi-line
+        docstring
+        """
+
+
+class MyClass:
+    """Summary
+
+    docstring
+    """
+
+    class InnerClass:
+        """Summary
+
+        docstring
+        """

tests/data/format/final_period/class_docstring.py.out

@@ -0,0 +1,29 @@
+class MyClass:
+    """Docstring."""
+
+    class InnerClass:
+        """Docstring."""
+
+
+class MyClass:
+    """A multi-line
+    docstring
+    """
+
+    class InnerClass:
+        """A multi-line
+        docstring
+        """
+
+
+class MyClass:
+    """Summary.
+
+    docstring
+    """
+
+    class InnerClass:
+        """Summary.
+
+        docstring
+        """

tests/data/format/final_period/function_docstrings.py

@@ -0,0 +1,29 @@
+def func()
+    """Docstring"""
+
+    def inner_func()
+        """Docstring"""
+
+
+def func()
+    """A multi-line
+    docstring
+    """
+
+    def inner_func()
+        """A multi-line
+        docstring
+        """
+
+
+def func()
+    """Summary
+
+    docstring
+    """
+
+    def inner_func()
+        """Summary
+
+        docstring
+        """

tests/data/format/final_period/function_docstrings.py.out

@@ -0,0 +1,29 @@
+def func()
+    """Docstring."""
+
+    def inner_func()
+        """Docstring."""
+
+
+def func()
+    """A multi-line
+    docstring
+    """
+
+    def inner_func()
+        """A multi-line
+        docstring
+        """
+
+
+def func()
+    """Summary.
+
+    docstring
+    """
+
+    def inner_func()
+        """Summary.
+
+        docstring
+        """

tests/data/format/final_period/module_docstring.py

@@ -0,0 +1,10 @@
+"""Docstring"""
+
+"""A multi-line
+docstring
+"""
+
+"""Summary
+
+docstring
+"""

tests/data/format/final_period/module_docstring.py.out

@@ -0,0 +1,10 @@
+"""Docstring."""
+
+"""A multi-line
+docstring
+"""
+
+"""Summary.
+
+docstring
+"""

tests/data/format/final_period/variable_docstring.py

@@ -0,0 +1,13 @@
+MYVAR = 1
+"""Docstring"""
+
+MYVAR = 1
+"""A multi-line
+docstring
+"""
+
+MYVAR = 1
+"""Summary
+
+A docstring
+"""