Add support for rendering a local copy of resources on the file system

CHANGES.rst

@@ -1,3 +1,10 @@
+v5.9.0
+======
+
+* #228: ``as_file`` now also supports a ``Traversable``
+  representing a directory and (when needed) renders the
+  full tree to a temporary directory.
+
 v5.8.1
 ======
 

importlib_resources/_common.py

@@ -93,13 +93,30 @@ def _tempfile(
             pass
 
 
+def _temp_file(path):
+    return _tempfile(path.read_bytes, suffix=path.name)
+
+
+def _is_present_dir(path: Traversable) -> bool:
+    """
+    Some Traversables implement ``is_dir()`` to raise an
+    exception (i.e. ``FileNotFoundError``) when the
+    directory doesn't exist. This function wraps that call
+    to always return a boolean and only return True
+    if there's a dir and it exists.
+    """
+    with contextlib.suppress(FileNotFoundError):
+        return path.is_dir()
+    return False
+
+
 @functools.singledispatch
 def as_file(path):
     """
     Given a Traversable object, return that object as a
     path on the local file system in a context manager.
     """
-    return _tempfile(path.read_bytes, suffix=path.name)
+    return _temp_dir(path) if _is_present_dir(path) else _temp_file(path)
 
 
 @as_file.register(pathlib.Path)
@@ -109,3 +126,34 @@ def _(path):
     Degenerate behavior for pathlib.Path objects.
     """
     yield path
+
+
+@contextlib.contextmanager
+def _temp_path(dir: tempfile.TemporaryDirectory):
+    """
+    Wrap tempfile.TemporyDirectory to return a pathlib object.
+    """
+    with dir as result:
+        yield pathlib.Path(result)
+
+
+@contextlib.contextmanager
+def _temp_dir(path):
+    """
+    Given a traversable dir, recursively replicate the whole tree
+    to the file system in a context manager.
+    """
+    assert path.is_dir()
+    with _temp_path(tempfile.TemporaryDirectory()) as temp_dir:
+        yield _write_contents(temp_dir, path)
+
+
+def _write_contents(target, source):
+    child = target.joinpath(source.name)
+    if source.is_dir():
+        child.mkdir()
+        for item in source.iterdir():
+            _write_contents(child, item)
+    else:
+        child.open('wb').write(source.read_bytes())
+    return child

importlib_resources/tests/test_resource.py

@@ -111,6 +111,14 @@ def test_submodule_contents_by_name(self):
             {'__init__.py', 'binary.file'},
         )
 
+    def test_as_file_directory(self):
+        with resources.as_file(resources.files('ziptestdata')) as data:
+            assert data.name == 'ziptestdata'
+            assert data.is_dir()
+            assert data.joinpath('subdirectory').is_dir()
+            assert len(list(data.iterdir()))
+        assert not data.parent.exists()
+
 
 class ResourceFromZipsTest02(util.ZipSetupBase, unittest.TestCase):
     ZIP_MODULE = zipdata02  # type: ignore