diff --git a/Lib/runpy.py b/Lib/runpy.py index 949fd5939ba..54fc136d407 100644 --- a/Lib/runpy.py +++ b/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. - 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. + 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 to set __name__; + otherwise, '' will be used for __name__. + + Returns the resulting module globals dictionary. """ if run_name is None: run_name = "" 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 00000000000..64a39564476 --- /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.