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