/Doc/library/runpy.rst

http://unladen-swallow.googlecode.com/ · ReStructuredText · 69 lines · 47 code · 22 blank · 0 comment · 0 complexity · cdb52dd98fd0c005cc6ca7ab39731130 MD5 · raw file

  1. :mod:`runpy` --- Locating and executing Python modules
  2. ======================================================
  3. .. module:: runpy
  4. :synopsis: Locate and run Python modules without importing them first.
  5. .. moduleauthor:: Nick Coghlan <ncoghlan@gmail.com>
  6. .. versionadded:: 2.5
  7. The :mod:`runpy` module is used to locate and run Python modules without
  8. importing them first. Its main use is to implement the :option:`-m` command line
  9. switch that allows scripts to be located using the Python module namespace
  10. rather than the filesystem.
  11. When executed as a script, the module effectively operates as follows::
  12. del sys.argv[0] # Remove the runpy module from the arguments
  13. run_module(sys.argv[0], run_name="__main__", alter_sys=True)
  14. The :mod:`runpy` module provides a single function:
  15. .. function:: run_module(mod_name[, init_globals] [, run_name][, alter_sys])
  16. Execute the code of the specified module and return the resulting module globals
  17. dictionary. The module's code is first located using the standard import
  18. mechanism (refer to PEP 302 for details) and then executed in a fresh module
  19. namespace.
  20. The optional dictionary argument *init_globals* may be used to pre-populate the
  21. globals dictionary before the code is executed. The supplied dictionary will not
  22. be modified. If any of the special global variables below are defined in the
  23. supplied dictionary, those definitions are overridden by the ``run_module``
  24. function.
  25. The special global variables ``__name__``, ``__file__``, ``__loader__`` and
  26. ``__builtins__`` are set in the globals dictionary before the module code is
  27. executed.
  28. ``__name__`` is set to *run_name* if this optional argument is supplied, and the
  29. *mod_name* argument otherwise.
  30. ``__loader__`` is set to the PEP 302 module loader used to retrieve the code for
  31. the module (This loader may be a wrapper around the standard import mechanism).
  32. ``__file__`` is set to the name provided by the module loader. If the loader
  33. does not make filename information available, this variable is set to ``None``.
  34. ``__builtins__`` is automatically initialised with a reference to the top level
  35. namespace of the :mod:`__builtin__` module.
  36. If the argument *alter_sys* is supplied and evaluates to ``True``, then
  37. ``sys.argv[0]`` is updated with the value of ``__file__`` and
  38. ``sys.modules[__name__]`` is updated with a temporary module object for the
  39. module being executed. Both ``sys.argv[0]`` and ``sys.modules[__name__]``
  40. are restored to their original values before the function returns.
  41. Note that this manipulation of :mod:`sys` is not thread-safe. Other threads may
  42. see the partially initialised module, as well as the altered list of arguments.
  43. It is recommended that the :mod:`sys` module be left alone when invoking this
  44. function from threaded code.
  45. .. seealso::
  46. :pep:`338` - Executing modules as scripts
  47. PEP written and implemented by Nick Coghlan.