From 2312252983d4a4759dcb7006f0ea77cfd5ec7efc Mon Sep 17 00:00:00 2001 From: Brett Cannon Date: Fri, 5 Jan 2018 15:23:23 -0800 Subject: [PATCH 1/4] Clarify the docstring for ResourceReader --- Lib/importlib/abc.py | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/Lib/importlib/abc.py b/Lib/importlib/abc.py index b772db3758cdee6..016249ad620e7c6 100644 --- a/Lib/importlib/abc.py +++ b/Lib/importlib/abc.py @@ -342,9 +342,14 @@ def set_data(self, path, data): _register(SourceLoader, machinery.SourceFileLoader) -class ResourceReader(Loader): +class ResourceReader: - """Abstract base class for loaders to provide resource reading support.""" + """Abstract base class to provide resource-reading support. + + Loaders who support resource reading are expected to implement + the ``get_resource_reader(fullname)`` method and have it either return None + or an object compatible with this ABC. + """ @abc.abstractmethod def open_resource(self, resource): From 97bd50015c8a7e4d4389c26d84f7fb0ea60b85b3 Mon Sep 17 00:00:00 2001 From: Brett Cannon Date: Fri, 5 Jan 2018 15:24:02 -0800 Subject: [PATCH 2/4] Document get_resource_reader() and deprecate ResourceLoader --- Doc/library/importlib.rst | 31 ++++++++++++++++++++++++------- Doc/whatsnew/3.7.rst | 15 ++++++++++++--- 2 files changed, 36 insertions(+), 10 deletions(-) diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst index e99c6067a3d69ce..fa5372af180ffa0 100644 --- a/Doc/library/importlib.rst +++ b/Doc/library/importlib.rst @@ -233,7 +233,6 @@ ABC hierarchy:: | +-- MetaPathFinder | +-- PathEntryFinder +-- Loader - +-- ResourceReader +-- ResourceLoader --------+ +-- InspectLoader | +-- ExecutionLoader --+ @@ -370,6 +369,13 @@ 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`. + + .. versionchanged:: 3.7 + Introduced the optional ``get_resource_reader()`` method. + .. method:: create_module(spec) A method that returns the module object to use when @@ -471,8 +477,7 @@ ABC hierarchy:: .. class:: ResourceReader - An :term:`abstract base class` for :term:`package` - :term:`loaders ` to provide the ability to read + An :term:`abstract base class` to provide the ability to read *resources*. From the perspective of this ABC, a *resource* is a binary @@ -487,13 +492,20 @@ ABC hierarchy:: expected to be a :term:`path-like object` which represents conceptually just a file name. This means that no subdirectory paths should be included in the *resource* argument. This is - because the location of the package that the loader is for acts - as the "directory". Hence the metaphor for directories and file + because the location of the package the reader is for acts as the + "directory". Hence the metaphor for directories and file names is packages and resources, respectively. This is also why instances of this class are expected to directly correlate to a specific package (instead of potentially representing multiple packages or a module). + Loaders that wish to support resource reading are expected to + provide a method called ``get_resource_loader(fullname)`` which + either returns an object implementing this ABC's interface or + :const:`None` for the package specified by *fullname*. An object + compatible with this ABC should only be returned when the + specified module is a package. + .. versionadded:: 3.7 .. abstractmethod:: open_resource(resource) @@ -529,9 +541,10 @@ ABC hierarchy:: are known a priori and the non-resource names would be useful. For instance, returning subdirectory names is allowed so that when it is known that the package and resources are stored on - the file system then those subdirectory names can be used. + the file system then those subdirectory names can be used + directly. - The abstract method returns an empty iterator. + The abstract method returns an iterator of no items. .. class:: ResourceLoader @@ -540,6 +553,10 @@ ABC hierarchy:: :pep:`302` protocol for loading arbitrary resources from the storage back-end. + .. deprecated:: 3.7 + This ABC is deprecated in favour of supporting resource loading + through :class:`importlib.abc.ResourceReader`. + .. abstractmethod:: get_data(path) An abstract method to return the bytes for the data located at *path*. diff --git a/Doc/whatsnew/3.7.rst b/Doc/whatsnew/3.7.rst index 1311e9e2016a43a..ced7bec3ccb9b49 100644 --- a/Doc/whatsnew/3.7.rst +++ b/Doc/whatsnew/3.7.rst @@ -288,7 +288,7 @@ importlib.resources This module provides several new APIs and one new ABC for access to, opening, and reading *resources* inside packages. Resources are roughly akin to files inside of packages, but they needn't be actual files on the physical file -system. Module loaders can implement the +system. Module loaders can support the :class:`importlib.abc.ResourceReader` ABC to support this new module's API. @@ -389,6 +389,12 @@ and the ``--directory`` to the command line of the module :mod:`~http.server`. With this parameter, the server serves the specified directory, by default it uses the current working directory. (Contributed by Stéphane Wirtel and Julien Palard in :issue:`28707`.) +importlib +--------- + +The :class:`importlib.abc.ResourceReader` ABC was introduced to +support the loading of resource from packages. + locale ------ @@ -717,6 +723,9 @@ Deprecated - The :mod:`macpath` is now deprecated and will be removed in Python 3.8. +- The :class:`importlib.abc.ResourceLoader` ABC has been deprecated in + favour of :class:`importlib.abc.ResourceReader`. + Changes in the C API -------------------- @@ -741,8 +750,8 @@ Windows Only been used. If the specified version is not available py.exe will error exit. (Contributed by Steve Barnes in :issue:`30291`.) -- The launcher can be run as "py -0" to produce a list of the installed pythons, - *with default marked with an asterix*. Running "py -0p" will include the paths. +- The launcher can be run as ``py -0`` to produce a list of the installed pythons, + *with default marked with an asterisk*. Running ``py -0p`` will include the paths. If py is run with a version specifier that cannot be matched it will also print the *short form* list of available specifiers. (Contributed by Steve Barnes in :issue:`30362`.) From 9999bbe7aeb8d870f9550c3e5a4736881063e5d6 Mon Sep 17 00:00:00 2001 From: Brett Cannon Date: Fri, 5 Jan 2018 15:29:01 -0800 Subject: [PATCH 3/4] Update the news entry --- .../2017-12-15-15-34-12.bpo-32248.zmO8G2.rst | 16 +++++++++++++--- 1 file changed, 13 insertions(+), 3 deletions(-) diff --git a/Misc/NEWS.d/next/Library/2017-12-15-15-34-12.bpo-32248.zmO8G2.rst b/Misc/NEWS.d/next/Library/2017-12-15-15-34-12.bpo-32248.zmO8G2.rst index 02b7e5fef1109d5..a41fde94b3d0161 100644 --- a/Misc/NEWS.d/next/Library/2017-12-15-15-34-12.bpo-32248.zmO8G2.rst +++ b/Misc/NEWS.d/next/Library/2017-12-15-15-34-12.bpo-32248.zmO8G2.rst @@ -1,3 +1,13 @@ -Add :class:`importlib.abc.ResourceReader` as an ABC for loaders to provide a -unified API for reading resources contained within packages. Also add -:mod:`importlib.resources` as the port of ``importlib_resources``. +Add :class:`importlib.abc.ResourceReader` as an ABC to provide a +unified API for reading resources contained within packages. Loaders +wishing to support resource reading are expected to implement the +``get_resource_reader(fullname)`` method. + +Also add :mod:`importlib.resources` as the stdlib port of the +``importlib_resources`` PyPI package. The modules provides a high-level +API for end-users to read resources in a nicer fashion than having to +directly interact with low-level details such as loaders. + +Thanks to this work, :class:`importlib.abc.ResourceLoader` has now +been documented as deprecated due to its under-specified nature and +lack of features as provided by :class:`importlib.abc.ResourceReader`. From cbe860e2c8c8cd58f249bfae72c8258b0280010e Mon Sep 17 00:00:00 2001 From: Brett Cannon Date: Fri, 12 Jan 2018 14:48:35 -0800 Subject: [PATCH 4/4] Address review comments --- Doc/library/importlib.rst | 10 +++++----- Doc/whatsnew/3.7.rst | 4 ++-- Lib/importlib/abc.py | 2 +- 3 files changed, 8 insertions(+), 8 deletions(-) diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst index fa5372af180ffa0..5fa1d7d869dd9db 100644 --- a/Doc/library/importlib.rst +++ b/Doc/library/importlib.rst @@ -492,7 +492,7 @@ ABC hierarchy:: expected to be a :term:`path-like object` which represents conceptually just a file name. This means that no subdirectory paths should be included in the *resource* argument. This is - because the location of the package the reader is for acts as the + because the location of the package the reader is for, acts as the "directory". Hence the metaphor for directories and file names is packages and resources, respectively. This is also why instances of this class are expected to directly correlate to @@ -501,10 +501,10 @@ ABC hierarchy:: Loaders that wish to support resource reading are expected to provide a method called ``get_resource_loader(fullname)`` which - either returns an object implementing this ABC's interface or - :const:`None` for the package specified by *fullname*. An object - compatible with this ABC should only be returned when the - specified module is a package. + returns an object implementing this ABC's interface. If the module + specified by fullname is not a package, this method should return + :const:`None`. An object compatible with this ABC should only be + returned when the specified module is a package. .. versionadded:: 3.7 diff --git a/Doc/whatsnew/3.7.rst b/Doc/whatsnew/3.7.rst index e76daa165e063a4..1041d31f3027104 100644 --- a/Doc/whatsnew/3.7.rst +++ b/Doc/whatsnew/3.7.rst @@ -328,8 +328,8 @@ importlib.resources This module provides several new APIs and one new ABC for access to, opening, and reading *resources* inside packages. Resources are roughly akin to files inside of packages, but they needn't be actual files on the physical file -system. Module loaders can support the -:class:`importlib.abc.ResourceReader` ABC to support this new module's API. +system. Module loaders can provide :class:`importlib.abc.ResourceReader` +implementations to support this new module's API. Improved Modules diff --git a/Lib/importlib/abc.py b/Lib/importlib/abc.py index 016249ad620e7c6..bbff7af58850961 100644 --- a/Lib/importlib/abc.py +++ b/Lib/importlib/abc.py @@ -346,7 +346,7 @@ class ResourceReader: """Abstract base class to provide resource-reading support. - Loaders who support resource reading are expected to implement + Loaders that support resource reading are expected to implement the ``get_resource_reader(fullname)`` method and have it either return None or an object compatible with this ABC. """