bpo-26792: Improve docstrings of runpy module run_functions (GH-30729)

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Co-authored-by: Kumar Aditya <59607654+kumaraditya303@users.noreply.github.com>
(cherry picked from commit 117836f123a1c65d9ba50401822b883f11f0a347)

Co-authored-by: Humbled Drugman <humbled.drugman@gmail.com>

diff --git a/Lib/runpy.py b/Lib/runpy.py
index 7e1e1ac5dde2dfe6b906c53f54b9854aeeed90ab..c602bbe3f7d634c5090f28f7892b7b8e52353370 100644 (file)
--- a/Lib/runpy.py
+++ b/Lib/runpy.py
@@ -199,9 +199,24 @@ def _run_module_as_main(mod_name, alter_argv=True):
 
 def run_module(mod_name, init_globals=None,
                run_name=None, alter_sys=False):
-    """Execute a module's code without importing it
+    """Execute a module's code without importing it.
 
-       Returns the resulting top level namespace dictionary
+       mod_name -- an absolute module name or package name.
+
+       Optional arguments:
+       init_globals -- dictionary used to pre-populate the module’s
+       globals dictionary before the code is executed.
+
+       run_name -- if not None, this will be used for setting __name__;
+       otherwise, __name__ will be set to mod_name + '__main__' if the
+       named module is a package and to just mod_name otherwise.
+
+       alter_sys -- if True, sys.argv[0] is updated with the value of
+       __file__ and sys.modules[__name__] is updated with a temporary
+       module object for the module being executed. Both are
+       restored to their original values before the function returns.
+
+       Returns the resulting module globals dictionary.
     """
     mod_name, mod_spec, code = _get_module_details(mod_name)
     if run_name is None:
@@ -243,14 +258,19 @@ def _get_code_from_file(run_name, fname):
     return code, fname
 
 def run_path(path_name, init_globals=None, run_name=None):
-    """Execute code located at the specified filesystem location
+    """Execute code located at the specified filesystem location.
+
+       path_name -- filesystem location of a Python script, zipfile,
+       or directory containing a top level __main__.py script.
+
+       Optional arguments:
+       init_globals -- dictionary used to pre-populate the module’s
+       globals dictionary before the code is executed.
 
-       Returns the resulting top level namespace dictionary
+       run_name -- if not None, this will be used to set __name__;
+       otherwise, '<run_path>' will be used for __name__.
 
-       The file path may refer directly to a Python script (i.e.
-       one that could be directly executed with execfile) or else
-       it may refer to a zipfile or directory containing a top
-       level __main__.py script.
+       Returns the resulting module globals dictionary.
     """
     if run_name is None:
         run_name = "<run_path>"

diff --git a/Misc/NEWS.d/next/Documentation/2022-01-23-20-44-53.bpo-26792.dQ1v1W.rst b/Misc/NEWS.d/next/Documentation/2022-01-23-20-44-53.bpo-26792.dQ1v1W.rst
new file mode 100644 (file)
index 0000000..64a3956
--- /dev/null
+++ b/Misc/NEWS.d/next/Documentation/2022-01-23-20-44-53.bpo-26792.dQ1v1W.rst
@@ -0,0 +1,2 @@
+Improve the docstrings of :func:`runpy.run_module` and :func:`runpy.run_path`.\r
+Original patch by Andrew Brezovsky.\r