From 997b8c140e768c849fa99d172245a7688af20a89 Mon Sep 17 00:00:00 2001 From: Barry Warsaw Date: Fri, 16 Feb 2018 10:45:39 -0500 Subject: [PATCH] Update and sync importlib.resources documentation (#5694) --- Doc/library/importlib.rst | 27 ++++++++++++++++++++++----- 1 file changed, 22 insertions(+), 5 deletions(-) diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst index c80f4606f3d..db75f69a0d0 100644 --- a/Doc/library/importlib.rst +++ b/Doc/library/importlib.rst @@ -369,9 +369,9 @@ ABC hierarchy:: 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 @@ 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. -Loaders can support resources by implementing the :class:`ResourceReader` -abstract base class. +.. note:: + + This module provides functionality similar to `pkg_resources + `_ `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 + `_ and + `migrating from pkg_resources to importlib.resources + `_. + +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.