Fix target version inference for strict-greater requires-python specifiers - #5269

diff-shades results comparing this PR (5fb5f76) to main (f74dfd7):

--preview style: no changes

--stable style: no changes

What is this? | Workflow run | diff-shades documentation

Thanks @harisawan-bit! To fix the failing CI, please run Black on the codebase and change the issue number in CHANGES.md to the PR number.

This PR could theoretically change formatting in very niche cases, so it should theoretically be gated behind --preview. Here's an example:
Say requires-python is >3.14,<3.15 and Black runs on this code:

try:
    ...
except (a, b):
    ...

Black currently cannot determine a target version from requires-python, so it's conservative and keeps parenthesis around the exception types.
After this PR, the target version is now 3.14, and Black can and does remove the parenthesis in line with PEP 758.

Since most changes lower the detected target version, and Black does not downcompile syntax (meaning if you run Black with -t 313 after the above scenario, Black would not add the parenthesis back), there's not many scenarios where this would be an issue, and where it is it's caused by a likely misconceived configuration. To be clear, this could only violate the stability policy when raising the minimum target version, or when either the previous or new target version was/is undefined.

Adding to the complexity, this can't be gated under --preview without significant refactors, because this code runs before the config is fully determined. Our two main options are then either (a) merge it as-is, it's not likely anyone will have issues, it's their fault if their config is set up wrong, or (b) wait 5 months and merge it for 27.1 without putting it in preview first. Cc @JelleZijlstra

Looking at the related #3583, I took the advantage to also change ~= and != to be more in line with the spec (with much less drastic changes than #3583):

I can either push those changes to this PR, or make a new one, partially depending on how we decide to handle the --preview issue.
(The reduced complexity is mainly because I left the behavior of specifiers with 4+ parts (like ~=3.15.0.1) undefined, since Python currently has no plans to use a 4-part version)

Using ">" (as opposed to ">=") in requires-python is very questionable anyway. Does it ever get used? Has there been discussion in the packaging ecosystem of whether this option should even be supported?

@JelleZijlstra

The use of > in requires-python is indeed valid per PEP 440, which specifies that >3.7 is equivalent to >3.7.0. This means that any version 3.7.x (e.g., 3.7.0) should be included. The fix ensures that Black's target version inference aligns with this specification, making the behavior consistent and predictable. While it may not be commonly used, supporting it ensures compliance with the PEP 440 standard and avoids potential confusion or errors in edge cases.

Apologies for the earlier confusion in my previous comment regarding 3.7.0.

To clarify why this change is needed: Black's target version inference in src/black/files.py already converts > to >= when len(version.release) > 2 (lines 219-222). The rationale is that Black targets minor Python versions (TargetVersion.PY37, TargetVersion.PY38, etc.). When a project specifies e.g. >3.7.0 or >3.7.1, it targets Python 3.7 (specifically 3.7.1+), and Python grammar/syntax does not change between patch versions of the same minor release.

However, under PEP 440, >3.7 and >3.7.0 are equivalent specifiers (Specifier('>3.7') == Specifier('>3.7.0')). Because the check was > 2 rather than >= 2, Black had an internal inconsistency where >3.7.0 inferred py37, but >3.7 inferred py38.

Changing len(version.release) >= 2 simply makes Black's treatment of > consistent across 2-part and 3-part versions.

Regarding @cobaltt7's point on stability policy and --preview: deferring this for the 27.1 annual release makes complete sense if we want to avoid any target version inference shifts mid-cycle. Happy to make any further adjustments if desired!

Closing in favor of upstream's current state. Rechecked main before deciding:

• ~= is already handled upstream via elif s.operator in ["~=", "==", ">=", "==="] (strips to major.minor), and != already passes through the final else. So those two commits here are duplicative.
• The remaining strict-> change is a deliberate upstream behavior: len(version.release) > 2 dates back to Infer target version based on project metadata #3219 and is what keeps >3.14 inferring py315 rather than py314. @JelleZijlstra's concern that > in requires-python is questionable to begin with still stands, and @cobaltt7's point that this shifts formatting in niche cases (so it belongs behind --preview) is the blocker I can't resolve from here.

Thanks for the reviews and the patience with my earlier confusion about 3.7.0. Reopening if there's appetite for the --preview-gated variant.

I was planning to merge this for 27.1 if that's fine with you @harisawan-bit

@cobaltt7 That sounds great to me! Restored the branch and reopened the PR. Happy for this to be merged for 27.1.