Merge pull request #2134 from pypa/feature/python-2-sunset-docs

Crash under Python 2

Author: jaraco

.github/ISSUE_TEMPLATE/setuptools-warns-about-python-2-incompatibility.md

@@ -13,7 +13,7 @@ Please DO NOT SUBMIT this template without first investigating the issue and ans
 
 If you did not intend to use this template, but only meant to file a blank issue, just hit the back button and click "Open a blank issue".
 
-It's by design that Setuptools 45 and later will stop working on Python 2. To ease the transition, Setuptools 45 was released to continue to have Python 2 compatibility, but emit a strenuous warning that it will stop working.
+Setuptools 45 dropped support for Python 2 with a strenuous warning and Setuptools 47 fails to run on Python 2.
 
 In most cases, using pip 9 or later to install Setuptools from PyPI or any index supporting the Requires-Python metadata will do the right thing and install Setuptools 44.x on Python 2.
 
@@ -28,6 +28,7 @@ Your first course of action should be to reason about how you managed to get an
 <!-- These are the recommended workarounds for the issue. Please
 try them first. -->
 
+- [ ] Read [Python 2 Sunset docs](https://setuptools.readthedocs.io/en/latest/python%202%20sunset.html).
 - [ ] Python 2 is required for this application.
 - [ ] I maintain the software that installs Setuptools (if not, please contact that project).
 - [ ] Setuptools installed with pip 9 or later.
@@ -40,6 +41,11 @@ try them first. -->
 - Python installed how:
 - Virtualenv version (if using virtualenv): n/a
 
+Command(s) that triggered the warning/error (and output):
+
+```
+```
+
 Command(s) used to install setuptools (and output):
 
 ```

.travis.yml

@@ -4,11 +4,6 @@ language: python
 jobs:
   fast_finish: true
   include:
-  - &latest_py2
-    python: 2.7
-    env: TOXENV=py27
-  - <<: *latest_py2
-    env: LANG=C TOXENV=py27
   - python: pypy3
     env: DISABLE_COVERAGE=1  # Don't run coverage on pypy (too slow).
   - python: 3.5

changelog.d/2094.breaking.rst

@@ -0,0 +1 @@
+Setuptools now actively crashes under Python 2. Python 3.5 or later is required. Users of Python 2 should use ``setuptools<45``.

docs/python 2 sunset.txt

@@ -0,0 +1,69 @@
+:orphan:
+
+Python 2 Sunset
+===============
+
+Since January 2020 and the release of Setuptools 45, Python 2 is no longer
+supported by the most current release (`discussion
+<https://github.com/pypa/setuptools/issues/1458>`_). Setuptools as a project
+continues to support Python 2 with bugfixes and important features on
+Setuptools 44.x.
+
+By design, most users will be unaffected by this change. That's because
+Setuptools 45 declares its supported Python versions to exclude Python 2.7,
+and installers such as pip 9 or later will honor this declaration and prevent
+installation of Setuptools 45 or later in Python 2 environments.
+
+Users that do import any portion of Setuptools 45 or later on Python 2 are
+directed to this documentation to provide guidance on how to work around the
+issues.
+
+Workarounds
+-----------
+
+The best recommendation is to avoid Python 2 and move to Python 3 where
+possible. This project acknowledges that not all environments can drop Python
+2 support, so provides other options.
+
+In less common scenarios, later versions of Setuptools can be installed on
+unsupported Python versions. In these environments, the installer is advised
+to first install ``setuptools<45`` to "pin Setuptools" to a compatible
+version.
+
+- When using older versions of pip (before 9.0), the ``Requires-Python``
+  directive is not honored and invalid versions can be installed. Users are
+  advised first to upgrade pip and retry or to pin Setuptools. Use ``pip
+  --version`` to determine the version of pip.
+- When using ``easy_install``, ``Requires-Python`` is not honored and later
+  versions can be installed. In this case, users are advised to pin
+  Setuptools. This applies to ``setup.py install`` invocations as well, as
+  they use Setuptools under the hood.
+
+It's still not working
+----------------------
+
+If after trying the above steps, the Python environment still has incompatible
+versions of Setuptools installed, here are some things to try.
+
+1. Uninstall and reinstall Setuptools. Run ``pip uninstall -y setuptools`` for
+   the relevant environment. Repeat until there is no Setuptools installed.
+   Then ``pip install setuptools``.
+2. If possible, attempt to replicate the problem in a second environment
+   (virtual machine, friend's computer, etc). If the issue is isolated to just
+   one unique enviornment, first determine what is different about those
+   environments (or reinstall/reset the failing one to defaults).
+3. End users who are not themselves the maintainers for the package they are
+   trying to install should contact the support channels for the relevant
+   application. Please be considerate of those projects by searching for
+   existing issues and following the latest guidance before reaching out for
+   support. When filing an issue, be sure to give as much detail as possible
+   to help the maintainers understand what factors led to the issue after
+   following their recommended guidance.
+4. Reach out to your local support groups. There's a good chance someone
+   nearby has the expertise and willingness to help.
+5. If all else fails, `file this template
+   <https://github.com/pypa/setuptools/issues/new?assignees=&labels=Python+2&template=setuptools-warns-about-python-2-incompatibility.md&title=Incompatible+install+in+(summarize+your+environment)>`_
+   with Setuptools. Please complete the whole template, providing as much
+   detail about what factors led to the issue. Setuptools maintainers will
+   summarily close tickets filed without any meaningful detail or engagement
+   with the issue.

pkg_resources/py2_warn.py

@@ -4,18 +4,13 @@
 
 
 msg = textwrap.dedent("""
-    You are running Setuptools on Python 2, which is no longer
-    supported and
-    >>> SETUPTOOLS WILL STOP WORKING <<<
-    in a subsequent release (no sooner than 2020-04-20).
-    Please ensure you are installing
-    Setuptools using pip 9.x or later or pin to `setuptools<45`
-    in your environment.
-    If you have done those things and are still encountering
-    this message, please follow up at
-    https://bit.ly/setuptools-py2-warning.
+    Encountered a version of Setuptools that no longer supports
+    this version of Python. Please head to
+    https://bit.ly/setuptools-py2-warning for support.
     """)
 
-pre = "Setuptools will stop working on Python 2\n"
+pre = "Setuptools no longer works on Python 2\n"
 
-sys.version_info < (3,) and warnings.warn(pre + "*" * 60 + msg + "*" * 60)
+if sys.version_info < (3,):
+    warnings.warn(pre + "*" * 60 + msg + "*" * 60)
+    raise SystemExit(32)