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. |
Terry Jan Reedy | fa089b9 | 2016-06-11 15:02:54 -0400 | [diff] [blame] | 6 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 7 | .. moduleauthor:: Nick Coghlan <ncoghlan@gmail.com> |
| 8 | |
Raymond Hettinger | a199368 | 2011-01-27 01:20:32 +0000 | [diff] [blame] | 9 | **Source code:** :source:`Lib/runpy.py` |
| 10 | |
| 11 | -------------- |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 12 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 13 | 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] | 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. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 17 | |
Nick Coghlan | a3d1cac | 2012-07-15 00:36:39 +1000 | [diff] [blame] | 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 | |
Nick Coghlan | 260bd3e | 2009-11-16 06:49:25 +0000 | [diff] [blame] | 27 | The :mod:`runpy` module provides two functions: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 28 | |
| 29 | |
Georg Brandl | 1824415 | 2009-09-02 20:34:52 +0000 | [diff] [blame] | 30 | .. 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] | 31 | |
Senthil Kumaran | 4932e14 | 2014-06-20 01:37:53 -0700 | [diff] [blame] | 32 | .. index:: |
| 33 | module: __main__ |
| 34 | |
Nick Coghlan | 260bd3e | 2009-11-16 06:49:25 +0000 | [diff] [blame] | 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 |
Victor Stinner | 766ad36 | 2010-05-14 14:36:18 +0000 | [diff] [blame] | 37 | 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] | 38 | fresh module namespace. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 39 | |
Martin Panter | 7dda421 | 2015-12-10 06:47:06 +0000 | [diff] [blame] | 40 | The *mod_name* argument should be an absolute module name. |
| 41 | If the module name refers to a package rather than a normal |
Nick Coghlan | 260bd3e | 2009-11-16 06:49:25 +0000 | [diff] [blame] | 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. |
Nick Coghlan | 3f48ae3 | 2009-02-08 01:58:26 +0000 | [diff] [blame] | 45 | |
Nick Coghlan | 260bd3e | 2009-11-16 06:49:25 +0000 | [diff] [blame] | 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`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 51 | |
Nick Coghlan | 720c7e2 | 2013-12-15 20:33:02 +1000 | [diff] [blame] | 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). |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 57 | |
Nick Coghlan | 260bd3e | 2009-11-16 06:49:25 +0000 | [diff] [blame] | 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. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 61 | |
Nick Coghlan | 720c7e2 | 2013-12-15 20:33:02 +1000 | [diff] [blame] | 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*). |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 65 | |
Nick Coghlan | 720c7e2 | 2013-12-15 20:33:02 +1000 | [diff] [blame] | 66 | ``__file__``, ``__cached__``, ``__loader__`` and ``__package__`` are |
| 67 | :ref:`set as normal <import-mod-attrs>` based on the module spec. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 68 | |
Nick Coghlan | 260bd3e | 2009-11-16 06:49:25 +0000 | [diff] [blame] | 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 |
Thomas Wouters | ed03b41 | 2007-08-28 21:37:11 +0000 | [diff] [blame] | 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. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 74 | |
Nick Coghlan | 260bd3e | 2009-11-16 06:49:25 +0000 | [diff] [blame] | 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. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 79 | |
Berker Peksag | 8b1cbd2 | 2014-12-10 01:47:02 +0200 | [diff] [blame] | 80 | .. seealso:: |
| 81 | The :option:`-m` option offering equivalent functionality from the |
| 82 | command line. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 83 | |
Nick Coghlan | 3f48ae3 | 2009-02-08 01:58:26 +0000 | [diff] [blame] | 84 | .. versionchanged:: 3.1 |
Georg Brandl | 67b21b7 | 2010-08-17 15:07:14 +0000 | [diff] [blame] | 85 | Added ability to execute packages by looking for a ``__main__`` submodule. |
Nick Coghlan | 3f48ae3 | 2009-02-08 01:58:26 +0000 | [diff] [blame] | 86 | |
Éric Araujo | 930df31 | 2010-12-16 06:28:48 +0000 | [diff] [blame] | 87 | .. versionchanged:: 3.2 |
Nick Coghlan | 720c7e2 | 2013-12-15 20:33:02 +1000 | [diff] [blame] | 88 | Added ``__cached__`` global variable (see :pep:`3147`). |
Éric Araujo | 930df31 | 2010-12-16 06:28:48 +0000 | [diff] [blame] | 89 | |
Nick Coghlan | 720c7e2 | 2013-12-15 20:33:02 +1000 | [diff] [blame] | 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``. |
Nick Coghlan | 3f48ae3 | 2009-02-08 01:58:26 +0000 | [diff] [blame] | 95 | |
Nick Coghlan | 260bd3e | 2009-11-16 06:49:25 +0000 | [diff] [blame] | 96 | .. function:: run_path(file_path, init_globals=None, run_name=None) |
| 97 | |
Senthil Kumaran | 4932e14 | 2014-06-20 01:37:53 -0700 | [diff] [blame] | 98 | .. index:: |
| 99 | module: __main__ |
| 100 | |
Nick Coghlan | 260bd3e | 2009-11-16 06:49:25 +0000 | [diff] [blame] | 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 | |
Nick Coghlan | 720c7e2 | 2013-12-15 20:33:02 +1000 | [diff] [blame] | 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). |
Nick Coghlan | 260bd3e | 2009-11-16 06:49:25 +0000 | [diff] [blame] | 126 | |
| 127 | ``__name__`` is set to *run_name* if this optional argument is not |
| 128 | :const:`None` and to ``'<run_path>'`` otherwise. |
| 129 | |
Nick Coghlan | 720c7e2 | 2013-12-15 20:33:02 +1000 | [diff] [blame] | 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`. |
Nick Coghlan | 260bd3e | 2009-11-16 06:49:25 +0000 | [diff] [blame] | 134 | |
Nick Coghlan | 720c7e2 | 2013-12-15 20:33:02 +1000 | [diff] [blame] | 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. |
Nick Coghlan | 260bd3e | 2009-11-16 06:49:25 +0000 | [diff] [blame] | 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 |
Georg Brandl | f285bcc | 2010-10-19 21:07:16 +0000 | [diff] [blame] | 150 | allowing the execution of sys.path entries. As the thread-safety |
Nick Coghlan | 260bd3e | 2009-11-16 06:49:25 +0000 | [diff] [blame] | 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 | |
Berker Peksag | 8b1cbd2 | 2014-12-10 01:47:02 +0200 | [diff] [blame] | 154 | .. seealso:: |
| 155 | :ref:`using-on-interface-options` for equivalent functionality on the |
| 156 | command line (``python path/to/script``). |
| 157 | |
Nick Coghlan | 260bd3e | 2009-11-16 06:49:25 +0000 | [diff] [blame] | 158 | .. versionadded:: 3.2 |
| 159 | |
Nick Coghlan | 720c7e2 | 2013-12-15 20:33:02 +1000 | [diff] [blame] | 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 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 166 | .. seealso:: |
| 167 | |
Berker Peksag | 8b1cbd2 | 2014-12-10 01:47:02 +0200 | [diff] [blame] | 168 | :pep:`338` -- Executing modules as scripts |
Nick Coghlan | 3f48ae3 | 2009-02-08 01:58:26 +0000 | [diff] [blame] | 169 | PEP written and implemented by Nick Coghlan. |
| 170 | |
Berker Peksag | 8b1cbd2 | 2014-12-10 01:47:02 +0200 | [diff] [blame] | 171 | :pep:`366` -- Main module explicit relative imports |
Nick Coghlan | 3f48ae3 | 2009-02-08 01:58:26 +0000 | [diff] [blame] | 172 | PEP written and implemented by Nick Coghlan. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 173 | |
Berker Peksag | 8b1cbd2 | 2014-12-10 01:47:02 +0200 | [diff] [blame] | 174 | :pep:`451` -- A ModuleSpec Type for the Import System |
Nick Coghlan | 720c7e2 | 2013-12-15 20:33:02 +1000 | [diff] [blame] | 175 | PEP written and implemented by Eric Snow |
| 176 | |
Nick Coghlan | 260bd3e | 2009-11-16 06:49:25 +0000 | [diff] [blame] | 177 | :ref:`using-on-general` - CPython command line details |
Nick Coghlan | a3d1cac | 2012-07-15 00:36:39 +1000 | [diff] [blame] | 178 | |
| 179 | The :func:`importlib.import_module` function |