Merge 01e14a5 into 8a84beb

CHANGES.md

@@ -22,6 +22,10 @@
 
 - All upper version bounds on dependencies have been removed (#2718)
 
+### Preview style
+
+- Introduce the `--preview` flag with no style changes (#2752)
+
 ## 21.12b0
 
 ### _Black_

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
 

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
+
+Potentially disruptive style changes between major releases are gathered under the
+`--preview` CLI flag. They will eventually become part of main functionality, but until
+then are described here.

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.

docs/usage_and_configuration/the_basics.md

@@ -28,11 +28,11 @@ python -m black {source_file_or_directory}
 
 _Black_ has quite a few knobs these days, although _Black_ is opinionated so style
 configuration options are deliberately limited and rarely added. You can list them by
-running `black --help`.
+running `black --help` or expanding the view below.
 
 <details>
 
-<summary>Help output</summary>
+<summary>CLI option reference</summary>
 
 ```{program-output} black --help
 

src/black/__init__.py

@@ -245,6 +245,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,
@@ -398,6 +406,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],
@@ -439,6 +448,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:

src/black/mode.py

@@ -166,6 +166,7 @@ class Mode:
     is_ipynb: bool = False
     magic_trailing_comma: bool = True
     experimental_string_processing: bool = False
+    preview: bool = False
 
     def get_cache_key(self) -> str:
         if self.target_versions:
@@ -183,5 +184,6 @@ def get_cache_key(self) -> str:
             str(int(self.is_ipynb)),
             str(int(self.magic_trailing_comma)),
             str(int(self.experimental_string_processing)),
+            str(int(self.preview)),
         ]
         return ".".join(parts)

tests/test_format.py

@@ -78,6 +78,8 @@
     "parenthesized_context_managers",
 ]
 
+PREVIEW_CASES = []
+
 SOURCES = [
     "src/black/__init__.py",
     "src/black/__main__.py",
@@ -150,6 +152,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