Add line wrapping to summaries of docstrings

docs/usage.rst

@@ -11,6 +11,7 @@ Current usage of ``pydocstringformatter``:
                                 [--summary-quotes-same-line]
                                 [--split-summary-body  --no-split-summary-body]
                                 [--strip-whitespaces  --no-strip-whitespaces]
+                                [--linewrap-full-docstring  --no-linewrap-full-docstring]
                                 [--beginning-quotes  --no-beginning-quotes]
                                 [--closing-quotes  --no-closing-quotes]
                                 [--capitalize-first-letter  --no-capitalize-first-letter]
@@ -79,3 +80,7 @@ Current usage of ``pydocstringformatter``:
                             currently optional as its considered somwehat
                             opinionated and might require major refactoring for
                             existing projects. (default: False)
+      --linewrap-full-docstring, --no-linewrap-full-docstring
+                            Activate or deactivate linewrap-full-docstring:
+                            Linewrap the docstring by the pre-defined line length.
+                            (default: False)

pydocstringformatter/formatting/__init__.py

@@ -8,6 +8,7 @@
     CapitalizeFirstLetterFormatter,
     ClosingQuotesFormatter,
     FinalPeriodFormatter,
+    LineWrapperFormatter,
     QuotesTypeFormatter,
     SplitSummaryAndDocstringFormatter,
     StripWhitespacesFormatter,
