gh-93610: Improve docs for importlib.resources

Doc/library/importlib.resources.abc.rst

@@ -1,3 +1,15 @@
+:mod:`importlib.resources.abc` -- Base classes for resources
+------------------------------------------------------------
+
+.. module:: importlib.resources.abc
+    :synopsis: Base classes for package resource reading, opening, and access
+
+**Source code:** :source:`Lib/importlib/resources/abc.py`
+
+--------------
+
+.. versionadded:: 3.11
+
 .. class:: ResourceReader
 
     *Superseded by TraversableResources*

Doc/library/importlib.resources.rst

@@ -4,7 +4,7 @@
 .. module:: importlib.resources
     :synopsis: Package resource reading, opening, and access
 
-**Source code:** :source:`Lib/importlib/resources.py`
+**Source code:** :source:`Lib/importlib/resources/`
 
 --------------
 
@@ -17,7 +17,9 @@ text mode.
 
 Resources are roughly akin to files inside directories, though it's important
 to keep in mind that this is just a metaphor.  Resources and packages **do
-not** have to exist as physical files and directories on the file system.
+not** have to exist as physical files and directories on the file system:
+for example, a package and its resources can be imported from a Zip file using
+:py:mod:`zipimport`.
 
 .. note::
 
@@ -33,47 +35,37 @@ not** have to exist as physical files and directories on the file system.
    on `using importlib.resources
    <http://importlib-resources.readthedocs.io/en/latest/using.html>`_ and
    `migrating from pkg_resources to importlib.resources
-   <http://importlib-resources.readthedocs.io/en/latest/migration.html>`_
-   and
-   `migrating legacy usage <https://importlib-resources.readthedocs.io/en/latest/using.html#migrating-from-legacy>`_.
+   <http://importlib-resources.readthedocs.io/en/latest/migration.html>`_.
 
-Loaders that wish to support resource reading should implement a
+:class:`Loaders <importlib.abc.Loader>` that wish to support resource reading should implement a
 ``get_resource_reader(fullname)`` method as specified by
-:class:`importlib.abc.ResourceReader`.
-
-The following types are defined.
+:class:`importlib.resources.abc.ResourceReader`.
 
 .. data:: Package
 
-    The ``Package`` type is defined as ``Union[str, ModuleType]``.  This means
-    that where the function describes accepting a ``Package``, you can pass in
-    either a string or a module.  Module objects must have a resolvable
-    ``__spec__.submodule_search_locations`` that is not ``None``.
-
-.. data:: Resource
-
-    This type describes the resource names passed into the various functions
-    in this package.  This is defined as ``Union[str, os.PathLike]``.
+    Where a function is described as accepting a ``Package``, you can pass in
+    either a module name (as a string) or a module object. Module objects must
+    have a resolvable ``__spec__.submodule_search_locations`` that is
+    not ``None``.
 
-
-The following functions are available.
+    The ``Package`` type is defined as ``Union[str, ModuleType]``.
 
 
 .. function:: files(package)
 
-    Returns an :class:`importlib.resources.abc.Traversable` object
+    Returns an :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).
 
     *package* is either a name or a module object which conforms to the
-    ``Package`` requirements.
+    :data:`Package` requirements.
 
     .. versionadded:: 3.9
 
 .. function:: as_file(traversable)
 
-    Given a :class:`importlib.resources.abc.Traversable` object representing
+    Given a :class:`~importlib.resources.abc.Traversable` object representing
     a file, typically from :func:`importlib.resources.files`, return
     a context manager for use in a :keyword:`with` statement.
     The context manager provides a :class:`pathlib.Path` object.
@@ -87,6 +79,22 @@ The following functions are available.
 
     .. versionadded:: 3.9
 
