Merge branch 'master' into deprecate-requires

5 files changed, 83 insertions, 45 deletions

diff --git a/README.rst b/README.rst
index a9bed521..0454f2ed 100644
--- a/README.rst
+++ b/README.rst
@@ -23,10 +23,6 @@ See the `Installation Instructions
 User's Guide for instructions on installing, upgrading, and uninstalling
 Setuptools.
 
-The project is `maintained at GitHub <https://github.com/pypa/setuptools>`_
-by the `Setuptools Developers
-<https://github.com/orgs/pypa/teams/setuptools-developers>`_.
-
 Questions and comments should be directed to the `distutils-sig
 mailing list <http://mail.python.org/pipermail/distutils-sig/>`_.
 Bug reports and especially tested patches may be
diff --git a/changelog.d/1537.doc.rst b/changelog.d/1537.doc.rst
new file mode 100644
index 00000000..02d15eae
--- /dev/null
+++ b/changelog.d/1537.doc.rst
@@ -0,0 +1 @@
+Document how to use setup.cfg for src/ layouts.
\ No newline at end of file
diff --git a/changelog.d/1553.doc.rst b/changelog.d/1553.doc.rst
new file mode 100644
index 00000000..2f68b95e
--- /dev/null
+++ b/changelog.d/1553.doc.rst
@@ -0,0 +1 @@
+Update installation instructions to point to ``pip install`` instead of ``ez_setup.py``.
\ No newline at end of file
diff --git a/docs/setuptools.txt b/docs/setuptools.txt
index ec40548a..9eec82f3 100644
--- a/docs/setuptools.txt
+++ b/docs/setuptools.txt
@@ -73,23 +73,17 @@ Developer's Guide
 Installing ``setuptools``
 =========================
 
-Please follow the `EasyInstall Installation Instructions`_ to install the
-current stable version of setuptools.  In particular, be sure to read the
-section on `Custom Installation Locations`_ if you are installing anywhere
-other than Python's ``site-packages`` directory.
+.. _EasyInstall Installation Instructions: easy_install.html
 
-.. _EasyInstall Installation Instructions: easy_install.html#installation-instructions
+.. _Custom Installation Locations: easy_install.html
 
-.. _Custom Installation Locations: easy_install.html#custom-installation-locations
+.. _Installing Packages: https://packaging.python.org/tutorials/installing-packages/
 
-If you want the current in-development version of setuptools, you should first
-install a stable version, and then run::
+To install the latest version of setuptools, use::
 
-    ez_setup.py setuptools==dev
-
-This will download and install the latest development (i.e. unstable) version
-of setuptools from the Python Subversion sandbox.
+    pip install -U setuptools
 
+Refer to `Installing Packages`_ guide for more information.
 
 Basic Use
 =========
@@ -1655,17 +1649,26 @@ Distributing Extensions compiled with Cython
 --------------------------------------------
 
 ``setuptools`` will detect at build time whether Cython is installed or not.
-If Cython is not found ``setputools`` will ignore pyx files. In case it's
-available you are supposed it will work with just a couple of adjustments.
-``setuptools`` includes transparent support for building Cython extensions, as
-long as you define your extensions using ``setuptools.Extension``.
-Then you should use Cython own ``build_ext`` in ``cmdclass``, e.g.::
+If Cython is not found ``setuptools`` will ignore pyx files.
+
+To ensure Cython is available, include Cython in the build-requires section
+of your pyproject.toml::
+
+    [build-system]
+    requires=[..., 'cython']
 
-   from Cython.Distutils import build_ext
+Built with pip 10 or later, that declaration is sufficient to include Cython
+in the build. For broader compatibility, declare the dependency in your
+setup-requires of setup.cfg::
+
+    [options]
+    setup_requires =
+        ...
+        cython
 
-   setup(...
-         cmdclass={"build_ext": build_ext}
-         ...)
+As long as Cython is present in the build environment, ``setuptools`` includes
+transparent support for building Cython extensions, as
+long as extensions are defined using ``setuptools.Extension``.
 
 If you follow these rules, you can safely list ``.pyx`` files as the source
 of your ``Extension`` objects in the setup script.  If it is, then ``setuptools``
@@ -2405,6 +2408,35 @@ Metadata and options are set in the config sections of the same name.
 * Unknown keys are ignored.
 
 
