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 (a] gmail.com> 8 9 **Source code:** :source:`Lib/runpy.py` 10 11 -------------- 12 13 The :mod:`runpy` module is used to locate and run Python modules without 14 importing them first. Its main use is to implement the :option:`-m` command 15 line switch that allows scripts to be located using the Python module 16 namespace rather than the filesystem. 17 18 Note that this is *not* a sandbox module - all code is executed in the 19 current process, and any side effects (such as cached imports of other 20 modules) will remain in place after the functions have returned. 21 22 Furthermore, any functions and classes defined by the executed code are not 23 guaranteed to work correctly after a :mod:`runpy` function has returned. 24 If that limitation is not acceptable for a given use case, :mod:`importlib` 25 is likely to be a more suitable choice than this module. 26 27 The :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
