Add SplitSummaryAndDocstringFormatter and update testutils

README.md

@@ -126,6 +126,24 @@ My docstring
 """
 ```
 
+**PEP 257: _Multi-line docstrings consist of a summary line just like a one-line
+docstring, followed by a blank line, followed by a more elaborate description._**
+
+```python
+# Bad
+"""Summary. Body."""
+
+"""Summary.
+   Body.
+   """
+
+# Good
+"""Summary.
+
+   Body.
+   """
+```
+
 ## Development
 
 For development and contributing guidelines please see

pydocstringformatter/formatting/__init__.py

@@ -7,9 +7,16 @@
     BeginningQuotesFormatter,
     ClosingQuotesFormatter,
     FinalPeriodFormatter,
+    SplitSummaryAndDocstringFormatter,
 )
 
+# The order of these formatters is important as they are called in order.
+# The order is currently:
+#   String manipulation such as adding extra new lines
+#   Determine if multi-line or single line and position quotes accordingly
+#   String manipulation in which being multi-line or single line matters
 FORMATTERS: List[Formatter] = [
+    SplitSummaryAndDocstringFormatter(),
     BeginningQuotesFormatter(),
     ClosingQuotesFormatter(),
     FinalPeriodFormatter(),

pydocstringformatter/formatting/base.py

@@ -36,13 +36,13 @@ class StringFormatter(Formatter):
     """Base class for formatter that only modifies the string content."""
 
     @abc.abstractmethod
-    def _treat_string(self, tokeninfo: tokenize.TokenInfo) -> str:
+    def _treat_string(self, tokeninfo: tokenize.TokenInfo, indent_length: int) -> str:
         """Return a modified string."""
 
     def treat_token(self, tokeninfo: tokenize.TokenInfo) -> tokenize.TokenInfo:
         return tokenize.TokenInfo(
             tokeninfo.type,
-            self._treat_string(tokeninfo),
+            self._treat_string(tokeninfo, tokeninfo.start[1]),
             tokeninfo.start,
             tokeninfo.end,
             tokeninfo.line,

pydocstringformatter/formatting/formatter.py

@@ -9,7 +9,7 @@ class BeginningQuotesFormatter(StringFormatter):
 
     name = "beginning-quotes"
 
-    def _treat_string(self, tokeninfo: tokenize.TokenInfo) -> str:
+    def _treat_string(self, tokeninfo: tokenize.TokenInfo, _: int) -> str:
         new_string = tokeninfo.string
         if new_string[3] == "\n":
             new_string = re.sub(r"\n *", "", new_string, 1)
@@ -21,7 +21,7 @@ class ClosingQuotesFormatter(StringFormatter):
 
     name = "closing-quotes"
 
-    def _treat_string(self, tokeninfo: tokenize.TokenInfo) -> str:
+    def _treat_string(self, tokeninfo: tokenize.TokenInfo, _: int) -> str:
         """Fix the position of end quotes for multi-line docstrings."""
         new_string = tokeninfo.string
         if "\n" not in new_string:
@@ -44,7 +44,7 @@ class FinalPeriodFormatter(StringFormatter):
 
     name = "final-period"
 
-    def _treat_string(self, tokeninfo: tokenize.TokenInfo) -> str:
+    def _treat_string(self, tokeninfo: tokenize.TokenInfo, _: int) -> str:
         """Add a period to the end of single-line docstrings and summaries."""
         # Handle single line docstrings
         if not tokeninfo.string.count("\n"):
@@ -65,3 +65,41 @@ def _treat_string(self, tokeninfo: tokenize.TokenInfo) -> str:
             # This is obviously dependent on whether 'pydocstringformatter' will
             # start enforcing summaries :)
         return tokeninfo.string
+
+
+class SplitSummaryAndDocstringFormatter(StringFormatter):
+    """Split the summary and body of a docstring based on a period in between them.
+
+    This formatter is currently optional as its considered somwehat opinionated
+    and might require major refactoring for existing projects.
+    """
+
+    name = "split-summary-body"
+    optional = True
+
+    def _treat_string(self, tokeninfo: tokenize.TokenInfo, indent_length: int) -> str:
+        """Split a summary and body if there is a period after the summary."""
+        if index := tokeninfo.string.find("."):
+            if (
+                index not in (-1, len(tokeninfo.string) - 4)
+                and "\n" not in tokeninfo.string[:index]  # Skip multi-line summaries
+            ):
+                # Handle summary with part of docstring body on same line
+                if tokeninfo.string[index + 1] == " ":
+                    return (
+                        tokeninfo.string[:index]
+                        + f".\n\n{' ' * indent_length}"
+                        + tokeninfo.string[index + 2 :]
+                    )
+
+                # Handle summary with part of docstring body on same line
+                if (
+                    tokeninfo.string[index + 1] == "\n"
+                    and tokeninfo.string[index + 2] != "\n"
+                ):
+                    return (
+                        tokeninfo.string[:index]
+                        + ".\n\n"
+                        + tokeninfo.string[index + 2 :]
+                    )
+        return tokeninfo.string

tests/data/format/summary_splitter/class_docstring.args

@@ -0,0 +1 @@
+--split-summary-body

tests/data/format/summary_splitter/class_docstring.py

@@ -0,0 +1,34 @@
+class MyClass:
+    """Summary. Body."""
+
+    class InnerClass:
+        """Summary. Body."""
+
+
+class MyClass:
+    """Summary without period Body."""
+
+    class InnerClass:
+        """Summary without period Body."""
+
+
+class MyClass:
+    """Summary. Body without period"""
+
+    class InnerClass:
+        """Summary. Body without period"""
+
+
+class MyClass:
+    """Summary.
+    Body without period"""
+
+    class InnerClass:
+        """Summary.
+        Body without period"""
+
+
+class MyClass:
+    """Summary over multiple
+    lines.
+    """

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

@@ -0,0 +1,50 @@
+class MyClass:
+    """Summary.
+
+    Body.
+    """
+
+    class InnerClass:
+        """Summary.
+
+        Body.
+        """
+
+
+class MyClass:
+    """Summary without period Body."""
+
+    class InnerClass:
+        """Summary without period Body."""
+
+
+class MyClass:
+    """Summary.
+
+    Body without period
+    """
+
+    class InnerClass:
+        """Summary.
+
+        Body without period
+        """
+
+
+class MyClass:
+    """Summary.
+
+    Body without period
+    """
+
+    class InnerClass:
+        """Summary.
+
+        Body without period
+        """
+
+
+class MyClass:
+    """Summary over multiple
+    lines.
+    """

tests/data/format/summary_splitter/function_docstrings.args

@@ -0,0 +1 @@
+--split-summary-body

tests/data/format/summary_splitter/function_docstrings.py

@@ -0,0 +1,28 @@
+def func():
+    """Summary. Body."""
+
+    def inner_func():
+        """Summary. Body."""
+
+
+def func():
+    """Summary without period Body."""
+
+    def inner_func():
+        """Summary without period Body."""
+
+
+def func():
+    """Summary. Body without period"""
+
+    def inner_func():
+        """Summary. Body without period"""
+
+
+def func():
+    """Summary.
+    Body without period"""
+
+    def inner_func():
+        """Summary.
+        Body without period"""

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

@@ -0,0 +1,44 @@
+def func():
+    """Summary.
+
+    Body.
+    """
+
+    def inner_func():
+        """Summary.
+
+        Body.
+        """
+
+
+def func():
+    """Summary without period Body."""
+
+    def inner_func():
+        """Summary without period Body."""
+
+
+def func():
+    """Summary.
+
+    Body without period
+    """
+
+    def inner_func():
+        """Summary.
+
+        Body without period
+        """
+
+
+def func():
+    """Summary.
+
+    Body without period
+    """
+
+    def inner_func():
+        """Summary.
+
+        Body without period
+        """

tests/data/format/summary_splitter/module_docstring.args

@@ -0,0 +1 @@
+--split-summary-body

tests/data/format/summary_splitter/module_docstring.py

@@ -0,0 +1,8 @@
+"""Summary. Body."""
+
+"""Summary without period Body."""
+
+"""Summary. Body without period"""
+
+"""Summary.
+Body without period"""

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

@@ -0,0 +1,16 @@
+"""Summary.
+
+Body.
+"""
+
+"""Summary without period Body."""
+
+"""Summary.
+
+Body without period
+"""
+
+"""Summary.
+
+Body without period
+"""

tests/data/format/summary_splitter/variable_docstring.args

@@ -0,0 +1 @@
+--split-summary-body

tests/data/format/summary_splitter/variable_docstring.py

@@ -0,0 +1,12 @@
+MYVAR = 1
+"""Summary. Body."""
+
+MYVAR = 1
+"""Summary without period Body."""
+
+MYVAR = 1
+"""Summary. Body without period"""
+
+MYVAR = 1
+"""Summary.
+Body without period"""

tests/data/format/summary_splitter/variable_docstring.py.out

@@ -0,0 +1,20 @@
+MYVAR = 1
+"""Summary.
+
+Body.
+"""
+
+MYVAR = 1
+"""Summary without period Body."""
+
+MYVAR = 1
+"""Summary.
+
+Body without period
+"""
+
+MYVAR = 1
+"""Summary.
+
+Body without period
+"""

tests/test_formatting.py

@@ -46,7 +46,15 @@ def test_formatting(
     with open(temp_file_name, "w", encoding="utf-8") as temp_file:
         temp_file.writelines(original_lines)
 
-    pydocstringformatter.run_docstring_formatter([temp_file_name, "--write"])
+    # Get any additional args as specified by an .args file
+    additional_args: List[str] = []
+    if os.path.exists(test_file.replace(".py", ".args")):
+        with open(test_file.replace(".py", ".args"), encoding="utf-8") as args_file:
+            additional_args = args_file.readlines()[0].split()
+
+    pydocstringformatter.run_docstring_formatter(
+        [temp_file_name, "--write"] + additional_args
+    )
 
     output = capsys.readouterr()
     assert not output.err

tests/test_run.py

@@ -7,6 +7,7 @@
 
 import pydocstringformatter
 from pydocstringformatter.formatting import FORMATTERS
+from pydocstringformatter.formatting.formatter import SplitSummaryAndDocstringFormatter
 from pydocstringformatter.testutils import FormatterAsserter
 
 
@@ -125,3 +126,14 @@ def test_begin_quote_formatters(
     ) as asserter:
         asserter.assert_format_when_activated()
         asserter.assert_no_change_when_deactivated()
+
+
+def test_optional_formatters_argument(
+    capsys: pytest.CaptureFixture[str], tmp_path: Path
+) -> None:
+    """Test that an optional formatter is correctly turned on and off with arguments."""
+    with FormatterAsserter(
+        '"""Summary. Body."""', [SplitSummaryAndDocstringFormatter()], capsys, tmp_path
+    ) as asserter:
+        asserter.assert_format_when_activated()
+        asserter.assert_no_change_when_deactivated()