Merge branch 'master' into check-file-distinfo

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

@@ -9,6 +9,10 @@ assignees: ''
 
 <!--
 
+Please DO NOT SUBMIT this template without first investigating the issue and answering the questions below. This template is intended mainly for developers of systems and not for end users. If you are an end user experiencing the warning, please work with your system maintainers (starting with the project you're trying to use) to report the issue.
+
+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.
 
 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.
@@ -32,8 +36,8 @@ try them first. -->
 ## Environment Details
 
 - Operating System and version:
-- Python version: 
-- Python installed how: 
+- Python version:
+- Python installed how:
 - Virtualenv version (if using virtualenv): n/a
 
 Command(s) used to install setuptools (and output):

.gitignore

@@ -19,3 +19,4 @@ setuptools.egg-info
 .cache
 .idea/
 .pytest_cache/
+.mypy_cache/

changelog.d/1698.doc.rst

+Added documentation for ``build_meta`` (a bare minimum, not completed).

changelog.d/2062.change.rst

+Change 'Mac OS X' to 'macOS' in code.

changelog.d/2082.misc.rst

+Filter ``lib2to3`` ``PendingDeprecationWarning`` and ``DeprecationWarning`` in testes,
+because ``lib2to3`` is `deprecated in Python 3.9 <https://bugs.python.org/issue40360>`_.

changelog.d/2086.change.rst

+Deprecate 'use_2to3' functionality. Packagers are encouraged to use single-source solutions or build tool chains to manage conversions outside of setuptools.

docs/build_meta.txt

+=======================================
+Build System Support
+=======================================
+
+What is it?
+-------------
+
+Python packaging has come `a long way <https://www.bernat.tech/pep-517-518/>`_.
+
+The traditional ``setuptools`` way of packgaging Python modules
+uses a ``setup()`` function within the ``setup.py`` script. Commands such as
+``python setup.py bdist`` or ``python setup.py bdist_wheel`` generate a 
+distribution bundle and ``python setup.py install`` installs the distribution. 
+This interface makes it difficult to choose other packaging tools without an 
+overhaul. Because ``setup.py`` scripts allowed for arbitrary execution, it
+proved difficult to provide a reliable user experience across environments
+and history.
+
+`PEP 517 <https://www.python.org/dev/peps/pep-0517/>`_ therefore came to
+rescue and specified a new standard to 
+package and distribute Python modules. Under PEP 517:
+
+    a ``pyproject.toml`` file is used to specify what program to use
+    for generating distribution. 
+
+    Then, two functions provided by the program, ``build_wheel(directory: str)`` 
+    and ``build_sdist(directory: str)`` create the distribution bundle at the 
+    specified ``directory``. The program is free to use its own configuration 
+    script or extend the ``.toml`` file. 
+
+    Lastly, ``pip install *.whl`` or ``pip install *.tar.gz`` does the actual
+    installation. If ``*.whl`` is available, ``pip`` will go ahead and copy
+    the files into ``site-packages`` directory. If not, ``pip`` will look at
+    ``pyproject.toml`` and decide what program to use to 'build from source' 
+    (the default is ``setuptools``)
+
+With this standard, switching between packaging tools becomes a lot easier. ``build_meta``
+implements ``setuptools``' build system support.
+
+How to use it?
+--------------
+
+Starting with a package that you want to distribute. You will need your source
+scripts, a ``pyproject.toml`` file and a ``setup.cfg`` file::
+
+    ~/meowpkg/
+        pyproject.toml
+        setup.cfg
+        meowpkg/__init__.py
+
+The pyproject.toml file is required to specify the build system (i.e. what is 
+being used to package your scripts and install from source). To use it with 
+setuptools, the content would be::
+
+    [build-system]
+    requires = ["setuptools", "wheel"]
+    build-backend = "setuptools.build_meta" 
+
+Use ``setuptools``' `declarative config`_ to specify the package information::
+
+    [metadata]
+    name = meowpkg
+    version = 0.0.1
+    description = a package that meows
+    
+    [options]
+    packages = find:
+
+Now generate the distribution. Although the PyPA is still working to
+`provide a recommended tool <https://github.com/pypa/packaging-problems/issues/219>`_
+to build packages, the `pep517 package <https://pypi.org/project/pep517`_
+provides this functionality. To build the package::
+
+    $ pip install -q pep517
+    $ mkdir dist
+    $ python -m pep517.build .
+
+And now it's done! The ``.whl`` file  and ``.tar.gz`` can then be distributed 
+and installed::
+
+    dist/
+        meowpkg-0.0.1.whl
+        meowpkg-0.0.1.tar.gz
+
+    $ pip install dist/meowpkg-0.0.1.whl
+
+or::
+
+    $ pip install dist/meowpkg-0.0.1.tar.gz

docs/history.txt

@@ -12,7 +12,7 @@ Credits
 
 * The original design for the ``.egg`` format and the ``pkg_resources`` API was
   co-created by Phillip Eby and Bob Ippolito. Bob also implemented the first
-  version of ``pkg_resources``, and supplied the OS X operating system version
+  version of ``pkg_resources``, and supplied the macOS operating system version
   compatibility algorithm.
 
 * Ian Bicking implemented many early "creature comfort" features of

docs/pkg_resources.txt

@@ -1621,7 +1621,7 @@ Platform Utilities
 
 ``get_build_platform()``
     Return this platform's identifier string.  For Windows, the return value
-    is ``"win32"``, and for Mac OS X it is a string of the form
+    is ``"win32"``, and for macOS it is a string of the form
     ``"macosx-10.4-ppc"``.  All other platforms return the same uname-based
     string that the ``distutils.util.get_platform()`` function returns.
     This string is the minimum platform version required by distributions built
@@ -1641,7 +1641,7 @@ Platform Utilities
     considered a wildcard, and the platforms are therefore compatible.
     Likewise, if the platform strings are equal, they're also considered
     compatible, and ``True`` is returned.  Currently, the only non-equal
-    platform strings that are considered compatible are Mac OS X platform
+    platform strings that are considered compatible are macOS platform
     strings with the same hardware type (e.g. ``ppc``) and major version
     (e.g. ``10``) with the `provided` platform's minor version being less than
     or equal to the `required` platform's minor version.
@@ -1674,7 +1674,7 @@ File/Path Utilities
     the same filesystem location if they have equal ``normalized_path()``
     values.  Specifically, this is a shortcut for calling ``os.path.realpath``
     and ``os.path.normcase`` on `path`.  Unfortunately, on certain platforms
-    (notably Cygwin and Mac OS X) the ``normcase`` function does not accurately
+    (notably Cygwin and macOS) the ``normcase`` function does not accurately
     reflect the platform's case-sensitivity, so there is always the possibility
     of two apparently-different paths being equal on such platforms.
 

docs/setuptools.txt

@@ -2106,8 +2106,9 @@ Configuring setup() using setup.cfg files
 .. note:: New in 30.3.0 (8 Dec 2016).
 
 .. important::
-    A ``setup.py`` file containing a ``setup()`` function call is still
-    required even if your configuration resides in ``setup.cfg``.
+    If compatibility with legacy builds (i.e. those not using the :pep:`517`
+    build API) is desired, a ``setup.py`` file containing a ``setup()`` function
+    call is still required even if your configuration resides in ``setup.cfg``.
 
 ``Setuptools`` allows using configuration files (usually :file:`setup.cfg`)
 to define a package’s metadata and other options that are normally supplied

pkg_resources/__init__.py

@@ -179,10 +179,10 @@ def get_supported_platform():
     """Return this platform's maximum compatible version.
 
     distutils.util.get_platform() normally reports the minimum version
-    of Mac OS X that would be required to *use* extensions produced by
+    of macOS that would be required to *use* extensions produced by
     distutils.  But what we want when checking compatibility is to know the
-    version of Mac OS X that we are *running*.  To allow usage of packages that
-    explicitly require a newer version of Mac OS X, we must also know the
+    version of macOS that we are *running*.  To allow usage of packages that
+    explicitly require a newer version of macOS, we must also know the
     current version of the OS.
 
     If this condition occurs for any other platform with a version in its
@@ -192,9 +192,9 @@ def get_supported_platform():
     m = macosVersionString.match(plat)
     if m is not None and sys.platform == "darwin":
         try:
-            plat = 'macosx-%s-%s' % ('.'.join(_macosx_vers()[:2]), m.group(3))
+            plat = 'macosx-%s-%s' % ('.'.join(_macos_vers()[:2]), m.group(3))
         except ValueError:
-            # not Mac OS X
+            # not macOS
             pass
     return plat
 
@@ -365,7 +365,7 @@ def get_provider(moduleOrReq):
     return _find_adapter(_provider_factories, loader)(module)
 
 
-def _macosx_vers(_cache=[]):
+def _macos_vers(_cache=[]):
     if not _cache:
         version = platform.mac_ver()[0]
         # fallback for MacPorts
@@ -381,7 +381,7 @@ def _macosx_vers(_cache=[]):
     return _cache[0]
 
 
-def _macosx_arch(machine):
+def _macos_arch(machine):
     return {'PowerPC': 'ppc', 'Power_Macintosh': 'ppc'}.get(machine, machine)
 
 
@@ -389,18 +389,18 @@ def get_build_platform():
     """Return this platform's string for platform-specific distributions
 
     XXX Currently this is the same as ``distutils.util.get_platform()``, but it
-    needs some hacks for Linux and Mac OS X.
+    needs some hacks for Linux and macOS.
     """
     from sysconfig import get_platform
 
     plat = get_platform()
     if sys.platform == "darwin" and not plat.startswith('macosx-'):
         try:
-            version = _macosx_vers()
+            version = _macos_vers()
             machine = os.uname()[4].replace(" ", "_")
             return "macosx-%d.%d-%s" % (
                 int(version[0]), int(version[1]),
-                _macosx_arch(machine),
+                _macos_arch(machine),
             )
         except ValueError:
             # if someone is running a non-Mac darwin system, this will fall
@@ -426,7 +426,7 @@ def compatible_platforms(provided, required):
         # easy case
         return True
 
-    # Mac OS X special cases
+    # macOS special cases
     reqMac = macosVersionString.match(required)
     if reqMac:
         provMac = macosVersionString.match(provided)
@@ -435,7 +435,7 @@ def compatible_platforms(provided, required):
         if not provMac:
             # this is backwards compatibility for packages built before
             # setuptools 0.6. All packages built after this point will
-            # use the new macosx designation.
+            # use the new macOS designation.
             provDarwin = darwinVersionString.match(provided)
             if provDarwin:
                 dversion = int(provDarwin.group(1))
@@ -443,7 +443,7 @@ def compatible_platforms(provided, required):
                 if dversion == 7 and macosversion >= "10.3" or \
                         dversion == 8 and macosversion >= "10.4":
                     return True
-            # egg isn't macosx or legacy darwin
+            # egg isn't macOS or legacy darwin
             return False
 
         # are they the same major version and machine type?

pkg_resources/api_tests.txt

@@ -290,8 +290,8 @@ Platform Compatibility Rules
 ----------------------------
 
 On the Mac, there are potential compatibility issues for modules compiled
-on newer versions of Mac OS X than what the user is running. Additionally,
-Mac OS X will soon have two platforms to contend with: Intel and PowerPC.
+on newer versions of macOS than what the user is running. Additionally,
+macOS will soon have two platforms to contend with: Intel and PowerPC.
 
 Basic equality works as on other platforms::
 

pytest.ini

@@ -20,3 +20,6 @@ filterwarnings =
     ignore:Unicode unequal comparison failed to convert:UnicodeWarning
     # https://github.com/pypa/setuptools/issues/2025
     ignore:direct construction of .*Item has been deprecated:DeprecationWarning
+    # https://github.com/pypa/setuptools/issues/2081
+    ignore:lib2to3 package is deprecated:PendingDeprecationWarning
+    ignore:lib2to3 package is deprecated:DeprecationWarning

setuptools/command/easy_install.py

-#!/usr/bin/env python
 """
 Easy Install
 ------------

setuptools/lib2to3_ex.py

@@ -7,11 +7,13 @@ Customized Mixin2to3 support:
 This module raises an ImportError on Python 2.
 """
 
+import warnings
 from distutils.util import Mixin2to3 as _Mixin2to3
 from distutils import log
 from lib2to3.refactor import RefactoringTool, get_fixers_from_package
 
 import setuptools
+from ._deprecation_warning import SetuptoolsDeprecationWarning
 
 
 class DistutilsRefactoringTool(RefactoringTool):
@@ -33,6 +35,13 @@ class Mixin2to3(_Mixin2to3):
             return
         if not files:
             return
+
+        warnings.warn(
+            "2to3 support is deprecated. If the project still "
+            "requires Python 2 support, please migrate to "
+            "a single-codebase solution or employ an "
+            "independent conversion process.",
+            SetuptoolsDeprecationWarning)
         log.info("Fixing " + " ".join(files))
         self.__build_fixer_names()
         self.__exclude_fixers()

setuptools/package_index.py

@@ -1053,7 +1053,7 @@ def open_with_auth(url, opener=urllib.request.urlopen):
     parsed = urllib.parse.urlparse(url)
     scheme, netloc, path, params, query, frag = parsed
 
-    # Double scheme does not raise on Mac OS X as revealed by a
+    # Double scheme does not raise on macOS as revealed by a
     # failing test. We would expect "nonnumeric port". Refs #20.
     if netloc.endswith(':'):
         raise http_client.InvalidURL("nonnumeric port: ''")

setuptools/tests/test_test.py

@@ -73,7 +73,11 @@ def quiet_log():
     log.set_verbosity(0)
 
 
+ack_2to3 = pytest.mark.filterwarnings('ignore:2to3 support is deprecated')
+
+
 @pytest.mark.usefixtures('sample_test', 'quiet_log')
+@ack_2to3
 def test_test(capfd):
     params = dict(
         name='foo',
@@ -124,6 +128,7 @@ def test_tests_are_run_once(capfd):
 
 
 @pytest.mark.usefixtures('sample_test')
+@ack_2to3
 def test_warns_deprecation(capfd):
     params = dict(
         name='foo',
@@ -149,6 +154,7 @@ def test_warns_deprecation(capfd):
 
 
 @pytest.mark.usefixtures('sample_test')
+@ack_2to3
 def test_deprecation_stderr(capfd):
     params = dict(
         name='foo',