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
7.. moduleauthor:: Nick Coghlan <ncoghlan@gmail.com>
8
9**Source code:** :source:`Lib/runpy.py`
10
11--------------
12
13The :mod:`runpy` module is used to locate and run Python modules without
14importing them first. Its main use is to implement the :option:`-m` command
15line switch that allows scripts to be located using the Python module
16namespace rather than the filesystem.
17
18Note that this is *not* a sandbox module - all code is executed in the
19current process, and any side effects (such as cached imports of other
20modules) will remain in place after the functions have returned.
21
22Furthermore, any functions and classes defined by the executed code are not
23guaranteed to work correctly after a :mod:`runpy` function has returned.
24If that limitation is not acceptable for a given use case, :mod:`importlib`
25is likely to be a more suitable choice than this module.
26
27The :mod:`runpy` module provides two functions:
28
29
30.. function:: run_module(mod_name, init_globals=None, run_name=None, alter_sys=False)
31
32   .. index::
33      module: __main__
34
35   Execute the code of the specified module and return the resulting module
36   globals dictionary. The module's code is first located using the standard
37   import mechanism (refer to :pep:`302` for details) and then executed in a
38   fresh module namespace.
39
40   The *mod_name* argument should be an absolute module name.
41   If the module name refers to a package rather than a normal
42   module, then that package is imported and the ``__main__`` submodule within
43   that package is then executed and the resulting module globals dictionary
44   returned.
45
46   The optional dictionary argument *init_globals* may be used to pre-populate
47   the module's globals dictionary before the code is executed. The supplied
48   dictionary will not be modified. If any of the special global variables
49   below are defined in the supplied dictionary, those definitions are
50   overridden by :func:`run_module`.
51
52   The special global variables ``__name__``, ``__spec__``, ``__file__``,
53   ``__cached__``, ``__loader__`` and ``__package__`` are set in the globals
54   dictionary before the module code is executed (Note that this is a
55   minimal set of variables - other variables may be set implicitly as an
56   interpreter implementation detail).
57
58   ``__name__`` is set to *run_name* if this optional argument is not
59   :const:`None`, to ``mod_name + '.__main__'`` if the named module is a
60   package and to the *mod_name* argument otherwise.
61
62   ``__spec__`` will be set appropriately for the *actually* imported
63   module (that is, ``__spec__.name`` will always be *mod_name* or
64   ``mod_name + '.__main__``, never *run_name*).
65
66   ``__file__``, ``__cached__``, ``__loader__`` and ``__package__`` are
67   :ref:`set as normal <import-mod-attrs>` based on the module spec.
68
69   If the argument *alter_sys* is supplied and evaluates to :const:`True`,
70   then ``sys.argv[0]`` is updated with the value of ``__file__`` and
71   ``sys.modules[__name__]`` is updated with a temporary module object for the
72   module being executed. Both ``sys.argv[0]`` and ``sys.modules[__name__]``
73   are restored to their original values before the function returns.
74
75   Note that this manipulation of :mod:`sys` is not thread-safe. Other threads
76   may see the partially initialised module, as well as the altered list of
77   arguments. It is recommended that the :mod:`sys` module be left alone when
78   invoking this function from threaded code.
79
80   .. seealso::
81      The :option:`-m` option offering equivalent functionality from the
82      command line.
83
84   .. versionchanged:: 3.1
85      Added ability to execute packages by looking for a ``__main__`` submodule.
86
87   .. versionchanged:: 3.2
88      Added ``__cached__`` global variable (see :pep:`3147`).
89
90   .. versionchanged:: 3.4
91      Updated to take advantage of the module spec feature added by
92      :pep:`451`. This allows ``__cached__`` to be set correctly for modules
93      run this way, as well as ensuring the real module name is always
94      accessible as ``__spec__.name``.
95
96.. function:: run_path(file_path, init_globals=None, run_name=None)
97
98   .. index::
99      module: __main__
100
101   Execute the code at the named filesystem location and return the resulting
102   module globals dictionary. As with a script name supplied to the CPython
103   command line, the supplied path may refer to a Python source file, a
104   compiled bytecode file or a valid sys.path entry containing a ``__main__``
105   module (e.g. a zipfile containing a top-level ``__main__.py`` file).
106
107   For a simple script, the specified code is simply executed in a fresh
108   module namespace. For a valid sys.path entry (typically a zipfile or
109   directory), the entry is first added to the beginning of ``sys.path``. The
110   function then looks for and executes a :mod:`__main__` module using the
111   updated path. Note that there is no special protection against invoking
112   an existing :mod:`__main__` entry located elsewhere on ``sys.path`` if
113   there is no such module at the specified location.
114
115   The optional dictionary argument *init_globals* may be used to pre-populate
116   the module's globals dictionary before the code is executed. The supplied
117   dictionary will not be modified. If any of the special global variables
118   below are defined in the supplied dictionary, those definitions are
119   overridden by :func:`run_path`.
120
121   The special global variables ``__name__``, ``__spec__``, ``__file__``,
122   ``__cached__``, ``__loader__`` and ``__package__`` are set in the globals
123   dictionary before the module code is executed (Note that this is a
124   minimal set of variables - other variables may be set implicitly as an
125   interpreter implementation detail).
126
127   ``__name__`` is set to *run_name* if this optional argument is not
128   :const:`None` and to ``'<run_path>'`` otherwise.
129
130   If the supplied path directly references a script file (whether as source
131   or as precompiled byte code), then ``__file__`` will be set to the
132   supplied path, and ``__spec__``, ``__cached__``, ``__loader__`` and
133   ``__package__`` will all be set to :const:`None`.
134
135   If the supplied path is a reference to a valid sys.path entry, then
136   ``__spec__`` will be set appropriately for the imported ``__main__``
137   module (that is, ``__spec__.name`` will always be ``__main__``).
138   ``__file__``, ``__cached__``, ``__loader__`` and ``__package__`` will be
139   :ref:`set as normal <import-mod-attrs>` based on the module spec.
140
141   A number of alterations are also made to the :mod:`sys` module. Firstly,
142   ``sys.path`` may be altered as described above. ``sys.argv[0]`` is updated
143   with the value of ``file_path`` and ``sys.modules[__name__]`` is updated
144   with a temporary module object for the module being executed. All
145   modifications to items in :mod:`sys` are reverted before the function
146   returns.
147
148   Note that, unlike :func:`run_module`, the alterations made to :mod:`sys`
149   are not optional in this function as these adjustments are essential to
150   allowing the execution of sys.path entries. As the thread-safety
151   limitations still apply, use of this function in threaded code should be
152   either serialised with the import lock or delegated to a separate process.
153
154   .. seealso::
155      :ref:`using-on-interface-options` for equivalent functionality on the
156      command line (``python path/to/script``).
157
158   .. versionadded:: 3.2
159
160   .. versionchanged:: 3.4
161      Updated to take advantage of the module spec feature added by
162      :pep:`451`. This allows ``__cached__`` to be set correctly in the
163      case where ``__main__`` is imported from a valid sys.path entry rather
164      than being executed directly.
165
166.. seealso::
167
168   :pep:`338` -- Executing modules as scripts
169      PEP written and implemented by Nick Coghlan.
170
171   :pep:`366` -- Main module explicit relative imports
172      PEP written and implemented by Nick Coghlan.
173
174   :pep:`451` -- A ModuleSpec Type for the Import System
175      PEP written and implemented by Eric Snow
176
177   :ref:`using-on-general` - CPython command line details
178
179   The :func:`importlib.import_module` function
180