https://github.com/python/cpython/commit/d786d59a8f7196bb630100a869f28ad13436b59c commit: d786d59a8f7196bb630100a869f28ad13436b59c branch: 3.14 author: Miss Islington (bot) <[email protected]> committer: encukou <[email protected]> date: 2026-04-07T12:48:29+02:00 summary:
[3.14] gh-146121: Clarify security model of pkgutil.getdata (GH-148197) (GH-148206) (cherry picked from commit cf59bf76470f3d75ad47d80ffb8ce76b64b5e943) Co-authored-by: Petr Viktorin <[email protected]> Co-authored-by: Stan Ulbrych <[email protected]> files: M Doc/library/pkgutil.rst diff --git a/Doc/library/pkgutil.rst b/Doc/library/pkgutil.rst index 47d24b6f7d06bb..aa7dd71c1329df 100644 --- a/Doc/library/pkgutil.rst +++ b/Doc/library/pkgutil.rst @@ -151,24 +151,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) _______________________________________________ Python-checkins mailing list -- [email protected] To unsubscribe send an email to [email protected] https://mail.python.org/mailman3//lists/python-checkins.python.org Member address: [email protected]
