From a2b5ba2a3a97eb3a0b5130a5b317bb750c1624cf Mon Sep 17 00:00:00 2001
From: =?utf8?q?Felix=20Hild=C3=A9n?= <felix.hilden@gmail.com>
Date: Thu, 3 Jun 2021 23:09:41 +0300
Subject: [PATCH] Add option to require a specific version to be running
 (#2300)
MIME-Version: 1.0
Content-Type: text/plain; charset=utf8
Content-Transfer-Encoding: 8bit

Closes #1246: This PR adds a new option (and automatically a toml entry, hooray for existing configuration management 🎉) to require a specific version of Black to be running.

For example: `black --required-version 20.8b -c "format = 'this'"`

Execution fails straight away if it doesn't match `__version__`.
---
 CHANGES.md                                 |  1 +
 docs/usage_and_configuration/the_basics.md | 15 ++++++++++++-
 src/black/__init__.py                      | 26 ++++++++++++++++++----
 tests/test_black.py                        | 10 +++++++++
 4 files changed, 47 insertions(+), 5 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index e4fa25c..16d9ebc 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -7,6 +7,7 @@
 - Correct max string length calculation when there are string operators (#2292)
 - Fixed option usage when using the `--code` flag (#2259)
 - Do not call `uvloop.install()` when _Black_ is used as a library (#2303)
+- Added `--required-version` option to require a specific version to be running (#2300)
 
 ## 21.5b2
 
diff --git a/docs/usage_and_configuration/the_basics.md b/docs/usage_and_configuration/the_basics.md
index c5e17e5..474ad66 100644
--- a/docs/usage_and_configuration/the_basics.md
+++ b/docs/usage_and_configuration/the_basics.md
@@ -167,7 +167,7 @@ $ black src/ -q
 error: cannot format src/black_primer/cli.py: Cannot parse: 5:6: mport asyncio
 ```
 
-### Getting the version
+### Versions
 
 You can check the version of _Black_ you have installed using the `--version` flag.
 
@@ -176,6 +176,19 @@ $ black --version
 black, version 21.5b0
 ```
 
+An option to require a specific version to be running is also provided.
+
+```console
+$ black --required-version 21.5b2 -c "format = 'this'"
+format = "this"
+$ black --required-version 31.5b2 -c "still = 'beta?!'"
+Oh no! 💥 💔 💥 The required version does not match the running version!
+```
+
+This is useful for example when running _Black_ in multiple environments that haven't
+necessarily installed the correct version. This option can be set in a configuration
+file for consistent results across environments.
+
 ## Configuration via a file
 
 _Black_ is able to read project-specific default values for its command line options
diff --git a/src/black/__init__.py b/src/black/__init__.py
index d95e9b1..a985926 100644
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -241,6 +241,14 @@ def validate_regex(
     is_flag=True,
     help="If --fast given, skip temporary sanity checks. [default: --safe]",
 )
+@click.option(
+    "--required-version",
+    type=str,
+    help=(
+        "Require a specific version of Black to be running (useful for unifying results"
+        " across many environments e.g. with a pyproject.toml file)."
+    ),
+)
 @click.option(
     "--include",
     type=str,
@@ -351,6 +359,7 @@ def main(
     experimental_string_processing: bool,
     quiet: bool,
     verbose: bool,
+    required_version: str,
     include: Pattern,
     exclude: Optional[Pattern],
     extend_exclude: Optional[Pattern],
@@ -360,6 +369,17 @@ def main(
     config: Optional[str],
 ) -> None:
     """The uncompromising code formatter."""
+    if config and verbose:
+        out(f"Using configuration from {config}.", bold=False, fg="blue")
+
+    error_msg = "Oh no! 💥 💔 💥"
+    if required_version and required_version != __version__:
+        err(
+            f"{error_msg} The required version `{required_version}` does not match"
+            f" the running version `{__version__}`!"
+        )
+        ctx.exit(1)
+
     write_back = WriteBack.from_configuration(check=check, diff=diff, color=color)
     if target_version:
         versions = set(target_version)
@@ -374,8 +394,6 @@ def main(
         magic_trailing_comma=not skip_magic_trailing_comma,
         experimental_string_processing=experimental_string_processing,
     )
-    if config and verbose:
-        out(f"Using configuration from {config}.", bold=False, fg="blue")
 
     if code is not None:
         # Run in quiet mode by default with -c; the extra output isn't useful.
@@ -428,9 +446,9 @@ def main(
             )
 
     if verbose or not quiet:
-        out("Oh no! 💥 💔 💥" if report.return_code else "All done! ✨ 🍰 ✨")
+        out(error_msg if report.return_code else "All done! ✨ 🍰 ✨")
         if code is None:
-            click.secho(str(report), err=True)
+            click.echo(str(report), err=True)
     ctx.exit(report.return_code)
 
 
diff --git a/tests/test_black.py b/tests/test_black.py
index f0a14aa..455cb33 100644
--- a/tests/test_black.py
+++ b/tests/test_black.py
@@ -1796,6 +1796,16 @@ class BlackTestCase(BlackBaseTestCase):
         for option in ["--include", "--exclude", "--extend-exclude", "--force-exclude"]:
             self.invokeBlack(["-", option, "**()(!!*)"], exit_code=2)
 
+    def test_required_version_matches_version(self) -> None:
+        self.invokeBlack(
+            ["--required-version", black.__version__], exit_code=0, ignore_config=True
+        )
+
+    def test_required_version_does_not_match_version(self) -> None:
+        self.invokeBlack(
+            ["--required-version", "20.99b"], exit_code=1, ignore_config=True
+        )
+
     def test_preserves_line_endings(self) -> None:
         with TemporaryDirectory() as workspace:
             test_file = Path(workspace) / "test.py"
-- 
2.39.5