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

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Co-authored-by: Kumar Aditya <59607654+kumaraditya303@users.noreply.github.com>

Lib/runpy.py

@@ -200,9 +200,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:
@@ -245,14 +260,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.
 
-       Returns the resulting top level namespace dictionary
+       path_name -- filesystem location of a Python script, zipfile,
+       or directory containing a top level __main__.py script.
 
-       The file path may refer directly to a Python script (i.e.
+       Optional arguments:
-       one that could be directly executed with execfile) or else
+       init_globals -- dictionary used to pre-populate the module’s
-       it may refer to a zipfile or directory containing a top
+       globals dictionary before the code is executed.
-       level __main__.py script.
+
+       run_name -- if not None, this will be used to set __name__;
+       otherwise, '<run_path>' will be used for __name__.
+
+       Returns the resulting module globals dictionary.
     """
     if run_name is None:
         run_name = "<run_path>"

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.