From 95e3e1d116ebfad4253297e36931fc9b25410d36 Mon Sep 17 00:00:00 2001 From: "Jason R. Coombs" Date: Thu, 29 Dec 2022 12:07:00 -0500 Subject: [PATCH] Update documentation to match the implementation with Anchor object being preferred and Package object being deprecated. --- Doc/library/importlib.resources.rst | 60 ++++++++++++++++++++--------- 1 file changed, 41 insertions(+), 19 deletions(-) diff --git a/Doc/library/importlib.resources.rst b/Doc/library/importlib.resources.rst index 399191301a36140..d697d44aca8b2a8 100644 --- a/Doc/library/importlib.resources.rst +++ b/Doc/library/importlib.resources.rst @@ -14,12 +14,13 @@ This module leverages Python's import system to provide access to *resources* within *packages*. "Resources" are file-like resources associated with a module or package in -Python. The resources may be contained directly in a package or within a -subdirectory contained in that package. Resources may be text or binary. As a -result, Python module sources (.py) of a package and compilation artifacts -(pycache) are technically de-facto resources of that package. In practice, -however, resources are primarily those non-Python artifacts exposed -specifically by the package author. +Python. The resources may be contained directly in a package, within a +subdirectory contained in that package, or adjacent to modules outside a +package. Resources may be text or binary. As a result, Python module sources +(.py) of a package and compilation artifacts (pycache) are technically +de-facto resources of that package. In practice, however, resources are +primarily those non-Python artifacts exposed specifically by the package +author. Resources can be opened or read in either binary or text mode. @@ -49,27 +50,34 @@ for example, a package and its resources can be imported from a zip file using ``get_resource_reader(fullname)`` method as specified by :class:`importlib.resources.abc.ResourceReader`. -.. data:: Package +.. data:: Anchor - Whenever a function accepts a ``Package`` argument, you can pass in - either a :class:`module object ` or a module name - as a string. You can only pass module objects whose - ``__spec__.submodule_search_locations`` is not ``None``. + Represents an anchor for resources, either a :class:`module object + ` or a module name as a string. Defined as + ``Union[str, ModuleType]``. - The ``Package`` type is defined as ``Union[str, ModuleType]``. - -.. function:: files(package) +.. function:: files(anchor: Optional[Anchor] = None) Returns a :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). + representing the resource container (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 - :data:`Package` requirements. + *anchor* is an optional :data:`Anchor`. If the anchor is a + package, resources are resolved from that package. If a module, + resources are resolved adjacent to that module (in the same package + or the package root). If the anchor is omitted, the caller's module + is used. .. versionadded:: 3.9 + .. versionchanged:: 3.12 + "package" parameter was renamed to "anchor". "anchor" can now + be a non-package module and if omitted will default to the caller's + module. "package" is still accepted for compatibility but will raise + a DeprecationWarning. Consider using ``importlib_resources >= 5.10`` + for a compatible interface on older Pythons. + .. function:: as_file(traversable) Given a :class:`~importlib.resources.abc.Traversable` object representing @@ -86,6 +94,7 @@ for example, a package and its resources can be imported from a zip file using .. versionadded:: 3.9 + Deprecated functions -------------------- @@ -94,6 +103,18 @@ scheduled for removal in a future version of Python. The main drawback of these functions is that they do not support directories: they assume all resources are located directly within a *package*. +.. data:: Package + + Whenever a function accepts a ``Package`` argument, you can pass in + either a :class:`module object ` or a module name + as a string. You can only pass module objects whose + ``__spec__.submodule_search_locations`` is not ``None``. + + The ``Package`` type is defined as ``Union[str, ModuleType]``. + + .. deprecated:: 3.12 + + .. data:: Resource For *resource* arguments of the functions below, you can pass in @@ -102,6 +123,7 @@ directories: they assume all resources are located directly within a *package*. The ``Resource`` type is defined as ``Union[str, os.PathLike]``. + .. function:: open_binary(package, resource) Open for binary reading the *resource* within *package*.