Add _adapters module, making SpecLoaderAdapter a first-class feature and not a compatibility feature. Add DegenerateFiles for readers that don't implement the files API such that the rest of the API can rely on it being implemented. Fixes #214.

Author: jaraco

importlib_resources/_adapters.py

@@ -0,0 +1,90 @@
+from contextlib import suppress
+
+from . import abc
+
+
+class SpecLoaderAdapter:
+    """
+    Adapt a package spec to adapt the underlying loader.
+    """
+
+    def __init__(self, spec, adapter=lambda spec: spec.loader):
+        self.spec = spec
+        self.loader = adapter(spec)
+
+    def __getattr__(self, name):
+        return getattr(self.spec, name)
+
+
+class TraversableResourcesLoader:
+    """
+    Adapt a loader to provide TraversableResources.
+    """
+
+    def __init__(self, spec):
+        self.spec = spec
+
+    def get_resource_reader(self, name):
+        return DegenerateFiles(self.spec)._native()
+
+
+class DegenerateFiles:
+    """
+    Adapter for an existing or non-existant resource reader
+    to provide a degenerate .files().
+    """
+
+    class Path(abc.Traversable):
+        def iterdir(self):
+            return iter(())
+
+        def read_bytes(self):
+            raise ValueError()
+
+        def read_text(self):
+            raise ValueError()
+
+        def is_dir(self):
+            return False
+
+        is_file = exists = is_dir
+
+        def joinpath(self, other):
+            return DegenerateFiles.Path()
+
+        __truediv__ = joinpath
+
+        def name(self):
+            return ''
+
+        def open(self):
+            raise ValueError()
+
+    def __init__(self, spec):
+        self.spec = spec
+
+    @property
+    def _reader(self):
+        with suppress(AttributeError):
+            return self.spec.loader.get_resource_reader(self.spec.name)
+
+    def _native(self):
+        """
+        Return the native reader if it supports files().
+        """
+        reader = self._reader
+        return reader if hasattr(reader, 'files') else self
+
+    def __getattr__(self, attr):
+        return getattr(self._reader, attr)
+
+    def files(self):
+        return DegenerateFiles.Path()
+
+
+def wrap_spec(package):
+    """
+    Construct a package spec with traversable compatibility
+    on the spec/loader/reader.
+    """
+    return SpecLoaderAdapter(package.__spec__, TraversableResourcesLoader)

importlib_resources/_common.py

@@ -9,7 +9,7 @@
 from typing import Union, Any, Optional
 from .abc import ResourceReader
 
-from ._compat import package_spec
+from ._compat import wrap_spec
 
 Package = Union[types.ModuleType, str]
 
@@ -63,7 +63,7 @@ def get_package(package):
     Raise an exception if the resolved module is not a package.
     """
     resolved = resolve(package)
-    if package_spec(resolved).submodule_search_locations is None:
+    if wrap_spec(resolved).submodule_search_locations is None:
         raise TypeError('{!r} is not a package'.format(package))
     return resolved
 
@@ -73,7 +73,7 @@ def from_package(package):
     Return a Traversable object for the given package.
 
     """
-    spec = package_spec(package)
+    spec = wrap_spec(package)
     reader = spec.loader.get_resource_reader(spec.name)
     return reader.files()
 

importlib_resources/_compat.py

@@ -1,9 +1,10 @@
+# flake8: noqa
+
 import abc
 import sys
+import pathlib
 from contextlib import suppress
 
-# flake8: noqa
-
 try:
     from zipfile import Path as ZipPath  # type: ignore
 except ImportError:
@@ -24,19 +25,6 @@ def runtime_checkable(cls):  # type: ignore
     Protocol = abc.ABC  # type: ignore
 
 
-class SpecLoaderAdapter:
-    """
-    Adapt a package spec to adapt the underlying loader.
-    """
-
-    def __init__(self, spec, adapter=lambda spec: spec.loader):
-        self.spec = spec
-        self.loader = adapter(spec)
-
-    def __getattr__(self, name):
-        return getattr(self.spec, name)
-
-
 class TraversableResourcesLoader:
     """
     Adapt loaders to provide TraversableResources and other
@@ -52,7 +40,7 @@ def path(self):
 
     def get_resource_reader(self, name):
         # Python < 3.9
-        from . import readers
+        from . import readers, _adapters
 
         def _zip_reader(spec):
             with suppress(AttributeError):
@@ -70,6 +58,10 @@ def _native_reader(spec):
             reader = _available_reader(spec)
             return reader if hasattr(reader, 'files') else None
 
+        def _file_reader(spec):
+            if pathlib.Path(self.path).exists():
+                return readers.FileReader(self)
+
         return (
             # native reader if it supplies 'files'
             _native_reader(self.spec)
@@ -81,17 +73,16 @@ def _native_reader(spec):
             _namespace_reader(self.spec)
             or
             # local FileReader
-            readers.FileReader(self)
+            _file_reader(self.spec)
+            or _adapters.DegenerateFiles(self.spec)
         )
 
 
-def package_spec(package):
+def wrap_spec(package):
     """
-    Construct a minimal package spec suitable for
-    matching the interfaces this library relies upon
-    in later Python versions.
+    Construct a package spec with traversable compatibility
+    on the spec/loader/reader.
     """
-    spec = package.__spec__
-    # avoid adapting the spec in test_package_has_no_reader_fallback
-    adapt = spec.loader.__class__ is not object
-    return SpecLoaderAdapter(spec, TraversableResourcesLoader) if adapt else spec
+    from . import _adapters
+
+    return _adapters.SpecLoaderAdapter(package.__spec__, TraversableResourcesLoader)