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 | |
Nick Coghlan | 260bd3e | 2009-11-16 06:49:25 +0000 | [diff] [blame] | 31 | Execute the code of the specified module and return the resulting module |
| 32 | globals dictionary. The module's code is first located using the standard |
Victor Stinner | 766ad36 | 2010-05-14 14:36:18 +0000 | [diff] [blame] | 33 | 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] | 34 | fresh module namespace. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 35 | |
Nick Coghlan | 260bd3e | 2009-11-16 06:49:25 +0000 | [diff] [blame] | 36 | If the supplied module name refers to a package rather than a normal |
| 37 | module, then that package is imported and the ``__main__`` submodule within |
| 38 | that package is then executed and the resulting module globals dictionary |
| 39 | returned. |
Nick Coghlan | 3f48ae3 | 2009-02-08 01:58:26 +0000 | [diff] [blame] | 40 | |
Nick Coghlan | 260bd3e | 2009-11-16 06:49:25 +0000 | [diff] [blame] | 41 | The optional dictionary argument *init_globals* may be used to pre-populate |
| 42 | the module's globals dictionary before the code is executed. The supplied |
| 43 | dictionary will not be modified. If any of the special global variables |
| 44 | below are defined in the supplied dictionary, those definitions are |
| 45 | overridden by :func:`run_module`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 46 | |
Barry Warsaw | 28a691b | 2010-04-17 00:19:56 +0000 | [diff] [blame] | 47 | The special global variables ``__name__``, ``__file__``, ``__cached__``, |
| 48 | ``__loader__`` |
Nick Coghlan | 260bd3e | 2009-11-16 06:49:25 +0000 | [diff] [blame] | 49 | and ``__package__`` are set in the globals dictionary before the module |
| 50 | code is executed (Note that this is a minimal set of variables - other |
| 51 | variables may be set implicitly as an interpreter implementation detail). |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 52 | |
Nick Coghlan | 260bd3e | 2009-11-16 06:49:25 +0000 | [diff] [blame] | 53 | ``__name__`` is set to *run_name* if this optional argument is not |
| 54 | :const:`None`, to ``mod_name + '.__main__'`` if the named module is a |
| 55 | package and to the *mod_name* argument otherwise. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 56 | |
Nick Coghlan | 260bd3e | 2009-11-16 06:49:25 +0000 | [diff] [blame] | 57 | ``__file__`` is set to the name provided by the module loader. If the |
| 58 | loader does not make filename information available, this variable is set |
Ezio Melotti | 6e40e27 | 2010-01-04 09:29:10 +0000 | [diff] [blame] | 59 | to :const:`None`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 60 | |
Éric Araujo | b547148 | 2011-04-24 02:44:39 +0200 | [diff] [blame] | 61 | ``__cached__`` will be set to ``None``. |
Barry Warsaw | 28a691b | 2010-04-17 00:19:56 +0000 | [diff] [blame] | 62 | |
Victor Stinner | 766ad36 | 2010-05-14 14:36:18 +0000 | [diff] [blame] | 63 | ``__loader__`` is set to the :pep:`302` module loader used to retrieve the |
Nick Coghlan | 260bd3e | 2009-11-16 06:49:25 +0000 | [diff] [blame] | 64 | code for the module (This loader may be a wrapper around the standard |
| 65 | import mechanism). |
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 | ``__package__`` is set to *mod_name* if the named module is a package and |
| 68 | to ``mod_name.rpartition('.')[0]`` otherwise. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 69 | |
Nick Coghlan | 260bd3e | 2009-11-16 06:49:25 +0000 | [diff] [blame] | 70 | If the argument *alter_sys* is supplied and evaluates to :const:`True`, |
| 71 | then ``sys.argv[0]`` is updated with the value of ``__file__`` and |
Thomas Wouters | ed03b41 | 2007-08-28 21:37:11 +0000 | [diff] [blame] | 72 | ``sys.modules[__name__]`` is updated with a temporary module object for the |
| 73 | module being executed. Both ``sys.argv[0]`` and ``sys.modules[__name__]`` |
| 74 | are restored to their original values before the function returns. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 75 | |
Nick Coghlan | 260bd3e | 2009-11-16 06:49:25 +0000 | [diff] [blame] | 76 | Note that this manipulation of :mod:`sys` is not thread-safe. Other threads |
| 77 | may see the partially initialised module, as well as the altered list of |
| 78 | arguments. It is recommended that the :mod:`sys` module be left alone when |
| 79 | invoking this function from threaded code. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 80 | |
| 81 | |
Nick Coghlan | 3f48ae3 | 2009-02-08 01:58:26 +0000 | [diff] [blame] | 82 | .. versionchanged:: 3.1 |
Georg Brandl | 67b21b7 | 2010-08-17 15:07:14 +0000 | [diff] [blame] | 83 | Added ability to execute packages by looking for a ``__main__`` submodule. |
Nick Coghlan | 3f48ae3 | 2009-02-08 01:58:26 +0000 | [diff] [blame] | 84 | |
Éric Araujo | 930df31 | 2010-12-16 06:28:48 +0000 | [diff] [blame] | 85 | .. versionchanged:: 3.2 |
| 86 | Added ``__cached__`` global variable (see :PEP:`3147`). |
| 87 | |
Nick Coghlan | 3f48ae3 | 2009-02-08 01:58:26 +0000 | [diff] [blame] | 88 | |
Nick Coghlan | 260bd3e | 2009-11-16 06:49:25 +0000 | [diff] [blame] | 89 | .. function:: run_path(file_path, init_globals=None, run_name=None) |
| 90 | |
| 91 | Execute the code at the named filesystem location and return the resulting |
| 92 | module globals dictionary. As with a script name supplied to the CPython |
| 93 | command line, the supplied path may refer to a Python source file, a |
| 94 | compiled bytecode file or a valid sys.path entry containing a ``__main__`` |
| 95 | module (e.g. a zipfile containing a top-level ``__main__.py`` file). |
| 96 | |
| 97 | For a simple script, the specified code is simply executed in a fresh |
| 98 | module namespace. For a valid sys.path entry (typically a zipfile or |
| 99 | directory), the entry is first added to the beginning of ``sys.path``. The |
| 100 | function then looks for and executes a :mod:`__main__` module using the |
| 101 | updated path. Note that there is no special protection against invoking |
| 102 | an existing :mod:`__main__` entry located elsewhere on ``sys.path`` if |
| 103 | there is no such module at the specified location. |
| 104 | |
| 105 | The optional dictionary argument *init_globals* may be used to pre-populate |
| 106 | the module's globals dictionary before the code is executed. The supplied |
| 107 | dictionary will not be modified. If any of the special global variables |
| 108 | below are defined in the supplied dictionary, those definitions are |
| 109 | overridden by :func:`run_path`. |
| 110 | |
| 111 | The special global variables ``__name__``, ``__file__``, ``__loader__`` |
| 112 | and ``__package__`` are set in the globals dictionary before the module |
| 113 | code is executed (Note that this is a minimal set of variables - other |
| 114 | variables may be set implicitly as an interpreter implementation detail). |
| 115 | |
| 116 | ``__name__`` is set to *run_name* if this optional argument is not |
| 117 | :const:`None` and to ``'<run_path>'`` otherwise. |
| 118 | |
| 119 | ``__file__`` is set to the name provided by the module loader. If the |
| 120 | loader does not make filename information available, this variable is set |
| 121 | to :const:`None`. For a simple script, this will be set to ``file_path``. |
| 122 | |
Victor Stinner | 766ad36 | 2010-05-14 14:36:18 +0000 | [diff] [blame] | 123 | ``__loader__`` is set to the :pep:`302` module loader used to retrieve the |
Nick Coghlan | 260bd3e | 2009-11-16 06:49:25 +0000 | [diff] [blame] | 124 | code for the module (This loader may be a wrapper around the standard |
| 125 | import mechanism). For a simple script, this will be set to :const:`None`. |
| 126 | |
| 127 | ``__package__`` is set to ``__name__.rpartition('.')[0]``. |
| 128 | |
| 129 | A number of alterations are also made to the :mod:`sys` module. Firstly, |
| 130 | ``sys.path`` may be altered as described above. ``sys.argv[0]`` is updated |
| 131 | with the value of ``file_path`` and ``sys.modules[__name__]`` is updated |
| 132 | with a temporary module object for the module being executed. All |
| 133 | modifications to items in :mod:`sys` are reverted before the function |
| 134 | returns. |
| 135 | |
| 136 | Note that, unlike :func:`run_module`, the alterations made to :mod:`sys` |
| 137 | are not optional in this function as these adjustments are essential to |
Georg Brandl | f285bcc | 2010-10-19 21:07:16 +0000 | [diff] [blame] | 138 | allowing the execution of sys.path entries. As the thread-safety |
Nick Coghlan | 260bd3e | 2009-11-16 06:49:25 +0000 | [diff] [blame] | 139 | limitations still apply, use of this function in threaded code should be |
| 140 | either serialised with the import lock or delegated to a separate process. |
| 141 | |
| 142 | .. versionadded:: 3.2 |
| 143 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 144 | .. seealso:: |
| 145 | |
| 146 | :pep:`338` - Executing modules as scripts |
Nick Coghlan | 3f48ae3 | 2009-02-08 01:58:26 +0000 | [diff] [blame] | 147 | PEP written and implemented by Nick Coghlan. |
| 148 | |
| 149 | :pep:`366` - Main module explicit relative imports |
| 150 | PEP written and implemented by Nick Coghlan. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 151 | |
Nick Coghlan | 260bd3e | 2009-11-16 06:49:25 +0000 | [diff] [blame] | 152 | :ref:`using-on-general` - CPython command line details |
Nick Coghlan | a3d1cac | 2012-07-15 00:36:39 +1000 | [diff] [blame] | 153 | |
| 154 | The :func:`importlib.import_module` function |