diff --git a/source/guides/dropping-older-python-versions.rst b/source/guides/dropping-older-python-versions.rst new file mode 100644 index 000000000..32f0883c2 --- /dev/null +++ b/source/guides/dropping-older-python-versions.rst @@ -0,0 +1,96 @@ +.. _`Dropping Support for Older Python Versions`: + +========================================== +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. + +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 +in the package metadata. If they do not match, it will attempt to install the last package distribution that supported that Python runtime. + +This mechanism can be used to drop support for older Python versions, by amending the "Requires-Python" attribute in the package metadata. + +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. + +Requirements +------------ + +This workflow requires that: + +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. + +Defining the Python version required +------------------------------------ + +1. Download the newest version of Setuptools +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Ensure that before you generate source distributions or binary distributions, you update Setuptools and twine. + +Steps:: + + pip install --upgrade setuptools twine + +Version should be above 24.0.0. + +2. Specify the version ranges for supported Python distributions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can specify version ranges and exclusion rules, such as at least Python 3. Or, Python 2.7, 3.4 and beyond. + +Examples:: + + Requires-Python: ">=3" + Requires-Python: ">2.7,!=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*" + +The way to set those values is within the call to `setup` within your setup.py script. This will insert the Requires-Python +metadata values based on the argument you provide in `python_requires`. + +..code-block:: Python + + from setuptools import setup + + + setup( + # Your setup arguments + python_requires='>=2.7', # Your supported Python ranges + ) + +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 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. + +You can see the contents of the generated file like this: + + tar xvfz dist/my-package-1.0.0.tar.gz -O | cat */PKG-INFO + +Validate that the following is in place, before publishing the package: + +- If you have upgraded correctly, the Metadata-Version value should be 1.2 or higher. +- The Requires-Python field is set and matches your specification in setup.py. + +4. Using Twine to publish +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Twine has a number of advantages, apart from being faster it is now the supported method for publishing packages. + +Make sure you are using the newest version of Twine, at least 1.9. + +Dropping a Python release +------------------------- + +Once you have published a package with the Requires-Python metadata, you can then make a further update removing that Python runtime from support. + +It must be done in this order for the automated fail-back to work. + +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 +have version 1.0.0 of the package installed, and any >=3.5 users will receive version 2.0.0. \ No newline at end of file diff --git a/source/guides/index.rst b/source/guides/index.rst index 113106c80..150284b66 100644 --- a/source/guides/index.rst +++ b/source/guides/index.rst @@ -15,6 +15,7 @@ introduction to packaging, see :doc:`/tutorials/index`. multi-version-installs single-sourcing-package-version supporting-multiple-python-versions + dropping-older-python-versions packaging-binary-extensions supporting-windows-using-appveyor packaging-namespace-packages