Merge branch 'main' into boolean-has_metadata-&-metadata_isdir

Author: Avasam

.gitignore

@@ -1,4 +1,5 @@
 # syntax: glob
+# See https://blog.jaraco.com/skeleton/#ignoring-artifacts before modifying.
 bin
 build
 dist
@@ -17,6 +18,5 @@ setuptools.egg-info
 *~
 .hg*
 .cache
-.idea/
 .pytest_cache/
 .mypy_cache/

docs/conf.py

@@ -161,22 +161,23 @@
 # Ref: https://stackoverflow.com/a/30624034/595220
 nitpick_ignore = [
     ('c:func', 'SHGetSpecialFolderPath'),  # ref to MS docs
+    ('envvar', 'DIST_EXTRA_CONFIG'),  # undocumented
     ('envvar', 'DISTUTILS_DEBUG'),  # undocumented
     ('envvar', 'HOME'),  # undocumented
     ('envvar', 'PLAT'),  # undocumented
-    ('envvar', 'DIST_EXTRA_CONFIG'),  # undocumented
     ('py:attr', 'CCompiler.language_map'),  # undocumented
     ('py:attr', 'CCompiler.language_order'),  # undocumented
-    ('py:class', 'distutils.dist.Distribution'),  # undocumented
-    ('py:class', 'distutils.extension.Extension'),  # undocumented
     ('py:class', 'BorlandCCompiler'),  # undocumented
     ('py:class', 'CCompiler'),  # undocumented
     ('py:class', 'CygwinCCompiler'),  # undocumented
+    ('py:class', 'distutils.dist.Distribution'),  # undocumented
     ('py:class', 'distutils.dist.DistributionMetadata'),  # undocumented
+    ('py:class', 'distutils.extension.Extension'),  # undocumented
     ('py:class', 'FileList'),  # undocumented
     ('py:class', 'IShellLink'),  # ref to MS docs
     ('py:class', 'MSVCCompiler'),  # undocumented
     ('py:class', 'OptionDummy'),  # undocumented
+    ('py:class', 'setuptools.dist.Distribution'),  # undocumented
     ('py:class', 'UnixCCompiler'),  # undocumented
     ('py:exc', 'CompileError'),  # undocumented
     ('py:exc', 'DistutilsExecError'),  # undocumented
@@ -186,8 +187,7 @@
     ('py:exc', 'PreprocessError'),  # undocumented
     ('py:exc', 'setuptools.errors.PlatformError'),  # sphinx cannot find it
     ('py:func', 'distutils.CCompiler.new_compiler'),  # undocumented
-    # undocumented:
-    ('py:func', 'distutils.dist.DistributionMetadata.read_pkg_file'),
+    ('py:func', 'distutils.dist.DistributionMetadata.read_pkg_file'),  # undocumented
     ('py:func', 'distutils.file_util._copy_file_contents'),  # undocumented
     ('py:func', 'distutils.log.debug'),  # undocumented
     ('py:func', 'distutils.spawn.find_executable'),  # undocumented

docs/userguide/datafiles.rst

@@ -10,12 +10,19 @@ by including the data files **inside the package directory**.
 
 Setuptools focuses on this most common type of data files and offers three ways
 of specifying which files should be included in your packages, as described in
-the following sections.
+the following section.
+
+
+Configuration Options
+=====================
+
+
+.. _include-package-data:
 
 include_package_data
-====================
+--------------------
 
-First, you can simply use the ``include_package_data`` keyword.
+First, you can use the ``include_package_data`` keyword.
 For example, if the package tree looks like this::
 
     project_root_directory
@@ -92,8 +99,10 @@ your package, provided:
       (where ``include_package_data=False`` by default), which was not changed
       to ensure backwards compatibility with existing projects.
 
+.. _package-data:
+
 package_data
-============
+------------
 
 By default, ``include_package_data`` considers **all** non ``.py`` files found inside
 the package directory (``src/mypkg`` in this case) as data files, and includes those that
@@ -260,8 +269,10 @@ we specify that ``data1.rst`` from ``mypkg1`` alone should be captured as well.
    Please check :ref:`section subdirectories <subdir-data-files>` below.
 
 
+.. _exclude-package-data:
+
 exclude_package_data
-====================
+--------------------
 
 Sometimes, the ``include_package_data`` or ``package_data`` options alone
 aren't sufficient to precisely define what files you want included. For example,
@@ -327,6 +338,38 @@ even if they were listed in ``package_data`` or were included as a result of usi
 ``include_package_data``.
 
 
+Summary
+-------
+
+In summary, the three options allow you to:
+
+``include_package_data``
+    Accept all data files and directories matched by
+    :ref:`MANIFEST.in <Using MANIFEST.in>` or added by
+    a :ref:`plugin <Adding Support for Revision Control Systems>`.
+
+``package_data``
+    Specify additional patterns to match files that may or may
+    not be matched by :ref:`MANIFEST.in <Using MANIFEST.in>`
+    or added by a :ref:`plugin <Adding Support for Revision Control Systems>`.
+
+``exclude_package_data``
+    Specify patterns for data files and directories that should *not* be
+    included when a package is installed, even if they would otherwise have
+    been included due to the use of the preceding options.
+
+.. note::
+    Due to the way the build process works, a data file that you
+    include in your project and then stop including may be "orphaned" in your
+    project's build directories, requiring you to manually deleting them.
+    This may also be important for your users and contributors
+    if they track intermediate revisions of your project using Subversion; be sure
+    to let them know when you make changes that remove files from inclusion so they
+    can also manually delete them.
+
+    See also troubleshooting information in :ref:`Caching and Troubleshooting`.
+
+
 .. _subdir-data-files:
 
 Subdirectory for Data Files
@@ -350,8 +393,13 @@ Here, the ``.rst`` files are placed under a ``data`` subdirectory inside ``mypkg
 while the ``.txt`` files are directly under ``mypkg``.
 
 In this case, the recommended approach is to treat ``data`` as a namespace package
-(refer :pep:`420`). With ``package_data``,
-the configuration might look like this:
+(refer :pep:`420`). This way, you can rely on the same methods described above,
+using either :ref:`package-data` or :ref:`include-package-data`.
+For the sake of completeness, we include below configuration examples
+for the subdirectory structure, but please refer to the detailed
+information in the previous sections of this document.
+
+With :ref:`package-data`, the configuration might look like this:
 
 .. tab:: pyproject.toml
 
@@ -407,8 +455,9 @@ which enables the ``data`` directory to be identified, and then, we separately s
 files for the root package ``mypkg``, and the namespace package ``data`` under the package
 ``mypkg``.
 
-With ``include_package_data`` the configuration is simpler: you simply need to enable
-scanning of namespace packages in the ``src`` directory and the rest is handled by Setuptools.
+Alternatively, you can also rely on :ref:`include-package-data`.
+Note that this is the default behaviour in ``pyproject.toml``, but you need to
+manually enable scanning of namespace packages in ``setup.cfg`` or ``setup.py``:
 
 .. tab:: pyproject.toml
 
@@ -422,7 +471,7 @@ scanning of namespace packages in the ``src`` directory and the rest is handled
 
         [tool.setuptools.packages.find]
         # scanning for namespace packages is true by default in pyproject.toml, so
-        # you need NOT include the following line.
+        # you need NOT include this configuration.
         namespaces = true
         where = ["src"]
 
@@ -451,34 +500,9 @@ scanning of namespace packages in the ``src`` directory and the rest is handled
             include_package_data=True,
         )
 