@@ -21,6 +22,7 @@
 FORMATTERS: List[Formatter] = [
     SplitSummaryAndDocstringFormatter(),
     StripWhitespacesFormatter(),
+    LineWrapperFormatter(),
     BeginningQuotesFormatter(),
     ClosingQuotesFormatter(),
     CapitalizeFirstLetterFormatter(),

pydocstringformatter/formatting/base.py

@@ -101,7 +101,13 @@ class SummaryAndDescriptionFormatter(StringAndQuotesFormatter):
     """Base class for formatter that modifies the summary and description."""
 
     @abc.abstractmethod
-    def _treat_summary(self, summary: str, indent_length: int) -> str:
+    def _treat_summary(
+        self,
+        summary: str,
+        indent_length: int,
+        quotes_length: Literal[1, 3],
+        description_exists: bool,
+    ) -> str:
         """Return a modified summary."""
 
     @abc.abstractmethod
@@ -156,7 +162,9 @@ def _treat_string(
             quotes_length,
         )
 
-        new_summary = self._treat_summary(summary, indent_length)
+        new_summary = self._treat_summary(
+            summary, indent_length, quotes_length, bool(description)
+        )
         docstring = f"{quotes}{prefix}{new_summary}"
 
         if description:
@@ -173,7 +181,13 @@ class SummaryFormatter(SummaryAndDescriptionFormatter):
     """Base class for formatter that only modifies the summary of a docstring."""
 
     @abc.abstractmethod
-    def _treat_summary(self, summary: str, indent_length: int) -> str:
+    def _treat_summary(
+        self,
+        summary: str,
+        indent_length: int,
+        quotes_length: Literal[1, 3],
+        description_exists: bool,
+    ) -> str:
         """Return a modified summary."""
 
     def _treat_description(self, description: str, indent_length: int) -> str:

pydocstringformatter/formatting/formatter.py

@@ -1,4 +1,5 @@
 import re
+import textwrap
 import tokenize
 from typing import Literal
 
@@ -54,6 +55,50 @@ def _treat_string(self, tokeninfo: tokenize.TokenInfo, _: int) -> str:
         return new_string or tokeninfo.string
 
 
+class LineWrapperFormatter(SummaryFormatter):
+    """Linewrap the docstring by the pre-defined line length."""
+
+    name = "linewrap-full-docstring"
+    optional = True
+
+    def _treat_summary(
+        self,
+        summary: str,
+        indent_length: int,
+        quotes_length: Literal[1, 3],
+        description_exists: bool,
+    ) -> str:
+        """Wrap the summary of a docstring."""
+
+        # We need to deduct ending quotes if there is no description
+        line_length = 88 if description_exists else 88 - quotes_length
+        summary_lines = summary.splitlines()
+
+        new_summary = "\n".join(
+            textwrap.wrap(
+                summary_lines[0],
+                width=line_length,
+                initial_indent=" " * (indent_length + quotes_length),
+                subsequent_indent=" " * indent_length,
+                replace_whitespace=True,
+            )
+        )[indent_length + quotes_length :]
+
+        if len(summary_lines) > 1:
+            for line in summary_lines[1:]:
+                new_summary += "\n"
+                new_summary += "\n".join(
+                    textwrap.wrap(
+                        line,
+                        width=line_length,
+                        subsequent_indent=" " * indent_length,
+                        replace_whitespace=True,
+                    )
+                )
+
+        return new_summary
+
+
 class ClosingQuotesFormatter(StringFormatter):
     """Fix the position of the closing quotes."""
 
@@ -83,7 +128,13 @@ class FinalPeriodFormatter(SummaryFormatter):
     name = "final-period"
     END_OF_SENTENCE_PUNCTUATION = {".", "?", "!", "‽", ":", ";"}
 
-    def _treat_summary(self, summary: str, indent_length: int) -> str:
+    def _treat_summary(
+        self,
+        summary: str,
+        indent_length: int,
+        quotes_length: Literal[1, 3],
+        description_exists: bool,
+    ) -> str:
         """Add a period to the end of single-line docstrings and summaries."""
         if summary[-1] in self.END_OF_SENTENCE_PUNCTUATION:
             return summary
@@ -120,7 +171,13 @@ class SplitSummaryAndDocstringFormatter(SummaryFormatter):
     """Pattern to match against an end of sentence period."""
 
     # pylint: disable-next=too-many-branches
-    def _treat_summary(self, summary: str, indent_length: int) -> str:
+    def _treat_summary(
+        self,
+        summary: str,
+        indent_length: int,
+        quotes_length: Literal[1, 3],
+        description_exists: bool,
+    ) -> str:
         """Split a summary and body if there is a period after the summary."""
         new_summary = None
 

tests/data/format/linewrap_summary/function_docstrings.args

@@ -0,0 +1 @@
+--linewrap-full-docstring

tests/data/format/linewrap_summary/function_docstrings.py

@@ -0,0 +1,27 @@
+def func():
+    """A very long summary line that needs to be wrapped. A very long summary line that needs to be wrapped.
+
+    A description that is not too long.
+    """
+
+
+def func():
+    """A very long multi-line summary line that needs to be wrapped. A very long multi-line summary line that needs to be wrapped.
+    A very long summary line that needs to be wrapped.
+
+    A description that is not too long.
+    """
+
+
+def func():
+    """A multi-line summary that can be on one line.
+    But it has a new line so it isn't.
+
+    A description that is not too long.
+    """
+
+
+# Since the ending quotes will be appended on the same line this
+# exceeds the max length.
+def func():
+    """A multi-line summary that can be on one line. Something that is just too longgg."""

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

@@ -0,0 +1,31 @@
+def func():
+    """A very long summary line that needs to be wrapped. A very long summary line that
+    needs to be wrapped.
+
+    A description that is not too long.
+    """
+
+
+def func():
+    """A very long multi-line summary line that needs to be wrapped. A very long multi-
+    line summary line that needs to be wrapped.
+    A very long summary line that needs to be wrapped.
+
+    A description that is not too long.
+    """
+
+
+def func():
+    """A multi-line summary that can be on one line.
+    But it has a new line so it isn't.
+
+    A description that is not too long.
+    """
+
+
+# Since the ending quotes will be appended on the same line this
+# exceeds the max length.
+def func():
+    """A multi-line summary that can be on one line. Something that is just too
+    longgg.
+    """