Tutorial for phasing out Python versions

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.

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