Doc/library/runpy.rst

   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