Merge branch 'main' into issue_4149

Author: JelleZijlstra

.github/workflows/pypi_upload.yml

@@ -89,7 +89,7 @@ jobs:
 
     steps:
       - uses: actions/checkout@v4
-      - uses: pypa/[email protected].4
+      - uses: pypa/[email protected].5
         with:
           only: ${{ matrix.only }}
 

CHANGES.md

@@ -18,6 +18,8 @@
   due to an outstanding crash and proposed formatting tweaks (#4198)
 - Fixed a bug where base expressions caused inconsistent formatting of \*\* in tenary
   expression (#4154)
+- Checking for newline before adding one on docstring that is almost at the line limit
+  (#4185)
 
 ### Configuration
 

docs/requirements.txt

@@ -6,4 +6,4 @@ Sphinx==7.2.6
 docutils==0.20.1
 sphinxcontrib-programoutput==0.17
 sphinx_copybutton==0.5.2
-furo==2023.9.10
+furo==2024.1.29

docs/the_black_code_style/future_style.md

@@ -30,6 +30,8 @@ Currently, the following features are included in the preview style:
   parameters
 - `is_simple_lookup_for_doublestar_expression`: fix line length computation for certain
   expressions that involve the power operator
+- `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
-                # 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:

src/black/mode.py

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

src/black/resources/black.schema.json

@@ -86,7 +86,8 @@
           "wrap_long_dict_values_in_parens",
           "multiline_string_handling",
           "typed_params_trailing_comma",
-          "is_simple_lookup_for_doublestar_expression"
+          "is_simple_lookup_for_doublestar_expression",
+          "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 ............................................................................
+"""