commit f26b0190c21b7519349605c05ac2a76091f71f7f
author Miss Islington (bot) <31488909+miss-islington@users.noreply.github.com> Fri Feb 16 08:07:53 2018 -0800
committer Barry Warsaw <barry@python.org> Fri Feb 16 11:07:53 2018 -0500
tree 442884c10927fd042dca0c3a0d7632e529c427cc
parent f0616ce137abecd18e9a1b1e191f657f049a4147

Update and sync importlib.resources documentation (GH-5694) (#5697)

(cherry picked from commit 997b8c140e768c849fa99d172245a7688af20a89)

Co-authored-by: Barry Warsaw <barry@python.org>

Doc/library/importlib.rst

diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst
index c80f460..db75f69 100644
--- a/Doc/library/importlib.rst
+++ b/Doc/library/importlib.rst
@@ -369,9 +369,9 @@
     An abstract base class for a :term:`loader`.
     See :pep:`302` for the exact definition for a loader.
 
-    For loaders that wish to support resource reading, they should
-    implement a ``get_resource_reader(fullname)`` method as specified
-    by :class:`importlib.abc.ResourceReader`.
+    Loaders that wish to support resource reading should implement a
+    ``get_resource_reader(fullname)`` method as specified by
+    :class:`importlib.abc.ResourceReader`.
 
     .. versionchanged:: 3.7
        Introduced the optional ``get_resource_reader()`` method.
@@ -813,8 +813,25 @@
 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.
 
-Loaders can support resources by implementing the :class:`ResourceReader`
-abstract base class.
+.. note::
+
+   This module provides functionality similar to `pkg_resources
+   <https://setuptools.readthedocs.io/en/latest/pkg_resources.html>`_ `Basic
+   Resource Access
+   <http://setuptools.readthedocs.io/en/latest/pkg_resources.html#basic-resource-access>`_
+   without the performance overhead of that package.  This makes reading
+   resources included in packages easier, with more stable and consistent
+   semantics.
+
+   The standalone backport of this module provides more information
+   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>`_.
+
+Loaders 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.