Merge branch 'main' into pytest-mypy-log-filename

Author: Avasam

.bumpversion.cfg

@@ -1,5 +1,5 @@
 [bumpversion]
-current_version = 71.1.0
+current_version = 72.1.0
 commit = True
 tag = True
 

NEWS.rst

@@ -1,3 +1,21 @@
+v72.1.0
+=======
+
+Features
+--------
+
+- Restore the tests command and deprecate access to the module. (#4519) (#4520)
+
+
+v72.0.0
+=======
+
+Deprecations and Removals
+-------------------------
+
+- The test command has been removed. Users relying on 'setup.py test' will need to migrate to another test runner or pin setuptools before this version. (#931)
+
+
 v71.1.0
 =======
 

docs/userguide/dependency_management.rst

@@ -18,24 +18,56 @@ Build system requirement
 ========================
 
 After organizing all the scripts and files and getting ready for packaging,
-there needs to be a way to specify what programs and libraries are actually needed
-to do the packaging (in our case, ``setuptools`` of course).
-This needs to be specified in your ``pyproject.toml`` file
-(if you have forgot what this is, go to :doc:`/userguide/quickstart` or :doc:`/build_meta`):
+there needs to be a way to specify what programs and libraries (build backend)
+are actually needed to build the package for distribution. For Setuptools, the
+requisite library is ``setuptools``. Specify the build backend in a
+``pyproject.toml`` file (see also :doc:`/userguide/quickstart` or
+:doc:`/build_meta`):
 
 .. code-block:: toml
 
     [build-system]
     requires = ["setuptools"]
     #...
 
-Please note that you should also include here any other ``setuptools`` plugin
-(e.g., :pypi:`setuptools-scm`, :pypi:`setuptools-golang`, :pypi:`setuptools-rust`)
+Also include any other ``setuptools`` plugins
+(e.g., :pypi:`setuptools_scm`, :pypi:`setuptools-golang`, :pypi:`setuptools-rust`)
 or build-time dependency (e.g., :pypi:`Cython`, :pypi:`cppy`, :pypi:`pybind11`).
 
+.. code-block:: toml
+
+    [build-system]
+    requires = ["setuptools", "cython", "setuptools_scm"]
+
+
+If the project depends on a feature introduced in a specific version of Setuptools,
+it is good practice to specify it as a lower bound:
+
+.. code-block:: toml
+
+    [build-system]
+    requires = ["setuptools >= 61.2"]
+
+Some may be tempted to also include an upper-bound for yet unreleased major
+versions (e.g. ``setuptools <= 70``) or pin to a specific version (e.g.
+``setuptools == 70.0.4``) in order to avoid the project being uninstallable
+should those backward-incompatible changes affect this release of the project.
+Setuptools maintainers recommend strongly against this precautionary approach.
+The team primarily maintains one release, the latest monotonically-increasing
+release, and encourages users to use that latest release (work at HEAD). As a
+result, the team is cognizant of and takes responsibility for making
+backward-incompatible changes and aims to mitigate the impact of any breaking
+changes prior to releasing that change. By pinning against an unreleased
+version, it causes toil (maintenance burden) for each and every project that
+does the pinning (and the consumers that use it) and increases the risk of
+erosion if maintenance is unsustained. This tradeoff between reproducibility
+and compatibility is especially stark because Setuptools frequently releases
+backward-incompatible releases for a variety of reasons, many of which won't
+affect a given project.
+
 .. note::
     In previous versions of ``setuptools``,
-    this used to be accomplished with the ``setup_requires`` keyword but is
+    the ``setup_requires`` keyword performed a similar function but is
     now considered deprecated in favor of the :pep:`517` style described above.
     To peek into how this legacy keyword is used, consult our :doc:`guide on
     deprecated practice (WIP) </deprecated/index>`.

docs/userguide/quickstart.rst

@@ -7,7 +7,7 @@ Installation
 
 You can install the latest version of ``setuptools`` using :pypi:`pip`::
 
-    pip install --upgrade setuptools
+    pip install --upgrade setuptools[core]
 
 Most of the times, however, you don't have to...
 
@@ -56,6 +56,16 @@ containing a ``build-system`` section similar to the example below:
 This section declares what are your build system dependencies, and which
 library will be used to actually do the packaging.
 
+.. note::
+
+   Package maintainers might be tempted to use ``setuptools[core]`` as the
+   requirement, given the guidance above. Avoid doing so, as the extra
+   is currently considered an internal implementation detail and is likely
+   to go away in the future and the Setuptools team will not support
+   compatibility for problems arising from packages published with this
+   extra declared. Vendored packages will satisfy the dependencies in
+   the most common isolated build scenarios.
+
 .. note::
 
    Historically this documentation has unnecessarily listed ``wheel``

pyproject.toml

@@ -5,7 +5,7 @@ backend-path = ["."]
 
 [project]
 name = "setuptools"
-version = "71.1.0"
+version = "72.1.0"
 authors = [
 	{ name = "Python Packaging Authority", email = "distutils-sig@python.org" },
 ]
@@ -141,7 +141,6 @@ rotate = "setuptools.command.rotate:rotate"
 saveopts = "setuptools.command.saveopts:saveopts"
 sdist = "setuptools.command.sdist:sdist"
 setopt = "setuptools.command.setopt:setopt"
-test = "setuptools.command.test:test"
 upload_docs = "setuptools.command.upload_docs:upload_docs"
 
 [project.entry-points."setuptools.finalize_distribution_options"]
@@ -153,19 +152,15 @@ eager_resources = "setuptools.dist:assert_string_list"
 namespace_packages = "setuptools.dist:check_nsp"
 extras_require = "setuptools.dist:check_extras"
 install_requires = "setuptools.dist:check_requirements"
-tests_require = "setuptools.dist:check_requirements"
 setup_requires = "setuptools.dist:check_requirements"
 python_requires = "setuptools.dist:check_specifier"
 entry_points = "setuptools.dist:check_entry_points"
-test_suite = "setuptools.dist:check_test_suite"
 zip_safe = "setuptools.dist:assert_bool"
 package_data = "setuptools.dist:check_package_data"
 exclude_package_data = "setuptools.dist:check_package_data"
 include_package_data = "setuptools.dist:assert_bool"
 packages = "setuptools.dist:check_packages"
 dependency_links = "setuptools.dist:assert_string_list"
-test_loader = "setuptools.dist:check_importable"
-test_runner = "setuptools.dist:check_importable"
 use_2to3 = "setuptools.dist:invalid_unless_false"
 
 [project.entry-points."egg_info.writers"]

setuptools/_path.py

@@ -1,7 +1,11 @@
+import contextlib
 import os
 import sys
 from typing import Union
 
+from more_itertools import unique_everseen
+
+
 if sys.version_info >= (3, 9):
     StrPath = Union[str, os.PathLike[str]]  #  Same as _typeshed.StrPath
 else:
@@ -38,3 +42,41 @@ def normpath(filename: StrPath) -> str:
     # See pkg_resources.normalize_path for notes about cygwin
     file = os.path.abspath(filename) if sys.platform == 'cygwin' else filename
     return os.path.normcase(os.path.realpath(os.path.normpath(file)))
+
+
+@contextlib.contextmanager
+def paths_on_pythonpath(paths):
+    """
+    Add the indicated paths to the head of the PYTHONPATH environment
+    variable so that subprocesses will also see the packages at
+    these paths.
+
+    Do this in a context that restores the value on exit.
+
+    >>> getfixture('monkeypatch').setenv('PYTHONPATH', 'anything')
+    >>> with paths_on_pythonpath(['foo', 'bar']):
+    ...     assert 'foo' in os.environ['PYTHONPATH']
+    ...     assert 'anything' in os.environ['PYTHONPATH']
+    >>> os.environ['PYTHONPATH']
+    'anything'
+
+    >>> getfixture('monkeypatch').delenv('PYTHONPATH')
+    >>> with paths_on_pythonpath(['foo', 'bar']):
+    ...     assert 'foo' in os.environ['PYTHONPATH']
+    >>> os.environ.get('PYTHONPATH')
+    """
+    nothing = object()
+    orig_pythonpath = os.environ.get('PYTHONPATH', nothing)
+    current_pythonpath = os.environ.get('PYTHONPATH', '')
+    try:
+        prefix = os.pathsep.join(unique_everseen(paths))
+        to_join = filter(None, [prefix, current_pythonpath])
+        new_path = os.pathsep.join(to_join)
+        if new_path:
+            os.environ['PYTHONPATH'] = new_path
+        yield
+    finally:
+        if orig_pythonpath is nothing:
+            os.environ.pop('PYTHONPATH', None)
+        else:
+            os.environ['PYTHONPATH'] = orig_pythonpath