Update "Dropping older Python versions" guide #1471

chrysle · 2023-12-23T14:26:43Z

An attempt to improve the guide. Actually I find the title a bit inaccurate. What about "Changing required Python versions in the package metadata"?

📚 Documentation preview 📚: https://python-packaging-user-guide--1471.org.readthedocs.build/en/1471/guides/dropping-older-python-versions/

source/guides/dropping-older-python-versions.rst

webknjaz · 2023-12-31T16:09:12Z

source/guides/dropping-older-python-versions.rst

@@ -4,23 +4,17 @@
 Dropping support for older Python versions
 ==========================================

-Dropping support for older Python versions is supported by the standard :ref:`core-metadata` 1.2 specification via a "Requires-Python" attribute.
+Dropping support for older Python versions is supported by the standard :ref:`core-metadata` 1.2 specification via a :ref:`"Requires-Python" <core-metadata-requires-python>` attribute.


support ... is supported

Can we change one of these words to something else to improve the writing style?

Also, perhaps using s/a/the/ would be more grammatically correct.

webknjaz · 2023-12-31T16:18:10Z

source/guides/dropping-older-python-versions.rst

+For :ref:`setuptools` users, another way to achieve this is using the ``python_requires`` parameter
+in the call to ``setup`` within your :file:`setup.py` script.


Let's make this a bit more accurate:

Suggested change

For :ref:`setuptools` users, another way to achieve this is using the ``python_requires`` parameter

in the call to ``setup`` within your :file:`setup.py` script.

For :ref:`setuptools` users, another way to achieve this is using the ``python_requires`` parameter in your :file:`setup.cfg` config or the :file:`setup.py` script.

``setuptools < 61`` does not support declaring the package metadata in :file:`pyproject.toml`.

webknjaz · 2023-12-31T16:20:22Z

source/guides/dropping-older-python-versions.rst

+
+
+For :ref:`setuptools` users, another way to achieve this is using the ``python_requires`` parameter
+in the call to ``setup`` within your :file:`setup.py` script.

 .. code-block:: python


Can we demonstrate using a declarative config instead of a script here?

Suggested change

.. code-block:: python

.. code-block:: ini

# setup.cfg

[options]

python_requires = >= 3.8

Also, setuptools now has comprehensive examples in the docs. See:

https://setuptools.pypa.io/en/latest/userguide/dependency_management.html#python-requirement

https://setuptools.pypa.io/en/latest/userguide/declarative_config.html

https://setuptools.pypa.io/en/latest/userguide/pyproject_config.html

So perhaps linking them instead of having a tool-specific example spelled out, would be a good option.

webknjaz · 2023-12-31T16:21:26Z

source/guides/dropping-older-python-versions.rst

    )

+It is warned against adding upper bounds to the version ranges, e. g. ``">= 3.8 < 3.10"``. This can cause different errors


Could you add an admonition here? Like .. caution::? https://pradyunsg.me/furo/reference/admonitions/#caution

webknjaz · 2023-12-31T16:22:01Z

source/guides/dropping-older-python-versions.rst

 3. Validating the Metadata before publishing
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

 Within a Python source package (the zip or the tar-gz file you download) is a text file called PKG-INFO.

-This file is generated by :ref:`distutils` or :ref:`setuptools` when it generates the source package.
-The file contains a set of keys and values, the list of keys is part of the PyPa standard metadata format.
+This file is generated by the build backend when it generates the source package.


Could you link the build backend term?

webknjaz · 2023-12-31T16:22:15Z

source/guides/dropping-older-python-versions.rst


 You can see the contents of the generated file like this:

 .. code-block:: bash

-    tar xfO dist/my-package-1.0.0.tar.gz my-package-1.0.0/PKG-INFO
+    tar xf dist/my-package-1.0.0.tar.gz my-package-1.0.0/PKG-INFO -O


webknjaz · 2023-12-31T16:27:51Z

source/guides/dropping-older-python-versions.rst

