Merge tag 'v8.7.0' into cpython

jaraco · jaraco · commit b67ac80c4927 · 2025-08-17T10:12:17.000-07:00
diff --git a/Lib/importlib/metadata/__init__.py b/Lib/importlib/metadata/__init__.py
diff --git a/Lib/importlib/metadata/_adapters.py b/Lib/importlib/metadata/_adapters.py
@@ -1,11 +1,58 @@
+import email.message
+import email.policy
 import re
 import textwrap
-import email.message
 
 from ._text import FoldedCase
 
 
+class RawPolicy(email.policy.EmailPolicy):
+ def fold(self, name, value):
+ folded = self.linesep.join(
+ textwrap.indent(value, prefix=' ' * 8, predicate=lambda line: True)
+ .lstrip()
+ .splitlines()
+ )
+ return f'{name}: {folded}{self.linesep}'
+
+
 class Message(email.message.Message):
+ r"""
+ Specialized Message subclass to handle metadata naturally.
+
+ Reads values that may have newlines in them and converts the
+ payload to the Description.
+
+ >>> msg_text = textwrap.dedent('''
+ ... Name: Foo
+ ... Version: 3.0
+ ... License: blah
+ ... de-blah
+ ... <BLANKLINE>
+ ... First line of description.
+ ... Second line of description.
+ ... <BLANKLINE>
+ ... Fourth line!
+ ... ''').lstrip().replace('<BLANKLINE>', '')
+ >>> msg = Message(email.message_from_string(msg_text))
+ >>> msg['Description']
+ 'First line of description.\nSecond line of description.\n\nFourth line!\n'
+
+ Message should render even if values contain newlines.
+
+ >>> print(msg)
+ Name: Foo
+ Version: 3.0
+ License: blah
+ de-blah
+ Description: First line of description.
+ Second line of description.
+ <BLANKLINE>
+ Fourth line!
+ <BLANKLINE>
+ <BLANKLINE>
+ """
+
 multiple_use_keys = set(
 map(
 FoldedCase,
@@ -57,15 +104,20 @@ def __getitem__(self, item):
 def _repair_headers(self):
 def redent(value):
 "Correct for RFC822 indentation"
- if not value or '\n' not in value:
+ indent = ' ' * 8
+ if not value or '\n' + indent not in value:
 return value
- return textwrap.dedent(' ' * 8 + value)
+ return textwrap.dedent(indent + value)
 
 headers = [(key, redent(value)) for key, value in vars(self)['_headers']]
 if self._payload:
 headers.append(('Description', self.get_payload()))
+ self.set_payload('')
 return headers
 
+ def as_string(self):
+ return super().as_string(policy=RawPolicy())
+
 @property
 def json(self):
 """
diff --git a/Lib/importlib/metadata/_collections.py b/Lib/importlib/metadata/_collections.py
@@ -1,4 +1,5 @@
 import collections
+import typing
 
 
 # from jaraco.collections 3.3
@@ -24,7 +25,10 @@ def freeze(self):
 self._frozen = lambda key: self.default_factory()
 
 
-class Pair(collections.namedtuple('Pair', 'name value')):
+class Pair(typing.NamedTuple):
+ name: str
+ value: str
+
 @classmethod
 def parse(cls, text):
 return cls(*map(str.strip, text.split("=", 1)))
diff --git a/Lib/importlib/metadata/_functools.py b/Lib/importlib/metadata/_functools.py
@@ -1,5 +1,5 @@
-import types
 import functools
+import types
 
 
 # from jaraco.functools 3.3
diff --git a/Lib/importlib/metadata/_meta.py b/Lib/importlib/metadata/_meta.py
@@ -1,9 +1,13 @@
 from __future__ import annotations
 
 import os
-from typing import Protocol
-from typing import Any, Dict, Iterator, List, Optional, TypeVar, Union, overload
-
+from collections.abc import Iterator
+from typing import (
+ Any,
+ Protocol,
+ TypeVar,
+ overload,
+)
 
 _T = TypeVar("_T")
 
@@ -20,25 +24,25 @@ def __iter__(self) -> Iterator[str]: ... # pragma: no cover
 @overload
 def get(
 self, name: str, failobj: None = None
- ) -> Optional[str]: ... # pragma: no cover
+ ) -> str | None: ... # pragma: no cover
 
 @overload
- def get(self, name: str, failobj: _T) -> Union[str, _T]: ... # pragma: no cover
+ def get(self, name: str, failobj: _T) -> str | _T: ... # pragma: no cover
 
 # overload per python/importlib_metadata#435
 @overload
 def get_all(
 self, name: str, failobj: None = None
- ) -> Optional[List[Any]]: ... # pragma: no cover
+ ) -> list[Any] | None: ... # pragma: no cover
 
 @overload
- def get_all(self, name: str, failobj: _T) -> Union[List[Any], _T]:
+ def get_all(self, name: str, failobj: _T) -> list[Any] | _T:
 """
 Return all values associated with a possibly multi-valued key.
 """
 
 @property
- def json(self) -> Dict[str, Union[str, List[str]]]:
+ def json(self) -> dict[str, str | list[str]]:
 """
 A JSON-compatible form of the metadata.
 """
@@ -50,11 +54,11 @@ class SimplePath(Protocol):
 """
 
 def joinpath(
- self, other: Union[str, os.PathLike[str]]
+ self, other: str | os.PathLike[str]
 ) -> SimplePath: ... # pragma: no cover
 
 def __truediv__(
- self, other: Union[str, os.PathLike[str]]
+ self, other: str | os.PathLike[str]
 ) -> SimplePath: ... # pragma: no cover
 
 @property
diff --git a/Lib/importlib/metadata/_typing.py b/Lib/importlib/metadata/_typing.py
@@ -0,0 +1,15 @@
+import functools
+import typing
+
+from ._meta import PackageMetadata
+
+md_none = functools.partial(typing.cast, PackageMetadata)
+"""
+Suppress type errors for optional metadata.
+
+Although Distribution.metadata can return None when metadata is corrupt
+and thus None, allow callers to assume it's not None and crash if
+that's the case.
+
+# python/importlib_metadata#493
+"""
diff --git a/Lib/test/test_importlib/metadata/_path.py b/Lib/test/test_importlib/metadata/_path.py
@@ -1,9 +1,14 @@
-# from jaraco.path 3.7
+# from jaraco.path 3.7.2
+
+from __future__ import annotations
 
 import functools
 import pathlib
-from typing import Dict, Protocol, Union
-from typing import runtime_checkable
+from collections.abc import Mapping
+from typing import TYPE_CHECKING, Protocol, Union, runtime_checkable
+
+if TYPE_CHECKING:
+ from typing_extensions import Self
 
 
 class Symlink(str):
@@ -12,29 +17,25 @@ class Symlink(str):
 """
 
 
-FilesSpec = Dict[str, Union[str, bytes, Symlink, 'FilesSpec']] # type: ignore
+FilesSpec = Mapping[str, Union[str, bytes, Symlink, 'FilesSpec']]
 
 
 @runtime_checkable
 class TreeMaker(Protocol):
- def __truediv__(self, *args, **kwargs): ... # pragma: no cover
-
- def mkdir(self, **kwargs): ... # pragma: no cover
-
- def write_text(self, content, **kwargs): ... # pragma: no cover
-
- def write_bytes(self, content): ... # pragma: no cover
-
- def symlink_to(self, target): ... # pragma: no cover
+ def __truediv__(self, other, /) -> Self: ...
+ def mkdir(self, *, exist_ok) -> object: ...
+ def write_text(self, content, /, *, encoding) -> object: ...
+ def write_bytes(self, content, /) -> object: ...
+ def symlink_to(self, target, /) -> object: ...
 
 
-def _ensure_tree_maker(obj: Union[str, TreeMaker]) -> TreeMaker:
- return obj if isinstance(obj, TreeMaker) else pathlib.Path(obj) # type: ignore
+def _ensure_tree_maker(obj: str | TreeMaker) -> TreeMaker:
+ return obj if isinstance(obj, TreeMaker) else pathlib.Path(obj)
 
 
 def build(
 spec: FilesSpec,
- prefix: Union[str, TreeMaker] = pathlib.Path(), # type: ignore
+ prefix: str | TreeMaker = pathlib.Path(),
 ):
 """
 Build a set of files/directories, as described by the spec.
@@ -66,23 +67,24 @@ def build(
 
 
 @functools.singledispatch
-def create(content: Union[str, bytes, FilesSpec], path):
+def create(content: str | bytes | FilesSpec, path: TreeMaker) -> None:
 path.mkdir(exist_ok=True)
- build(content, prefix=path) # type: ignore
+ # Mypy only looks at the signature of the main singledispatch method. So it must contain the complete Union
+ build(content, prefix=path) # type: ignore[arg-type] # python/mypy#11727
 
 
 @create.register
-def _(content: bytes, path):
+def _(content: bytes, path: TreeMaker) -> None:
 path.write_bytes(content)
 
 
 @create.register
-def _(content: str, path):
+def _(content: str, path: TreeMaker) -> None:
 path.write_text(content, encoding='utf-8')
 
 
 @create.register
-def _(content: Symlink, path):
+def _(content: Symlink, path: TreeMaker) -> None:
 path.symlink_to(content)
 
 
diff --git a/Lib/test/test_importlib/metadata/fixtures.py b/Lib/test/test_importlib/metadata/fixtures.py
@@ -1,11 +1,11 @@
-import sys
+import contextlib
 import copy
+import functools
 import json
-import shutil
 import pathlib
+import shutil
+import sys
 import textwrap
-import functools
-import contextlib
 
 from test.support import import_helper
 from test.support import os_helper
@@ -14,14 +14,10 @@
 from . import _path
 from ._path import FilesSpec
 
-
-try:
- from importlib import resources # type: ignore
-
- getattr(resources, 'files')
- getattr(resources, 'as_file')
-except (ImportError, AttributeError):
- import importlib_resources as resources # type: ignore
+if sys.version_info >= (3, 9):
+ from importlib import resources
+else:
+ import importlib_resources as resources
 
 
 @contextlib.contextmanager
diff --git a/Lib/test/test_importlib/metadata/test_api.py b/Lib/test/test_importlib/metadata/test_api.py
@@ -1,9 +1,8 @@
+import importlib
 import re
 import textwrap
 import unittest
-import importlib
 
-from . import fixtures
 from importlib.metadata import (
 Distribution,
 PackageNotFoundError,
@@ -15,6 +14,8 @@
 version,
 )
 
+from . import fixtures
+
 
 class APITests(
 fixtures.EggInfoPkg,
diff --git a/Lib/test/test_importlib/metadata/test_main.py b/Lib/test/test_importlib/metadata/test_main.py
@@ -1,17 +1,14 @@
-import re
+import importlib
 import pickle
+import re
 import unittest
-import importlib
-import importlib.metadata
 from test.support import os_helper
 
 try:
 import pyfakefs.fake_filesystem_unittest as ffs
 except ImportError:
 from .stubs import fake_filesystem_unittest as ffs
 
-from . import fixtures
-from ._path import Symlink
 from importlib.metadata import (
 Distribution,
 EntryPoint,
@@ -24,6 +21,9 @@
 version,
 )
 
+from . import fixtures
+from ._path import Symlink
+
 
 class BasicTests(fixtures.DistInfoPkg, unittest.TestCase):
 version_pattern = r'\d+\.\d+(\.\d)?'
@@ -157,6 +157,16 @@ def test_valid_dists_preferred(self):
 dist = Distribution.from_name('foo')
 assert dist.version == "1.0"
 
+ def test_missing_metadata(self):
+ """
+ Dists with a missing metadata file should return None.
+
+ Ref python/importlib_metadata#493.
+ """
+ fixtures.build_files(self.make_pkg('foo-4.3', files={}), self.site_dir)
+ assert Distribution.from_name('foo').metadata is None
+ assert metadata('foo') is None
+
 
 class NonASCIITests(fixtures.OnSysPath, fixtures.SiteDir, unittest.TestCase):
 @staticmethod
diff --git a/Lib/test/test_importlib/metadata/test_zip.py b/Lib/test/test_importlib/metadata/test_zip.py
@@ -1,7 +1,6 @@
 import sys
 import unittest
 
-from . import fixtures
 from importlib.metadata import (
 PackageNotFoundError,
 distribution,
@@ -11,6 +10,8 @@
 version,
 )
 
+from . import fixtures
+
 
 class TestZip(fixtures.ZipFixtures, unittest.TestCase):
 def setUp(self):

-Original file line number
+Diff line change
@@ @@ -1,4 +1,5 @@ @@
 importcollections
 +importtyping
 # from jaraco.collections 3.3
 self._frozen=lambdakey: self.default_factory()
 -classPair(collections.namedtuple('Pair', 'name value')):
 +classPair(typing.NamedTuple):
 +name: str
 +value: str
++
 @classmethod
 defparse(cls, text):
 returncls(*map(str.strip, text.split("=", 1)))
-Original file line number
+Diff line change
@@ @@ -1,5 +1,5 @@ @@
 -importtypes
 importfunctools
 +importtypes
 # from jaraco.functools 3.3
-Original file line number
+Diff line change
@@ @@ -1,9 +1,13 @@ @@
 from __future__ importannotations
 importos
 -fromtypingimportProtocol
 -fromtypingimportAny, Dict, Iterator, List, Optional, TypeVar, Union, overload
+-
 +fromcollections.abcimportIterator
 +fromtypingimport (
 +Any,
 +Protocol,
 +TypeVar,
 +overload,
 +)
 _T=TypeVar("_T")
 @overload
 defget(
 self, name: str, failobj: None=None
 - ) ->Optional[str]: ... # pragma: no cover
 + ) ->str|None: ... # pragma: no cover
 @overload
 -defget(self, name: str, failobj: _T) ->Union[str, _T]: ... # pragma: no cover
 +defget(self, name: str, failobj: _T) ->str|_T: ... # pragma: no cover
 # overload per python/importlib_metadata#435
 @overload
 defget_all(
 self, name: str, failobj: None=None
 - ) ->Optional[List[Any]]: ... # pragma: no cover
 + ) ->list[Any]|None: ... # pragma: no cover
 @overload
 -defget_all(self, name: str, failobj: _T) ->Union[List[Any], _T]:
 +defget_all(self, name: str, failobj: _T) ->list[Any]|_T:
 """
  Return all values associated with a possibly multi-valued key.
  """
 @property
 -defjson(self) ->Dict[str, Union[str, List[str]]]:
 +defjson(self) ->dict[str, str|list[str]]:
 """
  A JSON-compatible form of the metadata.
  """
  """
 defjoinpath(
 -self, other: Union[str, os.PathLike[str]]
 +self, other: str|os.PathLike[str]
  ) ->SimplePath: ... # pragma: no cover
 def__truediv__(
 -self, other: Union[str, os.PathLike[str]]
 +self, other: str|os.PathLike[str]
  ) ->SimplePath: ... # pragma: no cover
 @property
-Original file line number
+Diff line change
@@ @@ -1,9 +1,14 @@ @@
 -# from jaraco.path 3.7
 +# from jaraco.path 3.7.2
++
 +from __future__ importannotations
 importfunctools
 importpathlib
 -fromtypingimportDict, Protocol, Union
 -fromtypingimportruntime_checkable
 +fromcollections.abcimportMapping
 +fromtypingimportTYPE_CHECKING, Protocol, Union, runtime_checkable
++
 +ifTYPE_CHECKING:
 +fromtyping_extensionsimportSelf
 classSymlink(str):
  """
 -FilesSpec=Dict[str, Union[str, bytes, Symlink, 'FilesSpec']]# type: ignore
 +FilesSpec=Mapping[str, Union[str, bytes, Symlink, 'FilesSpec']]
 @runtime_checkable
 classTreeMaker(Protocol):
 -def__truediv__(self, *args, **kwargs): ... # pragma: no cover
+-
 -defmkdir(self, **kwargs): ... # pragma: no cover
+-
 -defwrite_text(self, content, **kwargs): ... # pragma: no cover
+-
 -defwrite_bytes(self, content): ... # pragma: no cover
+-
 -defsymlink_to(self, target): ... # pragma: no cover
 +def__truediv__(self, other, /) ->Self: ...
 +defmkdir(self, *, exist_ok) ->object: ...
 +defwrite_text(self, content, /, *, encoding) ->object: ...
 +defwrite_bytes(self, content, /) ->object: ...
 +defsymlink_to(self, target, /) ->object: ...
 -def_ensure_tree_maker(obj: Union[str, TreeMaker]) ->TreeMaker:
 -returnobjifisinstance(obj, TreeMaker) elsepathlib.Path(obj)# type: ignore
 +def_ensure_tree_maker(obj: str|TreeMaker) ->TreeMaker:
 +returnobjifisinstance(obj, TreeMaker) elsepathlib.Path(obj)
 defbuild(
 spec: FilesSpec,
 -prefix: Union[str, TreeMaker]=pathlib.Path(),# type: ignore
 +prefix: str|TreeMaker=pathlib.Path(),
 ):
 """
  Build a set of files/directories, as described by the spec.
 @functools.singledispatch
 -defcreate(content: Union[str, bytes, FilesSpec], path):
 +defcreate(content: str|bytes|FilesSpec, path: TreeMaker) ->None:
 path.mkdir(exist_ok=True)
 -build(content, prefix=path) # type: ignore
 +# Mypy only looks at the signature of the main singledispatch method. So it must contain the complete Union
 +build(content, prefix=path) # type: ignore[arg-type] # python/mypy#11727
 @create.register
 -def_(content: bytes, path):
 +def_(content: bytes, path: TreeMaker) ->None:
 path.write_bytes(content)
 @create.register
 -def_(content: str, path):
 +def_(content: str, path: TreeMaker) ->None:
 path.write_text(content, encoding='utf-8')
 @create.register
 -def_(content: Symlink, path):
 +def_(content: Symlink, path: TreeMaker) ->None:
 path.symlink_to(content)
-Original file line number
+Diff line change
@@ @@ -1,11 +1,11 @@ @@
 -importsys
 +importcontextlib
 importcopy
 +importfunctools
 importjson
 -importshutil
 importpathlib
 +importshutil
 +importsys
 importtextwrap
 -importfunctools
 -importcontextlib
 fromtest.supportimportimport_helper
 fromtest.supportimportos_helper
 from . import_path
 from ._pathimportFilesSpec
+-
 -try:
 -fromimportlibimportresources# type: ignore
+-
 -getattr(resources, 'files')
 -getattr(resources, 'as_file')
 -except (ImportError, AttributeError):
 -importimportlib_resourcesasresources# type: ignore
 +ifsys.version_info>= (3, 9):
 +fromimportlibimportresources
 +else:
 +importimportlib_resourcesasresources
 @contextlib.contextmanager
-Original file line number
+Diff line change
@@ @@ -1,17 +1,14 @@ @@
 -importre
 +importimportlib
 importpickle
 +importre
 importunittest
 -importimportlib
 -importimportlib.metadata
 fromtest.supportimportos_helper
 try:
 importpyfakefs.fake_filesystem_unittestasffs
 exceptImportError:
 from .stubsimportfake_filesystem_unittestasffs
 -from . importfixtures
 -from ._pathimportSymlink
 fromimportlib.metadataimport (
 Distribution,
 EntryPoint,
 version,
+)
 +from . importfixtures
 +from ._pathimportSymlink
++
 classBasicTests(fixtures.DistInfoPkg, unittest.TestCase):
 version_pattern=r'\d+\.\d+(\.\d)?'
 dist=Distribution.from_name('foo')
 assertdist.version=="1.0"
 +deftest_missing_metadata(self):
 +"""
 + Dists with a missing metadata file should return None.
++
 + Ref python/importlib_metadata#493.
 + """
 +fixtures.build_files(self.make_pkg('foo-4.3', files={}), self.site_dir)
 +assertDistribution.from_name('foo').metadataisNone
 +assertmetadata('foo') isNone
++
 classNonASCIITests(fixtures.OnSysPath, fixtures.SiteDir, unittest.TestCase):
 @staticmethod