A better description for "Requires-Python" metadata field #1274
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
ofek
approved these changes
Jul 13, 2023
wimglenn
force-pushed
the
Requires-Python
branch
2 times, most recently
from
9b81007 to
c4d514d
Compare
sinoroc
reviewed
Sep 7, 2023
webknjaz
reviewed
Sep 14, 2023
webknjaz
reviewed
Sep 14, 2023
webknjaz
reviewed
Sep 14, 2023
wimglenn
force-pushed
the
Requires-Python
branch
from
26a19d5 to
e9b412f
Compare
seberg
reviewed
Oct 7, 2023
…is should better demonstrate that usage of this field is more commonly about _excluding known incompatible versions_ than it is about specifying _guaranteed compatible versions_. Remove the multiple example code-block because it is not a (multiple use) field, and the other examples seem to exist only to show further usage of PEP 440 version specifiers (which are explained better elsewhere) rather than Requires-Python itself.
wimglenn
force-pushed
the
Requires-Python
branch
from
e9b412f to
174b29b
Compare
pradyunsg
approved these changes
Nov 5, 2023
rgommers
approved these changes
Nov 8, 2023
2 tasks
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
The common usage of this field is for Dropping support for older Python versions. Adding upper bounds can be problematic.
The current description is misleading, and that was discussed extensively here, but unfortunately no PR came out of it. So here's an attempt!
I won't reproduce all of Henry's excellent arguments, but I will reiterate that the wording "is guaranteed to be compatible with" causes issues - today I've witnessed an environment failing to bootstrap when updated from Python 3.11.3 to Python 3.11.4 because one (internal) dependency had declared an upper bound on 3.11.3.
This was added because 3.11.3 was the runtime the developer's code was tested in, and if you were to take the current description literally, it's quite right that their distribution is not "guaranteed to be compatible with" 3.11.4 - how could you guarantee compatibility with an unreleased Python version? For someone unfamiliar with Python packaging, it is not obvious that such an upper bound would wreak havoc on the tooling and block an upgrade until a new release is published without over-constraining the Requires-Python metadata.