Merge branch 'feature/extensible-traversable' into 'master'

jaraco · jaraco · commit 81e7f72a4d5f · 2020-03-06T18:13:36.000Z
Extensibility support for traversable objects Closes python#77 See merge request python-devs/importlib_resources!85
diff --git a/importlib_resources/_compat.py b/importlib_resources/_compat.py
@@ -8,6 +8,12 @@
     from pathlib2 import Path, PurePath                         # type: ignore
 
 
+try:
+    from contextlib import suppress
+except ImportError:
+    from contextlib2 import suppress                         # type: ignore
+
+
 try:
     from functools import singledispatch
 except ImportError:
diff --git a/importlib_resources/abc.py b/importlib_resources/abc.py
@@ -116,3 +116,21 @@ def open(self, mode='r', *args, **kwargs):
         When opening as text, accepts encoding parameters such as those
         accepted by io.TextIOWrapper.
         """
+
+
+class TraversableResources(ResourceReader):
+    @abc.abstractmethod
+    def files(self):
+        """Return a Traversable object for the loaded package."""
+
+    def open_resource(self, resource):
+        return self.files().joinpath(resource).open('rb')
+
+    def resource_path(self, resource):
+        raise FileNotFoundError(resource)
+
+    def is_resource(self, path):
+        return self.files().joinpath(path).isfile()
+
+    def contents(self):
+        return (item.name for item in self.files().iterdir())
diff --git a/importlib_resources/docs/changelog.rst b/importlib_resources/docs/changelog.rst
@@ -4,6 +4,13 @@
 
 v1.3.0
 ======
+* Add extensibility support for non-standard loaders to supply
+  ``Traversable`` resources. Introduces a new abstract base
+  class ``abc.TraversableResources`` that supersedes (but
+  implements for compatibility) ``abc.ResourceReader``. Any
+  loader that implements (implicitly or explicitly) the
+  ``TraversableResources.files`` method will be capable of
+  supplying resources with subdirectory support. Closes #77.
 * Preferred way to access ``as_file`` is now from top-level module.
   ``importlib_resources.trees.as_file`` is deprecated and discouraged.
   Closes #86.
diff --git a/importlib_resources/docs/index.rst b/importlib_resources/docs/index.rst
@@ -9,8 +9,8 @@ problems of ``pkg_resources``.
 
 In our terminology, a *resource* is a file tree that is located within an
 importable `Python package`_.  Resources can live on the file system or in a
-zip file, with limited support for loader_ supporting the appropriate API for
-reading resources.
+zip file, with support for other loader_ classes that implement the appropriate
+API for reading resources.
 
 ``importlib_resources`` is a backport of Python 3.9's standard library
 `importlib.resources`_ module for Python 2.7, and 3.5 through 3.8.  Users of
diff --git a/importlib_resources/docs/using.rst b/importlib_resources/docs/using.rst
@@ -55,29 +55,6 @@ the ``data.one`` package, and
 ``data`` package.
 
 
-Caveats
-=======
-
-Subdirectory Access
--------------------
-
-Prior to importlib_resources 1.1 and the ``files()`` API, resources that were
-not direct descendents of a package's folder were inaccessible through the
-API, so in the example above ``resources1/resource1.1`` is not a resource of
-the ``data.one`` package and ``two/resource2.txt`` is not a resource of the
-``data`` package. Therefore, if subdirectory access is required, use the
-``files()`` API.
-
-Resource Reader Support
------------------------
-
-Due to the limitations on resource readers to access files beyond direct
-descendents of a package, the ``files()`` API does not rely
-on the importlib ResourceReader interface and thus only supports resources
-exposed by the built-in path and zipfile loaders. If support for arbitrary
-resource readers is required, the other API functions still support loading
-those resources.
-
 Example
 =======
 
@@ -186,6 +163,16 @@ manager.
 Both relative and absolute paths work for Python 3.7 and newer.
 
 
+Extending
+=========
+
+Starting with Python 3.9 and ``importlib_resources`` 1.3, this package
+provides an interface for non-standard loaders, such as those used by
+executable bundlers, to supply resources. These loaders should subclass
+from the ``TraversableResources`` abstract class and implement the
+``files()`` method to return a ``Traversable`` object.
+
+
 .. rubric:: Footnotes
 
 .. [#fn1] We're ignoring `PEP 420
diff --git a/importlib_resources/trees.py b/importlib_resources/trees.py
@@ -6,13 +6,29 @@
 
 from ._compat import (
     Path, package_spec, FileNotFoundError, ZipPath,
-    singledispatch,
+    singledispatch, suppress,
     )
 
 
 def from_package(package):
-    """Return a Traversable object for the given package"""
+    """
+    Return a Traversable object for the given package.
+
+    """
     spec = package_spec(package)
+    return from_traversable_resources(spec) or fallback_resources(spec)
+
+
+def from_traversable_resources(spec):
+    """
+    If the spec.loader implements TraversableResources,
+    directly or implicitly, it will have a ``files()`` method.
+    """
+    with suppress(AttributeError):
+        return spec.loader.files()
+
+
+def fallback_resources(spec):
     package_directory = Path(spec.origin).parent
     try:
         archive_path = spec.loader.archive
@@ -44,7 +60,7 @@ def _tempfile(reader):
 @contextlib.contextmanager
 def as_file(path):
     """
-    Given a path-like object, return that object as a
+    Given a Traversable object, return that object as a
     path on the local file system in a context manager.
     """
     with _tempfile(path.read_bytes) as local:
@@ -55,6 +71,6 @@ def as_file(path):
 @contextlib.contextmanager
 def _(path):
     """
-    Degenerate behavior for pathlib.Path objects
+    Degenerate behavior for pathlib.Path objects.
     """
     yield path
diff --git a/setup.cfg b/setup.cfg
@@ -22,6 +22,7 @@ install_requires =
     zipp >= 0.4; python_version < '3.8'
     singledispatch; python_version < '3.4'
     importlib_metadata; python_version < '3.8'
+    contextlib2; python_version < '3'
 setup_requires = setuptools_scm[toml] >= 3.4.1
 packages = find:
 
