From 08917bda38b9c5d4c9947386e842990ceccb27a8 Mon Sep 17 00:00:00 2001 From: Chris Barker Date: Mon, 8 Jul 2024 15:19:32 -0700 Subject: [PATCH 01/10] edited source file import recipe to make it more clear --- Doc/library/importlib.rst | 32 ++++++++++++++++++++------------ 1 file changed, 20 insertions(+), 12 deletions(-) diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst index 2ec15dd171c18a..fe03da4f3be29b 100644 --- a/Doc/library/importlib.rst +++ b/Doc/library/importlib.rst @@ -1586,18 +1586,26 @@ Importing a source file directly To import a Python source file directly, use the following recipe:: - import importlib.util - import sys - - # For illustrative purposes. - import tokenize - file_path = tokenize.__file__ - module_name = tokenize.__name__ - - spec = importlib.util.spec_from_file_location(module_name, file_path) - module = importlib.util.module_from_spec(spec) - sys.modules[module_name] = module - spec.loader.exec_module(module) + import importlib.util + import sys + + + def import_from_path(module_name, file_path): + spec = importlib.util.spec_from_file_location(module_name, file_path) + module = importlib.util.module_from_spec(spec) + sys.modules[module_name] = module + spec.loader.exec_module(module) + return module + + # For illustrative purposes a name and file path of an + # existing module is needed -- use the json module + # as an example + import json + file_path = json.__file__ + module_name = json.__name__ + + # equivalent of ``import json`` + json = import_from_path(module_name, file_path) Implementing lazy imports From bab2fa8448c6087f3891a1d8f91fea8ddc1bf035 Mon Sep 17 00:00:00 2001 From: Chris Barker Date: Mon, 8 Jul 2024 15:31:39 -0700 Subject: [PATCH 02/10] added a note about deprecation of the load_module() method. --- Doc/library/importlib.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst index fe03da4f3be29b..97aace668dbf72 100644 --- a/Doc/library/importlib.rst +++ b/Doc/library/importlib.rst @@ -1584,6 +1584,8 @@ Note that if ``name`` is a submodule (contains a dot), Importing a source file directly '''''''''''''''''''''''''''''''' +.. note:: ``SourceFileLoader.load_module()`` has been deprecated -- this recipe should be used instead. + To import a Python source file directly, use the following recipe:: import importlib.util From 81885ade3de621fc9c799b2baf9d5b22b0242592 Mon Sep 17 00:00:00 2001 From: Chris Barker Date: Tue, 9 Jul 2024 22:17:53 -0700 Subject: [PATCH 03/10] Update Doc/library/importlib.rst Co-authored-by: Brett Cannon --- Doc/library/importlib.rst | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst index 97aace668dbf72..994ed97c14e4a9 100644 --- a/Doc/library/importlib.rst +++ b/Doc/library/importlib.rst @@ -1599,9 +1599,7 @@ To import a Python source file directly, use the following recipe:: spec.loader.exec_module(module) return module - # For illustrative purposes a name and file path of an - # existing module is needed -- use the json module - # as an example + # For illustrative purposes only (use of `json` is arbitrary). import json file_path = json.__file__ module_name = json.__name__ From 7905ab063980221658ea26030308441034206365 Mon Sep 17 00:00:00 2001 From: Chris Barker Date: Tue, 9 Jul 2024 22:19:07 -0700 Subject: [PATCH 04/10] 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 994ed97c14e4a9..4e47774aba6562 100644 --- a/Doc/library/importlib.rst +++ b/Doc/library/importlib.rst @@ -1604,7 +1604,7 @@ To import a Python source file directly, use the following recipe:: file_path = json.__file__ module_name = json.__name__ - # equivalent of ``import json`` + # Similar outcome as ``import json``. json = import_from_path(module_name, file_path) From c78a1a64ab97e36f4567e268a56300c460c247fd Mon Sep 17 00:00:00 2001 From: Chris Barker Date: Tue, 9 Jul 2024 22:25:38 -0700 Subject: [PATCH 05/10] removed the note directive. --- Doc/library/importlib.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst index 4e47774aba6562..942d2d0416e795 100644 --- a/Doc/library/importlib.rst +++ b/Doc/library/importlib.rst @@ -1584,7 +1584,7 @@ Note that if ``name`` is a submodule (contains a dot), Importing a source file directly '''''''''''''''''''''''''''''''' -.. note:: ``SourceFileLoader.load_module()`` has been deprecated -- this recipe should be used instead. +``SourceFileLoader.load_module()`` has been deprecated -- this recipe should be used instead. To import a Python source file directly, use the following recipe:: @@ -1599,6 +1599,7 @@ To import a Python source file directly, use the following recipe:: spec.loader.exec_module(module) return module + # For illustrative purposes only (use of `json` is arbitrary). import json file_path = json.__file__ From b9cb5d30b753048b9695353ebc621c46dc51bb61 Mon Sep 17 00:00:00 2001 From: Chris Barker Date: Wed, 10 Jul 2024 07:52:50 -0700 Subject: [PATCH 06/10] Update importlib.rst Co-authored-by: Peter Bierma --- 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 942d2d0416e795..91600fcd14937b 100644 --- a/Doc/library/importlib.rst +++ b/Doc/library/importlib.rst @@ -1605,7 +1605,7 @@ To import a Python source file directly, use the following recipe:: file_path = json.__file__ module_name = json.__name__ - # Similar outcome as ``import json``. + # Similar outcome as `import json`. json = import_from_path(module_name, file_path) From 73e4c94395e46ff40bb0b023bea49403377836e0 Mon Sep 17 00:00:00 2001 From: Chris Barker Date: Mon, 15 Jul 2024 15:07:26 -0700 Subject: [PATCH 07/10] added intro paragraph to Importing a source file directly recipe with cautions. --- 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 91600fcd14937b..0d008d9663804f 100644 --- a/Doc/library/importlib.rst +++ b/Doc/library/importlib.rst @@ -1584,9 +1584,10 @@ Note that if ``name`` is a submodule (contains a dot), Importing a source file directly '''''''''''''''''''''''''''''''' -``SourceFileLoader.load_module()`` has been deprecated -- this recipe should be used instead. +This recipe should be used with caution: it is an approximation of an import statement where the file path is specified directly, rather than `sys.path` being searched. +Alternatives should first be considered, such as modifying `sys.path` when a proper module is required, or using `runpy.run_path()` when the global namespace resulting from running a Python file is appropriate. -To import a Python source file directly, use the following recipe:: +To import a Python source file directly from a path, use the following recipe:: import importlib.util import sys @@ -1632,7 +1633,6 @@ The example below shows how to implement lazy imports:: False - Setting up an importer '''''''''''''''''''''' From fed1797003190f0d97299c056ecb811333f86775 Mon Sep 17 00:00:00 2001 From: Chris Barker Date: Mon, 15 Jul 2024 15:36:35 -0700 Subject: [PATCH 08/10] Update Doc/library/importlib.rst Co-authored-by: Peter Bierma --- 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 0d008d9663804f..80d787c4334a3e 100644 --- a/Doc/library/importlib.rst +++ b/Doc/library/importlib.rst @@ -1585,7 +1585,7 @@ Importing a source file directly '''''''''''''''''''''''''''''''' This recipe should be used with caution: it is an approximation of an import statement where the file path is specified directly, rather than `sys.path` being searched. -Alternatives should first be considered, such as modifying `sys.path` when a proper module is required, or using `runpy.run_path()` when the global namespace resulting from running a Python file is appropriate. +Alternatives should first be considered, such as modifying :data:`sys.path` when a proper module is required, or using :func:`runpy.run_path` when the global namespace resulting from running a Python file is appropriate. To import a Python source file directly from a path, use the following recipe:: From e5a864e06f29afcc3bb6fc0d21cf4bd25ab5b5e2 Mon Sep 17 00:00:00 2001 From: Chris Barker Date: Mon, 15 Jul 2024 15:36:44 -0700 Subject: [PATCH 09/10] Update Doc/library/importlib.rst Co-authored-by: Peter Bierma --- 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 80d787c4334a3e..9e360f319c7a73 100644 --- a/Doc/library/importlib.rst +++ b/Doc/library/importlib.rst @@ -1584,7 +1584,7 @@ Note that if ``name`` is a submodule (contains a dot), Importing a source file directly '''''''''''''''''''''''''''''''' -This recipe should be used with caution: it is an approximation of an import statement where the file path is specified directly, rather than `sys.path` being searched. +This recipe should be used with caution: it is an approximation of an import statement where the file path is specified directly, rather than :data:`sys.path` being searched. Alternatives should first be considered, such as modifying :data:`sys.path` when a proper module is required, or using :func:`runpy.run_path` when the global namespace resulting from running a Python file is appropriate. To import a Python source file directly from a path, use the following recipe:: From e6a19656b0a72becac125f495bc6111f51bf2039 Mon Sep 17 00:00:00 2001 From: Brett Cannon Date: Fri, 13 Sep 2024 16:13:38 -0700 Subject: [PATCH 10/10] Wrap lines to 80 columns --- Doc/library/importlib.rst | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst index 9e360f319c7a73..158ccfb281f734 100644 --- a/Doc/library/importlib.rst +++ b/Doc/library/importlib.rst @@ -1584,8 +1584,12 @@ Note that if ``name`` is a submodule (contains a dot), Importing a source file directly '''''''''''''''''''''''''''''''' -This recipe should be used with caution: it is an approximation of an import statement where the file path is specified directly, rather than :data:`sys.path` being searched. -Alternatives should first be considered, such as modifying :data:`sys.path` when a proper module is required, or using :func:`runpy.run_path` when the global namespace resulting from running a Python file is appropriate. +This recipe should be used with caution: it is an approximation of an import +statement where the file path is specified directly, rather than +:data:`sys.path` being searched. Alternatives should first be considered first, +such as modifying :data:`sys.path` when a proper module is required, or using +:func:`runpy.run_path` when the global namespace resulting from running a Python +file is appropriate. To import a Python source file directly from a path, use the following recipe::