Merge branch 'master' into feature/extensible-traversable

Author: jaraco

README.rst

@@ -2,10 +2,10 @@
  ``importlib_resources``
 =========================
 
-``importlib_resources`` is a backport of Python 3.7's standard library
+``importlib_resources`` is a backport of Python standard library
 `importlib.resources
-<https://docs.python.org/3.7/library/importlib.html#module-importlib.resources>`_
-module for Python 2.7, and 3.4 through 3.6.  Users of Python 3.7 and beyond
+<https://docs.python.org/3.9/library/importlib.html#module-importlib.resources>`_
+module for Python 2.7, and 3.4 through 3.8.  Users of Python 3.9 and beyond
 should use the standard library module, since for these versions,
 ``importlib_resources`` just delegates to that module.
 

importlib_resources/__init__.py

@@ -3,12 +3,14 @@
 import sys
 
 from ._compat import metadata
+from .trees import as_file
 
 
 __all__ = [
     'Package',
     'Resource',
     'ResourceReader',
+    'as_file',
     'contents',
     'files',
     'is_resource',

importlib_resources/_py3.py

@@ -10,10 +10,11 @@
 from pathlib import Path
 from types import ModuleType
 from typing import Iterable, Iterator, Optional, Set, Union   # noqa: F401
-from typing import ContextManager
 from typing import cast
 from typing.io import BinaryIO, TextIO
 
+if False:  # TYPE_CHECKING
+    from typing import ContextManager
 
 Package = Union[ModuleType, str]
 if sys.version_info >= (3, 6):
@@ -131,7 +132,7 @@ def read_text(package: Package,
         return fp.read()
 
 
-def files(package: Package) -> trees.Traversable:
+def files(package: Package) -> resources_abc.Traversable:
     """
     Get a Traversable resource from a package
     """
@@ -140,7 +141,7 @@ def files(package: Package) -> trees.Traversable:
 
 def path(
         package: Package, resource: Resource,
-        ) -> ContextManager[Path]:
+        ) -> 'ContextManager[Path]':
     """A context manager providing a file path object to the resource.
 
     If the resource does not already exist on its own on the file system,

importlib_resources/abc.py

@@ -1,7 +1,8 @@
 from __future__ import absolute_import
 
+import abc
+
 from ._compat import ABC, FileNotFoundError
-from abc import abstractmethod
 
 # We use mypy's comment syntax here since this file must be compatible with
 # both Python 2 and 3.
@@ -15,7 +16,7 @@
 class ResourceReader(ABC):
     """Abstract base class for loaders to provide resource reading support."""
 
-    @abstractmethod
+    @abc.abstractmethod
     def open_resource(self, resource):
         # type: (Text) -> BinaryIO
         """Return an opened, file-like object for binary reading.
@@ -28,7 +29,7 @@ def open_resource(self, resource):
         # it'll still do the right thing.
         raise FileNotFoundError
 
-    @abstractmethod
+    @abc.abstractmethod
     def resource_path(self, resource):
         # type: (Text) -> Text
         """Return the file system path to the specified resource.
@@ -42,7 +43,7 @@ def resource_path(self, resource):
         # it'll still do the right thing.
         raise FileNotFoundError
 
-    @abstractmethod
+    @abc.abstractmethod
     def is_resource(self, path):
         # type: (Text) -> bool
         """Return True if the named 'path' is a resource.
@@ -51,15 +52,74 @@ def is_resource(self, path):
         """
         raise FileNotFoundError
 
-    @abstractmethod
+    @abc.abstractmethod
     def contents(self):
         # type: () -> Iterable[str]
         """Return an iterable of entries in `package`."""
         raise FileNotFoundError
 
 
+class Traversable(ABC):
+    """
+    An object with a subset of pathlib.Path methods suitable for
+    traversing directories and opening files.
+    """
+
+    @abc.abstractmethod
+    def iterdir(self):
+        """
+        Yield Traversable objects in self
+        """
+
+    @abc.abstractmethod
+    def read_bytes(self):
+        """
+        Read contents of self as bytes
+        """
+
+    @abc.abstractmethod
+    def read_text(self, encoding=None):
+        """
+        Read contents of self as bytes
+        """
+
+    @abc.abstractmethod
+    def is_dir(self):
+        """
+        Return True if self is a dir
+        """
+
+    @abc.abstractmethod
+    def is_file(self):
+        """
+        Return True if self is a file
+        """
+
+    @abc.abstractmethod
+    def joinpath(self, child):
+        """
+        Return Traversable child in self
+        """
+
+    @abc.abstractmethod
+    def __truediv__(self, child):
+        """
+        Return Traversable child in self
+        """
+
+    @abc.abstractmethod
+    def open(self, mode='r', *args, **kwargs):
+        """
+        mode may be 'r' or 'rb' to open as text or binary. Return a handle
+        suitable for reading (same as pathlib.Path.open).
+
+        When opening as text, accepts encoding parameters such as those
+        accepted by io.TextIOWrapper.
+        """
+
+
 class TraversableResources(ResourceReader):
-    @abstractmethod
+    @abc.abstractmethod
     def files(self):
         """Return a Traversable object for the loaded package."""
 

importlib_resources/docs/changelog.rst

@@ -2,7 +2,7 @@
  importlib_resources NEWS
 ==========================
 
-v1.2.0
+v1.3.0
 ======
 * Add extensibility support for non-standard loaders to supply
   ``Traversable`` resources. Introduces a new abstract base
@@ -12,6 +12,13 @@ v1.2.0
   ``TraversableResources.files`` method will be capable of
   supplying resources with subdirectory support. Closes #77.
 
+v1.2.0
+======
+* Traversable now requires an ``open`` method. Closes #81.
+* Fixed error on ``Python 3.5.{0,3}``. Closes #83.
+* Updated packaging to resolve version from package metadata.
+  Closes #82.
+
 v1.1.0
 ======
 * Add support for retrieving resources from subdirectories of packages

importlib_resources/docs/using.rst

@@ -132,8 +132,7 @@ to this temporary file as a :py:class:`pathlib.Path` object.  In order to
 properly clean up this temporary file, what's actually returned is a context
 manager that you can use in a ``with``-statement::
 
-    from importlib_resources import files
-    from importlib_resources.trees import as_file
+    from importlib_resources import files, as_file
 
     source = files(email.tests.data).joinpath('message.eml')
     with as_file(source) as eml:

importlib_resources/trees.py

@@ -1,65 +1,15 @@
 from __future__ import absolute_import
 
 import os
-import abc
 import tempfile
 import contextlib
 
 from ._compat import (
-    ABC, Path, package_spec, FileNotFoundError, ZipPath,
+    Path, package_spec, FileNotFoundError, ZipPath,
     singledispatch,
     )
 
 
-class Traversable(ABC):
-    """
-    An object with a subset of pathlib.Path methods suitable for
-    traversing directories and opening files.
-    """
-
-    @abc.abstractmethod
-    def iterdir(self):
-        """
-        Yield Traversable objects in self
-        """
-
-    @abc.abstractmethod
-    def read_bytes(self):
-        """
-        Read contents of self as bytes
-        """
-
-    @abc.abstractmethod
-    def read_text(self, encoding=None):
-        """
-        Read contents of self as bytes
-        """
-
-    @abc.abstractmethod
-    def is_dir(self):
-        """
-        Return True if self is a dir
-        """
-
-    @abc.abstractmethod
-    def is_file(self):
-        """
-        Return True if self is a file
-        """
-
-    @abc.abstractmethod
-    def joinpath(self, child):
-        """
-        Return Traversable child in self
-        """
-
-    @abc.abstractmethod
-    def __truediv__(self, child):
-        """
-        Return Traversable child in self
-        """
-
-
 def from_package(package):
     """
     Return a Traversable object for the given package.

tox.ini

@@ -40,6 +40,7 @@ commands =
 deps =
     mypy
     flake8
+    flake8-typing-imports
 
 
 [testenv:docs]