Move multiline_string_handling from unstable to preview

CHANGES.md

@@ -14,6 +14,7 @@
 
 <!-- Changes that affect Black's preview style -->
 
+- Move `multiline_string_handling` from `--unstable` to `--preview` (#4760)
 - Fix bug where module docstrings would be treated as normal strings if preceeded by
   comments (#4764)
 - Fix bug where python 3.12 generics syntax split line happens weirdly (#4777)

docs/the_black_code_style/future_style.md

@@ -9,15 +9,6 @@ CLI flag. At the end of each year, these changes may be adopted into the default
 as described in [The Black Code Style](index.md). Because the functionality is
 experimental, feedback and issue reports are highly encouraged!
 
-In the past, the preview style included some features with known bugs, so that we were
-unable to move these features to the stable style. Therefore, such features are now
-moved to the `--unstable` style. All features in the `--preview` style are expected to
-make it to next year's stable style; features in the `--unstable` style will be
-stabilized only if issues with them are fixed. If bugs are discovered in a `--preview`
-feature, it is demoted to the `--unstable` style. To avoid thrash when a feature is
-demoted from the `--preview` to the `--unstable` style, users can use the
-`--enable-unstable-feature` flag to enable specific unstable features.
-
 (labels/preview-features)=
 
 Currently, the following features are included in the preview style:
@@ -40,17 +31,10 @@ Currently, the following features are included in the preview style:
 - `fix_module_docstring_detection`: Fix module docstrings being treated as normal
   strings if preceeded by comments.
 - `fix_type_expansion_split`: Fix type expansions split in generic functions.
-
-(labels/unstable-features)=
-
-The unstable style additionally includes the following features:
-
-- `string_processing`: split long string literals and related changes
-  ([see below](labels/string-processing))
 - `multiline_string_handling`: more compact formatting of expressions involving
   multiline strings ([see below](labels/multiline-string-handling))
-- `hug_parens_with_braces_and_square_brackets`: more compact formatting of nested
-  brackets ([see below](labels/hug-parens))
+- `fix_module_docstring_detection`: Fix module docstrings being treated as normal
+  strings if preceeded by comments.
 
 (labels/wrap-long-dict-values)=
 
@@ -79,6 +63,78 @@ my_dict = {
 }
 ```
 
+(labels/multiline-string-handling)=
+
+### Improved multiline string handling
+
+_Black_ is smarter when formatting multiline strings, especially in function arguments,
+to avoid introducing extra line breaks. Previously, it would always consider multiline
+strings as not fitting on a single line. With this new feature, _Black_ looks at the
+context around the multiline string to decide if it should be inlined or split to a
+separate line. For example, when a multiline string is passed to a function, _Black_
+will only split the multiline string if a line is too long or if multiple arguments are
+being passed.
+
+For example, _Black_ will reformat
+
+```python
+textwrap.dedent(
+    """\
+    This is a
+    multiline string
+"""
+)
+```
+
+to:
+
+```python
+textwrap.dedent("""\
+    This is a
+    multiline string
+""")
+```
+
+And:
+
+```python
+MULTILINE = """
+foobar
+""".replace(
+    "\n", ""
+)
+```
+
+to:
+
+```python
+MULTILINE = """
+foobar
+""".replace("\n", "")
+```
+
+## Unstable style
+
+(labels/unstable-style)=
+
+In the past, the preview style included some features with known bugs, so that we were
+unable to move these features to the stable style. Therefore, such features are now
+moved to the `--unstable` style. All features in the `--preview` style are expected to
+make it to next year's stable style; features in the `--unstable` style will be
+stabilized only if issues with them are fixed. If bugs are discovered in a `--preview`
+feature, it is demoted to the `--unstable` style. To avoid thrash when a feature is
+demoted from the `--preview` to the `--unstable` style, users can use the
+`--enable-unstable-feature` flag to enable specific unstable features.
+
+(labels/unstable-features)=
+
+The unstable style additionally includes the following features:
+
+- `hug_parens_with_braces_and_square_brackets`: more compact formatting of nested
+  brackets ([see below](labels/hug-parens))
+- `string_processing`: split long string literals and related changes
+  ([see below](labels/string-processing))
+
 (labels/hug-parens)=
 
 ### Improved multiline dictionary and list indentation for sole function parameter
@@ -160,121 +216,6 @@ foo(
 _Black_ will split long string literals and merge short ones. Parentheses are used where
 appropriate. When split, parts of f-strings that don't need formatting are converted to
 plain strings. f-strings will not be merged if they contain internal quotes and it would
-change their quotation mark style. User-made splits are respected when they do not
-exceed the line length limit. Line continuation backslashes are converted into
+change their quotation mark style. Line continuation backslashes are converted into
 parenthesized strings. Unnecessary parentheses are stripped. The stability and status of
 this feature is tracked in [this issue](https://github.com/psf/black/issues/2188).
-
-(labels/multiline-string-handling)=
-
-### Improved multiline string handling
-
-_Black_ is smarter when formatting multiline strings, especially in function arguments,
-to avoid introducing extra line breaks. Previously, it would always consider multiline
-strings as not fitting on a single line. With this new feature, _Black_ looks at the
-context around the multiline string to decide if it should be inlined or split to a
-separate line. For example, when a multiline string is passed to a function, _Black_
-will only split the multiline string if a line is too long or if multiple arguments are
-being passed.
-
-For example, _Black_ will reformat
-
-```python
-textwrap.dedent(
-    """\
-    This is a
-    multiline string
-"""
-)
-```
-
-to:
-
-```python
-textwrap.dedent("""\
-    This is a
-    multiline string
-""")
-```
-
-And:
-
-```python
-MULTILINE = """
-foobar
-""".replace(
-    "\n", ""
-)
-```
-
-to:
-
-```python
-MULTILINE = """
-foobar
-""".replace("\n", "")
-```
-
-Implicit multiline strings are special, because they can have inline comments. Strings
-without comments are merged, for example
-
-```python
-s = (
-    "An "
-    "implicit "
-    "multiline "
-    "string"
-)
-```
-
-becomes
-
-```python
-s = "An implicit multiline string"
-```
-
-A comment on any line of the string (or between two string lines) will block the
-merging, so
-
-```python
-s = (
-    "An "  # Important comment concerning just this line
-    "implicit "
-    "multiline "
-    "string"
-)
-```
-
-and
-
-```python
-s = (
-    "An "
-    "implicit "
-    # Comment in between
-    "multiline "
-    "string"
-)
-```
-
-will not be merged. Having the comment after or before the string lines (but still
-inside the parens) will merge the string. For example
-
-```python
-s = (  # Top comment
-    "An "
-    "implicit "
-    "multiline "
-    "string"
-    # Bottom comment
-)
-```
-
-becomes
-
-```python
-s = (  # Top comment
-    "An implicit multiline string"
-    # Bottom comment
-)
-```

src/black/mode.py

@@ -244,8 +244,6 @@ class Preview(Enum):
 UNSTABLE_FEATURES: set[Preview] = {
     # Many issues, see summary in https://github.com/psf/black/issues/4042
     Preview.string_processing,
-    # See issue #4159
-    Preview.multiline_string_handling,
     # See issue #4036 (crash), #4098, #4099 (proposed tweaks)
     Preview.hug_parens_with_braces_and_square_brackets,
 }

tests/data/cases/preview_multiline_strings.py

@@ -1,4 +1,4 @@
-# flags: --unstable
+# flags: --preview
 """cow
 say""",
 call(3, "dogsay", textwrap.dedent("""dove
@@ -157,24 +157,6 @@ def dastardly_default_value(
 `--global-option` is reserved to flags like `--verbose` or `--quiet`.
 """
 
-this_will_become_one_line = (
-    "a"
-    "b"
-    "c"
-)
-
-this_will_stay_on_three_lines = (
-    "a"  # comment
-    "b"
-    "c"
-)
-
-this_will_also_become_one_line = (  # comment
-    "a"
-    "b"
-    "c"
-)
-
 assert some_var == expected_result, """
 test
 """
@@ -451,16 +433,6 @@ def dastardly_default_value(
 `--global-option` is reserved to flags like `--verbose` or `--quiet`.
 """
 
-this_will_become_one_line = "abc"
-
-this_will_stay_on_three_lines = (
-    "a"  # comment
-    "b"
-    "c"
-)
-
-this_will_also_become_one_line = "abc"  # comment
-
 assert some_var == expected_result, """
 test
 """