Update documentation to match the implementation with Anchor object being preferred and Package object being deprecated.

jaraco · jaraco · commit 81c3c5ec7180 · 2022-12-29T12:14:41.000-05:00
diff --git 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,35 @@ 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 <types.ModuleType>` 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
+    <types.ModuleType>` 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 passing the anchor positionally or
+       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 +95,7 @@ for example, a package and its resources can be imported from a zip file using
 
     .. versionadded:: 3.9
 
+
 Deprecated functions
 --------------------
 
@@ -94,6 +104,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 <types.ModuleType>` 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 +124,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*.
