diff options
| -rw-r--r-- | Doc/library/importlib.rst | 31 | ||||
| -rw-r--r-- | Doc/whatsnew/3.7.rst | 17 | ||||
| -rw-r--r-- | Lib/importlib/abc.py | 9 | ||||
| -rw-r--r-- | Misc/NEWS.d/next/Library/2017-12-15-15-34-12.bpo-32248.zmO8G2.rst | 13 |
4 files changed, 57 insertions, 13 deletions
diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst index e99c606..5fa1d7d 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 <loader>` 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 + 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 .. 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 992d9ba..1041d31 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 implement 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 @@ -429,6 +429,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 ------ @@ -761,6 +767,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 -------------------- @@ -785,8 +794,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`.) diff --git a/Lib/importlib/abc.py b/Lib/importlib/abc.py index b772db3..bbff7af 100644 --- a/Lib/importlib/abc.py +++ b/Lib/importlib/abc.py @@ -342,9 +342,14 @@ class SourceLoader(_bootstrap_external.SourceLoader, ResourceLoader, ExecutionLo _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 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. + """ @abc.abstractmethod def open_resource(self, resource): 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 new file mode 100644 index 0000000..a41fde9 --- /dev/null +++ b/Misc/NEWS.d/next/Library/2017-12-15-15-34-12.bpo-32248.zmO8G2.rst @@ -0,0 +1,13 @@ +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`. |