1 :mod:`runpy` --- Locating and executing Python modules

     2 ======================================================

     3 

     4 .. module:: runpy

     5    :synopsis: Locate and run Python modules without importing them first.

     6 .. moduleauthor:: Nick Coghlan <ncoghlan@gmail.com>

     7 

     8 

     9 .. versionadded:: 2.5

    10 

    11 The :mod:`runpy` module is used to locate and run Python modules without

    12 importing them first. Its main use is to implement the :option:`-m` command line

    13 switch that allows scripts to be located using the Python module namespace

    14 rather than the filesystem.

    15 

    16 When executed as a script, the module effectively operates as follows::

    17 

    18    del sys.argv[0]  # Remove the runpy module from the arguments

    19    run_module(sys.argv[0], run_name="__main__", alter_sys=True)

    20 

    21 The :mod:`runpy` module provides a single function:

    22 

    23 

    24 .. function:: run_module(mod_name[, init_globals] [, run_name][, alter_sys])

    25 

    26    Execute the code of the specified module and return the resulting module globals

    27    dictionary. The module's code is first located using the standard import

    28    mechanism (refer to PEP 302 for details) and then executed in a fresh module

    29    namespace.

    30 

    31    The optional dictionary argument *init_globals* may be used to pre-populate the

    32    globals dictionary before the code is executed. The supplied dictionary will not

    33    be modified. If any of the special global variables below are defined in the

    34    supplied dictionary, those definitions are overridden by the ``run_module``

    35    function.

    36 

    37    The special global variables ``__name__``, ``__file__``, ``__loader__`` and

    38    ``__builtins__`` are set in the globals dictionary before the module code is

    39    executed.

    40 

    41    ``__name__`` is set to *run_name* if this optional argument is supplied, and the

    42    *mod_name* argument otherwise.

    43 

    44    ``__loader__`` is set to the PEP 302 module loader used to retrieve the code for

    45    the module (This loader may be a wrapper around the standard import mechanism).

    46 

    47    ``__file__`` is set to the name provided by the module loader. If the loader

    48    does not make filename information available, this variable is set to ``None``.

    49 

    50    ``__builtins__`` is automatically initialised with a reference to the top level

    51    namespace of the :mod:`__builtin__` module.

    52 

    53    If the argument *alter_sys* is supplied and evaluates to ``True``, then

    54    ``sys.argv[0]`` is updated with the value of ``__file__`` and

    55    ``sys.modules[__name__]`` is updated with a temporary module object for the

    56    module being executed. Both ``sys.argv[0]`` and ``sys.modules[__name__]``

    57    are restored to their original values before the function returns.

    58 

    59    Note that this manipulation of :mod:`sys` is not thread-safe. Other threads may

    60    see the partially initialised module, as well as the altered list of arguments.

    61    It is recommended that the :mod:`sys` module be left alone when invoking this

    62    function from threaded code.

    63 

    64 

    65 .. seealso::

    66 

    67    :pep:`338` - Executing modules as scripts

    68       PEP written and  implemented by Nick Coghlan.

    69