Skip to content

Enh: added first language for Python versions #501

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Jun 10, 2025
Merged

Enh: added first language for Python versions #501

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
5871f57
added first language for Python versions
mrgah May 19, 2025
6d40a7e
changed admonition to tip class
mrgah May 20, 2025
158f0a6
Merge branch 'main' into add-py-versions
mrgah May 20, 2025
4347b76
'[pre-commit.ci 🤖] Apply code format tools to PR'
pre-commit-ci[bot] May 20, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions tutorials/pyproject-toml.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -307,6 +307,14 @@ The `requires-python` field helps pip identify which Python versions that your p
It is set to a single value.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I realize this PR was opened just to add new guidance, but we should really update this paragraph to specify that, even with lower bounds, requires-python is not necessary for every package and is only something to be used when the author has confidence there are versions of Python the package versions Must Not be installed for.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

it seems like there's a bit of an open question about how to frame this. what about something like the following?

We recommend adding the requires-python field to your pyproject.toml [project] table.
This is not mandatory, but the requires-python field helps pip identify which Python versions that your package supports, and is only required when there are versions of Python the package will not work with.
It is set to a single value.
The packaging specification definesrequires-python as a string that uses version specifiers. Most projects will specify the oldest Python version supported by the package. In some advanced cases, an upper bound is set to indicate which future Python versions, if any, will be supported.

Copy link
Collaborator

@ucodery ucodery May 20, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

IMO "We recommend" is still too strong. @lwasser I might have missed some conversation this week, but I believe we recommend leaving it out, until a version of Python is known to break the package.

It is set to a single value.

This might just be my reading of the guide, but this sounds like the field takes a single version string. It takes a single version specifier which is a version operator plus version string, maybe multiple. But we should specify that the only versions specifier we recommend is > 3.X.Y or >= 3.X.Y. I am against even mentioning an upper bound, and would probably be okay saying to not do that, although that can just add confusion. Not sure Leah's thought on the upper.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

sorry about the slow reply here friends.

I remember in Slack talking with Pradyun about requires-python being something we want to add to support pip. So that is why the language is there "we recommend" that you add it.

This way, maintainers are intentional about what versions they do and do not support.

IMO it seems like a good practice for people to be intentional about this. Especially in a world where there i think are still a few 2.x users out there 🙃 Are you OK with this @ucodery ? I do trust both or your opinions here I just also remember Pradyun's comments (which I interpreted as - let's use we recommend)

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I opened a new issue for this discussion. I think it would derail this great PR. With your approval already standing, I will merge this.

The [packaging specification](https://packaging.python.org/en/latest/specifications/core-metadata/#core-metadata-requires-python) defines`requires-python` as a string that uses version specifiers. Most projects will specify the oldest Python version supported by the package. In some advanced cases, an upper bound is set to indicate which future Python versions, if any, will be supported.

:::{admonition} But how do I figure out which Python versions I should support?
:class: tip
Good question. The Python developer guide provides a [status page](https://devguide.python.org/versions/) (and a handy visualization) that explains the status of each Python release. Python releases go through several different phases that are explained in [PEP 602](https://peps.python.org/pep-0602/).

We recommend that you use the latest Python release in the **bugfix** phase. If your Python release is in the **security** phase, we recommend migrating to a newer version of Python.

[SPEC 0](https://scientific-python.org/specs/spec-0000/) of the Scientific Python project suggests a common schedule for dependencies, including Python release versions, and is also worth considering for your project.
:::

{emphasize-lines="22"}
```toml
Expand Down
Loading