From e66edc971dbbc7eaf5345717e24818e2737dd387 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9ry=20Ogam?= Date: Sun, 9 Feb 2020 01:45:48 +0100 Subject: [PATCH 1/6] Update runpy.rst --- Doc/library/runpy.rst | 30 +++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/Doc/library/runpy.rst b/Doc/library/runpy.rst index af35e81a2d4523..6d8ff73d5ae34a 100644 --- a/Doc/library/runpy.rst +++ b/Doc/library/runpy.rst @@ -10,7 +10,7 @@ -------------- -The :mod:`runpy` module is used to locate and run Python modules without +The :mod:`runpy` module is used to locate and execute Python modules without importing them first. Its main use is to implement the :option:`-m` command line switch that allows scripts to be located using the Python module namespace rather than the filesystem. @@ -33,7 +33,7 @@ The :mod:`runpy` module provides two functions: module: __main__ Execute the code of the specified module and return the resulting module - globals dictionary. The module's code is first located using the standard + globals dictionary. The module code is first located using the standard import mechanism (refer to :pep:`302` for details) and then executed in a fresh module namespace. @@ -44,16 +44,16 @@ The :mod:`runpy` module provides two functions: returned. The optional dictionary argument *init_globals* may be used to pre-populate - the module's globals dictionary before the code is executed. The supplied + the module globals dictionary before the code is executed. The supplied dictionary will not be modified. If any of the special global variables below are defined in the supplied dictionary, those definitions are overridden by :func:`run_module`. The special global variables ``__name__``, ``__spec__``, ``__file__``, ``__cached__``, ``__loader__`` and ``__package__`` are set in the globals - dictionary before the module code is executed (Note that this is a + dictionary before the module code is executed. (Note that this is a minimal set of variables - other variables may be set implicitly as an - interpreter implementation detail). + interpreter implementation detail.) ``__name__`` is set to *run_name* if this optional argument is not :const:`None`, to ``mod_name + '.__main__'`` if the named module is a @@ -61,7 +61,7 @@ The :mod:`runpy` module provides two functions: ``__spec__`` will be set appropriately for the *actually* imported module (that is, ``__spec__.name`` will always be *mod_name* or - ``mod_name + '.__main__``, never *run_name*). + ``mod_name + '.__main__'``, never *run_name*). ``__file__``, ``__cached__``, ``__loader__`` and ``__package__`` are :ref:`set as normal ` based on the module spec. @@ -90,7 +90,7 @@ The :mod:`runpy` module provides two functions: .. versionchanged:: 3.4 Updated to take advantage of the module spec feature added by :pep:`451`. This allows ``__cached__`` to be set correctly for modules - run this way, as well as ensuring the real module name is always + executed this way, as well as ensuring the real module name is always accessible as ``__spec__.name``. .. function:: run_path(file_path, init_globals=None, run_name=None) @@ -113,26 +113,26 @@ The :mod:`runpy` module provides two functions: there is no such module at the specified location. The optional dictionary argument *init_globals* may be used to pre-populate - the module's globals dictionary before the code is executed. The supplied + the module globals dictionary before the code is executed. The supplied dictionary will not be modified. If any of the special global variables below are defined in the supplied dictionary, those definitions are overridden by :func:`run_path`. The special global variables ``__name__``, ``__spec__``, ``__file__``, ``__cached__``, ``__loader__`` and ``__package__`` are set in the globals - dictionary before the module code is executed (Note that this is a + dictionary before the module code is executed. (Note that this is a minimal set of variables - other variables may be set implicitly as an - interpreter implementation detail). + interpreter implementation detail.) ``__name__`` is set to *run_name* if this optional argument is not :const:`None` and to ``''`` otherwise. - If the supplied path directly references a script file (whether as source + If ``file_path`` directly references a script file (whether as source or as precompiled byte code), then ``__file__`` will be set to the supplied path, and ``__spec__``, ``__cached__``, ``__loader__`` and ``__package__`` will all be set to :const:`None`. - If the supplied path is a reference to a valid sys.path entry, then + If ``file_path`` references a valid sys.path entry, then ``__spec__`` will be set appropriately for the imported ``__main__`` module (that is, ``__spec__.name`` will always be ``__main__``). ``__file__``, ``__cached__``, ``__loader__`` and ``__package__`` will be @@ -141,9 +141,9 @@ The :mod:`runpy` module provides two functions: A number of alterations are also made to the :mod:`sys` module. Firstly, ``sys.path`` may be altered as described above. ``sys.argv[0]`` is updated with the value of ``file_path`` and ``sys.modules[__name__]`` is updated - with a temporary module object for the module being executed. All - modifications to items in :mod:`sys` are reverted before the function - returns. + with a temporary module object for the module being executed. Both + ``sys.argv[0]`` and ``sys.modules[__name__]`` are restored to their + original values before the function returns. Note that, unlike :func:`run_module`, the alterations made to :mod:`sys` are not optional in this function as these adjustments are essential to From 62a7864c259081e39ab2f89c9432131ddec13dfb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9ry=20Ogam?= Date: Sun, 9 Feb 2020 01:57:03 +0100 Subject: [PATCH 2/6] Update runpy.rst --- Doc/library/runpy.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Doc/library/runpy.rst b/Doc/library/runpy.rst index 6d8ff73d5ae34a..c341bad7d02091 100644 --- a/Doc/library/runpy.rst +++ b/Doc/library/runpy.rst @@ -141,9 +141,9 @@ The :mod:`runpy` module provides two functions: A number of alterations are also made to the :mod:`sys` module. Firstly, ``sys.path`` may be altered as described above. ``sys.argv[0]`` is updated with the value of ``file_path`` and ``sys.modules[__name__]`` is updated - with a temporary module object for the module being executed. Both - ``sys.argv[0]`` and ``sys.modules[__name__]`` are restored to their - original values before the function returns. + with a temporary module object for the module being executed. All + modifications to items in :mod:`sys` are reverted before the function + returns. Note that, unlike :func:`run_module`, the alterations made to :mod:`sys` are not optional in this function as these adjustments are essential to From 5ccd613feed92dc622865148aa5774a8d5c93984 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9ry=20Ogam?= Date: Tue, 11 Feb 2020 11:10:10 +0100 Subject: [PATCH 3/6] Update runpy.rst --- Doc/library/runpy.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Doc/library/runpy.rst b/Doc/library/runpy.rst index c341bad7d02091..f02c8254a5bce0 100644 --- a/Doc/library/runpy.rst +++ b/Doc/library/runpy.rst @@ -32,7 +32,7 @@ The :mod:`runpy` module provides two functions: .. index:: module: __main__ - Execute the code of the specified module and return the resulting module + Execute the code of the specified module and return the resulting module's globals dictionary. The module code is first located using the standard import mechanism (refer to :pep:`302` for details) and then executed in a fresh module namespace. @@ -40,7 +40,7 @@ The :mod:`runpy` module provides two functions: The *mod_name* argument should be an absolute module name. If the module name refers to a package rather than a normal module, then that package is imported and the ``__main__`` submodule within - that package is then executed and the resulting module globals dictionary + that package is then executed and the resulting module's globals dictionary returned. The optional dictionary argument *init_globals* may be used to pre-populate @@ -99,7 +99,7 @@ The :mod:`runpy` module provides two functions: module: __main__ Execute the code at the named filesystem location and return the resulting - module globals dictionary. As with a script name supplied to the CPython + module's globals dictionary. As with a script name supplied to the CPython command line, the supplied path may refer to a Python source file, a compiled bytecode file or a valid sys.path entry containing a ``__main__`` module (e.g. a zipfile containing a top-level ``__main__.py`` file). @@ -113,7 +113,7 @@ The :mod:`runpy` module provides two functions: there is no such module at the specified location. The optional dictionary argument *init_globals* may be used to pre-populate - the module globals dictionary before the code is executed. The supplied + the module's globals dictionary before the code is executed. The supplied dictionary will not be modified. If any of the special global variables below are defined in the supplied dictionary, those definitions are overridden by :func:`run_path`. From a0ad2bf88a34703f921bec871fa795f91b429172 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9ry=20Ogam?= Date: Tue, 11 Feb 2020 11:11:12 +0100 Subject: [PATCH 4/6] Update runpy.rst --- Doc/library/runpy.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/runpy.rst b/Doc/library/runpy.rst index f02c8254a5bce0..c8d0c36399c165 100644 --- a/Doc/library/runpy.rst +++ b/Doc/library/runpy.rst @@ -44,7 +44,7 @@ The :mod:`runpy` module provides two functions: returned. The optional dictionary argument *init_globals* may be used to pre-populate - the module globals dictionary before the code is executed. The supplied + the module's globals dictionary before the code is executed. The supplied dictionary will not be modified. If any of the special global variables below are defined in the supplied dictionary, those definitions are overridden by :func:`run_module`. From 30aedb0465770aca4fe54bae10657597d14b1ef1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9ry=20Ogam?= Date: Thu, 5 Mar 2020 12:32:43 +0100 Subject: [PATCH 5/6] Update runpy.rst --- Doc/library/runpy.rst | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/Doc/library/runpy.rst b/Doc/library/runpy.rst index c8d0c36399c165..d0c311d57aac48 100644 --- a/Doc/library/runpy.rst +++ b/Doc/library/runpy.rst @@ -44,9 +44,9 @@ The :mod:`runpy` module provides two functions: returned. The optional dictionary argument *init_globals* may be used to pre-populate - the module's globals dictionary before the code is executed. The supplied - dictionary will not be modified. If any of the special global variables - below are defined in the supplied dictionary, those definitions are + the module's globals dictionary before the code is executed. + *init_globals* will not be modified. If any of the special global variables + below are defined in *init_globals*, those definitions are overridden by :func:`run_module`. The special global variables ``__name__``, ``__spec__``, ``__file__``, @@ -100,7 +100,7 @@ The :mod:`runpy` module provides two functions: Execute the code at the named filesystem location and return the resulting module's globals dictionary. As with a script name supplied to the CPython - command line, the supplied path may refer to a Python source file, a + command line, *file_path* may refer to a Python source file, a compiled bytecode file or a valid sys.path entry containing a ``__main__`` module (e.g. a zipfile containing a top-level ``__main__.py`` file). @@ -113,9 +113,9 @@ The :mod:`runpy` module provides two functions: there is no such module at the specified location. The optional dictionary argument *init_globals* may be used to pre-populate - the module's globals dictionary before the code is executed. The supplied - dictionary will not be modified. If any of the special global variables - below are defined in the supplied dictionary, those definitions are + the module's globals dictionary before the code is executed. + *init_globals* will not be modified. If any of the special global variables + below are defined in *init_globals*, those definitions are overridden by :func:`run_path`. The special global variables ``__name__``, ``__spec__``, ``__file__``, @@ -127,12 +127,12 @@ The :mod:`runpy` module provides two functions: ``__name__`` is set to *run_name* if this optional argument is not :const:`None` and to ``''`` otherwise. - If ``file_path`` directly references a script file (whether as source - or as precompiled byte code), then ``__file__`` will be set to the - supplied path, and ``__spec__``, ``__cached__``, ``__loader__`` and + If *file_path* directly references a script file (whether as source + or as precompiled byte code), then ``__file__`` will be set to + *file_path*, and ``__spec__``, ``__cached__``, ``__loader__`` and ``__package__`` will all be set to :const:`None`. - If ``file_path`` references a valid sys.path entry, then + If *file_path* references a valid sys.path entry, then ``__spec__`` will be set appropriately for the imported ``__main__`` module (that is, ``__spec__.name`` will always be ``__main__``). ``__file__``, ``__cached__``, ``__loader__`` and ``__package__`` will be @@ -140,7 +140,7 @@ The :mod:`runpy` module provides two functions: A number of alterations are also made to the :mod:`sys` module. Firstly, ``sys.path`` may be altered as described above. ``sys.argv[0]`` is updated - with the value of ``file_path`` and ``sys.modules[__name__]`` is updated + with the value of *file_path* and ``sys.modules[__name__]`` is updated with a temporary module object for the module being executed. All modifications to items in :mod:`sys` are reverted before the function returns. From 1c6ad90e4e2eeb904cd38d70facae3d30a2ded57 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Tue, 23 Jan 2024 00:54:06 +0100 Subject: [PATCH 6/6] Apply suggestions from code review --- Doc/library/runpy.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/Doc/library/runpy.rst b/Doc/library/runpy.rst index b4ef3a13d68e07..f2cb595f495f6b 100644 --- a/Doc/library/runpy.rst +++ b/Doc/library/runpy.rst @@ -10,7 +10,7 @@ -------------- -The :mod:`runpy` module is used to locate and execute Python modules without +The :mod:`runpy` module is used to locate and run Python modules without importing them first. Its main use is to implement the :option:`-m` command line switch that allows scripts to be located using the Python module namespace rather than the filesystem. @@ -33,13 +33,13 @@ The :mod:`runpy` module provides two functions: pair: module; __main__ Execute the code of the specified module and return the resulting module's - globals dictionary. The module code is first located using the standard + globals dictionary. The module's code is first located using the standard import mechanism (refer to :pep:`302` for details) and then executed in a fresh module namespace. The *mod_name* argument should be an absolute module name. If the module name refers to a package rather than a normal - module, then that package is imported and the :mod:`!__main__` submodule within + module, then that package is imported and the :mod:`__main__` submodule within that package is then executed and the resulting module globals dictionary returned. @@ -90,7 +90,7 @@ The :mod:`runpy` module provides two functions: .. versionchanged:: 3.4 Updated to take advantage of the module spec feature added by :pep:`451`. This allows ``__cached__`` to be set correctly for modules - executed this way, as well as ensuring the real module name is always + run this way, as well as ensuring the real module name is always accessible as ``__spec__.name``. .. versionchanged:: 3.12 @@ -107,7 +107,7 @@ The :mod:`runpy` module provides two functions: module's globals dictionary. As with a script name supplied to the CPython command line, *file_path* may refer to a Python source file, a compiled bytecode file or a valid :data:`sys.path` entry containing a - :mod:`!__main__` module + :mod:`__main__` module (e.g. a zipfile containing a top-level :file:`__main__.py` file). For a simple script, the specified code is simply executed in a fresh @@ -139,7 +139,7 @@ The :mod:`runpy` module provides two functions: ``__package__`` will all be set to :const:`None`. If *file_path* is a reference to a valid :data:`sys.path` entry, then - ``__spec__`` will be set appropriately for the imported :mod:`!__main__` + ``__spec__`` will be set appropriately for the imported :mod:`__main__` module (that is, ``__spec__.name`` will always be ``__main__``). ``__file__``, ``__cached__``, ``__loader__`` and ``__package__`` will be :ref:`set as normal ` based on the module spec.