+``Requires-Python`` should be amended. Of course this also depends on whether the project needs to be stable and
+well-covered for a wider range of users.
+
+Each version compatibility change should have an own release.


Suggested change

Each version compatibility change should have an own release.

Each version compatibility change should have its own release.

webknjaz · 2023-12-31T16:33:33Z

source/guides/dropping-older-python-versions.rst

+For example, you published version 1.0.0 of your package with ``Requires-Python: ">= 2.7"`` metadata.
+
+If you then 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 have version 1.0.0 of the package installed, and any ``>= 3.5`` users will receive version 2.0.0.


Not sure I agree with this at all. It's absolutely orthogonal to SemVer. The dependency resolvers will always select a runtime-compatible version for as long as this information is present in the package metadata.

Dropping a runtime support is not a feature change. And in SemVer, the major version release is for breaking APIs a project provides to the end-users. This metadata change may happen anytime and is a subject to different considerations that are dependent on the conventions of specific projects.

Let's not overload this guide with assumptions based on one specific schema for communicating API changes, that is known to be problematic anyway.

The maintainers can choose to synchronize dropping a runtime with a versioning scheme of their choice but that's not something that is mandatory for changing a metadata field value.

I think @jaraco mentioned this too somewhere.

Agreed on not making assumptions about versions schemes.

It's been my instinct that dropping a platform isn't a breaking change because of the reasons described (it doesn't break anyone who's likely to download it).

webknjaz · 2023-12-31T16:39:05Z

source/guides/dropping-older-python-versions.rst


-It must be done in this order for the automated fallback to work.
+It may be a good idea to create a minor release, stating that it is the last one compatible with the Python version to be removed, just before dropping that version.


I don't think this advice makes sense anymore. It could be a patch release too. The idea here was that before Requires-Python became a thing, many projects were released without this bit of metadata. And this would cause the dependency resolver to treat the old releases as supporting any Python runtime. So if people were to add a high minimum Python version right away, the resolver would backtrack to the one immediately preceding release.

So this is a good advice for old project that never had this metadata field set. Once they start using it, they can update it anytime, regardless of any other pieces of the metadata.

webknjaz · 2023-12-31T16:43:59Z

source/guides/dropping-older-python-versions.rst

-1. The publisher is using the latest version of :ref:`setuptools`,
-2. The latest version of :ref:`twine` is used to upload the package,
-3. The user installing the package has at least Pip 9.0, or a client that supports the Metadata 1.2 specification.
+This workflow requires that the user installing the package has at least Pip 9.0, or a client that supports the Metadata 1.2 specification.

 Dealing with the universal wheels


@chrysle this paragraph is specifically talking about setuptools, bdist_wheel as a setuptools' command that invokes the wheel project APIs internally and a CLI option (in the tip block below) that is supposed to be passed to the direct CLI invocation of setup.py, which is also discouraged.

So while you're on it, could to add clarifications that it's solely about the setuptools' mechanisms and maybe drop (or rephrase) the suggestions to use the CLI flag?

webknjaz · 2023-12-31T16:46:26Z

source/guides/dropping-older-python-versions.rst


-For example, you published the Requires-Python: ">=2.7" as version 1.0.0 of your package.
+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_ can simplify this task.


Let's put this into an admonition like .. hint:: or .. tip::.

Co-authored-by: Sviatoslav Sydorenko <wk.cvs.github@sydorenko.org.ua> Co-authored-by: Jean Abou-Samra <37271310+jeanas@users.noreply.github.com>

chrysle · 2024-01-01T15:07:35Z

Thank you for your comments! I addressed them.

jeanas

Sorry for the lack of explicit approval here. (I'm also going to resolve my comments. Edit: In fact I don't have the permissions to resolve them.)

chrysle · 2024-01-26T12:54:53Z

(I'm also going to resolve my comments. Edit: In fact I don't have the permissions to resolve them.)

I did that now, thank you for your review!

