From 9041c396d506af447724c15ca0e9caa5eb5db2c4 Mon Sep 17 00:00:00 2001 From: felix-hilden Date: Fri, 7 Jan 2022 15:19:24 +0200 Subject: [PATCH 1/9] Improve CLI reference wording --- docs/usage_and_configuration/the_basics.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/usage_and_configuration/the_basics.md b/docs/usage_and_configuration/the_basics.md index d002ff0173a..5603b1fd74a 100644 --- a/docs/usage_and_configuration/the_basics.md +++ b/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.
-Help output +CLI option reference ```{program-output} black --help From 8810264e77444478c7fc5d33c7c535cbc0decef0 Mon Sep 17 00:00:00 2001 From: felix-hilden Date: Fri, 7 Jan 2022 15:57:54 +0200 Subject: [PATCH 2/9] Create --preview flag --- docs/contributing/the_basics.md | 4 +++- docs/the_black_code_style/future_style.md | 6 ++++++ docs/the_black_code_style/index.rst | 2 +- src/black/__init__.py | 10 ++++++++++ src/black/mode.py | 2 ++ tests/test_format.py | 7 +++++++ 6 files changed, 29 insertions(+), 2 deletions(-) diff --git a/docs/contributing/the_basics.md b/docs/contributing/the_basics.md index 9a639731073..23fbb8a3d7e 100644 --- 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 a7676090553..e057cde4bdd 100644 --- 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 + +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. diff --git a/docs/the_black_code_style/index.rst b/docs/the_black_code_style/index.rst index d53703277e4..3952a174223 100644 --- 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 9bc8fc15c49..3446fb38acc 100644 --- a/src/black/__init__.py +++ b/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: diff --git a/src/black/mode.py b/src/black/mode.py index bd4428add66..bed28883088 100644 --- a/src/black/mode.py +++ b/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) diff --git a/tests/test_format.py b/tests/test_format.py index 30099aaf1bc..e3e5f5fdd4f 100644 --- a/tests/test_format.py +++ b/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 From 01e14a5685061ee23d377dab92e9cbb565b77f76 Mon Sep 17 00:00:00 2001 From: felix-hilden Date: Fri, 7 Jan 2022 16:01:43 +0200 Subject: [PATCH 3/9] Changelog entry --- CHANGES.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/CHANGES.md b/CHANGES.md index cb637d94c11..b28013e5104 100644 --- a/CHANGES.md +++ b/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_ From d62fbe72ae1ce293f5ba9ed6b85f83513e68fa4a Mon Sep 17 00:00:00 2001 From: felix-hilden Date: Fri, 7 Jan 2022 16:18:32 +0200 Subject: [PATCH 4/9] Revert stupidity --- docs/usage_and_configuration/the_basics.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/usage_and_configuration/the_basics.md b/docs/usage_and_configuration/the_basics.md index 5603b1fd74a..d002ff0173a 100644 --- a/docs/usage_and_configuration/the_basics.md +++ b/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` or expanding the view below. +running `black --help`.
-CLI option reference +Help output ```{program-output} black --help From 34087d7f4cd6ccae265d8e3582ea3d4c1fd23493 Mon Sep 17 00:00:00 2001 From: felix-hilden Date: Fri, 7 Jan 2022 21:15:33 +0200 Subject: [PATCH 5/9] Add type hints to test case lists --- tests/test_format.py | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/tests/test_format.py b/tests/test_format.py index e3e5f5fdd4f..5abea86e4da 100644 --- 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 @@ read_data, ) -SIMPLE_CASES = [ +SIMPLE_CASES: List[str] = [ "beginning_backslash", "bracketmatch", "class_blank_parentheses", @@ -55,13 +55,13 @@ "tupleassign", ] -SIMPLE_CASES_PY2 = [ +SIMPLE_CASES_PY2: List[str] = [ "numeric_literals_py2", "python2", "python2_unicode_literals", ] -EXPERIMENTAL_STRING_PROCESSING_CASES = [ +EXPERIMENTAL_STRING_PROCESSING_CASES: List[str] = [ "cantfit", "comments7", "long_strings", @@ -70,7 +70,7 @@ "percent_precedence", ] -PY310_CASES = [ +PY310_CASES: List[str] = [ "pattern_matching_simple", "pattern_matching_complex", "pattern_matching_extras", @@ -78,9 +78,9 @@ "parenthesized_context_managers", ] -PREVIEW_CASES = [] +PREVIEW_CASES: List[str] = [] -SOURCES = [ +SOURCES: List[str] = [ "src/black/__init__.py", "src/black/__main__.py", "src/black/brackets.py", From 66ddbd34d45854b913afdab59d7350c1869fbf71 Mon Sep 17 00:00:00 2001 From: Jelle Zijlstra Date: Thu, 13 Jan 2022 18:31:31 -0800 Subject: [PATCH 6/9] Update docs/the_black_code_style/future_style.md --- docs/the_black_code_style/future_style.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/the_black_code_style/future_style.md b/docs/the_black_code_style/future_style.md index e057cde4bdd..d0d0fc24374 100644 --- a/docs/the_black_code_style/future_style.md +++ b/docs/the_black_code_style/future_style.md @@ -43,6 +43,7 @@ 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. +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](the_black_code_style/index.rst). From bda59162a84db8834eeab893d4274b593e19f58e Mon Sep 17 00:00:00 2001 From: Jelle Zijlstra Date: Thu, 13 Jan 2022 18:34:05 -0800 Subject: [PATCH 7/9] Update docs/the_black_code_style/future_style.md --- docs/the_black_code_style/future_style.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/the_black_code_style/future_style.md b/docs/the_black_code_style/future_style.md index d0d0fc24374..7de4947733f 100644 --- a/docs/the_black_code_style/future_style.md +++ b/docs/the_black_code_style/future_style.md @@ -46,4 +46,4 @@ tracked in [this issue](https://github.com/psf/black/issues/2188). 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](the_black_code_style/index.rst). +[The Black Code Style](./index.rst). From fe5b1b0faad0ec25df24128995588e1b51774731 Mon Sep 17 00:00:00 2001 From: Jelle Zijlstra Date: Thu, 13 Jan 2022 18:36:47 -0800 Subject: [PATCH 8/9] Update docs/the_black_code_style/future_style.md --- docs/the_black_code_style/future_style.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/the_black_code_style/future_style.md b/docs/the_black_code_style/future_style.md index 7de4947733f..70ffeefc76a 100644 --- a/docs/the_black_code_style/future_style.md +++ b/docs/the_black_code_style/future_style.md @@ -43,7 +43,6 @@ 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). +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). From b409b556e16c2353e34ef5a17d2c1fa60c83f05b Mon Sep 17 00:00:00 2001 From: felix-hilden Date: Sun, 16 Jan 2022 18:30:37 +0200 Subject: [PATCH 9/9] Preview features enum --- src/black/mode.py | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/src/black/mode.py b/src/black/mode.py index a99a9a3a041..c8c2bd4eb26 100644 --- 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) @@ -132,6 +136,15 @@ class Mode: 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: version_str = ",".join(