+Deprecated functions
+--------------------
+
+An older, deprecated set of functions is still available, but is
+scheduled for removal in a future version of Python.
+The main drawback of these function is that they do not support
+directories: they assume all resources are located directly within a *package*.
+
+.. data:: Resource
+
+    For *resource* arguments of the functions below, you can pass in
+    the name of a resource as a string or
+    a :class:`path-like object <os.PathLike>`.
+
+    The ``Resource`` type is defined as ``Union[str, os.PathLike]``.
+
 .. function:: open_binary(package, resource)
 
     Open for binary reading the *resource* within *package*.
@@ -97,7 +105,11 @@ The following functions are available.
     sub-resources (i.e. it cannot be a directory).  This function returns a
     ``typing.BinaryIO`` instance, a binary I/O stream open for reading.
 
-   .. deprecated:: 3.11
+    .. deprecated:: 3.11
+
+       Calls to this function can be replaced by::
+
+          files(package).joinpath(resource).open('rb')
 
 
 .. function:: open_text(package, resource, encoding='utf-8', errors='strict')
@@ -114,7 +126,11 @@ The following functions are available.
     This function returns a ``typing.TextIO`` instance, a text I/O stream open
     for reading.
 
-   .. deprecated:: 3.11
+    .. deprecated:: 3.11
+
+       Calls to this function can be replaced by::
+
+          files(package).joinpath(resource).open('r', encoding=encoding)
 
 
 .. function:: read_binary(package, resource)
@@ -128,7 +144,11 @@ The following functions are available.
     sub-resources (i.e. it cannot be a directory).  This function returns the
     contents of the resource as :class:`bytes`.
 
-   .. deprecated:: 3.11
+    .. deprecated:: 3.11
+
+       Calls to this function can be replaced by::
+
+          files(package).joinpath(resource).read_bytes()
 
 
 .. function:: read_text(package, resource, encoding='utf-8', errors='strict')
@@ -143,7 +163,11 @@ The following functions are available.
     have the same meaning as with built-in :func:`open`.  This function
     returns the contents of the resource as :class:`str`.
 
-   .. deprecated:: 3.11
+    .. deprecated:: 3.11
+
+       Calls to this function can be replaced by::
+
+          files(package).joinpath(resource).read_text(encoding=encoding)
 
 
 .. function:: path(package, resource)
@@ -160,17 +184,26 @@ The following functions are available.
     within *package*; it may not contain path separators and it may not have
     sub-resources (i.e. it cannot be a directory).
 
-   .. deprecated:: 3.11
+    .. deprecated:: 3.11
+
+       Calls to this function can be replaced using :func:`as_file`::
+
+          as_file(files(package).joinpath(resource))
 
 
 .. function:: is_resource(package, name)
 
     Return ``True`` if there is a resource named *name* in the package,
-    otherwise ``False``.  Remember that directories are *not* resources!
+    otherwise ``False``.
+    This function does not consider directories to be resources.
     *package* is either a name or a module object which conforms to the
     ``Package`` requirements.
 
-   .. deprecated:: 3.11
+    .. deprecated:: 3.11
+
+       Calls to this function can be replaced by::
+
+          files(package).joinpath(resource).is_file()
 
 
 .. function:: contents(package)
@@ -182,4 +215,8 @@ The following functions are available.
     *package* is either a name or a module object which conforms to the
     ``Package`` requirements.
 
-   .. deprecated:: 3.11
+    .. deprecated:: 3.11
+
+       Calls to this function can be replaced by::
+
+          (resource for resource in files(package).iterdir() if resource.is_file())

Doc/library/importlib.rst

@@ -508,9 +508,6 @@ ABC hierarchy::
            The import machinery now takes care of this automatically.
 
 
-.. include:: importlib.resources.abc.rst
-
-
 :mod:`importlib.machinery` -- Importers and path hooks
 ------------------------------------------------------
 

Doc/library/modules.rst

@@ -18,5 +18,6 @@ The full list of modules described in this chapter is:
    runpy.rst
    importlib.rst
    importlib.resources.rst
+   importlib.resources.abc.rst
    importlib.metadata.rst
    sys_path_init.rst