[Python-checkins] bpo-26792: Improve docstrings of runpy module run_functions (GH-30729)

[miss-islington]

https://github.com/python/cpython/commit/7bd4411b90e9f4b376754be23b5f6b86bf4e3c5f
commit: 7bd4411b90e9f4b376754be23b5f6b86bf4e3c5f
branch: 3.10
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: miss-islington <31488909+miss-islington at users.noreply.github.com>
date: 2022-04-29T11:45:43-07:00
summary:

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


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

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

files:
A Misc/NEWS.d/next/Documentation/2022-01-23-20-44-53.bpo-26792.dQ1v1W.rst
M Lib/runpy.py

diff --git a/Lib/runpy.py b/Lib/runpy.py
index caba121426238..c7d3d8caad161 100644
--- a/Lib/runpy.py
+++ b/Lib/runpy.py
@@ -198,9 +198,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
index 0000000000000..64a3956447601
--- /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`.
+Original patch by Andrew Brezovsky.