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

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>

CHANGES.md

@@ -16,6 +16,8 @@
 
 - Move the `hug_parens_with_braces_and_square_brackets` feature to the unstable style
   due to an outstanding crash and proposed formatting tweaks (#4198)
+- Checking for newline before adding one on docstring that is almost at the line limit
+  (#4185)
 
 ### Configuration
 

docs/the_black_code_style/future_style.md

@@ -28,6 +28,8 @@ Currently, the following features are included in the preview style:
   longer normalized
 - `typed_params_trailing_comma`: consistently add trailing commas to typed function
   parameters
+- `docstring_check_for_newline`: checks if there is a newline before the terminating
+  quotes of a docstring
 
 (labels/unstable-features)=
 

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
+                # the maximum line length, and the closing quote is not
-                # closing quotes
+                # 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[-1 - quote_len] == "\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] = {

src/black/resources/black.schema.json

@@ -85,7 +85,8 @@
           "no_normalize_fmt_skip_whitespace",
           "wrap_long_dict_values_in_parens",
           "multiline_string_handling",
-          "typed_params_trailing_comma"
+          "typed_params_trailing_comma",
+          "docstring_check_for_newline"
         ]
       },
       "description": "Enable specific features included in the `--unstable` style. Requires `--preview`. No compatibility guarantees are provided on the behavior or existence of any unstable features."

tests/data/cases/docstring_newline_preview.py

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