Warn when target version exceeds runtime Python version (#4983)

Author: regiscamimura

CHANGES.md

@@ -49,6 +49,11 @@
 
 <!-- Changes to Black's terminal output and error messages -->
 
+- Emit a clear warning when the target Python version is newer than the running Python
+  version, since AST safety checks cannot parse newer syntax. Also replace the
+  misleading "INTERNAL ERROR" message with an actionable error explaining the version
+  mismatch (#4983)
+
 ### _Blackd_
 
 <!-- Changes to blackd -->

src/black/__init__.py

@@ -202,6 +202,27 @@ def target_version_option_callback(
     return [TargetVersion[val.upper()] for val in v]
 
 
+def _target_versions_exceed_runtime(
+    target_versions: set[TargetVersion],
+) -> bool:
+    if not target_versions:
+        return False
+    max_target_minor = max(tv.value for tv in target_versions)
+    return max_target_minor > sys.version_info[1]
+
+
+def _version_mismatch_message(target_versions: set[TargetVersion]) -> str:
+    max_target = max(target_versions, key=lambda tv: tv.value)
+    runtime = f"{sys.version_info[0]}.{sys.version_info[1]}"
+    return (
+        f"Python {runtime} cannot parse code formatted for"
+        f" {max_target.pretty()}. To fix this: run Black with"
+        f" {max_target.pretty()}, set --target-version to"
+        f" py3{sys.version_info[1]}, or use --fast to skip the safety"
+        " check."
+    )
+
+
 def enable_unstable_feature_callback(
     c: click.Context, p: click.Option | click.Parameter, v: tuple[str, ...]
 ) -> list[Preview]:
@@ -642,6 +663,14 @@ def main(
         enabled_features=set(enable_unstable_feature),
     )
 
+    if not fast and _target_versions_exceed_runtime(versions):
+        err(
+            f"Warning: {_version_mismatch_message(versions)} Black's safety"
+            " check verifies equivalence by parsing the AST, which fails"
+            " when the running Python is older than the target version.",
+            fg="yellow",
+        )
+
     lines: list[tuple[int, int]] = []
     if line_ranges:
         if ipynb:
@@ -1055,7 +1084,15 @@ def check_stability_and_equivalence(
     equivalent, or if a second pass of the formatter would format the
     content differently.
     """
-    assert_equivalent(src_contents, dst_contents)
+    try:
+        assert_equivalent(src_contents, dst_contents)
+    except ASTSafetyError:
+        if _target_versions_exceed_runtime(mode.target_versions):
+            raise ASTSafetyError(
+                "failed to verify equivalence of the formatted output:"
+                f" {_version_mismatch_message(mode.target_versions)}"
+            ) from None
+        raise
     assert_stable(src_contents, dst_contents, mode=mode, lines=lines)
 
 

tests/test_black.py

@@ -3174,6 +3174,53 @@ def test_equivalency_ast_parse_failure_includes_error(self) -> None:
         err.match("invalid character")
         err.match(r"\(<unknown>, line 1\)")
 
+    def test_target_version_exceeds_runtime_warning(self) -> None:
+        max_target = max(TargetVersion, key=lambda tv: tv.value)
+        if sys.version_info[1] >= max_target.value:
+            pytest.skip("no target version higher than runtime available")
+        target_name = f"py3{sys.version_info[1] + 1}"
+        code = "x = 1\n"
+        args = ["--target-version", target_name, "--code", code]
+        result = CliRunner().invoke(black.main, args)
+        stderr = result.stderr_bytes.decode() if result.stderr_bytes else ""
+        assert "Warning:" in stderr
+
+    def test_target_version_exceeds_runtime_no_warning_with_fast(self) -> None:
+        max_target = max(TargetVersion, key=lambda tv: tv.value)
+        if sys.version_info[1] >= max_target.value:
+            pytest.skip("no target version higher than runtime available")
+        target_name = f"py3{sys.version_info[1] + 1}"
+        code = "x = 1\n"
+        args = ["--fast", "--target-version", target_name, "--code", code]
+        result = CliRunner().invoke(black.main, args)
+        stderr = result.stderr_bytes.decode() if result.stderr_bytes else ""
+        assert "Warning:" not in stderr
+
+    def test_target_version_at_runtime_no_warning(self) -> None:
+        current_minor = sys.version_info[1]
+        target_name = f"py3{current_minor}"
+        code = "x = 1\n"
+        args = ["--target-version", target_name, "--code", code]
+        result = CliRunner().invoke(black.main, args)
+        stderr = result.stderr_bytes.decode() if result.stderr_bytes else ""
+        assert "Warning:" not in stderr
+
+    @pytest.mark.incompatible_with_mypyc
+    def test_target_version_exceeds_runtime_clear_error_message(self) -> None:
+        max_target = max(TargetVersion, key=lambda tv: tv.value)
+        if sys.version_info[1] >= max_target.value:
+            pytest.skip("no target version higher than runtime available")
+        future_target = TargetVersion[f"PY3{sys.version_info[1] + 1}"]
+        mode = Mode(target_versions={future_target})
+        with patch.object(
+            black,
+            "assert_equivalent",
+            side_effect=ASTSafetyError("mocked parse failure"),
+        ):
+            with pytest.raises(ASTSafetyError) as exc_info:
+                black.check_stability_and_equivalence("x = 1\n", "x = 1\n", mode=mode)
+            assert "INTERNAL ERROR" not in str(exc_info.value)
+
 
 try:
     with open(black.__file__, encoding="utf-8") as _bf: