gh-121190: Emit a better error message from importlib.resources.files() when module spec is None" (#148460)

Also merges incidental changes from importlib_resources 7.1.

Co-authored by: Yuichiro Tachibana (Tsuchiya) <t.yic.yt@gmail.com>

Author: jaraco

Lib/importlib/resources/_common.py

@@ -7,11 +7,11 @@
 import pathlib
 import tempfile
 import types
-from typing import cast, Optional, Union
+from typing import Optional, cast
 
 from .abc import ResourceReader, Traversable
 
-Package = Union[types.ModuleType, str]
+Package = types.ModuleType | str
 Anchor = Package
 
 
@@ -32,7 +32,7 @@ def get_resource_reader(package: types.ModuleType) -> Optional[ResourceReader]:
     # zipimport.zipimporter does not support weak references, resulting in a
     # TypeError.  That seems terrible.
     spec = package.__spec__
-    reader = getattr(spec.loader, "get_resource_reader", None)  # type: ignore[union-attr]
+    reader = getattr(spec.loader, 'get_resource_reader', None)  # type: ignore[union-attr]
     if reader is None:
         return None
     return reader(spec.name)  # type: ignore[union-attr]
@@ -50,7 +50,7 @@ def _(cand: str) -> types.ModuleType:
 
 @resolve.register
 def _(cand: None) -> types.ModuleType:
-    return resolve(_infer_caller().f_globals["__name__"])
+    return resolve(_infer_caller().f_globals['__name__'])
 
 
 def _infer_caller():
@@ -62,7 +62,7 @@ def is_this_file(frame_info):
         return frame_info.filename == stack[0].filename
 
     def is_wrapper(frame_info):
-        return frame_info.function == "wrapper"
+        return frame_info.function == 'wrapper'
 
     stack = inspect.stack()
     not_this_file = itertools.filterfalse(is_this_file, stack)
@@ -71,6 +71,19 @@ def is_wrapper(frame_info):
     return next(callers).frame
 
 
+def _assert_spec(package: types.ModuleType) -> None:
+    """
+    Provide a nicer error message when package is ``__main__``
+    and its ``__spec__`` is ``None``
+    (https://docs.python.org/3/reference/import.html#main-spec).
+    """
+    if package.__spec__ is None:
+        raise TypeError(
+            f"Cannot access resources for '{package.__name__}' "
+            "as it does not appear to correspond to an importable module (its __spec__ is None)."
+        )
+
+
 def from_package(package: types.ModuleType):
     """
     Return a Traversable object for the given package.
@@ -79,6 +92,7 @@ def from_package(package: types.ModuleType):
     # deferred for performance (python/cpython#109829)
     from ._adapters import wrap_spec
 
+    _assert_spec(package)
     spec = wrap_spec(package)
     reader = spec.loader.get_resource_reader(spec.name)
     return reader.files()
@@ -87,7 +101,7 @@ def from_package(package: types.ModuleType):
 @contextlib.contextmanager
 def _tempfile(
     reader,
-    suffix="",
+    suffix='',
     # gh-93353: Keep a reference to call os.remove() in late Python
     # finalization.
     *,

Lib/importlib/resources/abc.py

@@ -2,23 +2,21 @@
 import itertools
 import os
 import pathlib
+from collections.abc import Iterable, Iterator
 from typing import (
     Any,
     BinaryIO,
-    Iterable,
-    Iterator,
     Literal,
     NoReturn,
     Optional,
     Protocol,
     Text,
     TextIO,
-    Union,
     overload,
     runtime_checkable,
 )
 
-StrPath = Union[str, os.PathLike[str]]
+StrPath = str | os.PathLike[str]
 
 __all__ = ["ResourceReader", "Traversable", "TraversableResources"]
 
@@ -151,9 +149,7 @@ def open(self, mode: Literal['r'] = 'r', *args: Any, **kwargs: Any) -> TextIO: .
     def open(self, mode: Literal['rb'], *args: Any, **kwargs: Any) -> BinaryIO: ...
 
     @abc.abstractmethod
-    def open(
-        self, mode: str = 'r', *args: Any, **kwargs: Any
-    ) -> Union[TextIO, BinaryIO]:
+    def open(self, mode: str = 'r', *args: Any, **kwargs: Any) -> TextIO | BinaryIO:
         """
         mode may be 'r' or 'rb' to open as text or binary. Return a handle
         suitable for reading (same as pathlib.Path.open).

Lib/importlib/resources/simple.py

@@ -5,7 +5,7 @@
 import abc
 import io
 import itertools
-from typing import BinaryIO, List
+from typing import BinaryIO
 
 from .abc import Traversable, TraversableResources
 
@@ -24,14 +24,14 @@ def package(self) -> str:
         """
 
     @abc.abstractmethod
-    def children(self) -> List['SimpleReader']:
+    def children(self) -> list['SimpleReader']:
         """
         Obtain an iterable of SimpleReader for available
         child containers (e.g. directories).
         """
 
     @abc.abstractmethod
-    def resources(self) -> List[str]:
+    def resources(self) -> list[str]:
         """
         Obtain available named resources for this virtual package.
         """

Lib/test/test_importlib/resources/_path.py

@@ -1,6 +1,6 @@
 import functools
 import pathlib
-from typing import Dict, Protocol, Union, runtime_checkable
+from typing import Protocol, Union, runtime_checkable
 
 ####
 # from jaraco.path 3.7.1
@@ -12,7 +12,7 @@ class Symlink(str):
     """
 
 
-FilesSpec = Dict[str, Union[str, bytes, Symlink, 'FilesSpec']]
+FilesSpec = dict[str, Union[str, bytes, Symlink, 'FilesSpec']]
 
 
 @runtime_checkable
@@ -28,13 +28,13 @@ def write_bytes(self, content): ...  # pragma: no cover
     def symlink_to(self, target): ...  # pragma: no cover
 
 
-def _ensure_tree_maker(obj: Union[str, TreeMaker]) -> TreeMaker:
+def _ensure_tree_maker(obj: str | TreeMaker) -> TreeMaker:
     return obj if isinstance(obj, TreeMaker) else pathlib.Path(obj)  # type: ignore[return-value]
 
 
 def build(
     spec: FilesSpec,
-    prefix: Union[str, TreeMaker] = pathlib.Path(),  # type: ignore[assignment]
+    prefix: str | TreeMaker = pathlib.Path(),  # type: ignore[assignment]
 ):
     """
     Build a set of files/directories, as described by the spec.
@@ -66,7 +66,7 @@ def build(
 
 
 @functools.singledispatch
-def create(content: Union[str, bytes, FilesSpec], path):
+def create(content: str | bytes | FilesSpec, path):
     path.mkdir(exist_ok=True)
     build(content, prefix=path)  # type: ignore[arg-type]
 

Lib/test/test_importlib/resources/test_compatibilty_files.py

@@ -24,51 +24,46 @@ def files(self):
         return resources.files(self.package)
 
     def test_spec_path_iter(self):
-        self.assertEqual(
-            sorted(path.name for path in self.files.iterdir()),
-            ['a', 'b', 'c'],
-        )
+        assert sorted(path.name for path in self.files.iterdir()) == ['a', 'b', 'c']
 
     def test_child_path_iter(self):
-        self.assertEqual(list((self.files / 'a').iterdir()), [])
+        assert list((self.files / 'a').iterdir()) == []
 
     def test_orphan_path_iter(self):
-        self.assertEqual(list((self.files / 'a' / 'a').iterdir()), [])
-        self.assertEqual(list((self.files / 'a' / 'a' / 'a').iterdir()), [])
+        assert list((self.files / 'a' / 'a').iterdir()) == []
+        assert list((self.files / 'a' / 'a' / 'a').iterdir()) == []
 
     def test_spec_path_is(self):
-        self.assertFalse(self.files.is_file())
-        self.assertFalse(self.files.is_dir())
+        assert not self.files.is_file()
+        assert not self.files.is_dir()
 
     def test_child_path_is(self):
-        self.assertTrue((self.files / 'a').is_file())
-        self.assertFalse((self.files / 'a').is_dir())
+        assert (self.files / 'a').is_file()
+        assert not (self.files / 'a').is_dir()
 
     def test_orphan_path_is(self):
-        self.assertFalse((self.files / 'a' / 'a').is_file())
-        self.assertFalse((self.files / 'a' / 'a').is_dir())
-        self.assertFalse((self.files / 'a' / 'a' / 'a').is_file())
-        self.assertFalse((self.files / 'a' / 'a' / 'a').is_dir())
+        assert not (self.files / 'a' / 'a').is_file()
+        assert not (self.files / 'a' / 'a').is_dir()
+        assert not (self.files / 'a' / 'a' / 'a').is_file()
+        assert not (self.files / 'a' / 'a' / 'a').is_dir()
 
     def test_spec_path_name(self):
-        self.assertEqual(self.files.name, 'testingpackage')
+        assert self.files.name == 'testingpackage'
 
     def test_child_path_name(self):
-        self.assertEqual((self.files / 'a').name, 'a')
+        assert (self.files / 'a').name == 'a'
 
     def test_orphan_path_name(self):
-        self.assertEqual((self.files / 'a' / 'b').name, 'b')
-        self.assertEqual((self.files / 'a' / 'b' / 'c').name, 'c')
+        assert (self.files / 'a' / 'b').name == 'b'
+        assert (self.files / 'a' / 'b' / 'c').name == 'c'
 
     def test_spec_path_open(self):
-        self.assertEqual(self.files.read_bytes(), b'Hello, world!')
-        self.assertEqual(self.files.read_text(encoding='utf-8'), 'Hello, world!')
+        assert self.files.read_bytes() == b'Hello, world!'
+        assert self.files.read_text(encoding='utf-8') == 'Hello, world!'
 
     def test_child_path_open(self):
-        self.assertEqual((self.files / 'a').read_bytes(), b'Hello, world!')
-        self.assertEqual(
-            (self.files / 'a').read_text(encoding='utf-8'), 'Hello, world!'
-        )
+        assert (self.files / 'a').read_bytes() == b'Hello, world!'
+        assert (self.files / 'a').read_text(encoding='utf-8') == 'Hello, world!'
 
     def test_orphan_path_open(self):
         with self.assertRaises(FileNotFoundError):
@@ -86,7 +81,7 @@ def test_orphan_path_invalid(self):
 
     def test_wrap_spec(self):
         spec = wrap_spec(self.package)
-        self.assertIsInstance(spec.loader.get_resource_reader(None), CompatibilityFiles)
+        assert isinstance(spec.loader.get_resource_reader(None), CompatibilityFiles)
 
 
 class CompatibilityFilesNoReaderTests(unittest.TestCase):
@@ -99,4 +94,4 @@ def files(self):
         return resources.files(self.package)
 
     def test_spec_path_joinpath(self):
-        self.assertIsInstance(self.files / 'a', CompatibilityFiles.OrphanPath)
+        assert isinstance(self.files / 'a', CompatibilityFiles.OrphanPath)

Lib/test/test_importlib/resources/test_files.py

@@ -37,7 +37,7 @@ def test_traversable(self):
     def test_joinpath_with_multiple_args(self):
         files = resources.files(self.data)
         binfile = files.joinpath('subdirectory', 'binary.file')
-        self.assertTrue(binfile.is_file())
+        assert binfile.is_file()
 
 
 class OpenDiskTests(FilesTests, util.DiskSetup, unittest.TestCase):