Use _static.{List,Dict} and an attribute to track modifications instead of _static.{Tuple,Mapping} for better compatibility

Author: abravalheri

setuptools/_core_metadata.py

@@ -18,7 +18,8 @@
 from packaging.utils import canonicalize_name, canonicalize_version
 from packaging.version import Version
 
-from . import _normalization, _reqs, _static
+from . import _normalization, _reqs
+from ._static import is_static
 from .warnings import SetuptoolsDeprecationWarning
 
 from distutils.util import rfc822_escape
@@ -208,7 +209,7 @@ def write_field(key, value):
     _write_requirements(self, file)
 
     for field, attr in _POSSIBLE_DYNAMIC_FIELDS.items():
-        if hasattr(self, attr) and not isinstance(getattr(self, attr), _static.Static):
+        if (val := getattr(self, attr, None)) and not is_static(val):
             write_field('Dynamic', field)
 
     long_description = self.get_long_description()
@@ -291,6 +292,7 @@ def _distribution_fullname(name: str, version: str) -> str:
 
 
 _POSSIBLE_DYNAMIC_FIELDS = {
+    # Core Metadata Field x related Distribution attribute
     "author": "author",
     "author-email": "author_email",
     "classifier": "classifiers",
@@ -300,7 +302,7 @@ def _distribution_fullname(name: str, version: str) -> str:
     "home-page": "url",
     "keywords": "keywords",
     "license": "license",
-    # "license-file": "license_files", # PEP 639 allows backfilling without dynamic ??
+    # "license-file": "license_files", # XXX: does PEP 639 exempt Dynamic ??
     "maintainer": "maintainer",
     "maintainer-email": "maintainer_email",
     "obsoletes": "obsoletes",

setuptools/_static.py

@@ -1,12 +1,14 @@
-from collections import abc
-from functools import singledispatch
+from functools import wraps
+from typing import Any, TypeVar
 
 import packaging.specifiers
 
+from .warnings import SetuptoolsDeprecationWarning
+
 
 class Static:
     """
-    Wrapper for butil-in object types that are allow setuptools to identify
+    Wrapper for built-in object types that are allow setuptools to identify
     static core metadata (in opposition to ``Dynamic``, as defined :pep:`643`).
 
     The trick is to mark values with :class:`Static` when they come from
@@ -15,8 +17,43 @@ class Static:
 
     We inherit from built-in classes, so that we don't need to change the existing
     code base to deal with the new types.
-    We also prefer "immutable-ish" objects to avoid changes after the initial parsing.
+    We also should strive for immutability objects to avoid changes after the
+    initial parsing.
+    """
+
+    _mutated_: bool = False  # TODO: Remove after deprecation warning is solved
+
+
+def _prevent_modification(target: type, method: str, copying: str):
+    """
+    Because setuptools is very flexible we cannot fully prevent
+    plugins and user customisations from modifying static values that were
+    parsed from config files.
+    But we can attempt to block "in-place" mutations and identify when they
+    were done.
     """
+    fn = getattr(target, method)
+
+    @wraps(fn)
+    def _replacement(self: Static, *args, **kwargs):
+        # TODO: After deprecation period raise NotImplementedError instead of warning
+        #       which obviated the existence and checks of the `_mutated_` attribute.
+        self._mutated_ = True
+        SetuptoolsDeprecationWarning.emit(
+            "Direct modification of value will be disallowed",
+            f"""
+            In an effort to implement PEP 643, direct/in-place changes of static values
+            that come from configuration files are deprecated.
+            If you need to modify this value, please first create a copy with {copying}
+            and make sure conform to all relevant standards when overriding setuptools
+            functionality (https://packaging.python.org/en/latest/specifications/).
+            """,
+            due_date=(2025, 10, 10),  # Initially introduced in 2024-09-06
+        )
+        return fn(self, *args, **kwargs)
+
+    _replacement.__doc__ = ""  # otherwise doctest may fail.
+    setattr(target, method, _replacement)
 
 
 class Str(str, Static):
@@ -27,15 +64,69 @@ class Tuple(tuple, Static):
     pass
 
 
-class Mapping(dict, Static):
-    pass
+class List(list, Static):
+    """
+    :meta private:
+    >>> x = List([1, 2, 3])
+    >>> is_static(x)
+    True
+    >>> x += [0]  # doctest: +IGNORE_EXCEPTION_DETAIL
+    Traceback (most recent call last):
+    SetuptoolsDeprecationWarning: Direct modification ...
+    >>> is_static(x)  # no longer static after modification
+    False
+    >>> y = list(x)
+    >>> y.clear()
+    >>> y
+    []
+    >>> y == x
+    False
+    >>> is_static(List(y))
+    True
+    """
 
 
-def _do_not_modify(*_, **__):
-    raise NotImplementedError("Direct modification disallowed (statically defined)")
+# Make `List` immutable-ish
+# (certain places of setuptools/distutils issue a warn if we use tuple instead of list)
+for _method in (
+    '__delitem__',
+    '__iadd__',
+    '__setitem__',
+    'append',
+    'clear',
+    'extend',
+    'insert',
+    'remove',
+    'reverse',
+    'pop',
+):
+    _prevent_modification(List, _method, "`list(value)`")
 
 
-# Make `Mapping` immutable-ish (we cannot inherit from types.MappingProxyType):
+class Dict(dict, Static):
+    """
+    :meta private:
+    >>> x = Dict({'a': 1, 'b': 2})
+    >>> is_static(x)
+    True
+    >>> x['c'] = 0  # doctest: +IGNORE_EXCEPTION_DETAIL
+    Traceback (most recent call last):
+    SetuptoolsDeprecationWarning: Direct modification ...
+    >>> x._mutated_
+    True
+    >>> is_static(x)  # no longer static after modification
+    False
+    >>> y = dict(x)
+    >>> y.popitem()
+    ('b', 2)
+    >>> y == x
+    False
+    >>> is_static(Dict(y))
+    True
+    """
+
+
+# Make `Dict` immutable-ish (we cannot inherit from types.MappingProxyType):
 for _method in (
     '__delitem__',
     '__ior__',
@@ -46,38 +137,46 @@ def _do_not_modify(*_, **__):
     'setdefault',
     'update',
 ):
-    setattr(Mapping, _method, _do_not_modify)
+    _prevent_modification(Dict, _method, "`dict(value)`")
 
 
 class SpeficierSet(packaging.specifiers.SpecifierSet, Static):
-    """Not exactly a builtin type but useful for ``requires-python``"""
-
-
-@singledispatch
-def convert(value):
-    return value
+    """Not exactly a built-in type but useful for ``requires-python``"""
 
 
-@convert.register
-def _(value: str) -> Str:
-    return Str(value)
+T = TypeVar("T")
 
 
-@convert.register
-def _(value: str) -> Str:
-    return Str(value)
+def noop(value: T) -> T:
+    """
+    >>> noop(42)
+    42
+    """
+    return value
 
 
-@convert.register
-def _(value: tuple) -> Tuple:
-    return Tuple(value)
+_CONVERSIONS = {str: Str, tuple: Tuple, list: List, dict: Dict}
 
 
-@convert.register
-def _(value: list) -> Tuple:
-    return Tuple(value)
+def attempt_conversion(value: T) -> T:
+    """
+    >>> is_static(attempt_conversion("hello"))
+    True
+    >>> is_static(object())
+    False
+    """
+    return _CONVERSIONS.get(type(value), noop)(value)  # type: ignore[call-overload]
 
 
-@convert.register
-def _(value: abc.Mapping) -> Mapping:
-    return Mapping(value)
+def is_static(value: Any) -> bool:
+    """
+    >>> is_static(a := Dict({'a': 1}))
+    True
+    >>> is_static(dict(a))
+    False
+    >>> is_static(b := List([1, 2, 3]))
+    True
+    >>> is_static(list(b))
+    False
+    """
+    return isinstance(value, Static) and not value._mutated_

setuptools/config/expand.py

@@ -183,7 +183,8 @@ def read_attr(
 
     try:
         value = getattr(StaticModule(module_name, spec), attr_name)
-        return _static.convert(value)
+        # XXX: Is marking as static contents coming from modules too optimistic?
+        return _static.attempt_conversion(value)
     except Exception:
         # fallback to evaluate module
         module = _load_spec(spec, module_name)

setuptools/config/setupcfg.py

@@ -309,7 +309,7 @@ def _parse_list(cls, value, separator=','):
 
         :param value:
         :param separator: List items separator character.
-        :rtype: tuple
+        :rtype: list
         """
         if isinstance(value, list):  # _get_parser_compound case
             return value
@@ -387,15 +387,16 @@ def _parse_file(self, value, root_dir: StrPath | None):
         include_directive = 'file:'
 
         if not isinstance(value, str):
-            return _static.convert(value)
+            return value
 
         if not value.startswith(include_directive):
             return _static.Str(value)
 
         spec = value[len(include_directive) :]
         filepaths = [path.strip() for path in spec.split(',')]
         self._referenced_files.update(filepaths)
-        return _static.Str(expand.read_files(filepaths, root_dir))  # Too optimistic?
+        # XXX: Is marking as static contents coming from files too optimistic?
+        return _static.Str(expand.read_files(filepaths, root_dir))
 
     def _parse_attr(self, value, package_dir, root_dir: StrPath):
         """Represents value as a module attribute.
@@ -473,7 +474,7 @@ def parse_section(self, section_options) -> None:
         for name, (_, value) in section_options.items():
             with contextlib.suppress(KeyError):
                 # Keep silent for a new option may appear anytime.
-                self[name] = _static.convert(value)
+                self[name] = value
 
     def parse(self) -> None:
         """Parses configuration file items from one
@@ -548,22 +549,28 @@ def __init__(
     @property
     def parsers(self):
         """Metadata item name to parser function mapping."""
-        parse_tuple_static = self._get_parser_compound(self._parse_list, _static.Tuple)
-        parse_dict_static = self._get_parser_compound(self._parse_dict, _static.Mapping)
+        parse_list_static = self._get_parser_compound(self._parse_list, _static.List)
+        parse_dict_static = self._get_parser_compound(self._parse_dict, _static.Dict)
         parse_file = partial(self._parse_file, root_dir=self.root_dir)
         exclude_files_parser = self._exclude_files_parser
 
         return {
-            'platforms': parse_tuple_static,
-            'keywords': parse_tuple_static,
-            'provides': parse_tuple_static,
-            'obsoletes': parse_tuple_static,
-            'classifiers': self._get_parser_compound(parse_file, parse_tuple_static),
+            'author': _static.Str,
+            'author_email': _static.Str,
+            'maintainer': _static.Str,
+            'maintainer_email': _static.Str,
+            'platforms': parse_list_static,
+            'keywords': parse_list_static,
+            'provides': parse_list_static,
+            'obsoletes': parse_list_static,
+            'classifiers': self._get_parser_compound(parse_file, parse_list_static),
             'license': exclude_files_parser('license'),
-            'license_files': parse_tuple_static,
+            'license_files': parse_list_static,
             'description': parse_file,
             'long_description': parse_file,
-            'version': self._parse_version,
+            'long_description_content_type': _static.Str,
+            'version': self._parse_version,  # Cannot be marked as dynamic
+            'url': _static.Str,
             'project_urls': parse_dict_static,
         }
 
@@ -620,7 +627,8 @@ def _parse_requirements_list(self, label: str, value: str):
         _warn_accidental_env_marker_misconfig(label, value, parsed)
         # Filter it to only include lines that are not comments. `parse_list`
         # will have stripped each line and filtered out empties.
-        return _static.Tuple(line for line in parsed if not line.startswith("#"))
+        return _static.List(line for line in parsed if not line.startswith("#"))
+        # ^-- Use `_static.List` to mark a non-`Dynamic` Core Metadata
 
     @property
     def parsers(self):
@@ -642,14 +650,14 @@ def parsers(self):
                 "consider using implicit namespaces instead (PEP 420).",
                 # TODO: define due date, see setuptools.dist:check_nsp.
             ),
-            'install_requires': partial(
+            'install_requires': partial(  # Core Metadata
                 self._parse_requirements_list, "install_requires"
             ),
             'setup_requires': self._parse_list_semicolon,
             'packages': self._parse_packages,
             'entry_points': self._parse_file_in_root,
             'py_modules': parse_list,
-            'python_requires': _static.SpeficierSet,
+            'python_requires': _static.SpeficierSet,  # Core Metadata
             'cmdclass': parse_cmdclass,
         }
 
@@ -726,7 +734,7 @@ def parse_section_exclude_package_data(self, section_options) -> None:
         """
         self['exclude_package_data'] = self._parse_package_data(section_options)
 
-    def parse_section_extras_require(self, section_options) -> None:
+    def parse_section_extras_require(self, section_options) -> None:  # Core Metadata
         """Parses `extras_require` configuration file section.
 
         :param dict section_options:
@@ -736,7 +744,8 @@ def parse_section_extras_require(self, section_options) -> None:
             lambda k, v: self._parse_requirements_list(f"extras_require[{k}]", v),
         )
 
-        self['extras_require'] = _static.Mapping(parsed)
+        self['extras_require'] = _static.Dict(parsed)
+        # ^-- Use `_static.Dict` to mark a non-`Dynamic` Core Metadata
 
     def parse_section_data_files(self, section_options) -> None:
         """Parses `data_files` configuration file section.

setuptools/dist.py

@@ -394,11 +394,11 @@ def _normalize_requires(self):
         extras_require = getattr(self, "extras_require", None) or {}
 
         # Preserve the "static"-ness of values parsed from config files
-        seq = _static.Tuple if isinstance(install_requires, _static.Static) else list
-        self.install_requires = seq(map(str, _reqs.parse(install_requires)))
+        list_ = _static.List if _static.is_static(install_requires) else list
+        self.install_requires = list_(map(str, _reqs.parse(install_requires)))
 
-        mapp = _static.Mapping if isinstance(extras_require, _static.Static) else dict
-        self.extras_require = mapp(
+        dict_ = _static.Dict if _static.is_static(extras_require) else dict
+        self.extras_require = dict_(
             (k, list(map(str, _reqs.parse(v or [])))) for k, v in extras_require.items()
         )