edgarrmondragon · 2024-04-15T23:12:40Z

source/guides/dropping-older-python-versions.rst

-    Requires-Python: ">=3"
-    Requires-Python: ">2.7,!=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*"
+    Requires-Python: ">= 3"
+    Requires-Python: ">= 2.7, != 3.0.*, != 3.1.*, != 3.2.*, != 3.3.*"


Should this example be updated to use newer Python versions? I don't think most people reading this guide would be interested in supporting Python 2.7 or 3.4-3.7.

Update "Dropping older Python versions" guide

67cd77b

jeanas reviewed Dec 30, 2023

View reviewed changes

source/guides/dropping-older-python-versions.rst Outdated Show resolved Hide resolved

source/guides/dropping-older-python-versions.rst Outdated Show resolved Hide resolved

source/guides/dropping-older-python-versions.rst Outdated Show resolved Hide resolved

webknjaz reviewed Dec 31, 2023

View reviewed changes

Address review comments

430f5bd

Co-authored-by: Sviatoslav Sydorenko <wk.cvs.github@sydorenko.org.ua> Co-authored-by: Jean Abou-Samra <37271310+jeanas@users.noreply.github.com>

jeanas approved these changes Jan 25, 2024

View reviewed changes

chrysle requested a review from webknjaz January 29, 2024 14:26

edgarrmondragon reviewed Apr 15, 2024

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update "Dropping older Python versions" guide #1471

Update "Dropping older Python versions" guide #1471

chrysle commented Dec 23, 2023 •

edited by webknjaz

webknjaz Dec 31, 2023

webknjaz Dec 31, 2023

webknjaz Dec 31, 2023

webknjaz Dec 31, 2023

webknjaz Dec 31, 2023

webknjaz Dec 31, 2023

webknjaz Dec 31, 2023

webknjaz Dec 31, 2023

webknjaz Dec 31, 2023

webknjaz Dec 31, 2023

jaraco Apr 16, 2024

webknjaz Dec 31, 2023

webknjaz Dec 31, 2023 •

edited

webknjaz Dec 31, 2023

chrysle commented Jan 1, 2024

jeanas left a comment •

edited

chrysle commented Jan 26, 2024

edgarrmondragon Apr 15, 2024 •

edited

		For :ref:`setuptools` users, another way to achieve this is using the ``python_requires`` parameter
		in the call to ``setup`` within your :file:`setup.py` script.

-.. code-block:: python
+.. code-block:: ini
+   # setup.cfg
+   [options]
+   python_requires = >= 3.8

		)

		It is warned against adding upper bounds to the version ranges, e. g. ``">= 3.8 < 3.10"``. This can cause different errors

	Each version compatibility change should have an own release.
	Each version compatibility change should have its own release.

		For example, you published version 1.0.0 of your package with ``Requires-Python: ">= 2.7"`` metadata.

		If you then 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 have version 1.0.0 of the package installed, and any ``>= 3.5`` users will receive version 2.0.0.


		It must be done in this order for the automated fallback to work.
		It may be a good idea to create a minor release, stating that it is the last one compatible with the Python version to be removed, just before dropping that version.


		For example, you published the Requires-Python: ">=2.7" as version 1.0.0 of your package.
		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_ can simplify this task.

Update "Dropping older Python versions" guide #1471

Are you sure you want to change the base?

Update "Dropping older Python versions" guide #1471

Conversation

chrysle commented Dec 23, 2023 • edited by webknjaz

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

webknjaz Dec 31, 2023 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

chrysle commented Jan 1, 2024

jeanas left a comment • edited

Choose a reason for hiding this comment

chrysle commented Jan 26, 2024

edgarrmondragon Apr 15, 2024 • edited

Choose a reason for hiding this comment

chrysle commented Dec 23, 2023 •

edited by webknjaz

webknjaz Dec 31, 2023 •

edited

jeanas left a comment •

edited

edgarrmondragon Apr 15, 2024 •

edited