gh-116608: Bring back importlib.resources functional API

python · encukou · Apr 5, 2024 · Mar 7, 2024 · Mar 11, 2024 · Mar 11, 2024
commit bdc32099d08a95bed214b1c2f7505832dcc6a27f
@@ -97,3 +97,164 @@ for example, a package and its resources can be imported from a zip file using
 
     .. versionchanged:: 3.12
        Added support for *traversable* representing a directory.
+
+
+.. _importlib_resources_functional:
+
+Functional API
+^^^^^^^^^^^^^^
+
+A set of simplified, backwards-compatible helpers is available.
+These allow common operations in a single function call.
+
+For all the following functions:
+
+- *anchor* is an :class:`~importlib.resources.Anchor`,
+  as in :func:`~importlib.resources.files`.
+  Unlike in ``files``, it may not be omitted.
+
+- *path_names* are components of a resource's path name, relative to
+  the anchor.
+  The individual components may not contain path separators.
+  For example, to get the text of resource named ``info.txt``, use::
+
+      importlib.resources.read_text(my_module, "info.txt")
+
+  To get the text of ``info/chapter1.txt``, use::
+
+      importlib.resources.read_text(my_module, "info", "chapter1.txt")
+
+
+.. function:: open_binary(anchor, *path_names)
+
+    Open the named resource for binary reading.
+
+    See :ref:`the introduction <importlib_resources_functional>` for
+    details on *anchor* and *path_names*.
+
+    This function returns a :class:`~typing.BinaryIO` object,
+    that is, a binary stream open for reading.
+
+    For a single path name *name*, this function is roughly equivalent to::
+
+        files(anchor).joinpath(name).open('rb')
+
+    .. versionchanged:: 3.13
+        Multiple *path_names* are accepted.
+
+
+.. function:: open_text(anchor, *path_names, encoding='utf-8', errors='strict')
+
+    Open the named resource for text reading.
+    By default, the contents are read as strict UTF-8.
+
+    See :ref:`the introduction <importlib_resources_functional>` for
+    details on *anchor* and *path_names*.
+    *encoding* and *errors* have the same meaning as in built-in :func:`open`.
+
+    This function returns a :class:`~typing.TextIO` object,
+    that is, a text stream open for reading.
+
+    For a single path name *name*, this function is roughly equivalent to::
+
+          files(anchor).joinpath(name).open('r', encoding=encoding)
+
+    .. versionchanged:: 3.13
+        Multiple *path_names* are accepted.
+        *encoding* and *errors* must be given as keyword arguments.
+
+
+.. function:: read_binary(anchor, *path_names)
+
+    Read and return the contents of the named resource as :class:`bytes`.
+
+    See :ref:`the introduction <importlib_resources_functional>` for
+    details on *anchor* and *path_names*.
+
+    For a single path name *name*, this function is roughly equivalent to::
+
+          files(anchor).joinpath(name).read_bytes()
+
+    .. versionchanged:: 3.13
+        Multiple *path_names* are accepted.
+
+
+.. function:: read_text(anchor, *path_names, encoding='utf-8', errors='strict')
+
+    Read and return the contents of the named resource as :class:`str`.
+    By default, the contents are read as strict UTF-8.
+
+    See :ref:`the introduction <importlib_resources_functional>` for
+    details on *anchor* and *path_names*.
+    *encoding* and *errors* have the same meaning as in built-in :func:`open`.
+
+    For a single path name *name*, this function is roughly equivalent to::
+
+          files(anchor).joinpath(name).read_text(encoding=encoding)
+
+    .. versionchanged:: 3.13
+        Multiple *path_names* are accepted.
+        *encoding* and *errors* must be given as keyword arguments.
+
+
+.. function:: path(anchor, *path_names)
+
+    Provides the path to the *resource* as an actual file system path.  This
+    function returns a context manager for use in a :keyword:`with` statement.
+    The context manager provides a :class:`pathlib.Path` object.
+
+    Exiting the context manager cleans up any temporary files created, e.g.
+    when the resource needs to be extracted from a zip file.
+
+    For example, the :meth:`~pathlib.Path.stat` method requires
+    an actual file system path; it can be used like this::
+
+        with importlib.resources.path(anchor, "resource.txt") as fspath:
+            result = fspath.stat()
+
+    See :ref:`the introduction <importlib_resources_functional>` for
+    details on *anchor* and *path_names*.
+
+    For a single path name *name*, this function is roughly equivalent to::
+
+          as_file(files(anchor).joinpath(name))
+
+    .. versionchanged:: 3.13
+        Multiple *path_names* are accepted.
+        *encoding* and *errors* must be given as keyword arguments.
+
+
+.. function:: is_resource(anchor, *path_names)
+
+    Return ``True`` if the named resource exists, otherwise ``False``.
+    This function does not consider directories to be resources.
+
+    See :ref:`the introduction <importlib_resources_functional>` for
+    details on *anchor* and *path_names*.
+
+    For a single path name *name*, this function is roughly equivalent to::
+
+          files(anchor).joinpath(name).is_file()
+
+    .. versionchanged:: 3.13
+        Multiple *path_names* are accepted.
+
+
+.. function:: contents(anchor, *path_names)
+
+    Return an iterable over the named items within the package or path.
+    The iterable returns names of resources (e.g. files) and non-resources
+    (e.g. directories) as :class:`str`.
+    The iterable does not recurse into subdirectories.
+
+    See :ref:`the introduction <importlib_resources_functional>` for
+    details on *anchor* and *path_names*.
+
+    For a single path name *name*, this function is roughly equivalent to::
+
+        for resource in files(anchor).joinpath(name).iterdir():
+            yield resource.name
+
+    .. deprecated:: 3.11
+        Prefer ``iterdir()`` as above, which offers more control over the
+        results and richer functionality.
diff --git a/Doc/whatsnew/3.13.rst b/Doc/whatsnew/3.13.rst
@@ -361,6 +361,30 @@ and only logged in :ref:`Python Development Mode <devmode>` or on :ref:`Python
 built on debug mode <debug-build>`.
 (Contributed by Victor Stinner in :gh:`62948`.)
 
