Deprecate ESP and move the functionality under --preview (#2789)

diff --git a/CHANGES.md b/CHANGES.md
index 4b9ceae81dc54c518878a7a1c62019351e89780a..c3e2a3350d3978e180b2ca412d1257e409e82349 100644 (file)
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -30,6 +30,8 @@
 - Fix handling of standalone `match()` or `case()` when there is a trailing newline or a
   comment inside of the parentheses. (#2760)
 - Black now normalizes string prefix order (#2297)
 - Fix handling of standalone `match()` or `case()` when there is a trailing newline or a
   comment inside of the parentheses. (#2760)
 - Black now normalizes string prefix order (#2297)

+- Deprecate `--experimental-string-processing` and move the functionality under
+  `--preview` (#2789)

 
 ### Packaging
 
 
 ### Packaging
 


@@ -38,7 +40,8 @@
 
 ### Preview style
 
 
 ### Preview style
 

-- Introduce the `--preview` flag with no style changes (#2752)
+- Introduce the `--preview` flag (#2752)
+- Add `--experimental-string-processing` to the preview style (#2789)

 
 ### Integrations
 
 
 ### Integrations
 

diff --git a/docs/faq.md b/docs/faq.md
index c7d5ec33ad9dd1a0f17b21b75a7792b4453b04e8..94a978d826f397f58aa0ba004def5c3f609cf335 100644 (file)
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -33,7 +33,7 @@ still proposed on the issue tracker. See
 
 Starting in 2022, the formatting output will be stable for the releases made in the same
 year (other than unintentional bugs). It is possible to opt-in to the latest formatting
 
 Starting in 2022, the formatting output will be stable for the releases made in the same
 year (other than unintentional bugs). It is possible to opt-in to the latest formatting

-styles, using the `--future` flag.
+styles, using the `--preview` flag.

 
 ## Why is my file not formatted?
 
 
 ## Why is my file not formatted?
 

diff --git a/docs/the_black_code_style/current_style.md b/docs/the_black_code_style/current_style.md
index 11fe2c8cceb6fe84b8690b102b73fb410328090e..1d1e42e75c85ea06442258e4facf9d11cae84ff0 100644 (file)
--- a/docs/the_black_code_style/current_style.md
+++ b/docs/the_black_code_style/current_style.md
@@ -10,6 +10,10 @@ with `# fmt: off` and end with `# fmt: on`, or lines that ends with `# fmt: skip
 [YAPF](https://github.com/google/yapf)'s block comments to the same effect, as a
 courtesy for straddling code.
 
 [YAPF](https://github.com/google/yapf)'s block comments to the same effect, as a
 courtesy for straddling code.
 

+The rest of this document describes the current formatting style. If you're interested
+in trying out where the style is heading, see [future style](./future_style.md) and try
+running `black --preview`.
+

 ### How _Black_ wraps lines
 
 _Black_ ignores previous formatting and applies uniform horizontal and vertical
 ### How _Black_ wraps lines
 
 _Black_ ignores previous formatting and applies uniform horizontal and vertical


@@ -260,16 +264,6 @@ If you are adopting _Black_ in a large project with pre-existing string conventi
 you can pass `--skip-string-normalization` on the command line. This is meant as an
 adoption helper, avoid using this for new projects.
 
 you can pass `--skip-string-normalization` on the command line. This is meant as an
 adoption helper, avoid using this for new projects.
 

-(labels/experimental-string)=
-
-As an experimental option (can be enabled by `--experimental-string-processing`),
-_Black_ splits long strings (using parentheses where appropriate) and merges short ones.
-When split, parts of f-strings that don't need formatting are converted to plain
-strings. User-made splits are respected when they do not exceed the line length limit.
-Line continuation backslashes are converted into parenthesized strings. Unnecessary
-parentheses are stripped. Because the functionality is experimental, feedback and issue
-reports are highly encouraged!
-

 _Black_ also processes docstrings. Firstly the indentation of docstrings is corrected
 for both quotations and the text within, although relative indentation in the text is
 preserved. Superfluous trailing whitespace on each line and unnecessary new lines at the
 _Black_ also processes docstrings. Firstly the indentation of docstrings is corrected
 for both quotations and the text within, although relative indentation in the text is
 preserved. Superfluous trailing whitespace on each line and unnecessary new lines at the

diff --git a/docs/the_black_code_style/future_style.md b/docs/the_black_code_style/future_style.md
index 70ffeefc76afe961307b51e0f169673a25d0dca8..2ec2c0333a5fb3a1db077c20f74578956ef20739 100644 (file)
--- a/docs/the_black_code_style/future_style.md
+++ b/docs/the_black_code_style/future_style.md
@@ -34,15 +34,18 @@ with \
 Although when the target version is Python 3.9 or higher, _Black_ will use parentheses
 instead since they're allowed in Python 3.9 and higher.
 
 Although when the target version is Python 3.9 or higher, _Black_ will use parentheses
 instead since they're allowed in Python 3.9 and higher.
 

-## Improved string processing
-
-Currently, _Black_ does not split long strings to fit the line length limit. Currently,
-there is [an experimental option](labels/experimental-string) to enable splitting
-strings. We plan to enable this option by default once it is fully stable. This is
-tracked in [this issue](https://github.com/psf/black/issues/2188).
-

 ## Preview style
 
 Experimental, potentially disruptive style changes are gathered under the `--preview`
 CLI flag. At the end of each year, these changes may be adopted into the default style,
 ## Preview style
 
 Experimental, potentially disruptive style changes are gathered under the `--preview`
 CLI flag. At the end of each year, these changes may be adopted into the default style,

-as described in [The Black Code Style](./index.rst).
+as described in [The Black Code Style](./index.rst). Because the functionality is
+experimental, feedback and issue reports are highly encouraged!
+
+### Improved string processing
+
+_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. User-made splits are respected when they do not exceed the line length
+limit. 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).

diff --git a/src/black/__init__.py b/src/black/__init__.py
index 405a01082e7877d828691dd88be8f40e9e6b358e..67c272e3cc9a5e11ef7fe5419a08d0a413b3c9cd 100644 (file)
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -241,10 +241,7 @@ def validate_regex(
     "--experimental-string-processing",
     is_flag=True,
     hidden=True,
     "--experimental-string-processing",
     is_flag=True,
     hidden=True,

-    help=(
-        "Experimental option that performs more normalization on string literals."
-        " Currently disabled because it leads to some crashes."
-    ),
+    help="(DEPRECATED and now included in --preview) Normalize string literals.",

 )
 @click.option(
     "--preview",
 )
 @click.option(
     "--preview",

diff --git a/src/black/linegen.py b/src/black/linegen.py
index 6008c773f943f0c22e2fec52eb6f5bfbcea29ed8..9ee42aaaf7259e4441edb1c9f25c5bd1f9e89e47 100644 (file)
--- a/src/black/linegen.py
+++ b/src/black/linegen.py
@@ -23,8 +23,7 @@ from black.strings import get_string_prefix, fix_docstring
 from black.strings import normalize_string_prefix, normalize_string_quotes
 from black.trans import Transformer, CannotTransform, StringMerger
 from black.trans import StringSplitter, StringParenWrapper, StringParenStripper
 from black.strings import normalize_string_prefix, normalize_string_quotes
 from black.trans import Transformer, CannotTransform, StringMerger
 from black.trans import StringSplitter, StringParenWrapper, StringParenStripper

-from black.mode import Mode
-from black.mode import Feature
+from black.mode import Mode, Feature, Preview

 
 from blib2to3.pytree import Node, Leaf
 from blib2to3.pgen2 import token
 
 from blib2to3.pytree import Node, Leaf
 from blib2to3.pgen2 import token


@@ -338,7 +337,7 @@ def transform_line(
         and not (line.inside_brackets and line.contains_standalone_comments())
     ):
         # Only apply basic string preprocessing, since lines shouldn't be split here.
         and not (line.inside_brackets and line.contains_standalone_comments())
     ):
         # Only apply basic string preprocessing, since lines shouldn't be split here.

-        if mode.experimental_string_processing:
+        if Preview.string_processing in mode:

             transformers = [string_merge, string_paren_strip]
         else:
             transformers = []
             transformers = [string_merge, string_paren_strip]
         else:
             transformers = []


@@ -381,7 +380,7 @@ def transform_line(
         # via type ... https://github.com/mypyc/mypyc/issues/884
         rhs = type("rhs", (), {"__call__": _rhs})()
 
         # via type ... https://github.com/mypyc/mypyc/issues/884
         rhs = type("rhs", (), {"__call__": _rhs})()
 

-        if mode.experimental_string_processing:
+        if Preview.string_processing in mode:

             if line.inside_brackets:
                 transformers = [
                     string_merge,
             if line.inside_brackets:
                 transformers = [
                     string_merge,

diff --git a/src/black/mode.py b/src/black/mode.py
index c8c2bd4eb26b36bf2b7626e5cf0b5be83a9fc41a..b6d1a1fbbefee01c8cce696acfb20494265f10fb 100644 (file)
--- a/src/black/mode.py
+++ b/src/black/mode.py
@@ -7,9 +7,10 @@ chosen by the user.
 import sys
 
 from dataclasses import dataclass, field
 import sys
 
 from dataclasses import dataclass, field

-from enum import Enum
+from enum import Enum, auto

 from operator import attrgetter
 from typing import Dict, Set
 from operator import attrgetter
 from typing import Dict, Set

+from warnings import warn

 
 if sys.version_info < (3, 8):
     from typing_extensions import Final
 
 if sys.version_info < (3, 8):
     from typing_extensions import Final


@@ -124,6 +125,13 @@ def supports_feature(target_versions: Set[TargetVersion], feature: Feature) -> b
 class Preview(Enum):
     """Individual preview style features."""
 
 class Preview(Enum):
     """Individual preview style features."""
 

+    string_processing = auto()
+    hug_simple_powers = auto()
+
+
+class Deprecated(UserWarning):
+    """Visible deprecation warning."""
+

 
 @dataclass
 class Mode:
 
 @dataclass
 class Mode:


@@ -136,6 +144,14 @@ class Mode:
     experimental_string_processing: bool = False
     preview: bool = False
 
     experimental_string_processing: bool = False
     preview: bool = False
 

+    def __post_init__(self) -> None:
+        if self.experimental_string_processing:
+            warn(
+                "`experimental string processing` has been included in `preview`"
+                " and deprecated. Use `preview` instead.",
+                Deprecated,
+            )
+

     def __contains__(self, feature: Preview) -> bool:
         """
         Provide `Preview.FEATURE in Mode` syntax that mirrors the ``preview`` flag.
     def __contains__(self, feature: Preview) -> bool:
         """
         Provide `Preview.FEATURE in Mode` syntax that mirrors the ``preview`` flag.


@@ -143,6 +159,8 @@ class Mode:
         The argument is not checked and features are not differentiated.
         They only exist to make development easier by clarifying intent.
         """
         The argument is not checked and features are not differentiated.
         They only exist to make development easier by clarifying intent.
         """

+        if feature is Preview.string_processing:
+            return self.preview or self.experimental_string_processing

         return self.preview
 
     def get_cache_key(self) -> str:
         return self.preview
 
     def get_cache_key(self) -> str:

diff --git a/tests/test_black.py b/tests/test_black.py
index 202fe23ddcd940e482a37aba1df64328d99303cf..19cff23cb898f2256afc37f6128655c414e3de03 100644 (file)
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -150,6 +150,11 @@ class BlackTestCase(BlackBaseTestCase):
             os.unlink(tmp_file)
         self.assertFormatEqual(expected, actual)
 
             os.unlink(tmp_file)
         self.assertFormatEqual(expected, actual)
 

+    def test_experimental_string_processing_warns(self) -> None:
+        self.assertWarns(
+            black.mode.Deprecated, black.Mode, experimental_string_processing=True
+        )
+

     def test_piping(self) -> None:
         source, expected = read_data("src/black/__init__", data=False)
         result = BlackRunner().invoke(
     def test_piping(self) -> None:
         source, expected = read_data("src/black/__init__", data=False)
         result = BlackRunner().invoke(


@@ -342,7 +347,7 @@ class BlackTestCase(BlackBaseTestCase):
     @patch("black.dump_to_file", dump_to_stderr)
     def test_string_quotes(self) -> None:
         source, expected = read_data("string_quotes")
     @patch("black.dump_to_file", dump_to_stderr)
     def test_string_quotes(self) -> None:
         source, expected = read_data("string_quotes")

-        mode = black.Mode(experimental_string_processing=True)
+        mode = black.Mode(preview=True)

         assert_format(source, expected, mode)
         mode = replace(mode, string_normalization=False)
         not_normalized = fs(source, mode=mode)
         assert_format(source, expected, mode)
         mode = replace(mode, string_normalization=False)
         not_normalized = fs(source, mode=mode)

diff --git a/tests/test_format.py b/tests/test_format.py
index 00cd07f36f737b2797808b8aa630d371915cdcf9..40f225c95547786d78bb85434164a17d1944f3b8 100644 (file)
--- a/tests/test_format.py
+++ b/tests/test_format.py
@@ -55,15 +55,6 @@ SIMPLE_CASES: List[str] = [
     "tupleassign",
 ]
 
     "tupleassign",
 ]
 

-EXPERIMENTAL_STRING_PROCESSING_CASES: List[str] = [
-    "cantfit",
-    "comments7",
-    "long_strings",
-    "long_strings__edge_case",
-    "long_strings__regression",
-    "percent_precedence",
-]
-

 PY310_CASES: List[str] = [
     "pattern_matching_simple",
     "pattern_matching_complex",
 PY310_CASES: List[str] = [
     "pattern_matching_simple",
     "pattern_matching_complex",


@@ -73,7 +64,15 @@ PY310_CASES: List[str] = [
     "parenthesized_context_managers",
 ]
 
     "parenthesized_context_managers",
 ]
 

-PREVIEW_CASES: List[str] = []
+PREVIEW_CASES: List[str] = [
+    # string processing
+    "cantfit",
+    "comments7",
+    "long_strings",
+    "long_strings__edge_case",
+    "long_strings__regression",
+    "percent_precedence",
+]

 
 SOURCES: List[str] = [
     "src/black/__init__.py",
 
 SOURCES: List[str] = [
     "src/black/__init__.py",


@@ -136,11 +135,6 @@ def test_simple_format(filename: str) -> None:
     check_file(filename, DEFAULT_MODE)
 
 
     check_file(filename, DEFAULT_MODE)
 
 

-@pytest.mark.parametrize("filename", EXPERIMENTAL_STRING_PROCESSING_CASES)
-def test_experimental_format(filename: str) -> None:
-    check_file(filename, black.Mode(experimental_string_processing=True))
-
-

 @pytest.mark.parametrize("filename", PREVIEW_CASES)
 def test_preview_format(filename: str) -> None:
     check_file(filename, black.Mode(preview=True))
 @pytest.mark.parametrize("filename", PREVIEW_CASES)
 def test_preview_format(filename: str) -> None:
     check_file(filename, black.Mode(preview=True))