fix: additional newline added to docstring when the previous line length is less than the line length limit minus 1

CHANGES.md

@@ -14,6 +14,9 @@
 
 <!-- Changes that affect Black's preview style -->
 
+- Checking for newline before adding one on docstring that is almost at the line limit
+  (#4185)
+
 ### Configuration
 
 <!-- Changes to how Black can be configured -->

src/black/linegen.py

@@ -477,15 +477,22 @@ def visit_STRING(self, leaf: Leaf) -> Iterator[Line]:
                 last_line_length = len(lines[-1]) if docstring else 0
 
                 # If adding closing quotes would cause the last line to exceed
-                # the maximum line length then put a line break before the
-                # closing quotes
+                # the maximum line length, and the closing quote is not
+                # prefixed by a newline then put a line break before
+                # the closing quotes
                 if (
                     len(lines) > 1
                     and last_line_length + quote_len > self.mode.line_length
                     and len(indent) + quote_len <= self.mode.line_length
                     and not has_trailing_backslash
                 ):
-                    leaf.value = prefix + quote + docstring + "\n" + indent + quote
+                    if (
+                        Preview.docstring_check_for_newline in self.mode
+                        and leaf.value[-4] == "\n"
+                    ):
+                        leaf.value = prefix + quote + docstring + quote
+                    else:
+                        leaf.value = prefix + quote + docstring + "\n" + indent + quote
                 else:
                     leaf.value = prefix + quote + docstring + quote
             else:

src/black/mode.py

@@ -177,6 +177,7 @@ class Preview(Enum):
     wrap_long_dict_values_in_parens = auto()
     multiline_string_handling = auto()
     typed_params_trailing_comma = auto()
+    docstring_check_for_newline = auto()
 
 
 UNSTABLE_FEATURES: Set[Preview] = {

tests/data/cases/docstring_newline_preview.py

@@ -0,0 +1,4 @@
+# flags: --preview
+"""
+87 characters ............................................................................
+"""