From 7edb50f5a0afc56bb648dc14640ced144366b43a Mon Sep 17 00:00:00 2001
From: Brandon J <153339574+veryslowcode@users.noreply.github.com>
Date: Mon, 5 Feb 2024 05:56:07 -0700
Subject: [PATCH] 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                                    |  2 ++
 docs/the_black_code_style/future_style.md     |  2 ++
 src/black/linegen.py                          | 13 ++++++++++---
 src/black/mode.py                             |  1 +
 src/black/resources/black.schema.json         |  3 ++-
 tests/data/cases/docstring_newline_preview.py |  4 ++++
 6 files changed, 21 insertions(+), 4 deletions(-)
 create mode 100644 tests/data/cases/docstring_newline_preview.py

diff --git a/CHANGES.md b/CHANGES.md
index 4d646a2779e..a726a91457a 100644
--- a/CHANGES.md
+++ b/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
 
diff --git a/docs/the_black_code_style/future_style.md b/docs/the_black_code_style/future_style.md
index 86e5aa806b2..d7640765b30 100644
--- a/docs/the_black_code_style/future_style.md
+++ b/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)=
 
diff --git a/src/black/linegen.py b/src/black/linegen.py
index c74ff9c0b4b..c45a1308013 100644
--- a/src/black/linegen.py
+++ b/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[-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:
diff --git a/src/black/mode.py b/src/black/mode.py
index 5738bd6b793..9593a90d170 100644
--- a/src/black/mode.py
+++ b/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] = {
diff --git a/src/black/resources/black.schema.json b/src/black/resources/black.schema.json
index 40bf39137f7..5b1b1320eb4 100644
--- a/src/black/resources/black.schema.json
+++ b/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."
diff --git a/tests/data/cases/docstring_newline_preview.py b/tests/data/cases/docstring_newline_preview.py
new file mode 100644
index 00000000000..5c129ca5f80
--- /dev/null
+++ b/tests/data/cases/docstring_newline_preview.py
@@ -0,0 +1,4 @@
+# flags: --preview
+"""
+87 characters ............................................................................
+"""