+importlib
+---------
+
+Previously deprecated :mod:`importlib.resources` functions are un-deprecated:
+
+  * :func:`~importlib.resources.is_resource()`
+  * :func:`~importlib.resources.open_binary()`
+  * :func:`~importlib.resources.open_text()`
+  * :func:`~importlib.resources.path()`
+  * :func:`~importlib.resources.read_binary()`
+  * :func:`~importlib.resources.read_text()`
+
+All now allow for a directory (or tree) of resources, using multiple positional
+arguments.
+
+For text-reading functions, the *encoding* and *errors* must now be given as
+keyword arguments.
+
+The :func:`~importlib.resources.contents()` remains deprecated in favor of
+the full-featured :class:`~importlib.resources.Traversable` API.
+However, there is now no plan to remove it.
+
+(Contributed by Petr Viktorin in :gh:`106532`.)
+
 ipaddress
 ---------
 
@@ -1263,21 +1287,6 @@ configparser
 importlib
 ---------
 
-* Remove :mod:`importlib.resources` deprecated methods:
-
-  * ``contents()``
-  * ``is_resource()``
-  * ``open_binary()``
-  * ``open_text()``
-  * ``path()``
-  * ``read_binary()``
-  * ``read_text()``
-
-  Use :func:`importlib.resources.files()` instead.  Refer to `importlib-resources: Migrating from Legacy
-  <https://importlib-resources.readthedocs.io/en/latest/using.html#migrating-from-legacy>`_
-  for migration advice.
-  (Contributed by Jason R. Coombs in :gh:`106532`.)
-
 * Remove deprecated :meth:`~object.__getitem__` access for
   :class:`!importlib.metadata.EntryPoint` objects.
   (Contributed by Jason R. Coombs in :gh:`113175`.)

@@ -7,6 +7,16 @@
     Anchor,
 )
 
+from .functional import (
+    contents,
+    is_resource,
+    open_binary,
+    open_text,
+    path,
+    read_binary,
+    read_text,
+)
+
 from .abc import ResourceReader
 
 
@@ -16,4 +26,11 @@
     'ResourceReader',
     'as_file',
     'files',
+    'contents',
+    'is_resource',
+    'open_binary',
+    'open_text',
+    'path',
+    'read_binary',
+    'read_text',
 ]
diff --git a/Lib/importlib/resources/functional.py b/Lib/importlib/resources/functional.py
@@ -0,0 +1,78 @@
+"""Simplified function-based API for importlib.resources
+
+
+"""
+
+import os
+import warnings
+
+from ._common import files, as_file
+
+
+def open_binary(anchor, *path_names):
+    """Open for binary reading the *resource* within *package*."""
+    return _get_resource(anchor, path_names).open('rb')
+
+
+def open_text(anchor, *path_names, encoding='utf-8', errors='strict'):
+    """Open for text reading the *resource* within *package*."""
+    resource = _get_resource(anchor, path_names)
+    return resource.open('r', encoding=encoding, errors=errors)
+
+
+def read_binary(anchor, *path_names):
+    """Read and return contents of *resource* within *package* as bytes."""
+    return _get_resource(anchor, path_names).read_bytes()
+
+
+def read_text(anchor, *path_names, encoding='utf-8', errors='strict'):
+    """Read and return contents of *resource* within *package* as str."""
+    resource = _get_resource(anchor, path_names)
+    return resource.read_text(encoding=encoding, errors=errors)
+
+
+def path(anchor, *path_names):
+    """Return the path to the *resource* as an actual file system path."""
+    return as_file(_get_resource(anchor, path_names))
+
+
+def is_resource(anchor, *path_names):
+    """Return ``True`` if there is a resource named *name* in the package,
+
+    Otherwise returns ``False``.
+    """
+    return _get_resource(anchor, path_names).is_file()
+
+
+def contents(anchor, *path_names):
+    """Return an iterable over the named resources within the package.
+
+    The iterable returns :class:`str` resources (e.g. files).
+    The iterable does not recurse into subdirectories.
+    """
+    warnings.warn(
+        "importlib.resources.contents is deprecated. "
+        "Use files(anchor).iterdir() instead.",
+        DeprecationWarning,
+        stacklevel=1,
+    )
+    return (
+        resource.name
+        for resource
+        in _get_resource(anchor, path_names).iterdir()
+    )
+
+
+def _get_resource(anchor, path_names):
+    if anchor is None:
+        raise TypeError("anchor must be module or string, got None")
+    traversable = files(anchor)
+    for name in path_names:
+        str_path = str(name)
+        parent, file_name = os.path.split(str_path)
+        if parent:
+            raise ValueError(
+                'path name elements must not contain path separators, '
+                f'got {name!r}')
+        traversable = traversable.joinpath(file_name)
+    return traversable