diff --git a/docs/deprecated/distutils/configfile.rst b/docs/deprecated/distutils/configfile.rst index ab199dcaf7..b104db789a 100644 --- a/docs/deprecated/distutils/configfile.rst +++ b/docs/deprecated/distutils/configfile.rst @@ -131,13 +131,6 @@ Note that the ``doc_files`` option is simply a whitespace-separated string split across multiple lines for readability. -.. seealso:: - - :ref:`inst-config-syntax` in "Installing Python Modules" - More information on the configuration files is available in the manual for - system administrators. - - .. rubric:: Footnotes .. [#] This ideal probably won't be achieved until auto-configuration is fully diff --git a/docs/deprecated/distutils/packageindex.rst b/docs/deprecated/distutils/packageindex.rst index ccb9a598b2..27ea717a78 100644 --- a/docs/deprecated/distutils/packageindex.rst +++ b/docs/deprecated/distutils/packageindex.rst @@ -6,11 +6,10 @@ The Python Package Index (PyPI) ******************************* -The `Python Package Index (PyPI)`_ stores metadata describing distributions -packaged with distutils and other publishing tools, as well the distribution -archives themselves. +The `Python Package Index (PyPI) `_ stores +metadata describing distributions packaged with distutils and +other publishing tools, as well the distribution archives +themselves. -References to up to date PyPI documentation can be found at -:ref:`publishing-python-packages`. - -.. _Python Package Index (PyPI): https://pypi.org +The best resource for working with PyPI is the +`Python Packaging User Guide `_. diff --git a/docs/deprecated/distutils/uploading.rst b/docs/deprecated/distutils/uploading.rst index 4c391cab07..f5c4c619ab 100644 --- a/docs/deprecated/distutils/uploading.rst +++ b/docs/deprecated/distutils/uploading.rst @@ -4,5 +4,6 @@ Uploading Packages to the Package Index *************************************** -References to up to date PyPI documentation can be found at -:ref:`publishing-python-packages`. +See the +`Python Packaging User Guide `_ +for the best guidance on uploading packages. diff --git a/newsfragments/+f8383dcd.feature.rst b/newsfragments/+f8383dcd.feature.rst new file mode 100644 index 0000000000..c8f0e82e55 --- /dev/null +++ b/newsfragments/+f8383dcd.feature.rst @@ -0,0 +1 @@ +Merged with pypa/distutils@7a04cbda0fc714. \ No newline at end of file diff --git a/setuptools/_distutils/_functools.py b/setuptools/_distutils/_functools.py index e7053bac12..e03365eafa 100644 --- a/setuptools/_distutils/_functools.py +++ b/setuptools/_distutils/_functools.py @@ -1,3 +1,4 @@ +import collections.abc import functools @@ -18,3 +19,55 @@ def wrapper(param, *args, **kwargs): return func(param, *args, **kwargs) return wrapper + + +# from jaraco.functools 4.0 +@functools.singledispatch +def _splat_inner(args, func): + """Splat args to func.""" + return func(*args) + + +@_splat_inner.register +def _(args: collections.abc.Mapping, func): + """Splat kargs to func as kwargs.""" + return func(**args) + + +def splat(func): + """ + Wrap func to expect its parameters to be passed positionally in a tuple. + + Has a similar effect to that of ``itertools.starmap`` over + simple ``map``. + + >>> import itertools, operator + >>> pairs = [(-1, 1), (0, 2)] + >>> _ = tuple(itertools.starmap(print, pairs)) + -1 1 + 0 2 + >>> _ = tuple(map(splat(print), pairs)) + -1 1 + 0 2 + + The approach generalizes to other iterators that don't have a "star" + equivalent, such as a "starfilter". + + >>> list(filter(splat(operator.add), pairs)) + [(0, 2)] + + Splat also accepts a mapping argument. + + >>> def is_nice(msg, code): + ... return "smile" in msg or code == 0 + >>> msgs = [ + ... dict(msg='smile!', code=20), + ... dict(msg='error :(', code=1), + ... dict(msg='unknown', code=0), + ... ] + >>> for msg in filter(splat(is_nice), msgs): + ... print(msg) + {'msg': 'smile!', 'code': 20} + {'msg': 'unknown', 'code': 0} + """ + return functools.wraps(func)(functools.partial(_splat_inner, func=func)) diff --git a/setuptools/_distutils/_modified.py b/setuptools/_distutils/_modified.py new file mode 100644 index 0000000000..fbb95a8f27 --- /dev/null +++ b/setuptools/_distutils/_modified.py @@ -0,0 +1,72 @@ +"""Timestamp comparison of files and groups of files.""" + +import functools +import os.path + +from .errors import DistutilsFileError +from .py39compat import zip_strict +from ._functools import splat + + +def _newer(source, target): + return not os.path.exists(target) or ( + os.path.getmtime(source) > os.path.getmtime(target) + ) + + +def newer(source, target): + """ + Is source modified more recently than target. + + Returns True if 'source' is modified more recently than + 'target' or if 'target' does not exist. + + Raises DistutilsFileError if 'source' does not exist. + """ + if not os.path.exists(source): + raise DistutilsFileError("file '%s' does not exist" % os.path.abspath(source)) + + return _newer(source, target) + + +def newer_pairwise(sources, targets, newer=newer): + """ + Filter filenames where sources are newer than targets. + + Walk two filename iterables in parallel, testing if each source is newer + than its corresponding target. Returns a pair of lists (sources, + targets) where source is newer than target, according to the semantics + of 'newer()'. + """ + newer_pairs = filter(splat(newer), zip_strict(sources, targets)) + return tuple(map(list, zip(*newer_pairs))) or ([], []) + + +def newer_group(sources, target, missing='error'): + """ + Is target out-of-date with respect to any file in sources. + + Return True if 'target' is out-of-date with respect to any file + listed in 'sources'. In other words, if 'target' exists and is newer + than every file in 'sources', return False; otherwise return True. + ``missing`` controls how to handle a missing source file: + + - error (default): allow the ``stat()`` call to fail. + - ignore: silently disregard any missing source files. + - newer: treat missing source files as "target out of date". This + mode is handy in "dry-run" mode: it will pretend to carry out + commands that wouldn't work because inputs are missing, but + that doesn't matter because dry-run won't run the commands. + """ + + def missing_as_newer(source): + return missing == 'newer' and not os.path.exists(source) + + ignored = os.path.exists if missing == 'ignore' else None + return any( + missing_as_newer(source) or _newer(source, target) + for source in filter(ignored, sources) + ) + + +newer_pairwise_group = functools.partial(newer_pairwise, newer=newer_group) diff --git a/setuptools/_distutils/bcppcompiler.py b/setuptools/_distutils/bcppcompiler.py index ba45ea2b95..3c2ba15410 100644 --- a/setuptools/_distutils/bcppcompiler.py +++ b/setuptools/_distutils/bcppcompiler.py @@ -24,7 +24,7 @@ ) from .ccompiler import CCompiler, gen_preprocess_options from .file_util import write_file -from .dep_util import newer +from ._modified import newer from ._log import log diff --git a/setuptools/_distutils/ccompiler.py b/setuptools/_distutils/ccompiler.py index 1818fce901..c1c7d5476e 100644 --- a/setuptools/_distutils/ccompiler.py +++ b/setuptools/_distutils/ccompiler.py @@ -18,7 +18,7 @@ from .spawn import spawn from .file_util import move_file from .dir_util import mkpath -from .dep_util import newer_group +from ._modified import newer_group from .util import split_quoted, execute from ._log import log diff --git a/setuptools/_distutils/cmd.py b/setuptools/_distutils/cmd.py index 3860c3ff1e..8fdcbc0ea2 100644 --- a/setuptools/_distutils/cmd.py +++ b/setuptools/_distutils/cmd.py @@ -10,7 +10,7 @@ import logging from .errors import DistutilsOptionError -from . import util, dir_util, file_util, archive_util, dep_util +from . import util, dir_util, file_util, archive_util, _modified from ._log import log @@ -428,7 +428,7 @@ def make_file( # If 'outfile' must be regenerated (either because it doesn't # exist, is out-of-date, or the 'force' flag is true) then # perform the action that presumably regenerates it - if self.force or dep_util.newer_group(infiles, outfile): + if self.force or _modified.newer_group(infiles, outfile): self.execute(func, args, exec_msg, level) # Otherwise, print the "skip" message else: diff --git a/setuptools/_distutils/command/build_ext.py b/setuptools/_distutils/command/build_ext.py index fbeec342c0..b48f462626 100644 --- a/setuptools/_distutils/command/build_ext.py +++ b/setuptools/_distutils/command/build_ext.py @@ -19,7 +19,7 @@ ) from ..sysconfig import customize_compiler, get_python_version from ..sysconfig import get_config_h_filename -from ..dep_util import newer_group +from .._modified import newer_group from ..extension import Extension from ..util import get_platform from distutils._log import log diff --git a/setuptools/_distutils/command/build_scripts.py b/setuptools/_distutils/command/build_scripts.py index ce222f1e52..1a4d67f492 100644 --- a/setuptools/_distutils/command/build_scripts.py +++ b/setuptools/_distutils/command/build_scripts.py @@ -7,7 +7,7 @@ from stat import ST_MODE from distutils import sysconfig from ..core import Command -from ..dep_util import newer +from .._modified import newer from ..util import convert_path from distutils._log import log import tokenize diff --git a/setuptools/_distutils/dep_util.py b/setuptools/_distutils/dep_util.py index 48da8641c6..09a8a2e126 100644 --- a/setuptools/_distutils/dep_util.py +++ b/setuptools/_distutils/dep_util.py @@ -1,96 +1,14 @@ -"""distutils.dep_util +import warnings -Utility functions for simple, timestamp-based dependency of files -and groups of files; also, function based entirely on such -timestamp dependency analysis.""" +from . import _modified -import os -from .errors import DistutilsFileError - -def newer(source, target): - """Return true if 'source' exists and is more recently modified than - 'target', or if 'source' exists and 'target' doesn't. Return false if - both exist and 'target' is the same age or younger than 'source'. - Raise DistutilsFileError if 'source' does not exist. - """ - if not os.path.exists(source): - raise DistutilsFileError("file '%s' does not exist" % os.path.abspath(source)) - if not os.path.exists(target): - return 1 - - from stat import ST_MTIME - - mtime1 = os.stat(source)[ST_MTIME] - mtime2 = os.stat(target)[ST_MTIME] - - return mtime1 > mtime2 - - -# newer () - - -def newer_pairwise(sources, targets): - """Walk two filename lists in parallel, testing if each source is newer - than its corresponding target. Return a pair of lists (sources, - targets) where source is newer than target, according to the semantics - of 'newer()'. - """ - if len(sources) != len(targets): - raise ValueError("'sources' and 'targets' must be same length") - - # build a pair of lists (sources, targets) where source is newer - n_sources = [] - n_targets = [] - for i in range(len(sources)): - if newer(sources[i], targets[i]): - n_sources.append(sources[i]) - n_targets.append(targets[i]) - - return (n_sources, n_targets) - - -# newer_pairwise () - - -def newer_group(sources, target, missing='error'): - """Return true if 'target' is out-of-date with respect to any file - listed in 'sources'. In other words, if 'target' exists and is newer - than every file in 'sources', return false; otherwise return true. - 'missing' controls what we do when a source file is missing; the - default ("error") is to blow up with an OSError from inside 'stat()'; - if it is "ignore", we silently drop any missing source files; if it is - "newer", any missing source files make us assume that 'target' is - out-of-date (this is handy in "dry-run" mode: it'll make you pretend to - carry out commands that wouldn't work because inputs are missing, but - that doesn't matter because you're not actually going to run the - commands). - """ - # If the target doesn't even exist, then it's definitely out-of-date. - if not os.path.exists(target): - return 1 - - # Otherwise we have to find out the hard way: if *any* source file - # is more recent than 'target', then 'target' is out-of-date and - # we can immediately return true. If we fall through to the end - # of the loop, then 'target' is up-to-date and we return false. - from stat import ST_MTIME - - target_mtime = os.stat(target)[ST_MTIME] - for source in sources: - if not os.path.exists(source): - if missing == 'error': # blow up when we stat() the file - pass - elif missing == 'ignore': # missing source dropped from - continue # target's dependency list - elif missing == 'newer': # missing source means target is - return 1 # out-of-date - - source_mtime = os.stat(source)[ST_MTIME] - if source_mtime > target_mtime: - return 1 - else: - return 0 - - -# newer_group () +def __getattr__(name): + if name not in ['newer', 'newer_group', 'newer_pairwise']: + raise AttributeError(name) + warnings.warn( + "dep_util is Deprecated. Use functions from setuptools instead.", + DeprecationWarning, + stacklevel=2, + ) + return getattr(_modified, name) diff --git a/setuptools/_distutils/file_util.py b/setuptools/_distutils/file_util.py index 7c69906646..3f3e21b567 100644 --- a/setuptools/_distutils/file_util.py +++ b/setuptools/_distutils/file_util.py @@ -108,7 +108,7 @@ def copy_file( # noqa: C901 # changing it (ie. it's not already a hard/soft link to src OR # (not update) and (src newer than dst). - from distutils.dep_util import newer + from distutils._modified import newer from stat import ST_ATIME, ST_MTIME, ST_MODE, S_IMODE if not os.path.isfile(src): diff --git a/setuptools/_distutils/py39compat.py b/setuptools/_distutils/py39compat.py index c43e5f10fd..1b436d7658 100644 --- a/setuptools/_distutils/py39compat.py +++ b/setuptools/_distutils/py39compat.py @@ -1,5 +1,7 @@ -import sys +import functools +import itertools import platform +import sys def add_ext_suffix_39(vars): @@ -20,3 +22,45 @@ def add_ext_suffix_39(vars): needs_ext_suffix = sys.version_info < (3, 10) and platform.system() == 'Windows' add_ext_suffix = add_ext_suffix_39 if needs_ext_suffix else lambda vars: None + + +# from more_itertools +class UnequalIterablesError(ValueError): + def __init__(self, details=None): + msg = 'Iterables have different lengths' + if details is not None: + msg += (': index 0 has length {}; index {} has length {}').format(*details) + + super().__init__(msg) + + +# from more_itertools +def _zip_equal_generator(iterables): + _marker = object() + for combo in itertools.zip_longest(*iterables, fillvalue=_marker): + for val in combo: + if val is _marker: + raise UnequalIterablesError() + yield combo + + +# from more_itertools +def _zip_equal(*iterables): + # Check whether the iterables are all the same size. + try: + first_size = len(iterables[0]) + for i, it in enumerate(iterables[1:], 1): + size = len(it) + if size != first_size: + raise UnequalIterablesError(details=(first_size, i, size)) + # All sizes are equal, we can use the built-in zip. + return zip(*iterables) + # If any one of the iterables didn't have a length, start reading + # them until one runs out. + except TypeError: + return _zip_equal_generator(iterables) + + +zip_strict = ( + _zip_equal if sys.version_info < (3, 10) else functools.partial(zip, strict=True) +) diff --git a/setuptools/_distutils/tests/test_dep_util.py b/setuptools/_distutils/tests/test_modified.py similarity index 59% rename from setuptools/_distutils/tests/test_dep_util.py rename to setuptools/_distutils/tests/test_modified.py index e5dcad9464..ca07c7e853 100644 --- a/setuptools/_distutils/tests/test_dep_util.py +++ b/setuptools/_distutils/tests/test_modified.py @@ -1,10 +1,12 @@ -"""Tests for distutils.dep_util.""" +"""Tests for distutils._modified.""" import os +import types -from distutils.dep_util import newer, newer_pairwise, newer_group +import pytest + +from distutils._modified import newer, newer_pairwise, newer_group, newer_pairwise_group from distutils.errors import DistutilsFileError from distutils.tests import support -import pytest class TestDepUtil(support.TempdirManager): @@ -27,7 +29,7 @@ def test_newer(self): # than 'new_file'. assert not newer(old_file, new_file) - def test_newer_pairwise(self): + def _setup_1234(self): tmpdir = self.mkdtemp() sources = os.path.join(tmpdir, 'sources') targets = os.path.join(tmpdir, 'targets') @@ -40,9 +42,30 @@ def test_newer_pairwise(self): self.write_file(one) self.write_file(two) self.write_file(four) + return one, two, three, four + + def test_newer_pairwise(self): + one, two, three, four = self._setup_1234() assert newer_pairwise([one, two], [three, four]) == ([one], [three]) + def test_newer_pairwise_mismatch(self): + one, two, three, four = self._setup_1234() + + with pytest.raises(ValueError): + newer_pairwise([one], [three, four]) + + with pytest.raises(ValueError): + newer_pairwise([one, two], [three]) + + def test_newer_pairwise_empty(self): + assert newer_pairwise([], []) == ([], []) + + def test_newer_pairwise_fresh(self): + one, two, three, four = self._setup_1234() + + assert newer_pairwise([one, three], [two, four]) == ([], []) + def test_newer_group(self): tmpdir = self.mkdtemp() sources = os.path.join(tmpdir, 'sources') @@ -68,3 +91,29 @@ def test_newer_group(self): assert not newer_group([one, two, old_file], three, missing='ignore') assert newer_group([one, two, old_file], three, missing='newer') + + +@pytest.fixture +def groups_target(tmp_path): + """ + Set up some older sources, a target, and newer sources. + + Returns a simple namespace with these values. + """ + filenames = ['older.c', 'older.h', 'target.o', 'newer.c', 'newer.h'] + paths = [tmp_path / name for name in filenames] + + for mtime, path in enumerate(paths): + path.write_text('', encoding='utf-8') + + # make sure modification times are sequential + os.utime(path, (mtime, mtime)) + + return types.SimpleNamespace(older=paths[:2], target=paths[2], newer=paths[3:]) + + +def test_newer_pairwise_group(groups_target): + older = newer_pairwise_group([groups_target.older], [groups_target.target]) + newer = newer_pairwise_group([groups_target.newer], [groups_target.target]) + assert older == ([], []) + assert newer == ([groups_target.newer], [groups_target.target]) diff --git a/setuptools/_distutils/unixccompiler.py b/setuptools/_distutils/unixccompiler.py index 6ca2332ae1..bd8db9ac3f 100644 --- a/setuptools/_distutils/unixccompiler.py +++ b/setuptools/_distutils/unixccompiler.py @@ -20,7 +20,7 @@ import itertools from . import sysconfig -from .dep_util import newer +from ._modified import newer from .ccompiler import CCompiler, gen_preprocess_options, gen_lib_options from .errors import DistutilsExecError, CompileError, LibError, LinkError from ._log import log diff --git a/setuptools/_distutils/util.py b/setuptools/_distutils/util.py index 7ef47176e2..7ae914f7ee 100644 --- a/setuptools/_distutils/util.py +++ b/setuptools/_distutils/util.py @@ -14,7 +14,7 @@ import functools from .errors import DistutilsPlatformError, DistutilsByteCompileError -from .dep_util import newer +from ._modified import newer from .spawn import spawn from ._log import log diff --git a/setuptools/command/build_clib.py b/setuptools/command/build_clib.py index 5f4229b276..acd4d1d3ba 100644 --- a/setuptools/command/build_clib.py +++ b/setuptools/command/build_clib.py @@ -1,7 +1,12 @@ import distutils.command.build_clib as orig from distutils.errors import DistutilsSetupError from distutils import log -from setuptools.dep_util import newer_pairwise_group + +try: + from distutils._modified import newer_pairwise_group +except ImportError: + # fallback for SETUPTOOLS_USE_DISTUTILS=stdlib + from .._distutils._modified import newer_pairwise_group class build_clib(orig.build_clib): diff --git a/setuptools/dep_util.py b/setuptools/dep_util.py index dc9ccf62c2..2d8cc5217d 100644 --- a/setuptools/dep_util.py +++ b/setuptools/dep_util.py @@ -1,24 +1,14 @@ -from distutils.dep_util import newer_group +import warnings +from ._distutils import _modified -# yes, this is was almost entirely copy-pasted from -# 'newer_pairwise()', this is just another convenience -# function. -def newer_pairwise_group(sources_groups, targets): - """Walk both arguments in parallel, testing if each source group is newer - than its corresponding target. Returns a pair of lists (sources_groups, - targets) where sources is newer than target, according to the semantics - of 'newer_group()'. - """ - if len(sources_groups) != len(targets): - raise ValueError("'sources_group' and 'targets' must be the same length") - # build a pair of lists (sources_groups, targets) where source is newer - n_sources = [] - n_targets = [] - for i in range(len(sources_groups)): - if newer_group(sources_groups[i], targets[i]): - n_sources.append(sources_groups[i]) - n_targets.append(targets[i]) - - return n_sources, n_targets +def __getattr__(name): + if name not in ['newer_pairwise_group']: + raise AttributeError(name) + warnings.warn( + "dep_util is Deprecated. Use functions from setuptools instead.", + DeprecationWarning, + stacklevel=2, + ) + return getattr(_modified, name) diff --git a/setuptools/tests/test_dep_util.py b/setuptools/tests/test_dep_util.py deleted file mode 100644 index e5027c1020..0000000000 --- a/setuptools/tests/test_dep_util.py +++ /dev/null @@ -1,30 +0,0 @@ -from setuptools.dep_util import newer_pairwise_group -import os -import pytest - - -@pytest.fixture -def groups_target(tmpdir): - """Sets up some older sources, a target and newer sources. - Returns a 3-tuple in this order. - """ - creation_order = ['older.c', 'older.h', 'target.o', 'newer.c', 'newer.h'] - mtime = 0 - - for i in range(len(creation_order)): - creation_order[i] = os.path.join(str(tmpdir), creation_order[i]) - with open(creation_order[i], 'w'): - pass - - # make sure modification times are sequential - os.utime(creation_order[i], (mtime, mtime)) - mtime += 1 - - return creation_order[:2], creation_order[2], creation_order[3:] - - -def test_newer_pairwise_group(groups_target): - older = newer_pairwise_group([groups_target[0]], [groups_target[1]]) - newer = newer_pairwise_group([groups_target[2]], [groups_target[1]]) - assert older == ([], []) - assert newer == ([groups_target[2]], [groups_target[1]]) diff --git a/tox.ini b/tox.ini index b7f50ea89f..1ce665bdcd 100644 --- a/tox.ini +++ b/tox.ini @@ -53,7 +53,9 @@ deps = importlib_resources < 6 # twisted/towncrier#528 (waiting for release) commands = python -m sphinx -W --keep-going . {toxinidir}/build/html - python -m sphinxlint + python -m sphinxlint \ + # workaround for sphinx-contrib/sphinx-lint#83 + --jobs 1 [testenv:finalize] description = assemble changelog and tag a release