-Summary
-=======
-
-In summary, the three options allow you to:
-
-``include_package_data``
-    Accept all data files and directories matched by
-    :ref:`MANIFEST.in <Using MANIFEST.in>` or added by
-    a :ref:`plugin <Adding Support for Revision Control Systems>`.
-
-``package_data``
-    Specify additional patterns to match files that may or may
-    not be matched by :ref:`MANIFEST.in <Using MANIFEST.in>`
-    or added by a :ref:`plugin <Adding Support for Revision Control Systems>`.
-
-``exclude_package_data``
-    Specify patterns for data files and directories that should *not* be
-    included when a package is installed, even if they would otherwise have
-    been included due to the use of the preceding options.
-
-.. note::
-    Due to the way the build process works, a data file that you
-    include in your project and then stop including may be "orphaned" in your
-    project's build directories, requiring you to manually deleting them.
-    This may also be important for your users and contributors
-    if they track intermediate revisions of your project using Subversion; be sure
-    to let them know when you make changes that remove files from inclusion so they
-    can also manually delete them.
+To avoid common mistakes with :ref:`include-package-data`,
+please ensure :ref:`MANIFEST.in <Using MANIFEST.in>` is properly set
+or use a revision control system plugin (see :doc:`/userguide/miscellaneous`).
 
 
 .. _Accessing Data Files at Runtime:

