From 611e6b520955d13a04359cc2770f4d08059ef697 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9ry=20Ogam?= Date: Sun, 21 Oct 2018 01:00:18 +0200 Subject: [PATCH 01/46] Correct the description of ModuleSpec attributes * The ``loader`` attribute is not `None` for namespace packages (see https://stackoverflow.com/questions/52869541/namespace-package-loader-attribute-not-set-to-none). * The ``submodule_search_locations `` attribute is not `None` for non-package modules, it is not set (see https://docs.python.org/3/reference/import.html#__path__). * The ``cached `` attribute is not sometimes `None`, it is sometimes not set (see https://docs.python.org/3/reference/import.html#__cached__). * The ``parent `` attribute is not `None` but the empty string for non-package top-level modules (see https://docs.python.org/3/reference/import.html#__package__). --- Doc/library/importlib.rst | 27 ++++++++++++++------------- 1 file changed, 14 insertions(+), 13 deletions(-) diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst index 6f4da11989551e..7ed3c2673fb9c4 100644 --- a/Doc/library/importlib.rst +++ b/Doc/library/importlib.rst @@ -1297,30 +1297,29 @@ find and load modules. (``__name__``) - A string for the fully-qualified name of the module. + Fully-qualified name of the module. .. attribute:: loader (``__loader__``) - The loader to use for loading. For namespace packages this should be - set to ``None``. + Loader object to use for loading the module. .. attribute:: origin (``__file__``) - Name of the place from which the module is loaded, e.g. "builtin" for - built-in modules and the filename for modules loaded from source. - Normally "origin" should be set, but it may be ``None`` (the default) - which indicates it is unspecified (e.g. for namespace packages). + Path to the code from where the module should be loaded, e.g., + "builtin" for built-in modules and the filename for modules loaded from + source. It may be ``None`` (the default), which indicates it is + unspecified (e.g. for namespace packages). It is optional. .. attribute:: submodule_search_locations (``__path__``) - List of strings for where to find submodules, if a package (``None`` - otherwise). + Iterable (possibly empty) of locations to search for submodules of a + package module during import. Not set for non-package modules. .. attribute:: loader_state @@ -1331,18 +1330,20 @@ find and load modules. (``__cached__``) - String for where the compiled module should be stored (or ``None``). + Path to the compiled code from where the module should be loaded. + It is optional. .. attribute:: parent (``__package__``) - (Read-only) Fully-qualified name of the package to which the module - belongs as a submodule (or ``None``). + The ``__name__`` attribute of the module for package modules. + The empty string for non-package top-level modules or the parent + package's ``__name__`` attribute for non-package submodules. .. attribute:: has_location - Boolean indicating whether or not the module's "origin" + Boolean indicating whether or not the module's ``origin`` attribute refers to a loadable location. :mod:`importlib.util` -- Utility code for importers From 71137668b8dc7bde16ed3bb94a881ea844c8c1bd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9ry=20Ogam?= Date: Sun, 21 Oct 2018 18:12:19 +0200 Subject: [PATCH 02/46] Update the description of the `submodule_search_locations` and `cached` attributes --- Doc/library/importlib.rst | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst index 7ed3c2673fb9c4..7364c8869a6f85 100644 --- a/Doc/library/importlib.rst +++ b/Doc/library/importlib.rst @@ -1309,17 +1309,15 @@ find and load modules. (``__file__``) - Path to the code from where the module should be loaded, e.g., - "builtin" for built-in modules and the filename for modules loaded from - source. It may be ``None`` (the default), which indicates it is - unspecified (e.g. for namespace packages). It is optional. + Path to the code from where the module should be loaded. + It is ``None`` for builtin modules and namespace package modules. .. attribute:: submodule_search_locations (``__path__``) Iterable (possibly empty) of locations to search for submodules of a - package module during import. Not set for non-package modules. + package module during import. It is `None` for non-package modules. .. attribute:: loader_state @@ -1331,15 +1329,15 @@ find and load modules. (``__cached__``) Path to the compiled code from where the module should be loaded. - It is optional. + It is ``None`` for builtin modules and namespace package modules. .. attribute:: parent (``__package__``) The ``__name__`` attribute of the module for package modules. - The empty string for non-package top-level modules or the parent - package's ``__name__`` attribute for non-package submodules. + The empty string `''` for non-package top-level modules or the + parent package's ``__name__`` attribute for non-package submodules. .. attribute:: has_location From 11ed1366120c2a14b76602748bb583cd84d3c09c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9ry=20Ogam?= Date: Sun, 21 Oct 2018 20:09:13 +0200 Subject: [PATCH 03/46] Correct a typo --- Doc/library/importlib.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst index 7364c8869a6f85..3db711589fb9d9 100644 --- a/Doc/library/importlib.rst +++ b/Doc/library/importlib.rst @@ -1434,8 +1434,9 @@ an :term:`importer`. :exc:`ValueError` is raised if **name** is a relative module name but package is a false value (e.g. ``None`` or the empty string). - :exc:`ValueError` is also raised a relative name would escape its containing - package (e.g. requesting ``..bacon`` from within the ``spam`` package). + :exc:`ValueError` is also raised if a relative name would escape its + containing package (e.g. requesting ``..bacon`` from within the ``spam`` + package). .. versionadded:: 3.3 From 9a8d8e6614f86c81fc805519bc93797a51566831 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9ry=20Ogam?= Date: Mon, 26 Nov 2018 22:52:50 +0100 Subject: [PATCH 04/46] Fix and improve wording --- Doc/library/importlib.rst | 76 +++++++++++++++++++++------------------ 1 file changed, 41 insertions(+), 35 deletions(-) diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst index 3db711589fb9d9..f2673967263f79 100644 --- a/Doc/library/importlib.rst +++ b/Doc/library/importlib.rst @@ -420,30 +420,34 @@ ABC hierarchy:: reloaded): - :attr:`__name__` - The name of the module. + The module's fully-qualified name. - :attr:`__file__` - The path to where the module data is stored (not set for built-in - modules). + The location of the module's source code. + It is not set for built-in modules and frozen modules + and ``None`` for namespace packages. - :attr:`__cached__` - The path to where a compiled version of the module is/should be - stored (not set when the attribute would be inappropriate). + The location of the module's compiled code. + It is not set for built-in modules, frozen modules + and namespace packages. - :attr:`__path__` - A list of strings specifying the search path within a - package. This attribute is not set on modules. + The iterable (possibly empty) of the locations of the module's + submodules. + It is not set for non-package modules. - :attr:`__package__` - The parent package for the module/package. If the module is - top-level then it has a value of the empty string. The - :func:`importlib.util.module_for_loader` decorator can handle the - details for :attr:`__package__`. + The module's ``__name__`` attribute for a package, the parent + package's ``__name__`` attribute for a non-package submodule and + the empty string ``''`` for a non-package top-level module. + The :func:`importlib.util.module_for_loader` decorator can handle + the details for :attr:`__package__`. - :attr:`__loader__` - The loader used to load the module. The - :func:`importlib.util.module_for_loader` decorator can handle the - details for :attr:`__package__`. + The module's loader. + The :func:`importlib.util.module_for_loader` decorator can handle + the details for :attr:`__package__`. When :meth:`exec_module` is available then backwards-compatible functionality is provided. @@ -1285,11 +1289,12 @@ find and load modules. typically exposed as the module's ``__spec__`` attribute. In the descriptions below, the names in parentheses give the corresponding attribute available directly on the module object. - E.g. ``module.__spec__.origin == module.__file__``. Note however that - while the *values* are usually equivalent, they can differ since there is - no synchronization between the two objects. Thus it is possible to update - the module's ``__path__`` at runtime, and this will not be automatically - reflected in ``__spec__.submodule_search_locations``. + E.g., ``module.__spec__.name == module.__name__``. Note however that + while the *values* are usually equivalent, they can differ since there + is no synchronization between the two objects. Thus it is possible + to update the module's ``__path__`` at runtime for instance, and this + will not be automatically reflected in the module's + ``__spec__.submodule_search_locations``. .. versionadded:: 3.4 @@ -1297,52 +1302,53 @@ find and load modules. (``__name__``) - Fully-qualified name of the module. + The module's fully-qualified name. .. attribute:: loader (``__loader__``) - Loader object to use for loading the module. + The module's loader. .. attribute:: origin (``__file__``) - Path to the code from where the module should be loaded. - It is ``None`` for builtin modules and namespace package modules. + The location of the module's source code. + It is ``'built-in'`` for built-in modules, ``'frozen'`` for + frozen modules and ``None`` for namespace packages. .. attribute:: submodule_search_locations (``__path__``) - Iterable (possibly empty) of locations to search for submodules of a - package module during import. It is `None` for non-package modules. + The iterable (possibly empty) of the locations of the module's + submodules. + It is ``None`` for non-package modules. .. attribute:: loader_state - Container of extra module-specific data for use during loading (or - ``None``). + The container of module's extra data. .. attribute:: cached (``__cached__``) - - Path to the compiled code from where the module should be loaded. - It is ``None`` for builtin modules and namespace package modules. + The location of the module's compiled code. + It is ``None`` for built-in modules, frozen modules and + namespace packages. .. attribute:: parent (``__package__``) - The ``__name__`` attribute of the module for package modules. - The empty string `''` for non-package top-level modules or the - parent package's ``__name__`` attribute for non-package submodules. + The module's ``__name__`` attribute for a package, the parent + package's ``__name__`` attribute for a non-package submodule and + the empty string ``''`` for a non-package top-level module. .. attribute:: has_location - Boolean indicating whether or not the module's ``origin`` - attribute refers to a loadable location. + The flag indicating whether or not the module's ``__origin__`` attribute + refers to a location. :mod:`importlib.util` -- Utility code for importers --------------------------------------------------- From 859ff69b0dca1d361c8484af16cdfc4b95d84217 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9ry=20Ogam?= Date: Mon, 26 Nov 2018 23:28:53 +0100 Subject: [PATCH 05/46] Document the read-only property for spec.parent --- Doc/library/importlib.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst index f2673967263f79..b5aae4adbcba1e 100644 --- a/Doc/library/importlib.rst +++ b/Doc/library/importlib.rst @@ -1344,6 +1344,7 @@ find and load modules. The module's ``__name__`` attribute for a package, the parent package's ``__name__`` attribute for a non-package submodule and the empty string ``''`` for a non-package top-level module. + It is a read-only attribute. .. attribute:: has_location From 1f63f5ba11e0012106f58db78c7f737455514c86 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9ry=20Ogam?= Date: Sun, 2 Dec 2018 13:19:27 +0100 Subject: [PATCH 06/46] Add information on the loader_state and has_location attributes --- Doc/library/importlib.rst | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst index b5aae4adbcba1e..e389bb7f865af6 100644 --- a/Doc/library/importlib.rst +++ b/Doc/library/importlib.rst @@ -1314,7 +1314,7 @@ find and load modules. (``__file__``) - The location of the module's source code. + The origin of the module's source code. It is ``'built-in'`` for built-in modules, ``'frozen'`` for frozen modules and ``None`` for namespace packages. @@ -1328,7 +1328,8 @@ find and load modules. .. attribute:: loader_state - The container of module's extra data. + The container of the module's additional data meant for use by + the finder and corresponding loader. .. attribute:: cached @@ -1350,6 +1351,8 @@ find and load modules. The flag indicating whether or not the module's ``__origin__`` attribute refers to a location. + It is ``False`` for built-in modules, frozen modules, + namespace packages and modules dynamically created in code. :mod:`importlib.util` -- Utility code for importers --------------------------------------------------- From 98fdbf70222cbc22cda404726daa129df2533a50 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9ry=20Ogam?= Date: Thu, 2 May 2019 08:39:50 +0200 Subject: [PATCH 07/46] Update importlib.rst --- Doc/library/importlib.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst index e389bb7f865af6..aab7d4c53758e1 100644 --- a/Doc/library/importlib.rst +++ b/Doc/library/importlib.rst @@ -424,8 +424,8 @@ ABC hierarchy:: - :attr:`__file__` The location of the module's source code. - It is not set for built-in modules and frozen modules - and ``None`` for namespace packages. + It is ``None`` for namespace packages and not set for built-in + modules and frozen modules. - :attr:`__cached__` The location of the module's compiled code. From ac69aa18e262a597b1176116b52c4da365089c43 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9ry=20Ogam?= Date: Sat, 1 Jun 2019 09:27:56 +0200 Subject: [PATCH 08/46] Apply suggestions from code review Co-Authored-By: Brett Cannon <54418+brettcannon@users.noreply.github.com> --- Doc/library/importlib.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst index aab7d4c53758e1..dae22b8455ca99 100644 --- a/Doc/library/importlib.rst +++ b/Doc/library/importlib.rst @@ -440,7 +440,7 @@ ABC hierarchy:: - :attr:`__package__` The module's ``__name__`` attribute for a package, the parent package's ``__name__`` attribute for a non-package submodule and - the empty string ``''`` for a non-package top-level module. + ``''`` for a non-package top-level module. The :func:`importlib.util.module_for_loader` decorator can handle the details for :attr:`__package__`. @@ -1322,7 +1322,7 @@ find and load modules. (``__path__``) - The iterable (possibly empty) of the locations of the module's + The (possibly empty) iterable of the locations of the module's submodules. It is ``None`` for non-package modules. @@ -1344,7 +1344,7 @@ find and load modules. The module's ``__name__`` attribute for a package, the parent package's ``__name__`` attribute for a non-package submodule and - the empty string ``''`` for a non-package top-level module. + ``''`` for a non-package top-level module. It is a read-only attribute. .. attribute:: has_location From 8bbdb644be4a70c9457533ecafd4bbd27724372f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9ry=20Ogam?= Date: Tue, 4 Jun 2019 09:19:28 +0200 Subject: [PATCH 09/46] Update importlib.rst --- Doc/library/importlib.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst index dae22b8455ca99..3d2cb975598a6f 100644 --- a/Doc/library/importlib.rst +++ b/Doc/library/importlib.rst @@ -1288,13 +1288,13 @@ find and load modules. A specification for a module's import-system-related state. This is typically exposed as the module's ``__spec__`` attribute. In the descriptions below, the names in parentheses give the corresponding - attribute available directly on the module object. - E.g., ``module.__spec__.name == module.__name__``. Note however that - while the *values* are usually equivalent, they can differ since there - is no synchronization between the two objects. Thus it is possible - to update the module's ``__path__`` at runtime for instance, and this - will not be automatically reflected in the module's - ``__spec__.submodule_search_locations``. + attribute available directly on the module object. For example, + ``module.__spec__.name == module.__name__``. Note however that while + the *values* are usually equivalent, they can differ since there is no + synchronization between the two objects. For exemple, it is possible + to update the module's ``__name__`` at runtime and this will not be + automatically reflected in the module's ``__spec__.name``, or the + other way round. .. versionadded:: 3.4 From e126a5eb7f2dfa0718e283786e2ad0b7f11b756d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9ry=20Ogam?= Date: Tue, 4 Jun 2019 09:20:58 +0200 Subject: [PATCH 10/46] Update importlib.rst --- Doc/library/importlib.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst index 3d2cb975598a6f..27daf4ce6ab28d 100644 --- a/Doc/library/importlib.rst +++ b/Doc/library/importlib.rst @@ -1291,9 +1291,9 @@ find and load modules. attribute available directly on the module object. For example, ``module.__spec__.name == module.__name__``. Note however that while the *values* are usually equivalent, they can differ since there is no - synchronization between the two objects. For exemple, it is possible + synchronization between the two objects. For example, it is possible to update the module's ``__name__`` at runtime and this will not be - automatically reflected in the module's ``__spec__.name``, or the + automatically reflected in the module's ``__spec__.name``, or the other way round. .. versionadded:: 3.4 From 7b7eb9deb1d290419bbbf9b935169fa678fbeba3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9ry=20Ogam?= Date: Sun, 30 Jun 2019 17:05:14 +0200 Subject: [PATCH 11/46] Update importlib.rst --- Doc/library/importlib.rst | 122 +++++++++++++++++++++++++++----------- 1 file changed, 86 insertions(+), 36 deletions(-) diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst index 27daf4ce6ab28d..f1437be84ce8b7 100644 --- a/Doc/library/importlib.rst +++ b/Doc/library/importlib.rst @@ -421,31 +421,50 @@ ABC hierarchy:: - :attr:`__name__` The module's fully-qualified name. + It is ``'__main__'`` for non-package modules run from the file + system, non-package modules run from standard input and non-package + modules run from the module namespace. - :attr:`__file__` - The location of the module's source code. - It is ``None`` for namespace packages and not set for built-in - modules and frozen modules. + The place from which the module's data was imported. Its value and + meaning is up to the finder. + It is the relative path for modules run from the file system, the + absolute path for imported modules and modules run from the module + namespace and ``''`` for non-package modules run from + standard input. + It is not set for imported namespace packages, imported built-in + modules and imported frozen modules. - :attr:`__cached__` - The location of the module's compiled code. - It is not set for built-in modules, frozen modules - and namespace packages. + The location of the module's cached data. + It is the relative path for packages run from the file system and + the absolute path for imported modules and modules run from the + module namespace. + It is not set for non-package modules run from the file system, + non-package modules run from standard input, imported namespace + packages, imported built-in modules and imported frozen modules. - :attr:`__path__` - The iterable (possibly empty) of the locations of the module's - submodules. - It is not set for non-package modules. + The (possibly empty) iterable of all locations to search (i.e. the + search path) when looking for the package's submodules. Order is + significant. ``__path__`` is passed to finders instead of + ``sys.metapath`` during import of the package's submodules. + It is not set for non-package modules, packages run from the file + system and packages run from the module namespace. - :attr:`__package__` - The module's ``__name__`` attribute for a package, the parent - package's ``__name__`` attribute for a non-package submodule and - ``''`` for a non-package top-level module. + The module's ``__spec.__name`` attribute for imported packages and + packages run from the module namespace, the parent package's + ``__spec__.name`` attribute for imported non-package submodules and + non-paclage submodules run from the module namespace and ``''`` for + packages run from the file system, imported non-package top-level + modules and non-package top-level modules run from the module + namespace. The :func:`importlib.util.module_for_loader` decorator can handle the details for :attr:`__package__`. - :attr:`__loader__` - The module's loader. + The loader used when the module was imported. The :func:`importlib.util.module_for_loader` decorator can handle the details for :attr:`__package__`. @@ -1289,12 +1308,12 @@ find and load modules. typically exposed as the module's ``__spec__`` attribute. In the descriptions below, the names in parentheses give the corresponding attribute available directly on the module object. For example, - ``module.__spec__.name == module.__name__``. Note however that while + ``module.__spec__.origin == module.__file__``. Note however that while the *values* are usually equivalent, they can differ since there is no synchronization between the two objects. For example, it is possible - to update the module's ``__name__`` at runtime and this will not be - automatically reflected in the module's ``__spec__.name``, or the - other way round. + to update the module's ``__file__`` at runtime and this will not be + automatically reflected in the module's ``__spec__.origin``, and vice + versa. .. versionadded:: 3.4 @@ -1303,56 +1322,87 @@ find and load modules. (``__name__``) The module's fully-qualified name. + It is not set for non-package modules run from the file system and + non-package modules run from standard input. .. attribute:: loader (``__loader__``) - The module's loader. + The loader to use for importing the module. + It is not set for non-package modules run from the file system and + non-package modules run from standard input. .. attribute:: origin (``__file__``) - The origin of the module's source code. - It is ``'built-in'`` for built-in modules, ``'frozen'`` for - frozen modules and ``None`` for namespace packages. + The place from which the module's data was imported. Its value and meaning + is up to the finder. + It is the relative path for packages run from the file system and the + absolute path for imported modules and modules run from the module + namespace. + It is ``None`` for imported namespace packages, ``'built-in'`` for imported + built-in modules and ``'frozen'`` for imported frozen modules. + It is not set for non-package modules run from the file system and + non-package modules run from standard input. .. attribute:: submodule_search_locations (``__path__``) - The (possibly empty) iterable of the locations of the module's - submodules. - It is ``None`` for non-package modules. + The (possibly empty) iterable of all locations to search (i.e. the search + path) when looking for the package's submodules. Order is significant. + It is ``None`` for packages run from the file system, imported non-package + modules and modules run from the module namespace. + It is not set for non-package modules run from the file system and + non-package modules run from standard input. .. attribute:: loader_state - The container of the module's additional data meant for use by - the finder and corresponding loader. + The finder may set this to an object containing additional data for the + loader to use when loading the module. Otherwise it will be ``None``. .. attribute:: cached (``__cached__``) - The location of the module's compiled code. - It is ``None`` for built-in modules, frozen modules and - namespace packages. + + The location of the module's cached data. Some loaders support optimization + through caching the bytecode of the module. ``cached`` is how the finder + tells the loader where to look for that cached bytecode, or where to store + it. + It is the relative path for packages run from the file system and the + absolute path for imported modules and modules run from the module + namespace. + It is ``None`` for imported namespace packages, imported built-in modules + and imported frozen modules. + It is not set for non-package modules run from the file system and + non-package modules run from standard input. .. attribute:: parent (``__package__``) - The module's ``__name__`` attribute for a package, the parent - package's ``__name__`` attribute for a non-package submodule and - ``''`` for a non-package top-level module. + The module's ``__spec.__name`` attribute for imported packages and packages + run from the module namespace, the parent package's ``__spec__.name`` + attribute for imported non-package submodules and non-paclage submodules run + from the module namespace and ``''`` for packages run from the file system, + imported non-package top-level modules and non-package top-level modules run + from the module namespace. + It is not set for non-package modules run from the file system and + non-package modules run from standard input. It is a read-only attribute. .. attribute:: has_location - The flag indicating whether or not the module's ``__origin__`` attribute - refers to a location. - It is ``False`` for built-in modules, frozen modules, - namespace packages and modules dynamically created in code. + The boolean indicating whether or not the module's ``origin`` attribute + refers to a locatable resource. + It is ``True`` for packages run from the file system, imported modules and + modules run from the module namespace. + It is ``False`` for imported namespace packages, imported built-in modules, + imported frozen modules and modules dynamically created in code. + It is not set for non-package modules run from the file system and + non-package modules run from standard input. :mod:`importlib.util` -- Utility code for importers --------------------------------------------------- From 5290628801f495bb45855810d64b3c4f7f7c2662 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9ry=20Ogam?= Date: Sun, 30 Jun 2019 17:32:29 +0200 Subject: [PATCH 12/46] Update importlib.rst --- Doc/library/importlib.rst | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst index f1437be84ce8b7..086488cb2dde88 100644 --- a/Doc/library/importlib.rst +++ b/Doc/library/importlib.rst @@ -1398,9 +1398,8 @@ find and load modules. The boolean indicating whether or not the module's ``origin`` attribute refers to a locatable resource. It is ``True`` for packages run from the file system, imported modules and - modules run from the module namespace. - It is ``False`` for imported namespace packages, imported built-in modules, - imported frozen modules and modules dynamically created in code. + modules run from the module namespace and ``False`` for imported namespace + packages, imported built-in modules and imported frozen modules. It is not set for non-package modules run from the file system and non-package modules run from standard input. From 89efbfffaf24e8c624a2bf5894328073032b6275 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9ry=20Ogam?= Date: Sun, 30 Jun 2019 17:53:34 +0200 Subject: [PATCH 13/46] Update importlib.rst --- Doc/library/importlib.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst index 086488cb2dde88..511dde1faa9997 100644 --- a/Doc/library/importlib.rst +++ b/Doc/library/importlib.rst @@ -1395,8 +1395,8 @@ find and load modules. .. attribute:: has_location - The boolean indicating whether or not the module's ``origin`` attribute - refers to a locatable resource. + The Boolean indicating whether or not the module's ``origin`` attribute + refers to a locatable module. It is ``True`` for packages run from the file system, imported modules and modules run from the module namespace and ``False`` for imported namespace packages, imported built-in modules and imported frozen modules. From 8ba8ede927aa1ce45e9159c16a62d94de6296b92 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9ry=20Ogam?= Date: Sat, 13 Jul 2019 10:17:49 +0200 Subject: [PATCH 14/46] Apply suggestions from code review Co-Authored-By: Eric Snow --- Doc/library/importlib.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst index 511dde1faa9997..58b393e667ca92 100644 --- a/Doc/library/importlib.rst +++ b/Doc/library/importlib.rst @@ -1305,7 +1305,7 @@ find and load modules. .. class:: ModuleSpec(name, loader, *, origin=None, loader_state=None, is_package=None) A specification for a module's import-system-related state. This is - typically exposed as the module's ``__spec__`` attribute. In the + typically exposed as the module's :attr:`__spec__` attribute. In the descriptions below, the names in parentheses give the corresponding attribute available directly on the module object. For example, ``module.__spec__.origin == module.__file__``. Note however that while @@ -1319,7 +1319,7 @@ find and load modules. .. attribute:: name - (``__name__``) + (:attr:`__name__`) The module's fully-qualified name. It is not set for non-package modules run from the file system and @@ -1327,15 +1327,15 @@ find and load modules. .. attribute:: loader - (``__loader__``) + (:attr:`__loader__`) - The loader to use for importing the module. + The loader to use when importing the module. It is not set for non-package modules run from the file system and non-package modules run from standard input. .. attribute:: origin - (``__file__``) + (:attr:`__file__`) The place from which the module's data was imported. Its value and meaning is up to the finder. @@ -1349,7 +1349,7 @@ find and load modules. .. attribute:: submodule_search_locations - (``__path__``) + (:attr:`__path__`) The (possibly empty) iterable of all locations to search (i.e. the search path) when looking for the package's submodules. Order is significant. @@ -1365,7 +1365,7 @@ find and load modules. .. attribute:: cached - (``__cached__``) + (:attr:`__cached__`) The location of the module's cached data. Some loaders support optimization through caching the bytecode of the module. ``cached`` is how the finder @@ -1381,7 +1381,7 @@ find and load modules. .. attribute:: parent - (``__package__``) + (:attr:`__package__`) The module's ``__spec.__name`` attribute for imported packages and packages run from the module namespace, the parent package's ``__spec__.name`` From 2b7b6aa205e72b6de670cd683121574b694343b0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9ry=20Ogam?= Date: Sat, 13 Jul 2019 14:01:03 +0200 Subject: [PATCH 15/46] Update import.rst --- Doc/reference/import.rst | 90 ++++++++++++++++++++++++---------------- 1 file changed, 55 insertions(+), 35 deletions(-) diff --git a/Doc/reference/import.rst b/Doc/reference/import.rst index 44b5b818aa8233..69ec75290a3f50 100644 --- a/Doc/reference/import.rst +++ b/Doc/reference/import.rst @@ -538,26 +538,29 @@ the module. The ``__name__`` attribute must be set to the fully-qualified name of the module. This name is used to uniquely identify the module in the import system. + + ``__name__`` is set to ``'__main__'`` for non-package modules run + from the file system, non-package modules run from standard input + and non-package modules run from the module namespace. .. attribute:: __loader__ - The ``__loader__`` attribute must be set to the loader object that - the import machinery used when loading the module. This is mostly - for introspection, but can be used for additional loader-specific + The ``__loader__`` attribute must be set to the loader that the import + machinery used when loading the module. This is mostly for + introspection, but can be used for additional loader-specific functionality, for example getting data associated with a loader. .. attribute:: __package__ - The module's ``__package__`` attribute must be set. Its value must - be a string, but it can be the same value as its ``__name__``. When - the module is a package, its ``__package__`` value should be set to - its ``__name__``. When the module is not a package, ``__package__`` - should be set to the empty string for top-level modules, or for - submodules, to the parent package's name. See :pep:`366` for further - details. + The ``__package__`` attribute must be set to the fully-qualified name + of the package the module is in. When the module is a package, it is + set to its ``__name__`` attribute. When the module is not a package, + it is set to the empty string for top-level modules, or for + submodules, to the parent package's ``__name__`` attribute. See + :pep:`366` for further details. This attribute is used instead of ``__name__`` to calculate explicit - relative imports for main modules, as defined in :pep:`366`. It is + relative imports for main modules, as defined in :pep:`366`. It is expected to have the same value as ``__spec__.parent``. .. versionchanged:: 3.6 @@ -567,10 +570,10 @@ the module. .. attribute:: __spec__ The ``__spec__`` attribute must be set to the module spec that was - used when importing the module. Setting ``__spec__`` - appropriately applies equally to :ref:`modules initialized during - interpreter startup `. The one exception is ``__main__``, - where ``__spec__`` is :ref:`set to None in some cases `. + used when importing the module. Setting ``__spec__`` appropriately + applies equally to :ref:`modules initialized during interpreter + startup `. The one exception is ``__main__``, where + ``__spec__`` is :ref:`set to None in some cases `. When ``__package__`` is not defined, ``__spec__.parent`` is used as a fallback. @@ -583,33 +586,50 @@ the module. .. attribute:: __path__ - If the module is a package (either regular or namespace), the module - object's ``__path__`` attribute must be set. The value must be - iterable, but may be empty if ``__path__`` has no further significance. - If ``__path__`` is not empty, it must produce strings when iterated - over. More details on the semantics of ``__path__`` are given + If the module is a package, the ``__path__`` attribute must be set to an + iterable specifying the submodule search path within a package. If + ``__path__`` is empty, it has no further significance. If ``__path__`` + is not empty, it must produce strings when iterated over. More details + on the semantics of ``__path__`` are given :ref:`below `. - Non-package modules should not have a ``__path__`` attribute. + ``__path__`` is not set for non-package modules, packages run from the + file system and packages run from the module namespace. .. attribute:: __file__ -.. attribute:: __cached__ - ``__file__`` is optional. If set, this attribute's value must be a - string. The import system may opt to leave ``__file__`` unset if it - has no semantic meaning (e.g. a module loaded from a database). + The ``__file__`` attribute is optional. If ``__file__`` is set, it + must be set to the location from which the module was imported. The + import system may opt to leave ``__file__`` unset if it has no + semantic meaning (e.g. a module loaded from a database). + + ``__file__`` is set to the relative path to the code for modules run + from the file system, the absolute path to the code for imported + modules and modules run from the module namespace and ``''`` + for non-package modules run from standard input. ``__file__`` is + not set for imported namespace packages, imported built-in modules + and imported frozen modules. + +.. attribute:: __cached__ If ``__file__`` is set, it may also be appropriate to set the - ``__cached__`` attribute which is the path to any compiled version of - the code (e.g. byte-compiled file). The file does not need to exist - to set this attribute; the path can simply point to where the - compiled file would exist (see :pep:`3147`). - - It is also appropriate to set ``__cached__`` when ``__file__`` is not - set. However, that scenario is quite atypical. Ultimately, the - loader is what makes use of ``__file__`` and/or ``__cached__``. So - if a loader can load from a cached module but otherwise does not load - from a file, that atypical scenario may be appropriate. + ``__cached__`` attribute which must be set to the path to any compiled + version of the code (e.g. byte-compiled file). The file does not need + to exist to set this attribute; the path can simply point to where the + compiled file would exist (see :pep:`3147`). If ``__file__`` is not + set, it is also appropriate to set ``__cached__``. However, that + scenario is quite atypical. Ultimately, the loader is what makes use + of ``__file__`` and/or ``__cached__``. So if a loader can load from a + cached module but otherwise does not load from a file, that atypical + scenario may be appropriate. + + ``__cached__`` is set to the relative path to the compiled code for + packages run from the file system and the absolute path to the + compiled code for imported modules and modules run from the module + namespace. ``__cached__`` is not set for non-package modules run from + the file system, non-package modules run from standard input, imported + namespace packages, imported built-in modules and imported frozen + modules. .. _package-path-rules: From c71487c6caa208cdec5229fd8560bd9595668dd1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9ry=20Ogam?= Date: Sat, 13 Jul 2019 14:27:34 +0200 Subject: [PATCH 16/46] Update import.rst --- Doc/reference/import.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Doc/reference/import.rst b/Doc/reference/import.rst index 69ec75290a3f50..f48baada016599 100644 --- a/Doc/reference/import.rst +++ b/Doc/reference/import.rst @@ -555,9 +555,9 @@ the module. The ``__package__`` attribute must be set to the fully-qualified name of the package the module is in. When the module is a package, it is set to its ``__name__`` attribute. When the module is not a package, - it is set to the empty string for top-level modules, or for - submodules, to the parent package's ``__name__`` attribute. See - :pep:`366` for further details. + it is set to the empty string on top-level modules and to the parent + package's ``__name__`` attribute on submodules. See :pep:`366` for + further details. This attribute is used instead of ``__name__`` to calculate explicit relative imports for main modules, as defined in :pep:`366`. It is From d7e66f60fc8602e54563ab39bfe587cfde75d97b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9ry=20Ogam?= Date: Sat, 13 Jul 2019 15:28:29 +0200 Subject: [PATCH 17/46] Update import.rst --- Doc/reference/import.rst | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/Doc/reference/import.rst b/Doc/reference/import.rst index f48baada016599..b3a55402b23160 100644 --- a/Doc/reference/import.rst +++ b/Doc/reference/import.rst @@ -553,11 +553,9 @@ the module. .. attribute:: __package__ The ``__package__`` attribute must be set to the fully-qualified name - of the package the module is in. When the module is a package, it is - set to its ``__name__`` attribute. When the module is not a package, - it is set to the empty string on top-level modules and to the parent - package's ``__name__`` attribute on submodules. See :pep:`366` for - further details. + of the package the module is in (or the empty string for top-level + modules). For packages, it is the same as ``__name__``. See + :pep:`366` for further details. This attribute is used instead of ``__name__`` to calculate explicit relative imports for main modules, as defined in :pep:`366`. It is From 2123bb0d3d9f903c07b42c994e1c9d868a1f2d80 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9ry=20Ogam?= Date: Sat, 13 Jul 2019 15:42:51 +0200 Subject: [PATCH 18/46] Update import.rst --- Doc/reference/import.rst | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/Doc/reference/import.rst b/Doc/reference/import.rst index b3a55402b23160..999958903ff3e5 100644 --- a/Doc/reference/import.rst +++ b/Doc/reference/import.rst @@ -538,7 +538,7 @@ the module. The ``__name__`` attribute must be set to the fully-qualified name of the module. This name is used to uniquely identify the module in the import system. - + ``__name__`` is set to ``'__main__'`` for non-package modules run from the file system, non-package modules run from standard input and non-package modules run from the module namespace. @@ -585,13 +585,13 @@ the module. .. attribute:: __path__ If the module is a package, the ``__path__`` attribute must be set to an - iterable specifying the submodule search path within a package. If + iterable specifying the submodule search path within that package. If ``__path__`` is empty, it has no further significance. If ``__path__`` is not empty, it must produce strings when iterated over. More details on the semantics of ``__path__`` are given :ref:`below `. - ``__path__`` is not set for non-package modules, packages run from the + ``__path__`` is not set on non-package modules, packages run from the file system and packages run from the module namespace. .. attribute:: __file__ @@ -600,12 +600,12 @@ the module. must be set to the location from which the module was imported. The import system may opt to leave ``__file__`` unset if it has no semantic meaning (e.g. a module loaded from a database). - - ``__file__`` is set to the relative path to the code for modules run - from the file system, the absolute path to the code for imported + + ``__file__`` is set to the relative path to the code on modules run + from the file system, the absolute path to the code on imported modules and modules run from the module namespace and ``''`` - for non-package modules run from standard input. ``__file__`` is - not set for imported namespace packages, imported built-in modules + on non-package modules run from standard input. ``__file__`` is + not set on imported namespace packages, imported built-in modules and imported frozen modules. .. attribute:: __cached__ @@ -620,11 +620,11 @@ the module. of ``__file__`` and/or ``__cached__``. So if a loader can load from a cached module but otherwise does not load from a file, that atypical scenario may be appropriate. - - ``__cached__`` is set to the relative path to the compiled code for + + ``__cached__`` is set to the relative path to the compiled code on packages run from the file system and the absolute path to the - compiled code for imported modules and modules run from the module - namespace. ``__cached__`` is not set for non-package modules run from + compiled code on imported modules and modules run from the module + namespace. ``__cached__`` is not set on non-package modules run from the file system, non-package modules run from standard input, imported namespace packages, imported built-in modules and imported frozen modules. From 3abaa63cba1b7e8cb7d33c4531446841b76fc573 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9ry=20Ogam?= Date: Sat, 13 Jul 2019 15:45:06 +0200 Subject: [PATCH 19/46] Update importlib.rst --- Doc/library/importlib.rst | 45 +++++++++------------------------------ 1 file changed, 10 insertions(+), 35 deletions(-) diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst index 58b393e667ca92..4bf598a88c20e2 100644 --- a/Doc/library/importlib.rst +++ b/Doc/library/importlib.rst @@ -421,52 +421,27 @@ ABC hierarchy:: - :attr:`__name__` The module's fully-qualified name. - It is ``'__main__'`` for non-package modules run from the file - system, non-package modules run from standard input and non-package - modules run from the module namespace. - :attr:`__file__` - The place from which the module's data was imported. Its value and - meaning is up to the finder. - It is the relative path for modules run from the file system, the - absolute path for imported modules and modules run from the module - namespace and ``''`` for non-package modules run from - standard input. - It is not set for imported namespace packages, imported built-in - modules and imported frozen modules. + The location (usually filename) from which the module was imported. + It is not set on all modules (e.g. built-in modules). - :attr:`__cached__` - The location of the module's cached data. - It is the relative path for packages run from the file system and - the absolute path for imported modules and modules run from the - module namespace. - It is not set for non-package modules run from the file system, - non-package modules run from standard input, imported namespace - packages, imported built-in modules and imported frozen modules. + The path to where a compiled version of the module is stored. + It is not set when the attribute would be inappropriate. - :attr:`__path__` - The (possibly empty) iterable of all locations to search (i.e. the - search path) when looking for the package's submodules. Order is - significant. ``__path__`` is passed to finders instead of - ``sys.metapath`` during import of the package's submodules. - It is not set for non-package modules, packages run from the file - system and packages run from the module namespace. + The (possibly empty) iterable specifying the submodule search path + within a package. + It is not set on non-package modules. - :attr:`__package__` - The module's ``__spec.__name`` attribute for imported packages and - packages run from the module namespace, the parent package's - ``__spec__.name`` attribute for imported non-package submodules and - non-paclage submodules run from the module namespace and ``''`` for - packages run from the file system, imported non-package top-level - modules and non-package top-level modules run from the module - namespace. - The :func:`importlib.util.module_for_loader` decorator can handle - the details for :attr:`__package__`. + The fully-qualified name of the package the module is in (or the + empty string for top-level modules). For packages, it is the same + as ``__name__``. - :attr:`__loader__` The loader used when the module was imported. - The :func:`importlib.util.module_for_loader` decorator can handle - the details for :attr:`__package__`. When :meth:`exec_module` is available then backwards-compatible functionality is provided. From 084915dcef4c64be12dd19bbf3f8b354acb2c536 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9ry=20Ogam?= Date: Sat, 13 Jul 2019 17:13:59 +0200 Subject: [PATCH 20/46] Update importlib.rst --- Doc/library/importlib.rst | 90 ++++++++++++++------------------------- 1 file changed, 31 insertions(+), 59 deletions(-) diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst index 4bf598a88c20e2..8ae55ed3a2a20e 100644 --- a/Doc/library/importlib.rst +++ b/Doc/library/importlib.rst @@ -423,25 +423,25 @@ ABC hierarchy:: The module's fully-qualified name. - :attr:`__file__` - The location (usually filename) from which the module was imported. + The location from which the module was loaded (usually the path). It is not set on all modules (e.g. built-in modules). - :attr:`__cached__` - The path to where a compiled version of the module is stored. + The path to a compiled version of the code. It is not set when the attribute would be inappropriate. - :attr:`__path__` - The (possibly empty) iterable specifying the submodule search path - within a package. + The (possibly empty) iterable specifying the submodule search paths + within the package. It is not set on non-package modules. - :attr:`__package__` - The fully-qualified name of the package the module is in (or the - empty string for top-level modules). For packages, it is the same - as ``__name__``. + The fully-qualified name of the package under which the module was + loaded as a submodule (or the empty string for top-level modules). + For packages, it is the same as :attr:`__name__`. - :attr:`__loader__` - The loader used when the module was imported. + The loader that was used when loading the module. When :meth:`exec_module` is available then backwards-compatible functionality is provided. @@ -1286,9 +1286,9 @@ find and load modules. ``module.__spec__.origin == module.__file__``. Note however that while the *values* are usually equivalent, they can differ since there is no synchronization between the two objects. For example, it is possible - to update the module's ``__file__`` at runtime and this will not be - automatically reflected in the module's ``__spec__.origin``, and vice - versa. + to update the module's :attr:`__file__` at runtime and this will not be + automatically reflected in the module's :attr:`__spec__.origin`, and + vice versa. .. versionadded:: 3.4 @@ -1296,42 +1296,33 @@ find and load modules. (:attr:`__name__`) - The module's fully-qualified name. - It is not set for non-package modules run from the file system and - non-package modules run from standard input. + The module's fully-qualified name. Finders should always set this. A + ``None`` value has special meaning. .. attribute:: loader (:attr:`__loader__`) - The loader to use when importing the module. - It is not set for non-package modules run from the file system and - non-package modules run from standard input. + The loader that should be used when loading the module. Finders should + always set this. A ``None`` value is reserved for namespace packages. .. attribute:: origin (:attr:`__file__`) - The place from which the module's data was imported. Its value and meaning - is up to the finder. - It is the relative path for packages run from the file system and the - absolute path for imported modules and modules run from the module - namespace. - It is ``None`` for imported namespace packages, ``'built-in'`` for imported - built-in modules and ``'frozen'`` for imported frozen modules. - It is not set for non-package modules run from the file system and - non-package modules run from standard input. + The location from which the module should be loaded (e.g. ``'builtin'`` + for built-in modules and the path for modules loaded from source). + Finders should normally set this attribute, but it may be ``None`` (the + default) which indicates it is unspecified (like for namespace packages). .. attribute:: submodule_search_locations (:attr:`__path__`) - The (possibly empty) iterable of all locations to search (i.e. the search - path) when looking for the package's submodules. Order is significant. - It is ``None`` for packages run from the file system, imported non-package - modules and modules run from the module namespace. - It is not set for non-package modules run from the file system and - non-package modules run from standard input. + The (possibly empty) iterable specifying the submodule search paths + within the package (or ``None`` if not a package). Finders must set + this on a package, even if just to an empty list. For namespace + packages (where :attr:`origin` is ``None``) this is set automatically. .. attribute:: loader_state @@ -1342,41 +1333,22 @@ find and load modules. (:attr:`__cached__`) - The location of the module's cached data. Some loaders support optimization - through caching the bytecode of the module. ``cached`` is how the finder - tells the loader where to look for that cached bytecode, or where to store - it. - It is the relative path for packages run from the file system and the - absolute path for imported modules and modules run from the module - namespace. - It is ``None`` for imported namespace packages, imported built-in modules - and imported frozen modules. - It is not set for non-package modules run from the file system and - non-package modules run from standard input. + The path to where a compiled version of the code should be stored (or + ``None``). .. attribute:: parent (:attr:`__package__`) - The module's ``__spec.__name`` attribute for imported packages and packages - run from the module namespace, the parent package's ``__spec__.name`` - attribute for imported non-package submodules and non-paclage submodules run - from the module namespace and ``''`` for packages run from the file system, - imported non-package top-level modules and non-package top-level modules run - from the module namespace. - It is not set for non-package modules run from the file system and - non-package modules run from standard input. - It is a read-only attribute. + (Read-only) The fully-qualified name of the package under which the + module should be loaded as a submodule (or the empty string for top-level + modules). For packages, it is the same as :attr:`__name__`. .. attribute:: has_location - The Boolean indicating whether or not the module's ``origin`` attribute - refers to a locatable module. - It is ``True`` for packages run from the file system, imported modules and - modules run from the module namespace and ``False`` for imported namespace - packages, imported built-in modules and imported frozen modules. - It is not set for non-package modules run from the file system and - non-package modules run from standard input. + True if the spec's :attr:`origin` refers to a loadable location. False + otherwise. This value impacts how :attr:`origin` is interpreted and how + the module's :attr:`__file__`` is populated. :mod:`importlib.util` -- Utility code for importers --------------------------------------------------- From 88d267432b2adf048c3de1d7124ad084f1a5b8da Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9ry=20Ogam?= Date: Sat, 13 Jul 2019 17:14:05 +0200 Subject: [PATCH 21/46] Update import.rst --- Doc/reference/import.rst | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/Doc/reference/import.rst b/Doc/reference/import.rst index 999958903ff3e5..493c1247a8d868 100644 --- a/Doc/reference/import.rst +++ b/Doc/reference/import.rst @@ -545,17 +545,17 @@ the module. .. attribute:: __loader__ - The ``__loader__`` attribute must be set to the loader that the import - machinery used when loading the module. This is mostly for - introspection, but can be used for additional loader-specific - functionality, for example getting data associated with a loader. + The ``__loader__`` attribute must be set to the loader that was used + when loading the module. This is mostly for introspection, but can + be used for additional loader-specific functionality, for example + getting data associated with a loader. .. attribute:: __package__ The ``__package__`` attribute must be set to the fully-qualified name - of the package the module is in (or the empty string for top-level - modules). For packages, it is the same as ``__name__``. See - :pep:`366` for further details. + of the package under which the module was loaded as a submodule (or + the empty string for top-level modules). For packages, it is the same + as ``__name__``. See :pep:`366` for further details. This attribute is used instead of ``__name__`` to calculate explicit relative imports for main modules, as defined in :pep:`366`. It is @@ -585,7 +585,7 @@ the module. .. attribute:: __path__ If the module is a package, the ``__path__`` attribute must be set to an - iterable specifying the submodule search path within that package. If + iterable specifying the submodule search paths within that package. If ``__path__`` is empty, it has no further significance. If ``__path__`` is not empty, it must produce strings when iterated over. More details on the semantics of ``__path__`` are given @@ -611,7 +611,7 @@ the module. .. attribute:: __cached__ If ``__file__`` is set, it may also be appropriate to set the - ``__cached__`` attribute which must be set to the path to any compiled + ``__cached__`` attribute which must be set to the path to a compiled version of the code (e.g. byte-compiled file). The file does not need to exist to set this attribute; the path can simply point to where the compiled file would exist (see :pep:`3147`). If ``__file__`` is not From ee0625a746f8d2590ba1fa37a6628c5fbe367f6f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9ry=20Ogam?= Date: Fri, 9 Aug 2019 07:46:58 +0200 Subject: [PATCH 22/46] Apply suggestions from code review Co-Authored-By: Eric Snow --- Doc/library/importlib.rst | 29 +++++++++++++++++++++-------- 1 file changed, 21 insertions(+), 8 deletions(-) diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst index f7c06098581d41..06a393361727dd 100644 --- a/Doc/library/importlib.rst +++ b/Doc/library/importlib.rst @@ -431,7 +431,10 @@ ABC hierarchy:: It is not set when the attribute would be inappropriate. - :attr:`__path__` - The (possibly empty) iterable specifying the submodule search paths + For packages, the list of strings specifying where to look for submodules. + This is used in the same way as :attr:`sys.path`, but just for the package. + Effectively, it is the indicator that the module is a package. For + non-package modules ``__path__`` is not set. within the package. It is not set on non-package modules. @@ -1296,21 +1299,22 @@ find and load modules. (:attr:`__name__`) - The module's fully-qualified name. Finders should always set this. A - ``None`` value has special meaning. + The module's fully-qualified name. Finders should always set this to a + non-empty (identifier) string. The import system may set this to ``None`` + in a few special cases. .. attribute:: loader (:attr:`__loader__`) - The loader that should be used when loading the module. Finders should + The :class:`Loader ` that should be used when loading the module. Finders should always set this. A ``None`` value is reserved for namespace packages. .. attribute:: origin (:attr:`__file__`) - The location from which the module should be loaded (e.g. ``'builtin'`` + The name of where the module should be loaded from (e.g. ``'builtin'`` for built-in modules and the path for modules loaded from source). Finders should normally set this attribute, but it may be ``None`` (the default) which indicates it is unspecified (like for namespace packages). @@ -1319,21 +1323,30 @@ find and load modules. (:attr:`__path__`) - The (possibly empty) iterable specifying the submodule search paths + For packages, the Finder must set this to the iterable specifying the + locations where submodules may be found for the package, even if + it's just an empty list. + For non-package modules this should be set to ``None``. + For namespace packages (where :attr:`origin` is ``None``) this + is set automatically. within the package (or ``None`` if not a package). Finders must set this on a package, even if just to an empty list. For namespace packages (where :attr:`origin` is ``None``) this is set automatically. .. attribute:: loader_state - The finder may set this to an object containing additional data for the + The Finder may set this to an object containing additional, + module-specific data to use when loading the module. Otherwise + it should be set to ``None``. loader to use when loading the module. Otherwise it will be ``None``. .. attribute:: cached (:attr:`__cached__`) - The path to where a compiled version of the code should be stored (or + Where a compiled version of the code should be stored (or ``None``). + This is typically a filename as provided by + ::func::`importlib.util.cache_from_source`. ``None``). .. attribute:: parent From cd0edda18ea18c398192e398547aad4c3eb6a15d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9ry=20Ogam?= Date: Fri, 9 Aug 2019 07:54:47 +0200 Subject: [PATCH 23/46] Update importlib.rst --- Doc/library/importlib.rst | 22 ++++++++-------------- 1 file changed, 8 insertions(+), 14 deletions(-) diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst index 06a393361727dd..dca6c4964d5aa9 100644 --- a/Doc/library/importlib.rst +++ b/Doc/library/importlib.rst @@ -434,9 +434,7 @@ ABC hierarchy:: For packages, the list of strings specifying where to look for submodules. This is used in the same way as :attr:`sys.path`, but just for the package. Effectively, it is the indicator that the module is a package. For - non-package modules ``__path__`` is not set. - within the package. - It is not set on non-package modules. + non-package modules, it is not set. - :attr:`__package__` The fully-qualified name of the package under which the module was @@ -1307,8 +1305,9 @@ find and load modules. (:attr:`__loader__`) - The :class:`Loader ` that should be used when loading the module. Finders should - always set this. A ``None`` value is reserved for namespace packages. + The :class:`Loader ` that should be used when + loading the module. Finders should always set this. A ``None`` value + is reserved for namespace packages. .. attribute:: origin @@ -1326,19 +1325,15 @@ find and load modules. For packages, the Finder must set this to the iterable specifying the locations where submodules may be found for the package, even if it's just an empty list. - For non-package modules this should be set to ``None``. - For namespace packages (where :attr:`origin` is ``None``) this + For non-package modules, this should be set to ``None``. + For namespace packages (where :attr:`origin` is ``None``), this is set automatically. - within the package (or ``None`` if not a package). Finders must set - this on a package, even if just to an empty list. For namespace - packages (where :attr:`origin` is ``None``) this is set automatically. .. attribute:: loader_state The Finder may set this to an object containing additional, - module-specific data to use when loading the module. Otherwise - it should be set to ``None``. - loader to use when loading the module. Otherwise it will be ``None``. + module-specific data to use when loading the module. Otherwise it + should be set to ``None``. .. attribute:: cached @@ -1347,7 +1342,6 @@ find and load modules. Where a compiled version of the code should be stored (or ``None``). This is typically a filename as provided by ::func::`importlib.util.cache_from_source`. - ``None``). .. attribute:: parent From 8957275c64c782e584f348db2eab6f1695842a46 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9ry=20Ogam?= Date: Fri, 9 Aug 2019 09:18:45 +0200 Subject: [PATCH 24/46] Remove changes to the language reference (to do in another PR) --- Doc/reference/import.rst | 90 ++++++++++++++++------------------------ 1 file changed, 36 insertions(+), 54 deletions(-) diff --git a/Doc/reference/import.rst b/Doc/reference/import.rst index 9fb10582ba2e70..0228bfb7e984c5 100644 --- a/Doc/reference/import.rst +++ b/Doc/reference/import.rst @@ -538,26 +538,25 @@ the module. the module. This name is used to uniquely identify the module in the import system. - ``__name__`` is set to ``'__main__'`` for non-package modules run - from the file system, non-package modules run from standard input - and non-package modules run from the module namespace. - .. attribute:: __loader__ - The ``__loader__`` attribute must be set to the loader that was used - when loading the module. This is mostly for introspection, but can - be used for additional loader-specific functionality, for example - getting data associated with a loader. + The ``__loader__`` attribute must be set to the loader object that + the import machinery used when loading the module. This is mostly + for introspection, but can be used for additional loader-specific + functionality, for example getting data associated with a loader. .. attribute:: __package__ - The ``__package__`` attribute must be set to the fully-qualified name - of the package under which the module was loaded as a submodule (or - the empty string for top-level modules). For packages, it is the same - as ``__name__``. See :pep:`366` for further details. + The module's ``__package__`` attribute must be set. Its value must + be a string, but it can be the same value as its ``__name__``. When + the module is a package, its ``__package__`` value should be set to + its ``__name__``. When the module is not a package, ``__package__`` + should be set to the empty string for top-level modules, or for + submodules, to the parent package's name. See :pep:`366` for further + details. This attribute is used instead of ``__name__`` to calculate explicit - relative imports for main modules, as defined in :pep:`366`. It is + relative imports for main modules, as defined in :pep:`366`. It is expected to have the same value as ``__spec__.parent``. .. versionchanged:: 3.6 @@ -567,10 +566,10 @@ the module. .. attribute:: __spec__ The ``__spec__`` attribute must be set to the module spec that was - used when importing the module. Setting ``__spec__`` appropriately - applies equally to :ref:`modules initialized during interpreter - startup `. The one exception is ``__main__``, where - ``__spec__`` is :ref:`set to None in some cases `. + used when importing the module. Setting ``__spec__`` + appropriately applies equally to :ref:`modules initialized during + interpreter startup `. The one exception is ``__main__``, + where ``__spec__`` is :ref:`set to None in some cases `. When ``__package__`` is not defined, ``__spec__.parent`` is used as a fallback. @@ -583,50 +582,33 @@ the module. .. attribute:: __path__ - If the module is a package, the ``__path__`` attribute must be set to an - iterable specifying the submodule search paths within that package. If - ``__path__`` is empty, it has no further significance. If ``__path__`` - is not empty, it must produce strings when iterated over. More details - on the semantics of ``__path__`` are given + If the module is a package (either regular or namespace), the module + object's ``__path__`` attribute must be set. The value must be + iterable, but may be empty if ``__path__`` has no further significance. + If ``__path__`` is not empty, it must produce strings when iterated + over. More details on the semantics of ``__path__`` are given :ref:`below `. - ``__path__`` is not set on non-package modules, packages run from the - file system and packages run from the module namespace. + Non-package modules should not have a ``__path__`` attribute. .. attribute:: __file__ - - The ``__file__`` attribute is optional. If ``__file__`` is set, it - must be set to the location from which the module was imported. The - import system may opt to leave ``__file__`` unset if it has no - semantic meaning (e.g. a module loaded from a database). - - ``__file__`` is set to the relative path to the code on modules run - from the file system, the absolute path to the code on imported - modules and modules run from the module namespace and ``''`` - on non-package modules run from standard input. ``__file__`` is - not set on imported namespace packages, imported built-in modules - and imported frozen modules. - .. attribute:: __cached__ + ``__file__`` is optional. If set, this attribute's value must be a + string. The import system may opt to leave ``__file__`` unset if it + has no semantic meaning (e.g. a module loaded from a database). + If ``__file__`` is set, it may also be appropriate to set the - ``__cached__`` attribute which must be set to the path to a compiled - version of the code (e.g. byte-compiled file). The file does not need - to exist to set this attribute; the path can simply point to where the - compiled file would exist (see :pep:`3147`). If ``__file__`` is not - set, it is also appropriate to set ``__cached__``. However, that - scenario is quite atypical. Ultimately, the loader is what makes use - of ``__file__`` and/or ``__cached__``. So if a loader can load from a - cached module but otherwise does not load from a file, that atypical - scenario may be appropriate. - - ``__cached__`` is set to the relative path to the compiled code on - packages run from the file system and the absolute path to the - compiled code on imported modules and modules run from the module - namespace. ``__cached__`` is not set on non-package modules run from - the file system, non-package modules run from standard input, imported - namespace packages, imported built-in modules and imported frozen - modules. + ``__cached__`` attribute which is the path to any compiled version of + the code (e.g. byte-compiled file). The file does not need to exist + to set this attribute; the path can simply point to where the + compiled file would exist (see :pep:`3147`). + + It is also appropriate to set ``__cached__`` when ``__file__`` is not + set. However, that scenario is quite atypical. Ultimately, the + loader is what makes use of ``__file__`` and/or ``__cached__``. So + if a loader can load from a cached module but otherwise does not load + from a file, that atypical scenario may be appropriate. .. _package-path-rules: From 9147e5ce72634828c1f062b6973bc33002316337 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9ry=20Ogam?= Date: Fri, 9 Aug 2019 10:00:28 +0200 Subject: [PATCH 25/46] Update importlib.rst --- Doc/library/importlib.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst index dca6c4964d5aa9..9d2462c5c2755b 100644 --- a/Doc/library/importlib.rst +++ b/Doc/library/importlib.rst @@ -1306,8 +1306,7 @@ find and load modules. (:attr:`__loader__`) The :class:`Loader ` that should be used when - loading the module. Finders should always set this. A ``None`` value - is reserved for namespace packages. + loading the module. Finders should always set this. .. attribute:: origin From 779a2f17f943d61fd955a661d834295591f5e3ce Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9ry=20Ogam?= Date: Sat, 10 Aug 2019 11:30:13 +0200 Subject: [PATCH 26/46] Update importlib.rst --- Doc/library/importlib.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst index 9d2462c5c2755b..2d17251f67e31e 100644 --- a/Doc/library/importlib.rst +++ b/Doc/library/importlib.rst @@ -1298,8 +1298,7 @@ find and load modules. (:attr:`__name__`) The module's fully-qualified name. Finders should always set this to a - non-empty (identifier) string. The import system may set this to ``None`` - in a few special cases. + non-empty (identifier) string. .. attribute:: loader From ff0d5ae7d730e95cf56711f7dd40a2603a9d3fd0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9ry=20Ogam?= Date: Sat, 10 Aug 2019 12:44:03 +0200 Subject: [PATCH 27/46] Apply suggestions from code review Co-Authored-By: Eric Snow --- Doc/library/importlib.rst | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst index 2d17251f67e31e..fa5566bf69fa8f 100644 --- a/Doc/library/importlib.rst +++ b/Doc/library/importlib.rst @@ -1325,7 +1325,7 @@ find and load modules. it's just an empty list. For non-package modules, this should be set to ``None``. For namespace packages (where :attr:`origin` is ``None``), this - is set automatically. + is later set to a special object by the import system. .. attribute:: loader_state @@ -1337,7 +1337,8 @@ find and load modules. (:attr:`__cached__`) - Where a compiled version of the code should be stored (or ``None``). + (str) Where a compiled version of the code should be stored. For modules + that do not need compiled code stored, ``cached`` should be ``None``. This is typically a filename as provided by ::func::`importlib.util.cache_from_source`. @@ -1347,7 +1348,8 @@ find and load modules. (Read-only) The fully-qualified name of the package under which the module should be loaded as a submodule (or the empty string for top-level - modules). For packages, it is the same as :attr:`__name__`. + modules). For packages, it is the same as :attr:`__name__` (since in + that case ``parent`` relates to the package's `__init__` module). .. attribute:: has_location From e651eb7bf8d2f1398ac18c329fc8c0ca17195e71 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9ry=20Ogam?= Date: Sat, 10 Aug 2019 12:44:26 +0200 Subject: [PATCH 28/46] Update importlib.rst --- Doc/library/importlib.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst index fa5566bf69fa8f..33d7bb503044f1 100644 --- a/Doc/library/importlib.rst +++ b/Doc/library/importlib.rst @@ -1337,7 +1337,7 @@ find and load modules. (:attr:`__cached__`) - (str) Where a compiled version of the code should be stored. For modules + Where a compiled version of the code should be stored. For modules that do not need compiled code stored, ``cached`` should be ``None``. This is typically a filename as provided by ::func::`importlib.util.cache_from_source`. From 9e8c67f82c979ec1e30f0605895072621c564363 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9ry=20Ogam?= Date: Sat, 10 Aug 2019 23:55:44 +0200 Subject: [PATCH 29/46] Apply suggestions from code review Co-Authored-By: orlnub123 --- Doc/library/importlib.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst index 33d7bb503044f1..38c97ffb896365 100644 --- a/Doc/library/importlib.rst +++ b/Doc/library/importlib.rst @@ -438,11 +438,11 @@ ABC hierarchy:: - :attr:`__package__` The fully-qualified name of the package under which the module was - loaded as a submodule (or the empty string for top-level modules). + loaded as a submodule (or an empty string for top-level modules). For packages, it is the same as :attr:`__name__`. - :attr:`__loader__` - The loader that was used when loading the module. + The loader that was used to load the module. When :meth:`exec_module` is available then backwards-compatible functionality is provided. @@ -1283,8 +1283,8 @@ find and load modules. A specification for a module's import-system-related state. This is typically exposed as the module's :attr:`__spec__` attribute. In the descriptions below, the names in parentheses give the corresponding - attribute available directly on the module object. For example, - ``module.__spec__.origin == module.__file__``. Note however that while + attribute available directly on the module object, e.g. + ``module.__spec__.origin == module.__file__``. Note, however, that while the *values* are usually equivalent, they can differ since there is no synchronization between the two objects. For example, it is possible to update the module's :attr:`__file__` at runtime and this will not be From d79b79a578ab7330e48aefa623bac65334c08395 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9ry=20Ogam?= Date: Wed, 11 Sep 2019 11:33:10 +0200 Subject: [PATCH 30/46] Update Doc/library/importlib.rst Co-Authored-By: Julien Palard --- Doc/library/importlib.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst index 38c97ffb896365..272cd97933e1b0 100644 --- a/Doc/library/importlib.rst +++ b/Doc/library/importlib.rst @@ -1349,7 +1349,7 @@ find and load modules. (Read-only) The fully-qualified name of the package under which the module should be loaded as a submodule (or the empty string for top-level modules). For packages, it is the same as :attr:`__name__` (since in - that case ``parent`` relates to the package's `__init__` module). + that case ``parent`` relates to the package's ``__init__`` module). .. attribute:: has_location From 50cd998a7bca59d03332f4d8ff381191f5019f35 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9ry=20Ogam?= Date: Wed, 11 Sep 2019 11:51:38 +0200 Subject: [PATCH 31/46] Update importlib.rst --- Doc/library/importlib.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst index 272cd97933e1b0..b19ca9d20eff32 100644 --- a/Doc/library/importlib.rst +++ b/Doc/library/importlib.rst @@ -1355,7 +1355,7 @@ find and load modules. True if the spec's :attr:`origin` refers to a loadable location. False otherwise. This value impacts how :attr:`origin` is interpreted and how - the module's :attr:`__file__`` is populated. + the module's :attr:`__file__` is populated. :mod:`importlib.util` -- Utility code for importers --------------------------------------------------- From 55e038d40fd2a1ddd021f519bba2181f0f881ff0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9ry=20Ogam?= Date: Wed, 11 Sep 2019 14:30:03 +0200 Subject: [PATCH 32/46] Update importlib.rst --- Doc/library/importlib.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst index b19ca9d20eff32..7a9418f2486904 100644 --- a/Doc/library/importlib.rst +++ b/Doc/library/importlib.rst @@ -1340,7 +1340,7 @@ find and load modules. Where a compiled version of the code should be stored. For modules that do not need compiled code stored, ``cached`` should be ``None``. This is typically a filename as provided by - ::func::`importlib.util.cache_from_source`. + :func:`importlib.util.cache_from_source`. .. attribute:: parent From e8aa31380bfa06c45a481843c59f94f370d1775c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9ry=20Ogam?= Date: Fri, 23 Oct 2020 22:51:00 +0200 Subject: [PATCH 33/46] Update importlib.rst --- Doc/library/importlib.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst index 7a9418f2486904..2c8615b5ab3375 100644 --- a/Doc/library/importlib.rst +++ b/Doc/library/importlib.rst @@ -442,7 +442,7 @@ ABC hierarchy:: For packages, it is the same as :attr:`__name__`. - :attr:`__loader__` - The loader that was used to load the module. + The :term:`loader` that was used to load the module. When :meth:`exec_module` is available then backwards-compatible functionality is provided. From 51812a69f1f58865d3d46f8372a8f740f7ce3736 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9ry=20Ogam?= Date: Sat, 24 Oct 2020 03:54:51 +0200 Subject: [PATCH 34/46] Update importlib.rst --- Doc/library/importlib.rst | 117 +++++++++++++++++++------------------- 1 file changed, 58 insertions(+), 59 deletions(-) diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst index 2c8615b5ab3375..b9662cca4d2fb0 100644 --- a/Doc/library/importlib.rst +++ b/Doc/library/importlib.rst @@ -370,11 +370,11 @@ ABC hierarchy:: See :pep:`302` for the exact definition for a loader. Loaders that wish to support resource reading should implement a - ``get_resource_reader(fullname)`` method as specified by + :meth:`get_resource_reader(fullname)` method as specified by :class:`importlib.abc.ResourceReader`. .. versionchanged:: 3.7 - Introduced the optional ``get_resource_reader()`` method. + Introduced the optional :meth:`get_resource_reader` method. .. method:: create_module(spec) @@ -392,17 +392,17 @@ ABC hierarchy:: An abstract method that executes the module in its own namespace when a module is imported or reloaded. The module should already - be initialized when ``exec_module()`` is called. When this method exists, - :meth:`~importlib.abc.Loader.create_module` must be defined. + be initialized when :meth:`exec_module` is called. When this method exists, + :meth:`create_module` must be defined. .. versionadded:: 3.4 .. versionchanged:: 3.6 - :meth:`~importlib.abc.Loader.create_module` must also be defined. + :meth:`create_module` must also be defined. .. method:: load_module(fullname) - A legacy method for loading a module. If the module cannot be + A legacy method for loading a module. If the module cannot be loaded, :exc:`ImportError` is raised, otherwise the loaded module is returned. @@ -410,60 +410,61 @@ ABC hierarchy:: module should be used and reloaded. Otherwise the loader should create a new module and insert it into :data:`sys.modules` before any loading begins, to prevent recursion - from the import. If the loader inserted a module and the load fails, it + from the import. If the loader inserted a module and the load fails, it must be removed by the loader from :data:`sys.modules`; modules already in :data:`sys.modules` before the loader began execution should be left alone (see :func:`importlib.util.module_for_loader`). - The loader should set several attributes on the module. - (Note that some of these attributes can change when a module is + The loader should set several attributes on the module + (note that some of these attributes can change when a module is reloaded): - :attr:`__name__` The module's fully-qualified name. + It is ``'__main__'`` for the top-level module. - :attr:`__file__` The location from which the module was loaded (usually the path). It is not set on all modules (e.g. built-in modules). - :attr:`__cached__` - The path to a compiled version of the code. - It is not set when the attribute would be inappropriate. + The path to a compiled version of the module's code. + It is not set on all modules (e.g. built-in modules). - :attr:`__path__` - For packages, the list of strings specifying where to look for submodules. - This is used in the same way as :attr:`sys.path`, but just for the package. - Effectively, it is the indicator that the module is a package. For - non-package modules, it is not set. + The list of paths where to find submodules within a package. + It is used in the same way as :attr:`sys.path` but just for the + package. It is not set on non-package modules so it is the + indicator that a module is a package. - :attr:`__package__` - The fully-qualified name of the package under which the module was - loaded as a submodule (or an empty string for top-level modules). - For packages, it is the same as :attr:`__name__`. + The fully-qualified name of the package the module is in (or the + empty string for the top-level module). + It is the same as :attr:`__name__` for packages. - :attr:`__loader__` - The :term:`loader` that was used to load the module. + The :term:`loader` used to load the module. When :meth:`exec_module` is available then backwards-compatible functionality is provided. .. versionchanged:: 3.4 Raise :exc:`ImportError` when called instead of - :exc:`NotImplementedError`. Functionality provided when + :exc:`NotImplementedError`. Functionality provided when :meth:`exec_module` is available. .. deprecated:: 3.4 The recommended API for loading a module is :meth:`exec_module` - (and :meth:`create_module`). Loaders should implement - it instead of load_module(). The import machinery takes care of - all the other responsibilities of load_module() when exec_module() - is implemented. + (and :meth:`create_module`). Loaders should implement it instead of + :meth:`load_module`. The import machinery takes care of all the + other responsibilities of :meth:`load_module` when + :meth:`exec_module` is implemented. .. method:: module_repr(module) - A legacy method which when implemented calculates and returns the - given module's repr, as a string. The module type's default repr() will - use the result of this method as appropriate. + A legacy method which when implemented calculates and returns the given + module's representation, as a string. The module type's default + :meth:`__repr__` will use the result of this method as appropriate. .. versionadded:: 3.3 @@ -1286,10 +1287,10 @@ find and load modules. attribute available directly on the module object, e.g. ``module.__spec__.origin == module.__file__``. Note, however, that while the *values* are usually equivalent, they can differ since there is no - synchronization between the two objects. For example, it is possible - to update the module's :attr:`__file__` at runtime and this will not be - automatically reflected in the module's :attr:`__spec__.origin`, and - vice versa. + synchronization between the two objects. For example, it is possible to + update the module's :attr:`__file__` at runtime and this will not be + automatically reflected in the module's :attr:`__spec__.origin`, and vice + versa. .. versionadded:: 3.4 @@ -1297,65 +1298,63 @@ find and load modules. (:attr:`__name__`) - The module's fully-qualified name. Finders should always set this to a - non-empty (identifier) string. + The module's fully-qualified name. + The :term:`finder` should always set this attribute to a non-empty string. .. attribute:: loader (:attr:`__loader__`) - The :class:`Loader ` that should be used when - loading the module. Finders should always set this. + The :term:`loader` used to load the module. + The :term:`finder` should always set this attribute. .. attribute:: origin (:attr:`__file__`) - The name of where the module should be loaded from (e.g. ``'builtin'`` - for built-in modules and the path for modules loaded from source). - Finders should normally set this attribute, but it may be ``None`` (the - default) which indicates it is unspecified (like for namespace packages). + The location from which the module was loaded (usually the path). + The :term:`finder` should always set this attribute but it may be ``None`` + when unspecified (like for namespace packages). .. attribute:: submodule_search_locations (:attr:`__path__`) - For packages, the Finder must set this to the iterable specifying the - locations where submodules may be found for the package, even if - it's just an empty list. - For non-package modules, this should be set to ``None``. - For namespace packages (where :attr:`origin` is ``None``), this - is later set to a special object by the import system. + The list of paths where to find submodules within a package. + The :term:`finder` should always set this attribute to ``None`` for + non-package modules and set it later to a special object for namespace + packages. .. attribute:: loader_state - The Finder may set this to an object containing additional, - module-specific data to use when loading the module. Otherwise it - should be set to ``None``. + The :term:`finder` may set this to an object containing additional, + module-specific data to use when loading the module. Otherwise it should be + set to ``None``. .. attribute:: cached (:attr:`__cached__`) - Where a compiled version of the code should be stored. For modules - that do not need compiled code stored, ``cached`` should be ``None``. - This is typically a filename as provided by - :func:`importlib.util.cache_from_source`. + The path to a compiled version of the module's code. + The :term:`finder` should always set this attribute but it may be ``None`` + for modules that do not need compiled code stored. It is usually the same + as the path provided by :func:`importlib.util.cache_from_source`. .. attribute:: parent (:attr:`__package__`) - (Read-only) The fully-qualified name of the package under which the - module should be loaded as a submodule (or the empty string for top-level - modules). For packages, it is the same as :attr:`__name__` (since in - that case ``parent`` relates to the package's ``__init__`` module). + (Read-only) The fully-qualified name of the package the module is in (or the + empty string for the top-level module). + It is the same as :attr:`__name__` for packages (since ``parent`` refers to + the package's ``__init__`` module). .. attribute:: has_location - True if the spec's :attr:`origin` refers to a loadable location. False - otherwise. This value impacts how :attr:`origin` is interpreted and how - the module's :attr:`__file__` is populated. + ``True`` if the spec's :attr:`origin` refers to a loadable location. + ``False`` otherwise. This value impacts how :attr:`origin` is interpreted + and how the module's :attr:`__file__` is populated. + :mod:`importlib.util` -- Utility code for importers --------------------------------------------------- From 3899dfa2742283e6fe1682e0a1266b22cf75bc80 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9ry=20Ogam?= Date: Sat, 24 Oct 2020 04:22:52 +0200 Subject: [PATCH 35/46] Update importlib.rst --- Doc/library/importlib.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst index b9662cca4d2fb0..aaee261dbea2a9 100644 --- a/Doc/library/importlib.rst +++ b/Doc/library/importlib.rst @@ -1322,8 +1322,8 @@ find and load modules. The list of paths where to find submodules within a package. The :term:`finder` should always set this attribute to ``None`` for - non-package modules and set it later to a special object for namespace - packages. + non-package modules. It is set automatically later to a special object for + namespace packages. .. attribute:: loader_state From ce8d9ac955f533bebd9e6c30bfcce3a3545e726d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9ry=20Ogam?= Date: Fri, 23 Jul 2021 19:40:15 +0200 Subject: [PATCH 36/46] Update Doc/library/importlib.rst Co-authored-by: Brett Cannon --- Doc/library/importlib.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst index edf53b488930dd..28d94a331efe82 100644 --- a/Doc/library/importlib.rst +++ b/Doc/library/importlib.rst @@ -1393,7 +1393,7 @@ find and load modules. .. attribute:: has_location - ``True`` if the spec's :attr:`origin` refers to a loadable location. + ``True`` if the spec's :attr:`origin` refers to a loadable location, ``False`` otherwise. This value impacts how :attr:`origin` is interpreted and how the module's :attr:`__file__` is populated. From 0cc0b113e7eefb47b4f1462a5bedf111cf1733af Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9ry=20Ogam?= Date: Fri, 23 Jul 2021 19:41:33 +0200 Subject: [PATCH 37/46] Update Doc/library/importlib.rst Co-authored-by: Brett Cannon --- Doc/library/importlib.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst index 28d94a331efe82..adcf19493399d7 100644 --- a/Doc/library/importlib.rst +++ b/Doc/library/importlib.rst @@ -373,7 +373,7 @@ ABC hierarchy:: See :pep:`302` for the exact definition for a loader. Loaders that wish to support resource reading should implement a - :meth:`get_resource_reader(fullname)` method as specified by + :meth:`get_resource_reader` method as specified by :class:`importlib.abc.ResourceReader`. .. versionchanged:: 3.7 From 69d187d980c879267c2a58985eb22fd2e1270f48 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9ry=20Ogam?= Date: Fri, 23 Jul 2021 21:19:32 +0200 Subject: [PATCH 38/46] Update importlib.rst --- Doc/library/importlib.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst index adcf19493399d7..85e6b977523dbd 100644 --- a/Doc/library/importlib.rst +++ b/Doc/library/importlib.rst @@ -1366,7 +1366,7 @@ find and load modules. The list of paths where to find submodules within a package. The :term:`finder` should always set this attribute to ``None`` for - non-package modules. It is set automatically later to a special object for + non-package modules. It is set automatically later to a special object for namespace packages. .. attribute:: loader_state From 3461332a0ff335c8b4bbc1c162d37305cbe1f61b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9ry=20Ogam?= Date: Thu, 29 Jul 2021 20:20:42 +0200 Subject: [PATCH 39/46] Update importlib.rst --- Doc/library/importlib.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst index 85e6b977523dbd..fb82520667acb3 100644 --- a/Doc/library/importlib.rst +++ b/Doc/library/importlib.rst @@ -427,7 +427,7 @@ ABC hierarchy:: It is ``'__main__'`` for the top-level module. - :attr:`__file__` - The location from which the module was loaded (usually the path). + The location from which the module was loaded. It is not set on all modules (e.g. built-in modules). - :attr:`__cached__` @@ -435,7 +435,7 @@ ABC hierarchy:: It is not set on all modules (e.g. built-in modules). - :attr:`__path__` - The list of paths where to find submodules within a package. + The list of locations where the package's submodules will be found. It is used in the same way as :attr:`sys.path` but just for the package. It is not set on non-package modules so it is the indicator that a module is a package. @@ -1356,7 +1356,7 @@ find and load modules. (:attr:`__file__`) - The location from which the module was loaded (usually the path). + The location from which the module was loaded. The :term:`finder` should always set this attribute but it may be ``None`` when unspecified (like for namespace packages). @@ -1364,7 +1364,7 @@ find and load modules. (:attr:`__path__`) - The list of paths where to find submodules within a package. + The list of locations where the package's submodules will be found. The :term:`finder` should always set this attribute to ``None`` for non-package modules. It is set automatically later to a special object for namespace packages. From 19b0542e517746c3ef2e4d2b88e2fa41eb094f4a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9ry=20Ogam?= Date: Thu, 29 Jul 2021 23:57:10 +0200 Subject: [PATCH 40/46] Apply suggestions from code review Co-authored-by: Eric Snow --- Doc/library/importlib.rst | 19 +++++++++++-------- 1 file changed, 11 insertions(+), 8 deletions(-) diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst index fb82520667acb3..5ad4574fbb1db4 100644 --- a/Doc/library/importlib.rst +++ b/Doc/library/importlib.rst @@ -436,9 +436,10 @@ ABC hierarchy:: - :attr:`__path__` The list of locations where the package's submodules will be found. - It is used in the same way as :attr:`sys.path` but just for the - package. It is not set on non-package modules so it is the - indicator that a module is a package. + The import system passes this to ``__import__()`` and to finders + in the same way as :attr:`sys.path` but just for the package. + It is not set on non-package modules so it can be used + as an indicator that a module is a package. - :attr:`__package__` The fully-qualified name of the package the module is in (or the @@ -1357,15 +1358,17 @@ find and load modules. (:attr:`__file__`) The location from which the module was loaded. - The :term:`finder` should always set this attribute but it may be ``None`` - when unspecified (like for namespace packages). + The :term:`finder` should always set this attribute to a meaningful value + for the :term:`loader` to use. In the uncommon case that there isn't one + (like for namespace packages), it should be set to ``None``. .. attribute:: submodule_search_locations (:attr:`__path__`) The list of locations where the package's submodules will be found. - The :term:`finder` should always set this attribute to ``None`` for + Setting this to a list, even an empty one, is how a :term:`finder` indicates + to the import system that this is a package. It should be set to ``None`` for non-package modules. It is set automatically later to a special object for namespace packages. @@ -1388,8 +1391,8 @@ find and load modules. (:attr:`__package__`) (Read-only) The fully-qualified name of the package the module is in (or the - empty string for the top-level module). - It is the same as :attr:`__name__` for packages. + empty string for a top-level module). + If the module is a package then this is the same as :attr:`name`. .. attribute:: has_location From 5094cc5859eca887c5549628ae70415643d495d1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9ry=20Ogam?= Date: Fri, 30 Jul 2021 00:22:24 +0200 Subject: [PATCH 41/46] Update importlib.rst --- Doc/library/importlib.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst index 5ad4574fbb1db4..e491a68b831716 100644 --- a/Doc/library/importlib.rst +++ b/Doc/library/importlib.rst @@ -424,7 +424,7 @@ ABC hierarchy:: - :attr:`__name__` The module's fully-qualified name. - It is ``'__main__'`` for the top-level module. + It is ``'__main__'`` for a top-level module. - :attr:`__file__` The location from which the module was loaded. @@ -443,8 +443,8 @@ ABC hierarchy:: - :attr:`__package__` The fully-qualified name of the package the module is in (or the - empty string for the top-level module). - It is the same as :attr:`__name__` for packages. + empty string for a top-level module). + If the module is a package then this is the same as :attr:`__name__`. - :attr:`__loader__` The :term:`loader` used to load the module. @@ -1359,7 +1359,7 @@ find and load modules. The location from which the module was loaded. The :term:`finder` should always set this attribute to a meaningful value - for the :term:`loader` to use. In the uncommon case that there isn't one + for the :term:`loader` to use. In the uncommon case that there is not one (like for namespace packages), it should be set to ``None``. .. attribute:: submodule_search_locations From 7bd4866f021b29cf2ad9f0a5eda0709cb0f46327 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9ry=20Ogam?= Date: Fri, 30 Jul 2021 00:29:44 +0200 Subject: [PATCH 42/46] Update importlib.rst --- Doc/library/importlib.rst | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst index e491a68b831716..6738745ce84386 100644 --- a/Doc/library/importlib.rst +++ b/Doc/library/importlib.rst @@ -1329,13 +1329,12 @@ find and load modules. A specification for a module's import-system-related state. This is typically exposed as the module's :attr:`__spec__` attribute. In the descriptions below, the names in parentheses give the corresponding - attribute available directly on the module object, e.g. - ``module.__spec__.origin == module.__file__``. Note, however, that while - the *values* are usually equivalent, they can differ since there is no - synchronization between the two objects. For example, it is possible to - update the module's :attr:`__file__` at runtime and this will not be - automatically reflected in the module's :attr:`__spec__.origin`, and vice - versa. + attribute available directly on the module object, + e.g. ``module.__spec__.origin == module.__file__``. Note, however, that + while the *values* are usually equivalent, they can differ since there is + no synchronization between the two objects. For example, it is possible to update + the module's :attr:`__file__` at runtime and this will not be automatically + reflected in the module's :attr:`__spec__.origin`, and vice versa. .. versionadded:: 3.4 From fc40bb036246133cd9e8253acc510e2584be8518 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9ry=20Ogam?= Date: Fri, 30 Jul 2021 00:39:14 +0200 Subject: [PATCH 43/46] Update importlib.rst --- Doc/library/importlib.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst index 6738745ce84386..9c25dc33d8b4b2 100644 --- a/Doc/library/importlib.rst +++ b/Doc/library/importlib.rst @@ -439,7 +439,7 @@ ABC hierarchy:: The import system passes this to ``__import__()`` and to finders in the same way as :attr:`sys.path` but just for the package. It is not set on non-package modules so it can be used - as an indicator that a module is a package. + as an indicator that the module is a package. - :attr:`__package__` The fully-qualified name of the package the module is in (or the @@ -1366,14 +1366,14 @@ find and load modules. (:attr:`__path__`) The list of locations where the package's submodules will be found. - Setting this to a list, even an empty one, is how a :term:`finder` indicates - to the import system that this is a package. It should be set to ``None`` for + The :term:`finder` should set this attribute to a list, even an empty one, to indicate + to the import system that the module is a package. It should be set to ``None`` for non-package modules. It is set automatically later to a special object for namespace packages. .. attribute:: loader_state - The :term:`finder` may set this to an object containing additional, + The :term:`finder` may set this attribute to an object containing additional, module-specific data to use when loading the module. Otherwise it should be set to ``None``. From 60dc2013bcc62743dd8cd1edacf20b1f715bf8b0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9ry=20Ogam?= Date: Fri, 30 Jul 2021 01:03:05 +0200 Subject: [PATCH 44/46] Update importlib.rst --- Doc/library/importlib.rst | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst index 9c25dc33d8b4b2..03d1c92e1f9ebe 100644 --- a/Doc/library/importlib.rst +++ b/Doc/library/importlib.rst @@ -427,16 +427,18 @@ ABC hierarchy:: It is ``'__main__'`` for a top-level module. - :attr:`__file__` - The location from which the module was loaded. + The location the :term:`loader` should use to load the module. + For example, for modules loaded from a .py file this is the filename. It is not set on all modules (e.g. built-in modules). - :attr:`__cached__` - The path to a compiled version of the module's code. + The filename of a compiled version of the module's code. It is not set on all modules (e.g. built-in modules). - :attr:`__path__` The list of locations where the package's submodules will be found. - The import system passes this to ``__import__()`` and to finders + Most of the time this is a single directory. + The import system passes this attribute to ``__import__()`` and to finders in the same way as :attr:`sys.path` but just for the package. It is not set on non-package modules so it can be used as an indicator that the module is a package. @@ -1356,7 +1358,8 @@ find and load modules. (:attr:`__file__`) - The location from which the module was loaded. + The location the :term:`loader` should use to load the module. + For example, for modules loaded from a .py file this is the filename. The :term:`finder` should always set this attribute to a meaningful value for the :term:`loader` to use. In the uncommon case that there is not one (like for namespace packages), it should be set to ``None``. @@ -1366,6 +1369,7 @@ find and load modules. (:attr:`__path__`) The list of locations where the package's submodules will be found. + Most of the time this is a single directory. The :term:`finder` should set this attribute to a list, even an empty one, to indicate to the import system that the module is a package. It should be set to ``None`` for non-package modules. It is set automatically later to a special object for @@ -1381,7 +1385,7 @@ find and load modules. (:attr:`__cached__`) - The path to a compiled version of the module's code. + The filename of a compiled version of the module's code. The :term:`finder` should always set this attribute but it may be ``None`` for modules that do not need compiled code stored. From fcea8dd4ed1839fb06b54112d256c29da1136fd5 Mon Sep 17 00:00:00 2001 From: Brett Cannon Date: Tue, 16 Nov 2021 11:42:57 -0800 Subject: [PATCH 45/46] Update Doc/library/importlib.rst Co-authored-by: Eric Snow --- Doc/library/importlib.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst index 03d1c92e1f9ebe..e8ed68b8cec722 100644 --- a/Doc/library/importlib.rst +++ b/Doc/library/importlib.rst @@ -427,7 +427,7 @@ ABC hierarchy:: It is ``'__main__'`` for a top-level module. - :attr:`__file__` - The location the :term:`loader` should use to load the module. + The location the :term:`loader` used to load the module. For example, for modules loaded from a .py file this is the filename. It is not set on all modules (e.g. built-in modules). From 2bb2c14f06b8f1e42e9c2cc2c1f4dfe58b629961 Mon Sep 17 00:00:00 2001 From: Brett Cannon Date: Tue, 16 Nov 2021 11:43:05 -0800 Subject: [PATCH 46/46] Update Doc/library/importlib.rst Co-authored-by: Eric Snow --- Doc/library/importlib.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst index e8ed68b8cec722..519286a11811ed 100644 --- a/Doc/library/importlib.rst +++ b/Doc/library/importlib.rst @@ -424,7 +424,7 @@ ABC hierarchy:: - :attr:`__name__` The module's fully-qualified name. - It is ``'__main__'`` for a top-level module. + It is ``'__main__'`` for an executed module. - :attr:`__file__` The location the :term:`loader` used to load the module.