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

Convert Traversable from abstract base class to a runtime-checkable protocol

See merge request python-devs/importlib_resources!97

Author: jaraco

docs/changelog.rst

@@ -4,6 +4,10 @@
 
 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

importlib_resources/_compat.py

@@ -47,6 +47,19 @@ class ABC(object):                                          # type: ignore
     from zipp import Path as ZipPath  # type: ignore
 
 
+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
+
+
 class PackageSpec(object):
 	def __init__(self, **kwargs):
 		vars(self).update(kwargs)

importlib_resources/abc.py

@@ -2,7 +2,7 @@
 
 import abc
 
-from ._compat import ABC, FileNotFoundError
+from ._compat import ABC, FileNotFoundError, runtime_checkable, Protocol
 
 # Use mypy's comment syntax for Python 2 compatibility
 try:
@@ -57,7 +57,8 @@ def contents(self):
         raise FileNotFoundError
 
 
-class Traversable(ABC):
+@runtime_checkable
+class Traversable(Protocol):
     """
     An object with a subset of pathlib.Path methods suitable for
     traversing directories and opening files.

importlib_resources/tests/test_files.py

@@ -1,6 +1,8 @@
+import typing
 import unittest
 
 import importlib_resources as resources
+from importlib_resources.abc import Traversable
 from . import data01
 from . import util
 
@@ -16,6 +18,13 @@ def test_read_text(self):
         actual = files.joinpath('utf-8.file').read_text()
         assert actual == 'Hello, UTF-8 world!\n'
 
+    @unittest.skipUnless(
+        hasattr(typing, 'runtime_checkable'),
+        "Only suitable when typing supports runtime_checkable",
+        )
+    def test_traversable(self):
+        assert isinstance(resources.files(self.data), Traversable)
+
 
 class OpenDiskTests(FilesTests, unittest.TestCase):
     def setUp(self):