mirror of
https://github.com/python/cpython.git
synced 2025-10-31 05:31:20 +00:00
3f48ae35c7
svn+ssh://pythondev@svn.python.org/python/trunk ........ r69419 | nick.coghlan | 2009-02-08 11:26:34 +1000 (Sun, 08 Feb 2009) | 1 line Issue 4195: Restore the ability to execute packages with the -m switch (but this time in a way that leaves the import machinery in a valid state). (Original patch by Andi Vajda) ........ r69420 | nick.coghlan | 2009-02-08 11:46:01 +1000 (Sun, 08 Feb 2009) | 1 line Mention patch submitter in NEWS entry for r69419 ........
82 lines
3.5 KiB
ReStructuredText
82 lines
3.5 KiB
ReStructuredText
:mod:`runpy` --- Locating and executing Python modules
|
|
======================================================
|
|
|
|
.. module:: runpy
|
|
:synopsis: Locate and run Python modules without importing them first.
|
|
.. moduleauthor:: Nick Coghlan <ncoghlan@gmail.com>
|
|
|
|
|
|
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 provides a single function:
|
|
|
|
|
|
.. function:: run_module(mod_name[, init_globals] [, run_name][, alter_sys])
|
|
|
|
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.
|
|
|
|
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 special global variables ``__name__``, ``__file__``, ``__loader__``,
|
|
``__builtins__`` and ``__package__`` are set in the globals dictionary before
|
|
the module code is executed.
|
|
|
|
``__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.
|
|
|
|
``__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 ``None``.
|
|
|
|
``__builtins__`` is automatically initialised with a reference to the top level
|
|
namespace of the :mod:`builtins` module.
|
|
|
|
``__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
|
|
``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.
|
|
|
|
|
|
.. versionchanged:: 3.1
|
|
Added ability to execute packages by looking for a ``__main__`` submodule
|
|
|
|
|
|
.. seealso::
|
|
|
|
:pep:`338` - Executing modules as scripts
|
|
PEP written and implemented by Nick Coghlan.
|
|
|
|
:pep:`366` - Main module explicit relative imports
|
|
PEP written and implemented by Nick Coghlan.
|
|
|