bpo-39791: Add files() to importlib.resources (GH-19722)
* bpo-39791: Update importlib.resources to support files() API (importlib_resources 1.5).
* 📜🤖 Added by blurb_it.
* Add some documentation about the new objects added.
Co-authored-by: blurb-it[bot] <43283697+blurb-it[bot]@users.noreply.github.com>
diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst
index a612b1e..99bfeac 100644
--- a/Doc/library/importlib.rst
+++ b/Doc/library/importlib.rst
@@ -480,6 +480,8 @@
.. class:: ResourceReader
+ *Superseded by TraversableReader*
+
An :term:`abstract base class` to provide the ability to read
*resources*.
@@ -795,6 +797,28 @@
itself does not end in ``__init__``.
+.. class:: Traversable
+
+ An object with a subset of pathlib.Path methods suitable for
+ traversing directories and opening files.
+
+ .. versionadded:: 3.9
+
+
+.. class:: TraversableReader
+
+ An abstract base class for resource readers capable of serving
+ the ``files`` interface. Subclasses ResourceReader and provides
+ concrete implementations of the ResourceReader's abstract
+ methods. Therefore, any loader supplying TraversableReader
+ also supplies ResourceReader.
+
+ Loaders that wish to support resource reading are expected to
+ implement this interface.
+
+ .. versionadded:: 3.9
+
+
:mod:`importlib.resources` -- Resources
---------------------------------------
@@ -853,6 +877,19 @@
The following functions are available.
+
+.. function:: files(package)
+
+ Returns an :class:`importlib.resources.abc.Traversable` object
+ representing the resource container for the package (think directory)
+ and its resources (think files). A Traversable may contain other
+ containers (think subdirectories).
+
+ *package* is either a name or a module object which conforms to the
+ ``Package`` requirements.
+
+ .. versionadded:: 3.9
+
.. function:: open_binary(package, resource)
Open for binary reading the *resource* within *package*.