You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: source/guides/dropping-older-python-versions.rst
+53-53Lines changed: 53 additions & 53 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,34 +4,27 @@
4
4
Dropping support for older Python versions
5
5
==========================================
6
6
7
-
Dropping support for older Python versions is supported by the standard :ref:`core-metadata` 1.2 specification via a "Requires-Python" attribute.
7
+
The ability to drop support for older Python versions is enabled by the standard :ref:`core-metadata` 1.2 specification via the :ref:`"Requires-Python"<core-metadata-requires-python>` attribute.
8
8
9
-
Metadata 1.2+ clients, such as Pip 9.0+, will adhere to this specification by matching the current Python runtime and comparing it with the required version
9
+
Metadata 1.2+ installers, such as Pip, will adhere to this specification by matching the current Python runtime and comparing it with the required version
10
10
in the package metadata. If they do not match, it will attempt to install the last package distribution that supported that Python runtime.
11
11
12
-
This mechanism can be used to drop support for older Python versions, by amending the "Requires-Python" attribute in the package metadata.
13
-
14
-
This guide is specifically for users of :ref:`setuptools`, other packaging tools such as ``flit`` may offer similar functionality but users will need to consult relevant documentation.
12
+
This mechanism can be used to drop support for older Python versions, by amending the ``Requires-Python`` attribute in the package metadata.
15
13
16
14
Requirements
17
15
------------
18
16
19
-
This workflow requires that:
20
-
21
-
1. The publisher is using the latest version of :ref:`setuptools`,
22
-
2. The latest version of :ref:`twine` is used to upload the package,
23
-
3. The user installing the package has at least Pip 9.0, or a client that supports the Metadata 1.2 specification.
17
+
This workflow requires that the user installing the package uses Pip [#]_, or another installer that supports the Metadata 1.2 specification.
24
18
25
19
Dealing with the universal wheels
26
20
---------------------------------
27
21
28
-
Traditionally, projects providing Python code that is semantically
22
+
Traditionally, :ref:`setuptools` projects providing Python code that is semantically
29
23
compatible with both Python 2 and Python 3, produce :term:`wheels
30
24
<Wheel>` that have a ``py2.py3`` tag in their names. When dropping
31
25
support for Python 2, it is important not to forget to change this tag
32
26
to just ``py3``. It is often configured within :file:`setup.cfg` under
33
-
the ``[bdist_wheel]`` section by setting ``universal = 1`` if they
34
-
use setuptools.
27
+
the ``[bdist_wheel]`` section by setting ``universal = 1``.
35
28
36
29
If you use this method, either remove this option or section, or
37
30
explicitly set ``universal`` to ``0``:
@@ -43,69 +36,69 @@ explicitly set ``universal`` to ``0``:
43
36
[bdist_wheel]
44
37
universal = 0 # Make the generated wheels have "py3" tag
45
38
46
-
.. tip::
39
+
.. hint::
47
40
48
-
Since it is possible to override the :file:`setup.cfg` settings via
49
-
CLI flags, make sure that your scripts don't have ``--universal`` in
50
-
your package creation scripts.
41
+
Regarding :ref:`deprecated <setup-py-deprecated>` direct ``setup.py`` invocations,
42
+
passing the ``--universal`` flag on the command line could override this setting.
51
43
52
44
Defining the Python version required
53
45
------------------------------------
54
46
55
-
1. Download the newest version of Setuptools
56
-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
57
-
58
-
Ensure that before you generate source distributions or binary distributions, you update Setuptools and install twine.
47
+
1. Install twine
48
+
~~~~~~~~~~~~~~~~
59
49
50
+
Ensure that you have twine available at its latest version.
60
51
Steps:
61
52
62
53
.. tab:: Unix/macOS
63
54
64
55
.. code-block:: bash
65
56
66
-
python3 -m pip install --upgrade setuptools twine
57
+
python3 -m pip install --upgrade twine
67
58
68
59
.. tab:: Windows
69
60
70
61
.. code-block:: bat
71
62
72
-
py -m pip install --upgrade setuptools twine
73
-
74
-
``setuptools`` version should be above 24.0.0.
63
+
py -m pip install --upgrade twine
75
64
76
65
2. Specify the version ranges for supported Python distributions
The way to set those values is within the call to ``setup`` within your
89
-
:file:`setup.py` script. This will insert the ``Requires-Python``
90
-
metadata values based on the argument you provide in ``python_requires``.
80
+
You can specify version ranges and exclusion rules (complying with the :ref:`version-specifiers` specification),
81
+
such as at least Python 3.9. Or, at least Python 3.7 and beyond, skipping the 3.7.0 and 3.7.1 point releases:
91
82
92
-
.. code-block:: python
83
+
.. code-block:: toml
93
84
94
-
from setuptools import setup
85
+
requires-python = ">= 3.9"
86
+
requires-python = ">= 3.7, != 3.7.0, != 3.7.1"
95
87
96
88
97
-
setup(
98
-
# Your setup arguments
99
-
python_requires='>=2.7', # Your supported Python ranges
100
-
)
89
+
If using the :ref:`setuptools` build backend, consult the `dependency-management`_ documentation for more options.
90
+
91
+
.. caution::
92
+
Avoid adding upper bounds to the version ranges, e. g. ``">= 3.8, < 3.10"``. Doing so can cause different errors
93
+
and version conflicts. See the `discourse-discussion`_ for more information.
101
94
102
95
3. Validating the Metadata before publishing
103
96
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
104
97
105
98
Within a Python source package (the zip or the tar-gz file you download) is a text file called PKG-INFO.
106
99
107
-
This file is generated by :ref:`distutils` or :ref:`setuptools` when it generates the source package.
108
-
The file contains a set of keys and values, the list of keys is part of the PyPa standard metadata format.
100
+
This file is generated by the :term:`build backend <Build Backend>` when it generates the source package.
101
+
The file contains a set of keys and values, the list of keys is part of the PyPA standard metadata format.
109
102
110
103
You can see the contents of the generated file like this:
111
104
@@ -115,24 +108,31 @@ You can see the contents of the generated file like this:
115
108
116
109
Validate that the following is in place, before publishing the package:
117
110
118
-
- If you have upgraded correctly, the Metadata-Version value should be 1.2 or higher.
119
-
- The Requires-Python field is set and matches your specification in setup.py.
111
+
- If you have upgraded correctly, the ``Metadata-Version`` value should be 1.2 or higher.
112
+
- The ``Requires-Python`` field is set and matches your specification in the configuration file.
120
113
121
-
4. Using Twine to publish
114
+
4. Publishing the package
122
115
~~~~~~~~~~~~~~~~~~~~~~~~~
123
116
124
-
Twine has a number of advantages, apart from being faster it is now the supported method for publishing packages.
125
-
126
-
Make sure you are using the newest version of Twine, at least 1.9.
117
+
Proceed as suggested in :ref:`Uploading your Project to PyPI`.
127
118
128
-
Dropping a Python release
119
+
Dropping a Python version
129
120
-------------------------
130
121
131
-
Once you have published a package with the Requires-Python metadata, you can then make a further update removing that Python runtime from support.
122
+
In principle, at least metadata support for Python versions should be kept as long as possible, because
123
+
once that has been dropped, people still depending on a version will be forced to downgrade.
124
+
If however supporting a specific version becomes a blocker for a new feature or other issues occur, the metadata
125
+
``Requires-Python`` should be amended. Of course this also depends on whether the project needs to be stable and
126
+
well-covered for a wider range of users.
127
+
128
+
Each version compatibility change should have its own release.
129
+
130
+
.. tip::
132
131
133
-
It must be done in this order for the automated fallback to work.
132
+
When dropping a Python version, it might also be rewarding to upgrade the project's code syntax generally, apart from updating the versions used in visible places (like the testing environment). Tools like pyupgrade_ or `ruff <https://docs.astral.sh/ruff/linter/>`_ can automate some of this work.
134
133
135
-
For example, you published the Requires-Python: ">=2.7" as version 1.0.0 of your package.
If you were then to update the version string to ">=3.5", and publish a new version 2.0.0 of your package, any users running Pip 9.0+ from version 2.7 will
138
-
have version 1.0.0 of the package installed, and any >=3.5 users will receive version 2.0.0.
138
+
.. [#] Support for the Metadata 1.2 specification has been added in Pip 9.0.
0 commit comments