From f06b78ebcd72528d1abdca7da03fbe498f2772cb Mon Sep 17 00:00:00 2001 From: Inessa Pawson Date: Wed, 19 Aug 2026 22:39:40 -0400 Subject: [PATCH 1/3] docs: clarify recommended use of requires-python --- tutorials/pyproject-toml.md | 63 ++++++++++--------------------------- 1 file changed, 17 insertions(+), 46 deletions(-) diff --git a/tutorials/pyproject-toml.md b/tutorials/pyproject-toml.md index 240fcc1a6..2803fadd2 100644 --- a/tutorials/pyproject-toml.md +++ b/tutorials/pyproject-toml.md @@ -18,10 +18,9 @@ Following that you learned how to add a: to the root of your project directory. To enhance the visibility of your package on PyPI and provide more information -about its compatibility with Python versions, project development status, and -project maintainers, you should add additional metadata to your `pyproject.toml` -file. This -lesson will guide you through the process. +about its development status and maintainers, you should add additional +metadata to your `pyproject.toml` file. This lesson will guide you through +the process. :::{admonition} Learning Objectives @@ -88,14 +87,14 @@ build-backend = "hatchling.build" The pyproject.toml file tells your build tool: -- What {term}`Build backend` to use to build your package (we are using +- what {term}`Build backend` to use to build your package (we are using {term}`Hatchling` in this tutorial but there are [many others to choose from](/package-structure-code/python-package-build-tools)). -- How and where to retrieve your package's version: +- how and where to retrieve your package's version: - **statically** where you declare the version `version = "0.1.0"` or - **dynamically** where the tool looks to the most recent tag in your history to determine the current version. -- What {term}`Dependencies` your package needs -- What versions of Python your package supports (important for your users). +- what {term}`Dependencies` your package needs, +- it can also declare Python-version requirements if your package has them. The `pyproject.toml` file also makes it easy for anyone browsing your GitHub repository to quickly understand your package's structure such as: @@ -315,49 +314,26 @@ If you have multiple licenses, or a custom license, you can also express these u If you want to distribute license files, or other files containing legal information, with your package, you can include these using the [`license-files`](https://packaging.python.org/en/latest/guides/writing-pyproject-toml/#license-files) entry, but this is not required. -### Step 3: Specify Python version with `requires-python` - -Add the `requires-python` field to your `pyproject.toml` `[project]` table. -The `requires-python` field helps pip identify which Python versions that your package supports. -It is set to a single value. -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. -::: +:::{admonition} When to use `requires-python` +:class: tip +You do not need to specify `requires-python` for every package. However, if you know that your package will not work with older versions of Python, use `requires-python` to prevent installers from installing it with those versions. +For example, if your package requires features introduced in Python 3.10: -{emphasize-lines="22"} ```toml -[build-system] -requires = ["hatchling"] -build-backend = "hatchling.build" - [project] -name = "pyospackage" -version = "0.1.0" -description = """ -Tools that update the pyOpenSci contributor and review metadata -that is posted on our website -""" -authors = [ - { name = "Firstname Lastname", email = "email@pyopensci.org"}, - { name = "Secondperson Fullname", email = "email2@pyopensci.org" } -] -maintainers = [ - { name = "Secondperson Fullname", email = "email2@pyopensci.org" }, - { name = "New Friend", email = "newbie@pyopensci.org" } -] -readme = "README.md" -license = "MIT" requires-python = ">=3.10" ``` -### Step 4: Specify Dependencies +This helps `pip` select a compatible release of your package for the Python version a user is running. +::: + +### Step 3: Specify dependencies Next add your dependencies table to the project table. The `dependencies =` section contains a list (or array in the toml language) of the Python packages that your package requires to run properly in a Python environment. Similar to the requirements listed in the `[build-system]` table above: @@ -426,7 +402,6 @@ maintainers = [ ] readme = "README.md" license = "MIT" -requires-python = ">=3.10" dependencies = ["numpy>=1.0", "requests==10.1", "pandas", "pydantic>=1.7,<2"] ``` @@ -455,7 +430,7 @@ pydantic^1.10 One build tool that you should be aware of that pins dependencies to an upper bound by default is Poetry. [Read more about how to safely add dependencies with Poetry, here.](challenges-with-poetry) ::: -### Step 5: Add PyPI classifiers +### Step 4: Add PyPI classifiers Next you will add classifiers to your `pyproject.toml` file. The value for each classifier that you add to your `pyproject.toml` file must come from the list of [PyPI accepted classifier values found here](https://PyPI.org/classifiers/). Any deviations in spelling and format will cause issues when you publish to PyPI. @@ -500,7 +475,6 @@ maintainers = [ ] readme = "README.md" license = "MIT" -requires-python = ">=3.10" dependencies = ["numpy>=1.0", "requests==10.1", "pandas", "pydantic>=1.7,<2"] @@ -516,7 +490,7 @@ classifiers = [ Note that while classifiers are not required in your `pyproject.toml` file, they will help users find your package. As such we strongly recommend that you add them. -### Step 6: Add the `[project.urls]` table +### Step 5: Add the `[project.urls]` table Finally, add the project.urls table to your pyproject.toml file. @@ -549,7 +523,6 @@ maintainers = [ ] readme = "README.md" license = "MIT" -requires-python = ">=3.10" dependencies = ["numpy>=1.0", "requests==10.1", "pandas", "pydantic>=1.7,<2"] @@ -599,7 +572,6 @@ maintainers = [ ] readme = "README.md" license = "MIT" -requires-python = ">=3.10" dependencies = ["numpy>=1.0", "requests==10.1", "pandas", "pydantic>=1.7,<2"] @@ -672,7 +644,6 @@ classifiers = [ dependencies = ["numpy>=1.0", "requests==10.1", "pandas", "pydantic>=1.7,<2"] # This is the metadata that pip reads to understand what versions your package supports -requires-python = ">=3.10" readme = "README.md" # Pick your license using the license expression syntax specified here: From 655869e7c39bd3b8912f59bb903cb967a0471a48 Mon Sep 17 00:00:00 2001 From: Inessa Pawson Date: Wed, 19 Aug 2026 22:47:18 -0400 Subject: [PATCH 2/3] docs: minor edits --- tutorials/pyproject-toml.md | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/tutorials/pyproject-toml.md b/tutorials/pyproject-toml.md index 2803fadd2..9478a40e7 100644 --- a/tutorials/pyproject-toml.md +++ b/tutorials/pyproject-toml.md @@ -17,7 +17,7 @@ Following that you learned how to add a: to the root of your project directory. -To enhance the visibility of your package on PyPI and provide more information +To enhance the visibility of your package on PyPI and provide information about its development status and maintainers, you should add additional metadata to your `pyproject.toml` file. This lesson will guide you through the process. @@ -322,8 +322,10 @@ We recommend that you use the latest Python release in the **bugfix** phase. If :::{admonition} When to use `requires-python` :class: tip -You do not need to specify `requires-python` for every package. However, if you know that your package will not work with older versions of Python, use `requires-python` to prevent installers from installing it with those versions. -For example, if your package requires features introduced in Python 3.10: +You do not need to specify `requires-python` for every package. However, if you +know that your package will not work with older versions of Python, use `requires-python` +to prevent installers from installing it with those versions. For example, if your package +requires features introduced in Python 3.10: ```toml [project] @@ -336,7 +338,10 @@ This helps `pip` select a compatible release of your package for the Python vers ### Step 3: Specify dependencies Next add your dependencies table to the project table. -The `dependencies =` section contains a list (or array in the toml language) of the Python packages that your package requires to run properly in a Python environment. Similar to the requirements listed in the `[build-system]` table above: +The `dependencies =` section contains a list (or array in the toml language) of +the Python packages that your package requires to run properly in a Python +environment. Similar to the requirements listed in the `[build-system]` +table above: ```toml [build-system] # <- this is a table From bfaf325c875e75d941c35909681a6f8c8522f52c Mon Sep 17 00:00:00 2001 From: Inessa Pawson Date: Thu, 20 Aug 2026 00:07:16 -0400 Subject: [PATCH 3/3] docs: minor edits in admonitions --- tutorials/pyproject-toml.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/tutorials/pyproject-toml.md b/tutorials/pyproject-toml.md index 9478a40e7..9e708b387 100644 --- a/tutorials/pyproject-toml.md +++ b/tutorials/pyproject-toml.md @@ -319,8 +319,9 @@ If you want to distribute license files, or other files containing legal informa 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. +::: -:::{admonition} When to use `requires-python` +:::{admonition} When should I use `requires-python`? :class: tip You do not need to specify `requires-python` for every package. However, if you know that your package will not work with older versions of Python, use `requires-python`