Merge branch 'stdlib-sync' into 'master'

Sync with stdlib changes in GH#4911

See merge request python-devs/importlib_resources!52

Author: warsaw

.gitlab-ci.yml

@@ -10,18 +10,18 @@ qa:
 
 tests:
   script:
-    - tox -e py27-nocov,py34-nocov,py35-nocov,py36-nocov,py37-nocov
+    - tox -e py27-nocov,py34-nocov,py35-nocov,py36-nocov
 
 coverage:
   script:
-    - tox -e py27-cov,py34-cov,py35-cov,py36-cov,py37-cov
+    - tox -e py27-cov,py34-cov,py35-cov,py36-cov
   artifacts:
     paths:
       - coverage.xml
 
 diffcov:
   script:
-    - tox -e py27-diffcov,py34-diffcov,py35-diffcov,py36-diffcov,py37-diffcov
+    - tox -e py27-diffcov,py34-diffcov,py35-diffcov,py36-diffcov
 
 docs:
   script:

.travis.yml

@@ -1,16 +1,19 @@
 =========================
- ``importlib.resources``
+ ``importlib_resources``
 =========================
 
-This repository is to house the design and implementation of a planned
-``importlib.resources`` module for Python's stdlib -- aiming for Python 3.7 --
-along with a backport to target Python 2.7, and 3.4 - 3.6.
+``importlib_resources`` is a backport of Python 3.7's 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
+should use the standard library module, since for these versions,
+``importlib_resources`` just delegates to that module.
 
 The key goal of this module is to replace parts of `pkg_resources
 <https://setuptools.readthedocs.io/en/latest/pkg_resources.html>`_ with a
-solution in Python's stdlib that relies on well-defined APIs.  This should not
-only make reading resources included in packages easier, but have the
-semantics be stable and consistent.
+solution in Python's stdlib that relies on well-defined APIs.  This makes
+reading resources included in packages easier, with more stable and consistent
+semantics.
 
 
 Project details

README.rst

@@ -18,7 +18,6 @@ exclude_lines =
     pragma: nocover
     raise NotImplementedError
     raise AssertionError
-    pragma: FIXME
     assert\s
 
 [paths]

coverage.ini

@@ -2,10 +2,15 @@
 
 import sys
 
-__version__ = '0.2'
+__version__ = '0.3'
 
 
-if sys.version_info >= (3,):
+# Use the Python 3.7 stdlib implementation if available.
+if sys.version_info >= (3, 7):
+    from importlib.resources import (
+        Package, Resource, contents, is_resource, open_binary, open_text, path,
+        read_binary, read_text)
+elif sys.version_info >= (3,):
     from importlib_resources._py3 import (
         Package, Resource, contents, is_resource, open_binary, open_text, path,
         read_binary, read_text)

importlib_resources/__init__.py

@@ -11,8 +11,10 @@
 
 
 def _get_package(package):
-    # `package` will be a string or a module.  Always return a module which is
-    # a package, otherwise raise an exception.
+    """Normalize a path by ensuring it is a string.
+
+    If the resulting string contains path separators, an exception is raised.
+    """
     if isinstance(package, basestring):                      # noqa: F821
         module = import_module(package)
     else:
@@ -23,8 +25,10 @@ def _get_package(package):
 
 
 def _normalize_path(path):
-    # Ensure that the incoming `path`, which may be a string or a Path object,
-    # is a bare file name with no hierarchy.
+    """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:

importlib_resources/_py2.py

@@ -24,6 +24,11 @@
 
 
 def _get_package(package) -> ModuleType:
+    """Take a package name or module object and return the module.
+
+    If a name, the module is imported.  If the passed or imported module
+    object is not a package, raise an exception.
+    """
     if hasattr(package, '__spec__'):
         if package.__spec__.submodule_search_locations is None:
             raise TypeError('{!r} is not a package'.format(
@@ -39,6 +44,10 @@ def _get_package(package) -> ModuleType:
 
 
 def _normalize_path(path) -> str:
+    """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:
@@ -54,9 +63,11 @@ def _get_resource_reader(
     # 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.
-    if hasattr(package.__spec__.loader, 'open_resource'):
-        return cast(resources_abc.ResourceReader, package.__spec__.loader)
-    return None
+    spec = package.__spec__
+    reader = getattr(spec.loader, 'get_resource_reader', None)
+    if reader is None:
+        return None
+    return cast(resources_abc.ResourceReader, reader(spec.name))
 
 
 def open_binary(package: Package, resource: Resource) -> BinaryIO:
@@ -73,14 +84,14 @@ def open_binary(package: Package, resource: Resource) -> BinaryIO:
     full_path = os.path.join(package_path, resource)
     try:
         return builtins_open(full_path, mode='rb')
-    except IOError:
+    except OSError:
         # Just assume the loader is a resource loader; all the relevant
         # importlib.machinery loaders are and an AttributeError for
         # get_data() will make it clear what is needed from the loader.
         loader = cast(ResourceLoader, package.__spec__.loader)
         data = None
         if hasattr(package.__spec__.loader, 'get_data'):
-            with suppress(IOError):
+            with suppress(OSError):
                 data = loader.get_data(full_path)
         if data is None:
             package_name = package.__spec__.name
@@ -109,14 +120,14 @@ def open_text(package: Package,
     try:
         return builtins_open(
             full_path, mode='r', encoding=encoding, errors=errors)
-    except IOError:
+    except OSError:
         # Just assume the loader is a resource loader; all the relevant
         # importlib.machinery loaders are and an AttributeError for
         # get_data() will make it clear what is needed from the loader.
         loader = cast(ResourceLoader, package.__spec__.loader)
         data = None
         if hasattr(package.__spec__.loader, 'get_data'):
-            with suppress(IOError):
+            with suppress(OSError):
                 data = loader.get_data(full_path)
         if data is None:
             package_name = package.__spec__.name
@@ -173,7 +184,7 @@ def path(package: Package, resource: Resource) -> Iterator[Path]:
     # resource_path() raises FileNotFoundError.
     package_directory = Path(package.__spec__.origin).parent
     file_path = package_directory / resource
-    if file_path.exists():                          # pragma: FIXME
+    if file_path.exists():
         yield file_path
     else:
         with open_binary(package, resource) as fp:
@@ -213,10 +224,10 @@ def is_resource(package: Package, name: str) -> bool:
     # contents doesn't necessarily mean it's a resource.  Directories are not
     # resources, so let's try to find out if it's a directory or not.
     path = Path(package.__spec__.origin).parent / name
-    if path.is_file():                              # pragma: FIXME
+    if path.is_file():
         return True
     if path.is_dir():
-        return False                                # pragma: FIXME
+        return False
     # If it's not a file and it's not a directory, what is it?  Well, this
     # means the file doesn't exist on the file system, so it probably lives
     # inside a zip file.  We have to crack open the zip, look at its table of