Docstring too long (issue #1632 fix)

CHANGES.md

@@ -17,6 +17,7 @@
 
 <!-- Changes that affect Black's preview style -->
 
+- Fixed bug where docstrings with triple quotes could exceed max line length (#3044)
 - Remove redundant parentheses around awaited objects (#2991)
 - Parentheses around return annotations are now managed (#2990)
 - Remove unnecessary parentheses from `with` statements (#2926)

src/black/linegen.py

@@ -305,9 +305,9 @@ def visit_STRING(self, leaf: Leaf) -> Iterator[Line]:
             quote_len = 1 if docstring[1] != quote_char else 3
             docstring = docstring[quote_len:-quote_len]
             docstring_started_empty = not docstring
+            indent = " " * 4 * self.current_line.depth
 
             if is_multiline_string(leaf):
-                indent = " " * 4 * self.current_line.depth
                 docstring = fix_docstring(docstring, indent)
             else:
                 docstring = docstring.strip()
@@ -329,7 +329,24 @@ def visit_STRING(self, leaf: Leaf) -> Iterator[Line]:
 
             # We could enforce triple quotes at this point.
             quote = quote_char * quote_len
-            leaf.value = prefix + quote + docstring + quote
+
+            if Preview.long_docstring_quotes_on_newline in self.mode:
+                leaf.value = prefix + quote + docstring + quote
+            else:
+                # Put closing quotes on new line if max line length exceeded
+                last_line_length = len(docstring.splitlines()[-1]) if docstring else 0
+
+                # Make the docstring apart from the closing quotes, which happen below
+                docstring = prefix + quote + docstring
+                if (
+                    len(indent) + len(prefix) + 2 * len(quote) + last_line_length
+                    <= self.mode.line_length
+                ):
+                    docstring += quote
+                else:
+                    docstring += "\n" + indent + quote
+
+                leaf.value = docstring
 
         yield from self.visit_default(leaf)
 

src/black/mode.py

@@ -147,6 +147,7 @@ class Preview(Enum):
     remove_redundant_parens = auto()
     one_element_subscript = auto()
     annotation_parens = auto()
+    long_docstring_quotes_on_newline = auto()
 
 
 class Deprecated(UserWarning):

tests/data/docstring.py

@@ -188,6 +188,22 @@ def my_god_its_full_of_stars_2():
     "I'm sorry Dave "
 
 
+def docstring_almost_at_line_limit():
+    """long docstring.................................................................
+    """
+
+
+def docstring_almost_at_line_limit2():
+    """long docstring.................................................................
+
+    ..................................................................................
+    """
+
+
+def docstring_at_line_limit():
+    """long docstring................................................................"""
+
+
 # output
 
 class MyClass:
@@ -375,3 +391,19 @@ def my_god_its_full_of_stars_1():
 # the space below is actually a \u2001, removed in output
 def my_god_its_full_of_stars_2():
     "I'm sorry Dave"
+
+
+def docstring_almost_at_line_limit():
+    """long docstring.................................................................
+    """
+
+
+def docstring_almost_at_line_limit2():
+    """long docstring.................................................................
+
+    ..................................................................................
+    """
+
+
+def docstring_at_line_limit():
+    """long docstring................................................................"""