@@ -191,24 +191,48 @@ support.
191191 :meth: `get_data <importlib.abc.ResourceLoader.get_data> ` API. The
192192 *package * argument should be the name of a package, in standard module format
193193 (``foo.bar ``). The *resource * argument should be in the form of a relative
194- filename, using ``/ `` as the path separator. The parent directory name
195- ``.. `` is not allowed, and nor is a rooted name (starting with a ``/ ``).
194+ filename, using ``/ `` as the path separator.
196195
197196 The function returns a binary string that is the contents of the specified
198197 resource.
199198
199+ This function uses the :term: `loader ` method
200+ :func: `~importlib.abc.FileLoader.get_data `
201+ to support modules installed in the filesystem, but also in zip files,
202+ databases, or elsewhere.
203+
200204 For packages located in the filesystem, which have already been imported,
201205 this is the rough equivalent of::
202206
203207 d = os.path.dirname(sys.modules[package].__file__)
204208 data = open(os.path.join(d, resource), 'rb').read()
205209
210+ Like the :func: `open ` function, :func: `!get_data ` can follow parent
211+ directories (``../ ``) and absolute paths (starting with ``/ `` or ``C:/ ``,
212+ for example).
213+ It can open compilation/installation artifacts like ``.py `` and ``.pyc ``
214+ files or files with :func: `reserved filenames <os.path.isreserved> `.
215+ To be compatible with non-filesystem loaders, avoid using these features.
216+
217+ .. warning ::
218+
219+ This function is intended for trusted input.
220+ It does not verify that *resource * "belongs" to *package *.
221+
222+ If you use a user-provided *resource * path, consider verifying it.
223+ For example, require an alphanumeric filename with a known extension, or
224+ install and check a list of known resources.
225+
206226 If the package cannot be located or loaded, or it uses a :term: `loader `
207227 which does not support :meth: `get_data <importlib.abc.ResourceLoader.get_data> `,
208228 then ``None `` is returned. In particular, the :term: `loader ` for
209229 :term: `namespace packages <namespace package> ` does not support
210230 :meth: `get_data <importlib.abc.ResourceLoader.get_data> `.
211231
232+ .. seealso ::
233+
234+ The :mod: `importlib.resources ` module provides structured access to
235+ module resources.
212236
213237.. function :: resolve_name(name)
214238
0 commit comments