From 6a97526e2113025549385810edd62cc244c415c6 Mon Sep 17 00:00:00 2001 From: Petr Viktorin Date: Wed, 8 Jun 2022 17:51:56 +0200 Subject: [PATCH 01/17] Add a concrete example of why you'd use importlib.resources over Path(__file__) --- Doc/library/importlib.resources.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/Doc/library/importlib.resources.rst b/Doc/library/importlib.resources.rst index f62d15dd6fdc9e..21d0662c30750d 100644 --- a/Doc/library/importlib.resources.rst +++ b/Doc/library/importlib.resources.rst @@ -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:: From 77b50aeaaf0b39d0e4ccc4c9cb42de93bce97c96 Mon Sep 17 00:00:00 2001 From: Petr Viktorin Date: Wed, 8 Jun 2022 17:58:54 +0200 Subject: [PATCH 02/17] Link to the definition of a new term --- Doc/library/importlib.resources.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/importlib.resources.rst b/Doc/library/importlib.resources.rst index 21d0662c30750d..d8234ca244b4a4 100644 --- a/Doc/library/importlib.resources.rst +++ b/Doc/library/importlib.resources.rst @@ -39,7 +39,7 @@ for example, a package and its resources can be imported from a Zip file using and `migrating legacy usage `_. -Loaders that wish to support resource reading should implement a +:class:`Loaders ` that wish to support resource reading should implement a ``get_resource_reader(fullname)`` method as specified by :class:`importlib.abc.ResourceReader`. From 89f00a2c63cc8316aab0df85f155b3665e185fa0 Mon Sep 17 00:00:00 2001 From: Petr Viktorin Date: Wed, 8 Jun 2022 18:22:01 +0200 Subject: [PATCH 03/17] Add importlib.resources.abc docs to the hierarchy, to fix links --- Doc/library/importlib.resources.abc.rst | 12 ++++++++++++ Doc/library/importlib.resources.rst | 2 +- Doc/library/importlib.rst | 3 --- Doc/library/modules.rst | 1 + 4 files changed, 14 insertions(+), 4 deletions(-) diff --git a/Doc/library/importlib.resources.abc.rst b/Doc/library/importlib.resources.abc.rst index 6b0e1e04c8852a..2173093561c76d 100644 --- a/Doc/library/importlib.resources.abc.rst +++ b/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* diff --git a/Doc/library/importlib.resources.rst b/Doc/library/importlib.resources.rst index d8234ca244b4a4..0a1b994e11f1b4 100644 --- a/Doc/library/importlib.resources.rst +++ b/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/` -------------- diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst index aac556e2c68d94..f81c56a26f06ed 100644 --- a/Doc/library/importlib.rst +++ b/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 ------------------------------------------------------ diff --git a/Doc/library/modules.rst b/Doc/library/modules.rst index 6cf6eb28a1e058..8c5936a4d8de2b 100644 --- a/Doc/library/modules.rst +++ b/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 From 913490118e98d956915358a940b44bf2c1869a6d Mon Sep 17 00:00:00 2001 From: Petr Viktorin Date: Wed, 8 Jun 2022 18:46:57 +0200 Subject: [PATCH 04/17] Package: Document what this is first, then give the formal definition --- Doc/library/importlib.resources.rst | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/Doc/library/importlib.resources.rst b/Doc/library/importlib.resources.rst index 0a1b994e11f1b4..7645253f496e8e 100644 --- a/Doc/library/importlib.resources.rst +++ b/Doc/library/importlib.resources.rst @@ -47,10 +47,12 @@ The following types are defined. .. 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``. + 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 ``Package`` type is defined as ``Union[str, ModuleType]``. .. data:: Resource From 02745153eaa6be42e0d54c096f716f8b60be4e64 Mon Sep 17 00:00:00 2001 From: Petr Viktorin Date: Wed, 8 Jun 2022 18:48:40 +0200 Subject: [PATCH 05/17] Shorten links to Traversable --- Doc/library/importlib.resources.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/importlib.resources.rst b/Doc/library/importlib.resources.rst index 7645253f496e8e..9fade3eab0f94e 100644 --- a/Doc/library/importlib.resources.rst +++ b/Doc/library/importlib.resources.rst @@ -65,7 +65,7 @@ The following functions are available. .. 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). @@ -77,7 +77,7 @@ The following functions are available. .. 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. From 39ab32a42bad39280385f0147678871db20b4493 Mon Sep 17 00:00:00 2001 From: Petr Viktorin Date: Wed, 8 Jun 2022 18:49:05 +0200 Subject: [PATCH 06/17] Link to Package --- Doc/library/importlib.resources.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/importlib.resources.rst b/Doc/library/importlib.resources.rst index 9fade3eab0f94e..c92af6d787d52e 100644 --- a/Doc/library/importlib.resources.rst +++ b/Doc/library/importlib.resources.rst @@ -71,7 +71,7 @@ The following functions are available. containers (think subdirectories). *package* is either a name or a module object which conforms to the - ``Package`` requirements. + :data:`Package` requirements. .. versionadded:: 3.9 From 521ad26f766ee461d96e7b8bbc40ae2dc0ffa0d9 Mon Sep 17 00:00:00 2001 From: Petr Viktorin Date: Wed, 8 Jun 2022 18:49:22 +0200 Subject: [PATCH 07/17] Move deprecated functions to a dedicated section, add modern equivalents --- Doc/library/importlib.resources.rst | 52 +++++++++++++++++++++++++---- 1 file changed, 46 insertions(+), 6 deletions(-) diff --git a/Doc/library/importlib.resources.rst b/Doc/library/importlib.resources.rst index c92af6d787d52e..67b7db94b6dccc 100644 --- a/Doc/library/importlib.resources.rst +++ b/Doc/library/importlib.resources.rst @@ -54,11 +54,6 @@ The following types are defined. The ``Package`` type is defined as ``Union[str, ModuleType]``. -.. data:: Resource - - This type describes the resource names passed into the various functions - in this package. This is defined as ``Union[str, os.PathLike]``. - The following functions are available. @@ -91,6 +86,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 mailn drawback of these function is that they do not allow directories. +These functions are deprecated in favor of ``files`` + +.. 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 `. + + The ``Resource`` type is defined as ``Union[str, os.PathLike]``. + .. function:: open_binary(package, resource) Open for binary reading the *resource* within *package*. @@ -101,6 +112,10 @@ 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. + This function may be replaced by:: + + files(package).joinpath(resource).open('rb') + .. deprecated:: 3.11 @@ -118,6 +133,10 @@ The following functions are available. This function returns a ``typing.TextIO`` instance, a text I/O stream open for reading. + Calls to this function can be replaced by:: + + files(package).joinpath(resource).open('r', encoding=encoding, errors=errors) + .. deprecated:: 3.11 @@ -132,6 +151,10 @@ 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`. + Calls to this function can be replaced by:: + + files(package).joinpath(resource).read_bytes() + .. deprecated:: 3.11 @@ -147,6 +170,10 @@ 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`. + Calls to this function can be replaced by:: + + files(package).joinpath(resource).read_text(encoding=encoding, errors=errors) + .. deprecated:: 3.11 @@ -164,16 +191,25 @@ 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). + Calls to this function can be replaced using :func:`as_file`:: + + as_file(files(package).joinpath(resource)) + .. deprecated:: 3.11 .. 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. + Calls to this function can be replaced by:: + + files(package).joinpath(resource).is_file() + .. deprecated:: 3.11 @@ -186,4 +222,8 @@ The following functions are available. *package* is either a name or a module object which conforms to the ``Package`` requirements. + Calls to this function can be replaced by:: + + (resource for resource in files(package).iterdir() if resource.is_file()) + .. deprecated:: 3.11 From 719562bc437b440c8b2920b531a2295aa8add75a Mon Sep 17 00:00:00 2001 From: Petr Viktorin Date: Wed, 8 Jun 2022 18:53:16 +0200 Subject: [PATCH 08/17] Move replacements to the ..deprecated sections --- Doc/library/importlib.resources.rst | 42 ++++++++++++++--------------- 1 file changed, 21 insertions(+), 21 deletions(-) diff --git a/Doc/library/importlib.resources.rst b/Doc/library/importlib.resources.rst index 67b7db94b6dccc..de5cf8787a0473 100644 --- a/Doc/library/importlib.resources.rst +++ b/Doc/library/importlib.resources.rst @@ -112,11 +112,11 @@ These functions are deprecated in favor of ``files`` sub-resources (i.e. it cannot be a directory). This function returns a ``typing.BinaryIO`` instance, a binary I/O stream open for reading. - This function may be replaced by:: + .. deprecated:: 3.11 - files(package).joinpath(resource).open('rb') + Calls to this function can be replaced by:: - .. deprecated:: 3.11 + files(package).joinpath(resource).open('rb') .. function:: open_text(package, resource, encoding='utf-8', errors='strict') @@ -133,11 +133,11 @@ These functions are deprecated in favor of ``files`` This function returns a ``typing.TextIO`` instance, a text I/O stream open for reading. - Calls to this function can be replaced by:: + .. deprecated:: 3.11 - files(package).joinpath(resource).open('r', encoding=encoding, errors=errors) + Calls to this function can be replaced by:: - .. deprecated:: 3.11 + files(package).joinpath(resource).open('r', encoding=encoding, errors=errors) .. function:: read_binary(package, resource) @@ -151,11 +151,11 @@ These functions are deprecated in favor of ``files`` sub-resources (i.e. it cannot be a directory). This function returns the contents of the resource as :class:`bytes`. - Calls to this function can be replaced by:: + .. deprecated:: 3.11 - files(package).joinpath(resource).read_bytes() + Calls to this function can be replaced by:: - .. deprecated:: 3.11 + files(package).joinpath(resource).read_bytes() .. function:: read_text(package, resource, encoding='utf-8', errors='strict') @@ -170,11 +170,11 @@ These functions are deprecated in favor of ``files`` have the same meaning as with built-in :func:`open`. This function returns the contents of the resource as :class:`str`. - Calls to this function can be replaced by:: + .. deprecated:: 3.11 - files(package).joinpath(resource).read_text(encoding=encoding, errors=errors) + Calls to this function can be replaced by:: - .. deprecated:: 3.11 + files(package).joinpath(resource).read_text(encoding=encoding, errors=errors) .. function:: path(package, resource) @@ -191,11 +191,11 @@ These functions are deprecated in favor of ``files`` within *package*; it may not contain path separators and it may not have sub-resources (i.e. it cannot be a directory). - Calls to this function can be replaced using :func:`as_file`:: + .. deprecated:: 3.11 - as_file(files(package).joinpath(resource)) + Calls to this function can be replaced using :func:`as_file`:: - .. deprecated:: 3.11 + as_file(files(package).joinpath(resource)) .. function:: is_resource(package, name) @@ -206,11 +206,11 @@ These functions are deprecated in favor of ``files`` *package* is either a name or a module object which conforms to the ``Package`` requirements. - Calls to this function can be replaced by:: + .. deprecated:: 3.11 - files(package).joinpath(resource).is_file() + Calls to this function can be replaced by:: - .. deprecated:: 3.11 + files(package).joinpath(resource).is_file() .. function:: contents(package) @@ -222,8 +222,8 @@ These functions are deprecated in favor of ``files`` *package* is either a name or a module object which conforms to the ``Package`` requirements. - Calls to this function can be replaced by:: + .. deprecated:: 3.11 - (resource for resource in files(package).iterdir() if resource.is_file()) + Calls to this function can be replaced by:: - .. deprecated:: 3.11 + (resource for resource in files(package).iterdir() if resource.is_file()) From 9bcca6b51d64869511d2bd7e7c493ff16df4ae72 Mon Sep 17 00:00:00 2001 From: Petr Viktorin Date: Wed, 8 Jun 2022 18:56:21 +0200 Subject: [PATCH 09/17] Remove the link to migrating legacy usage: this is now documented here. --- Doc/library/importlib.resources.rst | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/Doc/library/importlib.resources.rst b/Doc/library/importlib.resources.rst index de5cf8787a0473..ff7ffb525cc699 100644 --- a/Doc/library/importlib.resources.rst +++ b/Doc/library/importlib.resources.rst @@ -35,9 +35,7 @@ for example, a package and its resources can be imported from a Zip file using on `using importlib.resources `_ and `migrating from pkg_resources to importlib.resources - `_ - and - `migrating legacy usage `_. + `_. :class:`Loaders ` that wish to support resource reading should implement a ``get_resource_reader(fullname)`` method as specified by From ac007c3f5c1c9060d2715688b61a66e2ab97655e Mon Sep 17 00:00:00 2001 From: Petr Viktorin Date: Wed, 8 Jun 2022 18:58:56 +0200 Subject: [PATCH 10/17] Remove `errors` arguments from the migration snippets --- Doc/library/importlib.resources.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/importlib.resources.rst b/Doc/library/importlib.resources.rst index ff7ffb525cc699..2042bd38a45d94 100644 --- a/Doc/library/importlib.resources.rst +++ b/Doc/library/importlib.resources.rst @@ -135,7 +135,7 @@ These functions are deprecated in favor of ``files`` Calls to this function can be replaced by:: - files(package).joinpath(resource).open('r', encoding=encoding, errors=errors) + files(package).joinpath(resource).open('r', encoding=encoding) .. function:: read_binary(package, resource) @@ -172,7 +172,7 @@ These functions are deprecated in favor of ``files`` Calls to this function can be replaced by:: - files(package).joinpath(resource).read_text(encoding=encoding, errors=errors) + files(package).joinpath(resource).read_text(encoding=encoding) .. function:: path(package, resource) From d1fefcb496e72bc0a7ecb474faf5ef2fa053514c Mon Sep 17 00:00:00 2001 From: Petr Viktorin Date: Wed, 8 Jun 2022 19:05:28 +0200 Subject: [PATCH 11/17] Fix qualname of importlib.resources.abc.ResourceReader --- Doc/library/importlib.resources.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/importlib.resources.rst b/Doc/library/importlib.resources.rst index 2042bd38a45d94..111bfec844b2c5 100644 --- a/Doc/library/importlib.resources.rst +++ b/Doc/library/importlib.resources.rst @@ -39,7 +39,7 @@ for example, a package and its resources can be imported from a Zip file using :class:`Loaders ` that wish to support resource reading should implement a ``get_resource_reader(fullname)`` method as specified by -:class:`importlib.abc.ResourceReader`. +:class:`importlib.resources.abc.ResourceReader`. The following types are defined. From 993ea9e20d3c56088cb36b44d1c2a73bc623cde9 Mon Sep 17 00:00:00 2001 From: Petr Viktorin Date: Wed, 8 Jun 2022 19:10:34 +0200 Subject: [PATCH 12/17] Reword the intro for deprecated functions --- Doc/library/importlib.resources.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/importlib.resources.rst b/Doc/library/importlib.resources.rst index 111bfec844b2c5..1fa75fffabf465 100644 --- a/Doc/library/importlib.resources.rst +++ b/Doc/library/importlib.resources.rst @@ -89,8 +89,8 @@ Deprecated functions An older, deprecated set of functions is still available, but is scheduled for removal in a future version of Python. -The mailn drawback of these function is that they do not allow directories. -These functions are deprecated in favor of ``files`` +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 From 77acd3305b4dc60e2469e78ec4570bc383264208 Mon Sep 17 00:00:00 2001 From: Petr Viktorin Date: Wed, 8 Jun 2022 19:12:32 +0200 Subject: [PATCH 13/17] Remove unnecessary "headings" --- Doc/library/importlib.resources.rst | 5 ----- 1 file changed, 5 deletions(-) diff --git a/Doc/library/importlib.resources.rst b/Doc/library/importlib.resources.rst index 1fa75fffabf465..80986c4cbfc89a 100644 --- a/Doc/library/importlib.resources.rst +++ b/Doc/library/importlib.resources.rst @@ -41,8 +41,6 @@ for example, a package and its resources can be imported from a Zip file using ``get_resource_reader(fullname)`` method as specified by :class:`importlib.resources.abc.ResourceReader`. -The following types are defined. - .. data:: Package Where a function is described as accepting a ``Package``, you can pass in @@ -53,9 +51,6 @@ The following types are defined. The ``Package`` type is defined as ``Union[str, ModuleType]``. -The following functions are available. - - .. function:: files(package) Returns an :class:`~importlib.resources.abc.Traversable` object From 1fb51a0a6cabeef249de65a2d6f4b27050392ab5 Mon Sep 17 00:00:00 2001 From: Petr Viktorin Date: Thu, 9 Jun 2022 11:23:46 +0200 Subject: [PATCH 14/17] Apply suggestions from code review Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> Co-authored-by: Stanley <46876382+slateny@users.noreply.github.com> --- Doc/library/importlib.resources.abc.rst | 6 +++--- Doc/library/importlib.resources.rst | 8 ++++---- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/Doc/library/importlib.resources.abc.rst b/Doc/library/importlib.resources.abc.rst index 2173093561c76d..c20fde20383feb 100644 --- a/Doc/library/importlib.resources.abc.rst +++ b/Doc/library/importlib.resources.abc.rst @@ -1,8 +1,8 @@ -:mod:`importlib.resources.abc` -- Base classes for resources ------------------------------------------------------------- +:mod:`importlib.resources.abc` -- Abstract base classes for resources +--------------------------------------------------------------------- .. module:: importlib.resources.abc - :synopsis: Base classes for package resource reading, opening, and access + :synopsis: Abstract base classes for resources **Source code:** :source:`Lib/importlib/resources/abc.py` diff --git a/Doc/library/importlib.resources.rst b/Doc/library/importlib.resources.rst index 80986c4cbfc89a..db274c414c51d3 100644 --- a/Doc/library/importlib.resources.rst +++ b/Doc/library/importlib.resources.rst @@ -18,7 +18,7 @@ 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: -for example, a package and its resources can be imported from a Zip file using +for example, a package and its resources can be imported from a zip file using :py:mod:`zipimport`. .. note:: @@ -53,7 +53,7 @@ for example, a package and its resources can be imported from a Zip file using .. function:: files(package) - Returns an :class:`~importlib.resources.abc.Traversable` object + Returns a :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). @@ -84,7 +84,7 @@ 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 +The main drawback of these functions is that they do not support directories: they assume all resources are located directly within a *package*. .. data:: Resource @@ -219,4 +219,4 @@ directories: they assume all resources are located directly within a *package*. Calls to this function can be replaced by:: - (resource for resource in files(package).iterdir() if resource.is_file()) + (resource.name for resource in files(package).iterdir() if resource.is_file()) From a5a537784266ee96417a46a2cc38d08a7dc47ba1 Mon Sep 17 00:00:00 2001 From: Petr Viktorin Date: Thu, 16 Jun 2022 17:47:35 +0200 Subject: [PATCH 15/17] Move classes that are actually in importlib.abc out from importlib.resources.abc --- Doc/library/importlib.resources.abc.rst | 245 ----------------------- Doc/library/importlib.rst | 246 ++++++++++++++++++++++++ 2 files changed, 246 insertions(+), 245 deletions(-) diff --git a/Doc/library/importlib.resources.abc.rst b/Doc/library/importlib.resources.abc.rst index c20fde20383feb..466966841b90bd 100644 --- a/Doc/library/importlib.resources.abc.rst +++ b/Doc/library/importlib.resources.abc.rst @@ -84,251 +84,6 @@ The abstract method returns an iterable of no items. -.. class:: ResourceLoader - - An abstract base class for a :term:`loader` which implements the optional - :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*. - Loaders that have a file-like storage back-end - that allows storing arbitrary data - can implement this abstract method to give direct access - to the data stored. :exc:`OSError` is to be raised if the *path* cannot - be found. The *path* is expected to be constructed using a module's - :attr:`__file__` attribute or an item from a package's :attr:`__path__`. - - .. versionchanged:: 3.4 - Raises :exc:`OSError` instead of :exc:`NotImplementedError`. - - -.. class:: InspectLoader - - An abstract base class for a :term:`loader` which implements the optional - :pep:`302` protocol for loaders that inspect modules. - - .. method:: get_code(fullname) - - Return the code object for a module, or ``None`` if the module does not - have a code object (as would be the case, for example, for a built-in - module). Raise an :exc:`ImportError` if loader cannot find the - requested module. - - .. note:: - While the method has a default implementation, it is suggested that - it be overridden if possible for performance. - - .. index:: - single: universal newlines; importlib.abc.InspectLoader.get_source method - - .. versionchanged:: 3.4 - No longer abstract and a concrete implementation is provided. - - .. abstractmethod:: get_source(fullname) - - An abstract method to return the source of a module. It is returned as - a text string using :term:`universal newlines`, translating all - recognized line separators into ``'\n'`` characters. Returns ``None`` - if no source is available (e.g. a built-in module). Raises - :exc:`ImportError` if the loader cannot find the module specified. - - .. versionchanged:: 3.4 - Raises :exc:`ImportError` instead of :exc:`NotImplementedError`. - - .. method:: is_package(fullname) - - An optional method to return a true value if the module is a package, a - false value otherwise. :exc:`ImportError` is raised if the - :term:`loader` cannot find the module. - - .. versionchanged:: 3.4 - Raises :exc:`ImportError` instead of :exc:`NotImplementedError`. - - .. staticmethod:: source_to_code(data, path='') - - Create a code object from Python source. - - The *data* argument can be whatever the :func:`compile` function - supports (i.e. string or bytes). The *path* argument should be - the "path" to where the source code originated from, which can be an - abstract concept (e.g. location in a zip file). - - With the subsequent code object one can execute it in a module by - running ``exec(code, module.__dict__)``. - - .. versionadded:: 3.4 - - .. versionchanged:: 3.5 - Made the method static. - - .. method:: exec_module(module) - - Implementation of :meth:`Loader.exec_module`. - - .. versionadded:: 3.4 - - .. method:: load_module(fullname) - - Implementation of :meth:`Loader.load_module`. - - .. deprecated:: 3.4 - use :meth:`exec_module` instead. - - -.. class:: ExecutionLoader - - An abstract base class which inherits from :class:`InspectLoader` that, - when implemented, helps a module to be executed as a script. The ABC - represents an optional :pep:`302` protocol. - - .. abstractmethod:: get_filename(fullname) - - An abstract method that is to return the value of :attr:`__file__` for - the specified module. If no path is available, :exc:`ImportError` is - raised. - - If source code is available, then the method should return the path to - the source file, regardless of whether a bytecode was used to load the - module. - - .. versionchanged:: 3.4 - Raises :exc:`ImportError` instead of :exc:`NotImplementedError`. - - -.. class:: FileLoader(fullname, path) - - An abstract base class which inherits from :class:`ResourceLoader` and - :class:`ExecutionLoader`, providing concrete implementations of - :meth:`ResourceLoader.get_data` and :meth:`ExecutionLoader.get_filename`. - - The *fullname* argument is a fully resolved name of the module the loader is - to handle. The *path* argument is the path to the file for the module. - - .. versionadded:: 3.3 - - .. attribute:: name - - The name of the module the loader can handle. - - .. attribute:: path - - Path to the file of the module. - - .. method:: load_module(fullname) - - Calls super's ``load_module()``. - - .. deprecated:: 3.4 - Use :meth:`Loader.exec_module` instead. - - .. abstractmethod:: get_filename(fullname) - - Returns :attr:`path`. - - .. abstractmethod:: get_data(path) - - Reads *path* as a binary file and returns the bytes from it. - - -.. class:: SourceLoader - - An abstract base class for implementing source (and optionally bytecode) - file loading. The class inherits from both :class:`ResourceLoader` and - :class:`ExecutionLoader`, requiring the implementation of: - - * :meth:`ResourceLoader.get_data` - * :meth:`ExecutionLoader.get_filename` - Should only return the path to the source file; sourceless - loading is not supported. - - The abstract methods defined by this class are to add optional bytecode - file support. Not implementing these optional methods (or causing them to - raise :exc:`NotImplementedError`) causes the loader to - only work with source code. Implementing the methods allows the loader to - work with source *and* bytecode files; it does not allow for *sourceless* - loading where only bytecode is provided. Bytecode files are an - optimization to speed up loading by removing the parsing step of Python's - compiler, and so no bytecode-specific API is exposed. - - .. method:: path_stats(path) - - Optional abstract method which returns a :class:`dict` containing - metadata about the specified path. Supported dictionary keys are: - - - ``'mtime'`` (mandatory): an integer or floating-point number - representing the modification time of the source code; - - ``'size'`` (optional): the size in bytes of the source code. - - Any other keys in the dictionary are ignored, to allow for future - extensions. If the path cannot be handled, :exc:`OSError` is raised. - - .. versionadded:: 3.3 - - .. versionchanged:: 3.4 - Raise :exc:`OSError` instead of :exc:`NotImplementedError`. - - .. method:: path_mtime(path) - - Optional abstract method which returns the modification time for the - specified path. - - .. deprecated:: 3.3 - This method is deprecated in favour of :meth:`path_stats`. You don't - have to implement it, but it is still available for compatibility - purposes. Raise :exc:`OSError` if the path cannot be handled. - - .. versionchanged:: 3.4 - Raise :exc:`OSError` instead of :exc:`NotImplementedError`. - - .. method:: set_data(path, data) - - Optional abstract method which writes the specified bytes to a file - path. Any intermediate directories which do not exist are to be created - automatically. - - When writing to the path fails because the path is read-only - (:attr:`errno.EACCES`/:exc:`PermissionError`), do not propagate the - exception. - - .. versionchanged:: 3.4 - No longer raises :exc:`NotImplementedError` when called. - - .. method:: get_code(fullname) - - Concrete implementation of :meth:`InspectLoader.get_code`. - - .. method:: exec_module(module) - - Concrete implementation of :meth:`Loader.exec_module`. - - .. versionadded:: 3.4 - - .. method:: load_module(fullname) - - Concrete implementation of :meth:`Loader.load_module`. - - .. deprecated:: 3.4 - Use :meth:`exec_module` instead. - - .. method:: get_source(fullname) - - Concrete implementation of :meth:`InspectLoader.get_source`. - - .. method:: is_package(fullname) - - Concrete implementation of :meth:`InspectLoader.is_package`. A module - is determined to be a package if its file path (as provided by - :meth:`ExecutionLoader.get_filename`) is a file named - ``__init__`` when the file extension is removed **and** the module name - itself does not end in ``__init__``. - - .. class:: Traversable An object with a subset of pathlib.Path methods suitable for diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst index f81c56a26f06ed..c78ae6257f44fd 100644 --- a/Doc/library/importlib.rst +++ b/Doc/library/importlib.rst @@ -508,6 +508,252 @@ ABC hierarchy:: The import machinery now takes care of this automatically. +.. class:: ResourceLoader + + An abstract base class for a :term:`loader` which implements the optional + :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*. + Loaders that have a file-like storage back-end + that allows storing arbitrary data + can implement this abstract method to give direct access + to the data stored. :exc:`OSError` is to be raised if the *path* cannot + be found. The *path* is expected to be constructed using a module's + :attr:`__file__` attribute or an item from a package's :attr:`__path__`. + + .. versionchanged:: 3.4 + Raises :exc:`OSError` instead of :exc:`NotImplementedError`. + + +.. class:: InspectLoader + + An abstract base class for a :term:`loader` which implements the optional + :pep:`302` protocol for loaders that inspect modules. + + .. method:: get_code(fullname) + + Return the code object for a module, or ``None`` if the module does not + have a code object (as would be the case, for example, for a built-in + module). Raise an :exc:`ImportError` if loader cannot find the + requested module. + + .. note:: + While the method has a default implementation, it is suggested that + it be overridden if possible for performance. + + .. index:: + single: universal newlines; importlib.abc.InspectLoader.get_source method + + .. versionchanged:: 3.4 + No longer abstract and a concrete implementation is provided. + + .. abstractmethod:: get_source(fullname) + + An abstract method to return the source of a module. It is returned as + a text string using :term:`universal newlines`, translating all + recognized line separators into ``'\n'`` characters. Returns ``None`` + if no source is available (e.g. a built-in module). Raises + :exc:`ImportError` if the loader cannot find the module specified. + + .. versionchanged:: 3.4 + Raises :exc:`ImportError` instead of :exc:`NotImplementedError`. + + .. method:: is_package(fullname) + + An optional method to return a true value if the module is a package, a + false value otherwise. :exc:`ImportError` is raised if the + :term:`loader` cannot find the module. + + .. versionchanged:: 3.4 + Raises :exc:`ImportError` instead of :exc:`NotImplementedError`. + + .. staticmethod:: source_to_code(data, path='') + + Create a code object from Python source. + + The *data* argument can be whatever the :func:`compile` function + supports (i.e. string or bytes). The *path* argument should be + the "path" to where the source code originated from, which can be an + abstract concept (e.g. location in a zip file). + + With the subsequent code object one can execute it in a module by + running ``exec(code, module.__dict__)``. + + .. versionadded:: 3.4 + + .. versionchanged:: 3.5 + Made the method static. + + .. method:: exec_module(module) + + Implementation of :meth:`Loader.exec_module`. + + .. versionadded:: 3.4 + + .. method:: load_module(fullname) + + Implementation of :meth:`Loader.load_module`. + + .. deprecated:: 3.4 + use :meth:`exec_module` instead. + + +.. class:: ExecutionLoader + + An abstract base class which inherits from :class:`InspectLoader` that, + when implemented, helps a module to be executed as a script. The ABC + represents an optional :pep:`302` protocol. + + .. abstractmethod:: get_filename(fullname) + + An abstract method that is to return the value of :attr:`__file__` for + the specified module. If no path is available, :exc:`ImportError` is + raised. + + If source code is available, then the method should return the path to + the source file, regardless of whether a bytecode was used to load the + module. + + .. versionchanged:: 3.4 + Raises :exc:`ImportError` instead of :exc:`NotImplementedError`. + + +.. class:: FileLoader(fullname, path) + + An abstract base class which inherits from :class:`ResourceLoader` and + :class:`ExecutionLoader`, providing concrete implementations of + :meth:`ResourceLoader.get_data` and :meth:`ExecutionLoader.get_filename`. + + The *fullname* argument is a fully resolved name of the module the loader is + to handle. The *path* argument is the path to the file for the module. + + .. versionadded:: 3.3 + + .. attribute:: name + + The name of the module the loader can handle. + + .. attribute:: path + + Path to the file of the module. + + .. method:: load_module(fullname) + + Calls super's ``load_module()``. + + .. deprecated:: 3.4 + Use :meth:`Loader.exec_module` instead. + + .. abstractmethod:: get_filename(fullname) + + Returns :attr:`path`. + + .. abstractmethod:: get_data(path) + + Reads *path* as a binary file and returns the bytes from it. + + +.. class:: SourceLoader + + An abstract base class for implementing source (and optionally bytecode) + file loading. The class inherits from both :class:`ResourceLoader` and + :class:`ExecutionLoader`, requiring the implementation of: + + * :meth:`ResourceLoader.get_data` + * :meth:`ExecutionLoader.get_filename` + Should only return the path to the source file; sourceless + loading is not supported. + + The abstract methods defined by this class are to add optional bytecode + file support. Not implementing these optional methods (or causing them to + raise :exc:`NotImplementedError`) causes the loader to + only work with source code. Implementing the methods allows the loader to + work with source *and* bytecode files; it does not allow for *sourceless* + loading where only bytecode is provided. Bytecode files are an + optimization to speed up loading by removing the parsing step of Python's + compiler, and so no bytecode-specific API is exposed. + + .. method:: path_stats(path) + + Optional abstract method which returns a :class:`dict` containing + metadata about the specified path. Supported dictionary keys are: + + - ``'mtime'`` (mandatory): an integer or floating-point number + representing the modification time of the source code; + - ``'size'`` (optional): the size in bytes of the source code. + + Any other keys in the dictionary are ignored, to allow for future + extensions. If the path cannot be handled, :exc:`OSError` is raised. + + .. versionadded:: 3.3 + + .. versionchanged:: 3.4 + Raise :exc:`OSError` instead of :exc:`NotImplementedError`. + + .. method:: path_mtime(path) + + Optional abstract method which returns the modification time for the + specified path. + + .. deprecated:: 3.3 + This method is deprecated in favour of :meth:`path_stats`. You don't + have to implement it, but it is still available for compatibility + purposes. Raise :exc:`OSError` if the path cannot be handled. + + .. versionchanged:: 3.4 + Raise :exc:`OSError` instead of :exc:`NotImplementedError`. + + .. method:: set_data(path, data) + + Optional abstract method which writes the specified bytes to a file + path. Any intermediate directories which do not exist are to be created + automatically. + + When writing to the path fails because the path is read-only + (:attr:`errno.EACCES`/:exc:`PermissionError`), do not propagate the + exception. + + .. versionchanged:: 3.4 + No longer raises :exc:`NotImplementedError` when called. + + .. method:: get_code(fullname) + + Concrete implementation of :meth:`InspectLoader.get_code`. + + .. method:: exec_module(module) + + Concrete implementation of :meth:`Loader.exec_module`. + + .. versionadded:: 3.4 + + .. method:: load_module(fullname) + + Concrete implementation of :meth:`Loader.load_module`. + + .. deprecated:: 3.4 + Use :meth:`exec_module` instead. + + .. method:: get_source(fullname) + + Concrete implementation of :meth:`InspectLoader.get_source`. + + .. method:: is_package(fullname) + + Concrete implementation of :meth:`InspectLoader.is_package`. A module + is determined to be a package if its file path (as provided by + :meth:`ExecutionLoader.get_filename`) is a file named + ``__init__`` when the file extension is removed **and** the module name + itself does not end in ``__init__``. + + + :mod:`importlib.machinery` -- Importers and path hooks ------------------------------------------------------ From a03df1f3813a709ac69988487ac2112a6504e865 Mon Sep 17 00:00:00 2001 From: Petr Viktorin Date: Thu, 16 Jun 2022 17:51:17 +0200 Subject: [PATCH 16/17] Fix references to classes in importlib.resources.abc --- Doc/library/importlib.resources.abc.rst | 6 +++--- Doc/library/importlib.rst | 4 ++-- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/Doc/library/importlib.resources.abc.rst b/Doc/library/importlib.resources.abc.rst index 466966841b90bd..d281ac032216a8 100644 --- a/Doc/library/importlib.resources.abc.rst +++ b/Doc/library/importlib.resources.abc.rst @@ -136,8 +136,8 @@ An abstract base class for resource readers capable of serving the :meth:`importlib.resources.files` interface. Subclasses - :class:`importlib.abc.ResourceReader` and provides - concrete implementations of the :class:`importlib.abc.ResourceReader`'s + :class:`importlib.resources.abc.ResourceReader` and provides + concrete implementations of the :class:`importlib.resources.abc.ResourceReader`'s abstract methods. Therefore, any loader supplying :class:`importlib.abc.TraversableReader` also supplies ResourceReader. @@ -148,5 +148,5 @@ .. abstractmethod:: files() - Returns a :class:`importlib.abc.Traversable` object for the loaded + Returns a :class:`importlib.resources.abc.Traversable` object for the loaded package. diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst index c78ae6257f44fd..ae0e69ca1f2c2f 100644 --- a/Doc/library/importlib.rst +++ b/Doc/library/importlib.rst @@ -401,7 +401,7 @@ ABC hierarchy:: Loaders that wish to support resource reading should implement a :meth:`get_resource_reader` method as specified by - :class:`importlib.abc.ResourceReader`. + :class:`importlib.resources.abc.ResourceReader`. .. versionchanged:: 3.7 Introduced the optional :meth:`get_resource_reader` method. @@ -516,7 +516,7 @@ ABC hierarchy:: .. deprecated:: 3.7 This ABC is deprecated in favour of supporting resource loading - through :class:`importlib.abc.ResourceReader`. + through :class:`importlib.resources.abc.ResourceReader`. .. abstractmethod:: get_data(path) From fa68025408a3fc3b7970954980d3658693b80bb1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20Langa?= Date: Mon, 25 Jul 2022 17:50:19 +0200 Subject: [PATCH 17/17] Slightly reword Package --- Doc/library/importlib.resources.rst | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/Doc/library/importlib.resources.rst b/Doc/library/importlib.resources.rst index 3c41e6a9c81a6c..d367dcee7c2072 100644 --- a/Doc/library/importlib.resources.rst +++ b/Doc/library/importlib.resources.rst @@ -43,14 +43,13 @@ for example, a package and its resources can be imported from a zip file using .. data:: Package - 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``. + Whenever a function accepts a ``Package`` argument, you can pass in + either a :class:`module object ` or a module name + as a string. You can only pass module objects whose + ``__spec__.submodule_search_locations`` is not ``None``. The ``Package`` type is defined as ``Union[str, ModuleType]``. - .. function:: files(package) Returns a :class:`~importlib.resources.abc.Traversable` object