diff options
Diffstat (limited to 'Doc/library/runpy.rst')
| -rw-r--r-- | Doc/library/runpy.rst | 146 |
1 files changed, 104 insertions, 42 deletions
diff --git a/Doc/library/runpy.rst b/Doc/library/runpy.rst index 1b48167..f7c77f6 100644 --- a/Doc/library/runpy.rst +++ b/Doc/library/runpy.rst @@ -5,71 +5,132 @@ :synopsis: Locate and run Python modules without importing them first. .. moduleauthor:: Nick Coghlan <ncoghlan@gmail.com> +**Source code:** :source:`Lib/runpy.py` -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. - -When executed as a script, the module effectively operates as follows:: +-------------- - del sys.argv[0] # Remove the runpy module from the arguments - run_module(sys.argv[0], run_name="__main__", alter_sys=True) +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. -The :mod:`runpy` module provides a single function: +The :mod:`runpy` module provides two functions: -.. function:: run_module(mod_name[, init_globals] [, run_name][, alter_sys]) +.. function:: run_module(mod_name, init_globals=None, run_name=None, alter_sys=False) - Execute the code of the specified module and return the resulting module 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. + Execute the code of the specified module and return the resulting module + 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. - If the supplied 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 returned. + If the supplied 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 + returned. - The optional dictionary argument *init_globals* may be used to pre-populate the - 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 the ``run_module`` - function. + 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 + overridden by :func:`run_module`. - The special global variables ``__name__``, ``__file__``, ``__loader__``, - ``__builtins__`` and ``__package__`` are set in the globals dictionary before - the module code is executed. + The special global variables ``__name__``, ``__file__``, ``__cached__``, + ``__loader__`` + and ``__package__`` are set in the globals 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). - ``__name__`` is set to *run_name* if this optional argument is supplied, to - ``mod_name + '.__main__'`` if the named module is a package and to the - *mod_name* argument otherwise. + ``__name__`` is set to *run_name* if this optional argument is not + :const:`None`, to ``mod_name + '.__main__'`` if the named module is a + package and to the *mod_name* argument otherwise. - ``__loader__`` is set to the PEP 302 module loader used to retrieve the code for - the module (This loader may be a wrapper around the standard import mechanism). + ``__file__`` is set to the name provided by the module loader. If the + loader does not make filename information available, this variable is set + to :const:`None`. - ``__file__`` is set to the name provided by the module loader. If the loader - does not make filename information available, this variable is set to ``None``. + ``__cached__`` will be set to ``None``. - ``__builtins__`` is automatically initialised with a reference to the top level - namespace of the :mod:`builtins` module. + ``__loader__`` is set to the :pep:`302` module loader used to retrieve the + code for the module (This loader may be a wrapper around the standard + import mechanism). - ``__package__`` is set to *mod_name* if the named module is a package and to - ``mod_name.rpartition('.')[0]`` otherwise. + ``__package__`` is set to *mod_name* if the named module is a package and + to ``mod_name.rpartition('.')[0]`` otherwise. - If the argument *alter_sys* is supplied and evaluates to ``True``, then - ``sys.argv[0]`` is updated with the value of ``__file__`` and + If the argument *alter_sys* is supplied and evaluates to :const:`True`, + then ``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 ``sys.argv[0]`` and ``sys.modules[__name__]`` are restored to their original values before the function returns. - Note that this manipulation of :mod:`sys` is not thread-safe. Other threads may - see the partially initialised module, as well as the altered list of arguments. - It is recommended that the :mod:`sys` module be left alone when invoking this - function from threaded code. + Note that this manipulation of :mod:`sys` is not thread-safe. Other threads + may see the partially initialised module, as well as the altered list of + arguments. It is recommended that the :mod:`sys` module be left alone when + invoking this function from threaded code. + .. versionchanged:: 3.1 Added ability to execute packages by looking for a ``__main__`` submodule. + .. versionchanged:: 3.2 + Added ``__cached__`` global variable (see :PEP:`3147`). + + +.. function:: run_path(file_path, init_globals=None, run_name=None) + + Execute the code at the named filesystem location and return the resulting + module 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). + + For a simple script, the specified code is simply executed in a fresh + module namespace. For a valid sys.path entry (typically a zipfile or + directory), the entry is first added to the beginning of ``sys.path``. The + function then looks for and executes a :mod:`__main__` module using the + updated path. Note that there is no special protection against invoking + an existing :mod:`__main__` entry located elsewhere on ``sys.path`` if + 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 + overridden by :func:`run_path`. + + The special global variables ``__name__``, ``__file__``, ``__loader__`` + and ``__package__`` are set in the globals 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). + + ``__name__`` is set to *run_name* if this optional argument is not + :const:`None` and to ``'<run_path>'`` otherwise. + + ``__file__`` is set to the name provided by the module loader. If the + loader does not make filename information available, this variable is set + to :const:`None`. For a simple script, this will be set to ``file_path``. + + ``__loader__`` is set to the :pep:`302` module loader used to retrieve the + code for the module (This loader may be a wrapper around the standard + import mechanism). For a simple script, this will be set to :const:`None`. + + ``__package__`` is set to ``__name__.rpartition('.')[0]``. + + 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. + + Note that, unlike :func:`run_module`, the alterations made to :mod:`sys` + are not optional in this function as these adjustments are essential to + allowing the execution of sys.path entries. As the thread-safety + limitations still apply, use of this function in threaded code should be + either serialised with the import lock or delegated to a separate process. + + .. versionadded:: 3.2 .. seealso:: @@ -79,3 +140,4 @@ The :mod:`runpy` module provides a single function: :pep:`366` - Main module explicit relative imports PEP written and implemented by Nick Coghlan. + :ref:`using-on-general` - CPython command line details |