[3.12] gh-121607: Edited source file import recipe to make it more clear (GH-121519...

gh-121607: Edited source file import recipe to make it more clear (GH-121519)
(cherry picked from commit 38809171b8768517824fb62d48abe2cb0aff8429)

Co-authored-by: Chris Barker <Chris.Barker@noaa.gov>
Co-authored-by: Brett Cannon <brett@python.org>
Co-authored-by: Peter Bierma <zintensitydev@gmail.com>

diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst
index 1dacbe64b748db8896142c0b988c7ed437830130..e4e09b096f7c048aac2dd10ddcb307cfd4b71c75 100644 (file)
--- a/Doc/library/importlib.rst
+++ b/Doc/library/importlib.rst
@@ -1495,20 +1495,34 @@ Note that if ``name`` is a submodule (contains a dot),
 Importing a source file directly
 ''''''''''''''''''''''''''''''''
 
-To import a Python source file directly, use the following recipe::
+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.
 
-  import importlib.util
-  import sys
+To import a Python source file directly from a path, 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)
+    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 only (use of `json` is arbitrary).
+    import json
+    file_path = json.__file__
+    module_name = json.__name__
+
+    # Similar outcome as `import json`.
+    json = import_from_path(module_name, file_path)
 
 
 Implementing lazy imports
@@ -1534,7 +1548,6 @@ The example below shows how to implement lazy imports::
     False
 
 
-
 Setting up an importer
 ''''''''''''''''''''''