docs/userguide/dependency_management.rst

@@ -19,7 +19,7 @@ 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
-do the packaging (in our case, ``setuptools`` of course).
+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`):
 

docs/userguide/miscellaneous.rst

@@ -168,6 +168,20 @@ binary extensions during the build process, or included in the final
 
    See :doc:`/userguide/datafiles` for more information.
 
+
+.. _Caching and Troubleshooting:
+
+Caching and Troubleshooting
+===========================
+
+Setuptools automatically creates a few directories to host build artefacts and
+cache files, such as ``build``, ``dist``, ``*.egg-info``.  While cache is
+useful to speed up incremental builds, in some edge cases it might become
+stale.  If you feel that caching is causing problems to your build, specially
+after changes in configuration or in the directory/file structure., consider
+removing ``build``, ``dist``, ``*.egg-info`` [#PKG-INFO]_ before rebuilding or
+reinstalling your project.
+
 ----
 
 .. [#build-process]
@@ -183,5 +197,9 @@ binary extensions during the build process, or included in the final
    :term:`Virtual Environment`.
    Therefore it only contains items that are required during runtime.
 
+.. [#PKG-INFO]
+   When working from an extracted sdist (e.g. for patching), you might also consider removing
+   the ``PKG-INFO`` file to force its recreation.
+
 .. _git: https://git-scm.com
 .. _mercurial: https://www.mercurial-scm.org

mypy.ini

@@ -1,5 +1,42 @@
 [mypy]
-ignore_missing_imports = True
-# required to support namespace packages
-# https://github.com/python/mypy/issues/14057
+# CI should test for all versions, local development gets hints for oldest supported
+python_version = 3.8
+strict = False
+warn_unused_ignores = True
+# required to support namespace packages: https://github.com/python/mypy/issues/14057
 explicit_package_bases = True
+exclude = (?x)(
+	^build/
+	| ^.tox/
+	| ^pkg_resources/tests/data/my-test-package-source/setup.py$ # Duplicate module name
+	| ^.+?/(_vendor|extern)/ # Vendored
+	| ^setuptools/_distutils/ # Vendored
+	| ^setuptools/config/_validate_pyproject/ # Auto-generated
+	)
+disable_error_code = 
+	# TODO: Test environment is not yet properly configured to install all imported packages
+	# import-not-found, # This can be left commented out for local runs until we enforce running mypy in the CI
+	# TODO: Not all dependencies are typed. Namely: distutils._modified, wheel.wheelfile, and jaraco.*
+	import-untyped,
+	# Ignoring attr-defined because setuptools wraps a lot of distutils classes, adding new attributes,
+	# w/o updating all the attributes and return types from the base classes for type-checkers to understand
+	# Especially with setuptools.dist.command vs distutils.dist.command vs setuptools._distutils.dist.command
+	# *.extern modules that actually live in *._vendor will also cause attr-defined issues on import
+	attr-defined,
+
+# Avoid raising issues when importing from "extern" modules, as those are added to path dynamically.
+# https://github.com/pypa/setuptools/pull/3979#discussion_r1367968993
+[mypy-pkg_resources.extern.*,setuptools.extern.*]
+ignore_missing_imports = True
+
+[mypy-pkg_resources.tests.*,setuptools.tests.*]
+disable_error_code =
+	# Tests include creating dynamic modules that won't exists statically before the test is run.
+	# Let's ignore all "import-not-found", as if an import really wasn't found, then the test would fail.
+	import-not-found,
+	# mmany untyped "jaraco" modules
+	import-untyped,
+
+# Mypy issue, this vendored module is already excluded!
+[mypy-setuptools._vendor.packaging._manylinux]
+disable_error_code = import-not-found

newsfragments/4244.bugfix.rst

@@ -0,0 +1 @@
+Return an empty `list` by default in ``pkg_resources.ResourceManager.cleanup_resources`` -- by :user:`Avasam`

pkg_resources/__init__.py

@@ -27,7 +27,7 @@
 import time
 import re
 import types
-from typing import Protocol
+from typing import List, Protocol
 import zipfile
 import zipimport
 import warnings
@@ -1339,7 +1339,7 @@ def set_extraction_path(self, path):
 
         self.extraction_path = path
 
-    def cleanup_resources(self, force=False):
+    def cleanup_resources(self, force=False) -> List[str]:
         """
         Delete all extracted resource files and directories, returning a list
         of the file and directory names that could not be successfully removed.
@@ -1351,6 +1351,7 @@ def cleanup_resources(self, force=False):
         directory used for extractions.
         """
         # XXX
+        return []
 
 
 def get_default_cache():
@@ -3207,7 +3208,9 @@ def _find_adapter(registry, ob):
     for t in types:
         if t in registry:
             return registry[t]
-    return None
+    # _find_adapter would previously return None, and immediatly be called.
+    # So we're raising a TypeError to keep backward compatibility if anyone depended on that behaviour.
+    raise TypeError(f"Could not find adapter for {registry} and {ob}")
 
 
 def ensure_directory(path):

pkg_resources/tests/test_pkg_resources.py

@@ -9,6 +9,7 @@
 import stat
 import distutils.dist
 import distutils.command.install_egg_info
+from typing import List
 
 from unittest import mock
 
@@ -32,7 +33,7 @@ def __call__(self):
 
 
 class TestZipProvider:
-    finalizers = []
+    finalizers: List[EggRemover] = []
 
     ref_time = datetime.datetime(2013, 5, 12, 13, 25, 0)
     "A reference time for a file modification"

setup.py

@@ -88,5 +88,6 @@ def _restore_install_lib(self):
 
 if __name__ == '__main__':
     # allow setup.py to run from another directory
-    here and os.chdir(here)
+    # TODO: Use a proper conditonal statement here
+    here and os.chdir(here)  # type: ignore[func-returns-value]
     dist = setuptools.setup(**setup_params)

setuptools/__init__.py

@@ -3,6 +3,7 @@
 import functools
 import os
 import re
+from typing import TYPE_CHECKING
 
 import _distutils_hack.override  # noqa: F401
 import distutils.core
@@ -105,8 +106,11 @@ def setup(**attrs):
 
 setup.__doc__ = distutils.core.setup.__doc__
 
-
-_Command = monkey.get_unpatched(distutils.core.Command)
+if TYPE_CHECKING:
+    # Work around a mypy issue where type[T] can't be used as a base: https://github.com/python/mypy/issues/10962
+    _Command = distutils.core.Command
+else:
+    _Command = monkey.get_unpatched(distutils.core.Command)
 
 
 class Command(_Command):
@@ -165,8 +169,9 @@ class Command(_Command):
     """
 
     command_consumes_arguments = False
+    distribution: Distribution  # override distutils.dist.Distribution with setuptools.dist.Distribution
 
-    def __init__(self, dist, **kw):
+    def __init__(self, dist: Distribution, **kw):
         """
         Construct the command for dist, updating
         vars(self) with any keyword parameters.