[3.13] gh-146121: Clarify security model of pkgutil.getdata; revert checks (GH-148197...

gh-146121: Clarify security model of pkgutil.getdata; revert checks (GH-148197)

This reverts commit bcdf231946b1da8bdfbab4c05539bb0cc964a1c7,
and clarifies get_data's security model.

(cherry picked from commit cf59bf76470f3d75ad47d80ffb8ce76b64b5e943)

Co-authored-by: Petr Viktorin <encukou@gmail.com>
Co-authored-by: Stan Ulbrych <stan@python.org>

diff --git a/Doc/library/pkgutil.rst b/Doc/library/pkgutil.rst
index b17a317244da9e65e97a6d417cdec64d03af60f5..c791ad5de26d631e9e644c7329e242f10fa4f56a 100644 (file)
--- a/Doc/library/pkgutil.rst
+++ b/Doc/library/pkgutil.rst
@@ -191,24 +191,48 @@ support.
    :meth:`get_data <importlib.abc.ResourceLoader.get_data>` API.  The
    *package* argument should be the name of a package, in standard module format
    (``foo.bar``).  The *resource* argument should be in the form of a relative
-   filename, using ``/`` as the path separator.  The parent directory name
-   ``..`` is not allowed, and nor is a rooted name (starting with a ``/``).
+   filename, using ``/`` as the path separator.
 
    The function returns a binary string that is the contents of the specified
    resource.
 
+   This function uses the :term:`loader` method
+   :func:`~importlib.abc.FileLoader.get_data`
+   to support modules installed in the filesystem, but also in zip files,
+   databases, or elsewhere.
+
    For packages located in the filesystem, which have already been imported,
    this is the rough equivalent of::
 
       d = os.path.dirname(sys.modules[package].__file__)
       data = open(os.path.join(d, resource), 'rb').read()
 
+   Like the :func:`open` function, :func:`!get_data` can follow parent
+   directories (``../``) and absolute paths (starting with ``/`` or ``C:/``,
+   for example).
+   It can open compilation/installation artifacts like ``.py`` and ``.pyc``
+   files or files with :func:`reserved filenames <os.path.isreserved>`.
+   To be compatible with non-filesystem loaders, avoid using these features.
+
+   .. warning::
+
+      This function is intended for trusted input.
+      It does not verify that *resource* "belongs" to *package*.
+
+   If you use a user-provided *resource* path, consider verifying it.
+   For example, require an alphanumeric filename with a known extension, or
+   install and check a list of known resources.
+
    If the package cannot be located or loaded, or it uses a :term:`loader`
    which does not support :meth:`get_data <importlib.abc.ResourceLoader.get_data>`,
    then ``None`` is returned.  In particular, the :term:`loader` for
    :term:`namespace packages <namespace package>` does not support
    :meth:`get_data <importlib.abc.ResourceLoader.get_data>`.
 
+   .. seealso::
+
+      The :mod:`importlib.resources` module provides structured access to
+      module resources.
 
 .. function:: resolve_name(name)