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 ............................................................................ +"""