+Using a ``src/`` layout
+=======================
+
+One commonly used package configuration has all the module source code in a
+subdirectory (often called the ``src/`` layout), like this::
+
+    ├── src
+    │   └── mypackage
+    │       ├── __init__.py
+    │       └── mod1.py
+    ├── setup.py
+    └── setup.cfg
+
+You can set up your ``setup.cfg`` to automatically find all your packages in
+the subdirectory like this:
+
+.. code-block:: ini
+
+    # This example contains just the necessary options for a src-layout, set up
+    # the rest of the file as described above.
+
+    [options]
+    package_dir=
+        =src
+    packages=find:
+
+    [options.packages.find]
+    where=src
+
 Specifying values
 =================
 
@@ -2505,7 +2537,7 @@ data_files               dict                                 40.5.0
     accepts the same keys as the `setuptools.find_packages` and the
     `setuptools.find_namespace_packages` function:
     ``where``, ``include``, and ``exclude``.
-    
+
     **find_namespace directive** - The ``find_namespace:`` directive is supported since Python >=3.3.
 
 
diff --git a/setuptools/config.py b/setuptools/config.py
index 1f9c50f9..d1ac6734 100644
--- a/setuptools/config.py
+++ b/setuptools/config.py
@@ -2,7 +2,9 @@ from __future__ import absolute_import, unicode_literals
 import io
 import os
 import sys
+
 import warnings
+import functools
 from collections import defaultdict
 from functools import partial
 from functools import wraps
@@ -63,6 +65,18 @@ def read_configuration(
     return configuration_to_dict(handlers)
 
 
+def _get_option(target_obj, key):
+    """
+    Given a target object and option key, get that option from
+    the target object, either through a get_{key} method or
+    from an attribute directly.
+    """
+    getter_name = 'get_{key}'.format(**locals())
+    by_attribute = functools.partial(getattr, target_obj, key)
+    getter = getattr(target_obj, getter_name, by_attribute)
+    return getter()
+
+
 def configuration_to_dict(handlers):
     """Returns configuration data gathered by given handlers as a dict.
 
@@ -74,20 +88,9 @@ def configuration_to_dict(handlers):
     config_dict = defaultdict(dict)
 
     for handler in handlers:
-
-        obj_alias = handler.section_prefix
-        target_obj = handler.target_obj
-
         for option in handler.set_options:
-            getter = getattr(target_obj, 'get_%s' % option, None)
-
-            if getter is None:
-                value = getattr(target_obj, option)
-
-            else:
-                value = getter()
-
-            config_dict[obj_alias][option] = value
+            value = _get_option(handler.target_obj, option)
+            config_dict[handler.section_prefix][option] = value
 
     return config_dict
 
@@ -112,7 +115,8 @@ def parse_configuration(
     options.parse()
 
     meta = ConfigMetadataHandler(
-        distribution.metadata, command_options, ignore_option_errors, distribution.package_dir)
+        distribution.metadata, command_options, ignore_option_errors,
+        distribution.package_dir)
     meta.parse()
 
     return meta, options
@@ -477,9 +481,12 @@ class ConfigMetadataHandler(ConfigHandler):
             # Be strict about versions loaded from file because it's easy to
             # accidentally include newlines and other unintended content
             if isinstance(parse(version), LegacyVersion):
-                raise DistutilsOptionError('Version loaded from %s does not comply with PEP 440: %s' % (
-                    value, version
-                ))
+                tmpl = (
+                    'Version loaded from {value} does not '
+                    'comply with PEP 440: {version}'
+                )
+                raise DistutilsOptionError(tmpl.format(**locals()))
+
             return version
 
         version = self._parse_attr(value, self.package_dir)
@@ -537,12 +544,13 @@ class ConfigOptionsHandler(ConfigHandler):
         find_directives = ['find:', 'find_namespace:']
         trimmed_value = value.strip()
 
-        if not trimmed_value in find_directives:
+        if trimmed_value not in find_directives:
             return self._parse_list(value)
 
         findns = trimmed_value == find_directives[1]
         if findns and not PY3:
-            raise DistutilsOptionError('find_namespace: directive is unsupported on Python < 3.3')
+            raise DistutilsOptionError(
+                'find_namespace: directive is unsupported on Python < 3.3')
 
         # Read function arguments from a dedicated section.
         find_kwargs = self.parse_section_packages__find(