Create --preview CLI flag (#2752)

diff --git a/CHANGES.md b/CHANGES.md
index 32059a305483cf5e2a0f1cd3494f5ae30c3925a1..4b9ceae81dc54c518878a7a1c62019351e89780a 100644 (file)
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -36,6 +36,10 @@
 - All upper version bounds on dependencies have been removed (#2718)
 - `typing-extensions` is no longer a required dependency in Python 3.10+ (#2772)
 
+### Preview style
+
+- Introduce the `--preview` flag with no style changes (#2752)
+
 ### Integrations
 
 - Update GitHub action to support containerized runs (#2748)

diff --git a/docs/contributing/the_basics.md b/docs/contributing/the_basics.md
index 9a639731073d871b6410cc4e1d45defac82abb88..23fbb8a3d7e1d939a2286caf5b4a095ac900168b 100644 (file)
--- a/docs/contributing/the_basics.md
+++ b/docs/contributing/the_basics.md
@@ -55,7 +55,9 @@ go back and workout what to add to the `CHANGES.md` for each release.
 
 If a change would affect the advertised code style, please modify the documentation (The
 _Black_ code style) to reflect that change. Patches that fix unintended bugs in
-formatting don't need to be mentioned separately though.
+formatting don't need to be mentioned separately though. If the change is implemented
+with the `--preview` flag, please include the change in the future style document
+instead and write the changelog entry under a dedicated "Preview changes" heading.
 
 ### Docs Testing
 

diff --git a/docs/the_black_code_style/future_style.md b/docs/the_black_code_style/future_style.md
index a7676090553a319a2f4ef003bed71634f0b17d3a..70ffeefc76afe961307b51e0f169673a25d0dca8 100644 (file)
--- a/docs/the_black_code_style/future_style.md
+++ b/docs/the_black_code_style/future_style.md
@@ -40,3 +40,9 @@ Currently, _Black_ does not split long strings to fit the line length limit. Cur
 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,
+as described in [The Black Code Style](./index.rst).

diff --git a/docs/the_black_code_style/index.rst b/docs/the_black_code_style/index.rst
index d53703277e4b184202bf311f58e7a8876df9c5db..3952a17422388f4cd83b2e421658e6438d12c337 100644 (file)
--- a/docs/the_black_code_style/index.rst
+++ b/docs/the_black_code_style/index.rst
@@ -32,7 +32,7 @@ versions of *Black*:
   improved formatting enabled by newer Python language syntax as well as due
   to improvements in the formatting logic.
 
-- The ``--future`` flag is exempt from this policy. There are no guarantees
+- The ``--preview`` flag is exempt from this policy. There are no guarantees
   around the stability of the output with that flag passed into *Black*. This
   flag is intended for allowing experimentation with the proposed changes to
   the *Black* code style.

diff --git a/src/black/__init__.py b/src/black/__init__.py
index fa918ce293172239fb87db2e0bfb600e836494d0..405a01082e7877d828691dd88be8f40e9e6b358e 100644 (file)
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -246,6 +246,14 @@ def validate_regex(
         " Currently disabled because it leads to some crashes."
     ),
 )
+@click.option(
+    "--preview",
+    is_flag=True,
+    help=(
+        "Enable potentially disruptive style changes that will be added to Black's main"
+        " functionality in the next major release."
+    ),
+)
 @click.option(
     "--check",
     is_flag=True,
@@ -399,6 +407,7 @@ def main(
     skip_string_normalization: bool,
     skip_magic_trailing_comma: bool,
     experimental_string_processing: bool,
+    preview: bool,
     quiet: bool,
     verbose: bool,
     required_version: Optional[str],
@@ -469,6 +478,7 @@ def main(
         string_normalization=not skip_string_normalization,
         magic_trailing_comma=not skip_magic_trailing_comma,
         experimental_string_processing=experimental_string_processing,
+        preview=preview,
     )
 
     if code is not None:

diff --git a/src/black/mode.py b/src/black/mode.py
index 5e04525cfc989a5619255e4119581c7c263761d0..c8c2bd4eb26b36bf2b7626e5cf0b5be83a9fc41a 100644 (file)
--- a/src/black/mode.py
+++ b/src/black/mode.py
@@ -121,6 +121,10 @@ def supports_feature(target_versions: Set[TargetVersion], feature: Feature) -> b
     return all(feature in VERSION_TO_FEATURES[version] for version in target_versions)
 
 
+class Preview(Enum):
+    """Individual preview style features."""
+
+
 @dataclass
 class Mode:
     target_versions: Set[TargetVersion] = field(default_factory=set)
@@ -130,6 +134,16 @@ class Mode:
     is_ipynb: bool = False
     magic_trailing_comma: bool = True
     experimental_string_processing: bool = False
+    preview: bool = False
+
+    def __contains__(self, feature: Preview) -> bool:
+        """
+        Provide `Preview.FEATURE in Mode` syntax that mirrors the ``preview`` flag.
+
+        The argument is not checked and features are not differentiated.
+        They only exist to make development easier by clarifying intent.
+        """
+        return self.preview
 
     def get_cache_key(self) -> str:
         if self.target_versions:
@@ -147,5 +161,6 @@ class Mode:
             str(int(self.is_ipynb)),
             str(int(self.magic_trailing_comma)),
             str(int(self.experimental_string_processing)),
+            str(int(self.preview)),
         ]
         return ".".join(parts)

diff --git a/tests/test_format.py b/tests/test_format.py
index db39678cdfe57e41c5f29641ca18e935b335dc74..00cd07f36f737b2797808b8aa630d371915cdcf9 100644 (file)
--- a/tests/test_format.py
+++ b/tests/test_format.py
@@ -1,5 +1,5 @@
 from dataclasses import replace
-from typing import Any, Iterator
+from typing import Any, Iterator, List
 from unittest.mock import patch
 
 import pytest
@@ -14,7 +14,7 @@ from tests.util import (
     read_data,
 )
 
-SIMPLE_CASES = [
+SIMPLE_CASES: List[str] = [
     "beginning_backslash",
     "bracketmatch",
     "class_blank_parentheses",
@@ -55,7 +55,7 @@ SIMPLE_CASES = [
     "tupleassign",
 ]
 
-EXPERIMENTAL_STRING_PROCESSING_CASES = [
+EXPERIMENTAL_STRING_PROCESSING_CASES: List[str] = [
     "cantfit",
     "comments7",
     "long_strings",
@@ -64,7 +64,7 @@ EXPERIMENTAL_STRING_PROCESSING_CASES = [
     "percent_precedence",
 ]
 
-PY310_CASES = [
+PY310_CASES: List[str] = [
     "pattern_matching_simple",
     "pattern_matching_complex",
     "pattern_matching_extras",
@@ -73,7 +73,9 @@ PY310_CASES = [
     "parenthesized_context_managers",
 ]
 
-SOURCES = [
+PREVIEW_CASES: List[str] = []
+
+SOURCES: List[str] = [
     "src/black/__init__.py",
     "src/black/__main__.py",
     "src/black/brackets.py",
@@ -139,6 +141,11 @@ 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", SOURCES)
 def test_source_is_formatted(filename: str) -> None:
     path = THIS_DIR.parent / filename