Merge branch 'master' into feature/multiplexer

Author: jaraco

.gitlab-ci.yml

@@ -15,14 +15,14 @@ tests:
 
 coverage:
   script:
-    - tox -e py27-cov,py35-cov,py36-cov
+    - tox -e py27-cov,py35-cov,py36-cov,py37-cov,py38-cov
   artifacts:
     paths:
       - coverage.xml
 
 diffcov:
   script:
-    - tox -e py27-diffcov,py35-diffcov,py36-diffcov
+    - tox -e py27-diffcov,py35-diffcov,py36-diffcov,py37-diffcov,py38-diffcov
 
 docs:
   script:

docs/changelog.rst

@@ -2,6 +2,14 @@
  importlib_resources NEWS
 ==========================
 
+v1.5.0
+======
+
+* Traversable is now a Protocol instead of an Abstract Base
+  Class (Python 2.7 and Python 3.8+).
+
+* Traversable objects now require a ``.name`` property.
+
 v1.4.0
 ======
 * #79: Temporary files created will now reflect the filename of

importlib_resources/__init__.py

@@ -3,7 +3,9 @@
 import sys
 
 from ._compat import metadata
-from ._common import as_file
+from ._common import (
+    as_file, files,
+    )
 
 # for compatibility. Ref #88
 __import__('importlib_resources.trees')
@@ -30,7 +32,6 @@
         Package,
         Resource,
         contents,
-        files,
         is_resource,
         open_binary,
         open_text,
@@ -42,7 +43,6 @@
 else:
     from importlib_resources._py2 import (
         contents,
-        files,
         is_resource,
         open_binary,
         open_text,

importlib_resources/_common.py

@@ -3,40 +3,85 @@
 import os
 import tempfile
 import contextlib
+import types
+import importlib
 
 from ._compat import (
-    Path, package_spec, FileNotFoundError, ZipPath,
-    singledispatch, suppress,
+    Path, FileNotFoundError,
+    singledispatch, package_spec,
     )
 
+if False:  # TYPE_CHECKING
+    from typing import Union, Any, Optional
+    from .abc import ResourceReader
+    Package = Union[types.ModuleType, str]
 
-def from_package(package):
+
+def files(package):
     """
-    Return a Traversable object for the given package.
+    Get a Traversable resource from a package
+    """
+    return from_package(get_package(package))
+
 
+def normalize_path(path):
+    # type: (Any) -> str
+    """Normalize a path by ensuring it is a string.
+
+    If the resulting string contains path separators, an exception is raised.
     """
-    spec = package_spec(package)
-    return from_traversable_resources(spec) or fallback_resources(spec)
+    str_path = str(path)
+    parent, file_name = os.path.split(str_path)
+    if parent:
+        raise ValueError('{!r} must be only a file name'.format(path))
+    return file_name
 
 
-def from_traversable_resources(spec):
+def get_resource_reader(package):
+    # type: (types.ModuleType) -> Optional[ResourceReader]
     """
-    If the spec.loader implements TraversableResources,
-    directly or implicitly, it will have a ``files()`` method.
+    Return the package's loader if it's a ResourceReader.
     """
-    with suppress(AttributeError):
-        return spec.loader.files()
+    # We can't use
+    # a issubclass() check here because apparently abc.'s __subclasscheck__()
+    # hook wants to create a weak reference to the object, but
+    # 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)
+    if reader is None:
+        return None
+    return reader(spec.name)
 
 
-def fallback_resources(spec):
-    package_directory = Path(spec.origin).parent
-    try:
-        archive_path = spec.loader.archive
-        rel_path = package_directory.relative_to(archive_path)
-        return ZipPath(archive_path, str(rel_path) + '/')
-    except Exception:
-        pass
-    return package_directory
+def resolve(cand):
+    # type: (Package) -> types.ModuleType
+    return (
+        cand if isinstance(cand, types.ModuleType)
+        else importlib.import_module(cand)
+        )
+
+
+def get_package(package):
+    # type: (Package) -> types.ModuleType
+    """Take a package name or module object and return the module.
+
+    Raise an exception if the resolved module is not a package.
+    """
+    resolved = resolve(package)
+    if package_spec(resolved).submodule_search_locations is None:
+        raise TypeError('{!r} is not a package'.format(package))
+    return resolved
+
+
+def from_package(package):
+    """
+    Return a Traversable object for the given package.
+
+    """
+    spec = package_spec(package)
+    reader = spec.loader.get_resource_reader(spec.name)
+    return reader.files()
 
 
 @contextlib.contextmanager

importlib_resources/_compat.py

@@ -47,14 +47,86 @@ class ABC(object):                                          # type: ignore
     from zipp import Path as ZipPath  # type: ignore
 
 
-class PackageSpec(object):
-	def __init__(self, **kwargs):
-		vars(self).update(kwargs)
+try:
+    from typing import runtime_checkable  # type: ignore
+except ImportError:
+    def runtime_checkable(cls):  # type: ignore
+        return cls
+
+
+try:
+    from typing import Protocol  # type: ignore
+except ImportError:
+    Protocol = ABC  # type: ignore
+
+
+__metaclass__ = type
+
+
+class PackageSpec:
+    def __init__(self, **kwargs):
+        vars(self).update(kwargs)
+
+
+class TraversableResourcesAdapter:
+    def __init__(self, spec):
+        self.spec = spec
+        self.loader = LoaderAdapter(spec)
+
+    def __getattr__(self, name):
+        return getattr(self.spec, name)
+
+
+class LoaderAdapter:
+    """
+    Adapt loaders to provide TraversableResources and other
+    compatibility.
+    """
+    def __init__(self, spec):
+        self.spec = spec
+
+    @property
+    def path(self):
+        # Python < 3
+        return self.spec.origin
+
+    def get_resource_reader(self, name):
+        # Python < 3.9
+        from . import readers
+
+        def _zip_reader(spec):
+            with suppress(AttributeError):
+                return readers.ZipReader(spec.loader, spec.name)
+
+        def _available_reader(spec):
+            with suppress(AttributeError):
+                return spec.loader.get_resource_reader(spec.name)
+
+        def _native_reader(spec):
+            reader = _available_reader(spec)
+            return reader if hasattr(reader, 'files') else None
+
+        return (
+            # native reader if it supplies 'files'
+            _native_reader(self.spec) or
+            # local ZipReader if a zip module
+            _zip_reader(self.spec) or
+            # local FileReader
+            readers.FileReader(self)
+            )
 
 
 def package_spec(package):
-	return getattr(package, '__spec__', None) or \
-		PackageSpec(
-			origin=package.__file__,
-			loader=getattr(package, '__loader__', None),
-		)
+    """
+    Construct a minimal package spec suitable for
+    matching the interfaces this library relies upon
+    in later Python versions.
+    """
+    spec = getattr(package, '__spec__', None) or \
+        PackageSpec(
+            origin=package.__file__,
+            loader=getattr(package, '__loader__', None),
+            name=package.__name__,
+            submodule_search_locations=getattr(package, '__path__', None),
+        )
+    return TraversableResourcesAdapter(spec)

importlib_resources/_py2.py

@@ -3,44 +3,13 @@
 
 from . import _common
 from ._compat import FileNotFoundError
-from importlib import import_module
 from io import BytesIO, TextIOWrapper, open as io_open
 
 
-def _resolve(name):
-    """If name is a string, resolve to a module."""
-    if not isinstance(name, basestring):                    # noqa: F821
-        return name
-    return import_module(name)
-
-
-def _get_package(package):
-    """Normalize a path by ensuring it is a string.
-
-    If the resulting string contains path separators, an exception is raised.
-    """
-    module = _resolve(package)
-    if not hasattr(module, '__path__'):
-        raise TypeError("{!r} is not a package".format(package))
-    return module
-
-
-def _normalize_path(path):
-    """Normalize a path by ensuring it is a string.
-
-    If the resulting string contains path separators, an exception is raised.
-    """
-    str_path = str(path)
-    parent, file_name = os.path.split(str_path)
-    if parent:
-        raise ValueError("{!r} must be only a file name".format(path))
-    return file_name
-
-
 def open_binary(package, resource):
     """Return a file-like object opened for binary reading of the resource."""
-    resource = _normalize_path(resource)
-    package = _get_package(package)
+    resource = _common.normalize_path(resource)
+    package = _common.get_package(package)
     # Using pathlib doesn't work well here due to the lack of 'strict' argument
     # for pathlib.Path.resolve() prior to Python 3.6.
     package_path = os.path.dirname(package.__file__)
@@ -89,10 +58,6 @@ def read_text(package, resource, encoding='utf-8', errors='strict'):
         return fp.read()
 
 
-def files(package):
-    return _common.from_package(_get_package(package))
-
-
 def path(package, resource):
     """A context manager providing a file path object to the resource.
 
@@ -102,7 +67,7 @@ def path(package, resource):
     raised if the file was deleted prior to the context manager
     exiting).
     """
-    path = files(package).joinpath(_normalize_path(resource))
+    path = _common.files(package).joinpath(_common.normalize_path(resource))
     if not path.is_file():
         raise FileNotFoundError(path)
     return _common.as_file(path)
@@ -113,8 +78,8 @@ def is_resource(package, name):
 
     Directories are *not* resources.
     """
-    package = _get_package(package)
-    _normalize_path(name)
+    package = _common.get_package(package)
+    _common.normalize_path(name)
     try:
         package_contents = set(contents(package))
     except OSError as error:
@@ -138,5 +103,5 @@ def contents(package):
     not considered resources.  Use `is_resource()` on each entry returned here
     to check if it is a resource or not.
     """
-    package = _get_package(package)
+    package = _common.get_package(package)
     return list(item.name for item in _common.from_package(package).iterdir())