Thomas Wouters | a977329 | 2006-04-21 09:43:23 +0000 | [diff] [blame] | 1 | """runpy.py - locating and running Python code using the module namespace |
| 2 | |
| 3 | Provides support for locating and running Python scripts using the Python |
| 4 | module namespace instead of the native filesystem. |
| 5 | |
| 6 | This allows Python code to play nicely with non-filesystem based PEP 302 |
| 7 | importers when locating support scripts as well as when importing modules. |
| 8 | """ |
| 9 | # Written by Nick Coghlan <ncoghlan at gmail.com> |
| 10 | # to implement PEP 338 (Executing Modules as Scripts) |
| 11 | |
Brett Cannon | aa93642 | 2012-04-27 15:30:58 -0400 | [diff] [blame] | 12 | |
Thomas Wouters | a977329 | 2006-04-21 09:43:23 +0000 | [diff] [blame] | 13 | import sys |
Nick Coghlan | be7e49f | 2012-07-20 23:40:09 +1000 | [diff] [blame] | 14 | import importlib.machinery # importlib first so we can test #15386 via -m |
Eric Snow | 6029e08 | 2014-01-25 15:32:46 -0700 | [diff] [blame] | 15 | import importlib.util |
Brett Cannon | 82d2107 | 2013-06-15 14:27:21 -0400 | [diff] [blame] | 16 | import types |
Nick Coghlan | 720c7e2 | 2013-12-15 20:33:02 +1000 | [diff] [blame] | 17 | from pkgutil import read_code, get_importer |
Thomas Wouters | a977329 | 2006-04-21 09:43:23 +0000 | [diff] [blame] | 18 | |
| 19 | __all__ = [ |
Nick Coghlan | 260bd3e | 2009-11-16 06:49:25 +0000 | [diff] [blame] | 20 | "run_module", "run_path", |
Thomas Wouters | a977329 | 2006-04-21 09:43:23 +0000 | [diff] [blame] | 21 | ] |
| 22 | |
Nick Coghlan | 260bd3e | 2009-11-16 06:49:25 +0000 | [diff] [blame] | 23 | class _TempModule(object): |
| 24 | """Temporarily replace a module in sys.modules with an empty namespace""" |
| 25 | def __init__(self, mod_name): |
| 26 | self.mod_name = mod_name |
Brett Cannon | 82d2107 | 2013-06-15 14:27:21 -0400 | [diff] [blame] | 27 | self.module = types.ModuleType(mod_name) |
Nick Coghlan | 260bd3e | 2009-11-16 06:49:25 +0000 | [diff] [blame] | 28 | self._saved_module = [] |
| 29 | |
| 30 | def __enter__(self): |
| 31 | mod_name = self.mod_name |
| 32 | try: |
| 33 | self._saved_module.append(sys.modules[mod_name]) |
| 34 | except KeyError: |
| 35 | pass |
| 36 | sys.modules[mod_name] = self.module |
| 37 | return self |
| 38 | |
| 39 | def __exit__(self, *args): |
| 40 | if self._saved_module: |
| 41 | sys.modules[self.mod_name] = self._saved_module[0] |
| 42 | else: |
| 43 | del sys.modules[self.mod_name] |
| 44 | self._saved_module = [] |
| 45 | |
| 46 | class _ModifiedArgv0(object): |
| 47 | def __init__(self, value): |
| 48 | self.value = value |
| 49 | self._saved_value = self._sentinel = object() |
| 50 | |
| 51 | def __enter__(self): |
| 52 | if self._saved_value is not self._sentinel: |
| 53 | raise RuntimeError("Already preserving saved value") |
| 54 | self._saved_value = sys.argv[0] |
| 55 | sys.argv[0] = self.value |
| 56 | |
| 57 | def __exit__(self, *args): |
| 58 | self.value = self._sentinel |
| 59 | sys.argv[0] = self._saved_value |
Thomas Wouters | a977329 | 2006-04-21 09:43:23 +0000 | [diff] [blame] | 60 | |
Brett Cannon | 2a17bde | 2014-05-30 14:55:29 -0400 | [diff] [blame] | 61 | # TODO: Replace these helpers with importlib._bootstrap functions |
Thomas Wouters | ed03b41 | 2007-08-28 21:37:11 +0000 | [diff] [blame] | 62 | def _run_code(code, run_globals, init_globals=None, |
Nick Coghlan | 720c7e2 | 2013-12-15 20:33:02 +1000 | [diff] [blame] | 63 | mod_name=None, mod_spec=None, |
| 64 | pkg_name=None, script_name=None): |
Benjamin Peterson | f6489f9 | 2009-11-25 17:46:26 +0000 | [diff] [blame] | 65 | """Helper to run code in nominated namespace""" |
Thomas Wouters | a977329 | 2006-04-21 09:43:23 +0000 | [diff] [blame] | 66 | if init_globals is not None: |
| 67 | run_globals.update(init_globals) |
Nick Coghlan | 720c7e2 | 2013-12-15 20:33:02 +1000 | [diff] [blame] | 68 | if mod_spec is None: |
| 69 | loader = None |
| 70 | fname = script_name |
| 71 | cached = None |
| 72 | else: |
| 73 | loader = mod_spec.loader |
| 74 | fname = mod_spec.origin |
| 75 | cached = mod_spec.cached |
| 76 | if pkg_name is None: |
| 77 | pkg_name = mod_spec.parent |
Thomas Wouters | a977329 | 2006-04-21 09:43:23 +0000 | [diff] [blame] | 78 | run_globals.update(__name__ = mod_name, |
Nick Coghlan | 720c7e2 | 2013-12-15 20:33:02 +1000 | [diff] [blame] | 79 | __file__ = fname, |
| 80 | __cached__ = cached, |
Nick Coghlan | 761bb11 | 2012-07-14 23:59:22 +1000 | [diff] [blame] | 81 | __doc__ = None, |
Nick Coghlan | 720c7e2 | 2013-12-15 20:33:02 +1000 | [diff] [blame] | 82 | __loader__ = loader, |
| 83 | __package__ = pkg_name, |
| 84 | __spec__ = mod_spec) |
Georg Brandl | 7cae87c | 2006-09-06 06:51:57 +0000 | [diff] [blame] | 85 | exec(code, run_globals) |
Thomas Wouters | a977329 | 2006-04-21 09:43:23 +0000 | [diff] [blame] | 86 | return run_globals |
| 87 | |
| 88 | def _run_module_code(code, init_globals=None, |
Nick Coghlan | 720c7e2 | 2013-12-15 20:33:02 +1000 | [diff] [blame] | 89 | mod_name=None, mod_spec=None, |
| 90 | pkg_name=None, script_name=None): |
Benjamin Peterson | f6489f9 | 2009-11-25 17:46:26 +0000 | [diff] [blame] | 91 | """Helper to run code in new namespace with sys modified""" |
Nick Coghlan | 720c7e2 | 2013-12-15 20:33:02 +1000 | [diff] [blame] | 92 | fname = script_name if mod_spec is None else mod_spec.origin |
| 93 | with _TempModule(mod_name) as temp_module, _ModifiedArgv0(fname): |
Nick Coghlan | 260bd3e | 2009-11-16 06:49:25 +0000 | [diff] [blame] | 94 | mod_globals = temp_module.module.__dict__ |
Thomas Wouters | ed03b41 | 2007-08-28 21:37:11 +0000 | [diff] [blame] | 95 | _run_code(code, mod_globals, init_globals, |
Nick Coghlan | 720c7e2 | 2013-12-15 20:33:02 +1000 | [diff] [blame] | 96 | mod_name, mod_spec, pkg_name, script_name) |
Thomas Wouters | ed03b41 | 2007-08-28 21:37:11 +0000 | [diff] [blame] | 97 | # Copy the globals of the temporary module, as they |
| 98 | # may be cleared when the temporary module goes away |
| 99 | return mod_globals.copy() |
Thomas Wouters | a977329 | 2006-04-21 09:43:23 +0000 | [diff] [blame] | 100 | |
Eric Snow | 6029e08 | 2014-01-25 15:32:46 -0700 | [diff] [blame] | 101 | # Helper to get the loader, code and filename for a module |
| 102 | def _get_module_details(mod_name): |
Nick Coghlan | 720c7e2 | 2013-12-15 20:33:02 +1000 | [diff] [blame] | 103 | try: |
Eric Snow | 6029e08 | 2014-01-25 15:32:46 -0700 | [diff] [blame] | 104 | spec = importlib.util.find_spec(mod_name) |
Nick Coghlan | 720c7e2 | 2013-12-15 20:33:02 +1000 | [diff] [blame] | 105 | except (ImportError, AttributeError, TypeError, ValueError) as ex: |
| 106 | # This hack fixes an impedance mismatch between pkgutil and |
| 107 | # importlib, where the latter raises other errors for cases where |
| 108 | # pkgutil previously raised ImportError |
| 109 | msg = "Error while finding spec for {!r} ({}: {})" |
| 110 | raise ImportError(msg.format(mod_name, type(ex), ex)) from ex |
Nick Coghlan | 720c7e2 | 2013-12-15 20:33:02 +1000 | [diff] [blame] | 111 | if spec is None: |
Guido van Rossum | 806c246 | 2007-08-06 23:33:07 +0000 | [diff] [blame] | 112 | raise ImportError("No module named %s" % mod_name) |
Nick Coghlan | 720c7e2 | 2013-12-15 20:33:02 +1000 | [diff] [blame] | 113 | if spec.submodule_search_locations is not None: |
Nick Coghlan | 3f48ae3 | 2009-02-08 01:58:26 +0000 | [diff] [blame] | 114 | if mod_name == "__main__" or mod_name.endswith(".__main__"): |
Benjamin Peterson | f6489f9 | 2009-11-25 17:46:26 +0000 | [diff] [blame] | 115 | raise ImportError("Cannot use package as __main__ module") |
Nick Coghlan | 3f48ae3 | 2009-02-08 01:58:26 +0000 | [diff] [blame] | 116 | try: |
| 117 | pkg_main_name = mod_name + ".__main__" |
| 118 | return _get_module_details(pkg_main_name) |
| 119 | except ImportError as e: |
| 120 | raise ImportError(("%s; %r is a package and cannot " + |
| 121 | "be directly executed") %(e, mod_name)) |
Nick Coghlan | 720c7e2 | 2013-12-15 20:33:02 +1000 | [diff] [blame] | 122 | loader = spec.loader |
| 123 | if loader is None: |
| 124 | raise ImportError("%r is a namespace package and cannot be executed" |
| 125 | % mod_name) |
Thomas Wouters | a977329 | 2006-04-21 09:43:23 +0000 | [diff] [blame] | 126 | code = loader.get_code(mod_name) |
| 127 | if code is None: |
Guido van Rossum | 806c246 | 2007-08-06 23:33:07 +0000 | [diff] [blame] | 128 | raise ImportError("No code object available for %s" % mod_name) |
Nick Coghlan | 720c7e2 | 2013-12-15 20:33:02 +1000 | [diff] [blame] | 129 | return mod_name, spec, code |
Thomas Wouters | ed03b41 | 2007-08-28 21:37:11 +0000 | [diff] [blame] | 130 | |
Benjamin Peterson | f6489f9 | 2009-11-25 17:46:26 +0000 | [diff] [blame] | 131 | # XXX ncoghlan: Should this be documented and made public? |
| 132 | # (Current thoughts: don't repeat the mistake that lead to its |
| 133 | # creation when run_module() no longer met the needs of |
| 134 | # mainmodule.c, but couldn't be changed because it was public) |
Nick Coghlan | 260bd3e | 2009-11-16 06:49:25 +0000 | [diff] [blame] | 135 | def _run_module_as_main(mod_name, alter_argv=True): |
Thomas Wouters | ed03b41 | 2007-08-28 21:37:11 +0000 | [diff] [blame] | 136 | """Runs the designated module in the __main__ namespace |
| 137 | |
Benjamin Peterson | f6489f9 | 2009-11-25 17:46:26 +0000 | [diff] [blame] | 138 | Note that the executed module will have full access to the |
| 139 | __main__ namespace. If this is not desirable, the run_module() |
R. David Murray | 445448c | 2009-12-20 17:28:31 +0000 | [diff] [blame] | 140 | function should be used to run the module code in a fresh namespace. |
Benjamin Peterson | f6489f9 | 2009-11-25 17:46:26 +0000 | [diff] [blame] | 141 | |
| 142 | At the very least, these variables in __main__ will be overwritten: |
| 143 | __name__ |
Thomas Wouters | ed03b41 | 2007-08-28 21:37:11 +0000 | [diff] [blame] | 144 | __file__ |
Barry Warsaw | 28a691b | 2010-04-17 00:19:56 +0000 | [diff] [blame] | 145 | __cached__ |
Thomas Wouters | ed03b41 | 2007-08-28 21:37:11 +0000 | [diff] [blame] | 146 | __loader__ |
Benjamin Peterson | f6489f9 | 2009-11-25 17:46:26 +0000 | [diff] [blame] | 147 | __package__ |
Thomas Wouters | ed03b41 | 2007-08-28 21:37:11 +0000 | [diff] [blame] | 148 | """ |
Christian Heimes | c3f30c4 | 2008-02-22 16:37:40 +0000 | [diff] [blame] | 149 | try: |
Nick Coghlan | 260bd3e | 2009-11-16 06:49:25 +0000 | [diff] [blame] | 150 | if alter_argv or mod_name != "__main__": # i.e. -m switch |
Nick Coghlan | 720c7e2 | 2013-12-15 20:33:02 +1000 | [diff] [blame] | 151 | mod_name, mod_spec, code = _get_module_details(mod_name) |
Nick Coghlan | 260bd3e | 2009-11-16 06:49:25 +0000 | [diff] [blame] | 152 | else: # i.e. directory or zipfile execution |
Nick Coghlan | 720c7e2 | 2013-12-15 20:33:02 +1000 | [diff] [blame] | 153 | mod_name, mod_spec, code = _get_main_module_details() |
Christian Heimes | c3f30c4 | 2008-02-22 16:37:40 +0000 | [diff] [blame] | 154 | except ImportError as exc: |
Benjamin Peterson | f6489f9 | 2009-11-25 17:46:26 +0000 | [diff] [blame] | 155 | # Try to provide a good error message |
| 156 | # for directories, zip files and the -m switch |
| 157 | if alter_argv: |
| 158 | # For -m switch, just display the exception |
| 159 | info = str(exc) |
| 160 | else: |
| 161 | # For directories/zipfiles, let the user |
| 162 | # know what the code was looking for |
Benjamin Peterson | e360795 | 2009-11-25 18:38:11 +0000 | [diff] [blame] | 163 | info = "can't find '__main__' module in %r" % sys.argv[0] |
Benjamin Peterson | f6489f9 | 2009-11-25 17:46:26 +0000 | [diff] [blame] | 164 | msg = "%s: %s" % (sys.executable, info) |
Christian Heimes | c3f30c4 | 2008-02-22 16:37:40 +0000 | [diff] [blame] | 165 | sys.exit(msg) |
Thomas Wouters | ed03b41 | 2007-08-28 21:37:11 +0000 | [diff] [blame] | 166 | main_globals = sys.modules["__main__"].__dict__ |
Nick Coghlan | 260bd3e | 2009-11-16 06:49:25 +0000 | [diff] [blame] | 167 | if alter_argv: |
Nick Coghlan | 720c7e2 | 2013-12-15 20:33:02 +1000 | [diff] [blame] | 168 | sys.argv[0] = mod_spec.origin |
Thomas Wouters | ed03b41 | 2007-08-28 21:37:11 +0000 | [diff] [blame] | 169 | return _run_code(code, main_globals, None, |
Nick Coghlan | 720c7e2 | 2013-12-15 20:33:02 +1000 | [diff] [blame] | 170 | "__main__", mod_spec) |
Thomas Wouters | ed03b41 | 2007-08-28 21:37:11 +0000 | [diff] [blame] | 171 | |
| 172 | def run_module(mod_name, init_globals=None, |
| 173 | run_name=None, alter_sys=False): |
| 174 | """Execute a module's code without importing it |
| 175 | |
| 176 | Returns the resulting top level namespace dictionary |
| 177 | """ |
Nick Coghlan | 720c7e2 | 2013-12-15 20:33:02 +1000 | [diff] [blame] | 178 | mod_name, mod_spec, code = _get_module_details(mod_name) |
Thomas Wouters | a977329 | 2006-04-21 09:43:23 +0000 | [diff] [blame] | 179 | if run_name is None: |
| 180 | run_name = mod_name |
Thomas Wouters | ed03b41 | 2007-08-28 21:37:11 +0000 | [diff] [blame] | 181 | if alter_sys: |
Nick Coghlan | 720c7e2 | 2013-12-15 20:33:02 +1000 | [diff] [blame] | 182 | return _run_module_code(code, init_globals, run_name, mod_spec) |
Thomas Wouters | ed03b41 | 2007-08-28 21:37:11 +0000 | [diff] [blame] | 183 | else: |
| 184 | # Leave the sys module alone |
Nick Coghlan | 720c7e2 | 2013-12-15 20:33:02 +1000 | [diff] [blame] | 185 | return _run_code(code, {}, init_globals, run_name, mod_spec) |
Thomas Wouters | a977329 | 2006-04-21 09:43:23 +0000 | [diff] [blame] | 186 | |
Benjamin Peterson | f6489f9 | 2009-11-25 17:46:26 +0000 | [diff] [blame] | 187 | def _get_main_module_details(): |
| 188 | # Helper that gives a nicer error message when attempting to |
| 189 | # execute a zipfile or directory by invoking __main__.py |
Nick Coghlan | 85e729e | 2012-07-15 18:09:52 +1000 | [diff] [blame] | 190 | # Also moves the standard __main__ out of the way so that the |
| 191 | # preexisting __loader__ entry doesn't cause issues |
Benjamin Peterson | f6489f9 | 2009-11-25 17:46:26 +0000 | [diff] [blame] | 192 | main_name = "__main__" |
Nick Coghlan | 85e729e | 2012-07-15 18:09:52 +1000 | [diff] [blame] | 193 | saved_main = sys.modules[main_name] |
| 194 | del sys.modules[main_name] |
Benjamin Peterson | f6489f9 | 2009-11-25 17:46:26 +0000 | [diff] [blame] | 195 | try: |
| 196 | return _get_module_details(main_name) |
| 197 | except ImportError as exc: |
| 198 | if main_name in str(exc): |
| 199 | raise ImportError("can't find %r module in %r" % |
Nick Coghlan | 85e729e | 2012-07-15 18:09:52 +1000 | [diff] [blame] | 200 | (main_name, sys.path[0])) from exc |
Benjamin Peterson | f6489f9 | 2009-11-25 17:46:26 +0000 | [diff] [blame] | 201 | raise |
Nick Coghlan | 85e729e | 2012-07-15 18:09:52 +1000 | [diff] [blame] | 202 | finally: |
| 203 | sys.modules[main_name] = saved_main |
Benjamin Peterson | f6489f9 | 2009-11-25 17:46:26 +0000 | [diff] [blame] | 204 | |
Thomas Wouters | a977329 | 2006-04-21 09:43:23 +0000 | [diff] [blame] | 205 | |
Nick Coghlan | 85e729e | 2012-07-15 18:09:52 +1000 | [diff] [blame] | 206 | def _get_code_from_file(run_name, fname): |
Nick Coghlan | 260bd3e | 2009-11-16 06:49:25 +0000 | [diff] [blame] | 207 | # Check for a compiled file first |
| 208 | with open(fname, "rb") as f: |
| 209 | code = read_code(f) |
| 210 | if code is None: |
| 211 | # That didn't work, so try it as normal source code |
Victor Stinner | 6c47102 | 2011-07-04 01:45:39 +0200 | [diff] [blame] | 212 | with open(fname, "rb") as f: |
Nick Coghlan | 260bd3e | 2009-11-16 06:49:25 +0000 | [diff] [blame] | 213 | code = compile(f.read(), fname, 'exec') |
Nick Coghlan | 720c7e2 | 2013-12-15 20:33:02 +1000 | [diff] [blame] | 214 | return code, fname |
Nick Coghlan | 260bd3e | 2009-11-16 06:49:25 +0000 | [diff] [blame] | 215 | |
| 216 | def run_path(path_name, init_globals=None, run_name=None): |
| 217 | """Execute code located at the specified filesystem location |
| 218 | |
| 219 | Returns the resulting top level namespace dictionary |
| 220 | |
| 221 | The file path may refer directly to a Python script (i.e. |
| 222 | one that could be directly executed with execfile) or else |
| 223 | it may refer to a zipfile or directory containing a top |
| 224 | level __main__.py script. |
| 225 | """ |
| 226 | if run_name is None: |
| 227 | run_name = "<run_path>" |
Nick Coghlan | 761bb11 | 2012-07-14 23:59:22 +1000 | [diff] [blame] | 228 | pkg_name = run_name.rpartition(".")[0] |
Nick Coghlan | 85e729e | 2012-07-15 18:09:52 +1000 | [diff] [blame] | 229 | importer = get_importer(path_name) |
Brett Cannon | e4f41de | 2013-06-16 13:13:40 -0400 | [diff] [blame] | 230 | # Trying to avoid importing imp so as to not consume the deprecation warning. |
| 231 | is_NullImporter = False |
| 232 | if type(importer).__module__ == 'imp': |
| 233 | if type(importer).__name__ == 'NullImporter': |
| 234 | is_NullImporter = True |
| 235 | if isinstance(importer, type(None)) or is_NullImporter: |
Nick Coghlan | 260bd3e | 2009-11-16 06:49:25 +0000 | [diff] [blame] | 236 | # Not a valid sys.path entry, so run the code directly |
| 237 | # execfile() doesn't help as we want to allow compiled files |
Nick Coghlan | 720c7e2 | 2013-12-15 20:33:02 +1000 | [diff] [blame] | 238 | code, fname = _get_code_from_file(run_name, path_name) |
| 239 | return _run_module_code(code, init_globals, run_name, |
| 240 | pkg_name=pkg_name, script_name=fname) |
Nick Coghlan | 260bd3e | 2009-11-16 06:49:25 +0000 | [diff] [blame] | 241 | else: |
| 242 | # Importer is defined for path, so add it to |
| 243 | # the start of sys.path |
| 244 | sys.path.insert(0, path_name) |
| 245 | try: |
| 246 | # Here's where things are a little different from the run_module |
| 247 | # case. There, we only had to replace the module in sys while the |
| 248 | # code was running and doing so was somewhat optional. Here, we |
| 249 | # have no choice and we have to remove it even while we read the |
| 250 | # code. If we don't do this, a __loader__ attribute in the |
| 251 | # existing __main__ module may prevent location of the new module. |
Nick Coghlan | 720c7e2 | 2013-12-15 20:33:02 +1000 | [diff] [blame] | 252 | mod_name, mod_spec, code = _get_main_module_details() |
Nick Coghlan | 260bd3e | 2009-11-16 06:49:25 +0000 | [diff] [blame] | 253 | with _TempModule(run_name) as temp_module, \ |
| 254 | _ModifiedArgv0(path_name): |
| 255 | mod_globals = temp_module.module.__dict__ |
| 256 | return _run_code(code, mod_globals, init_globals, |
Nick Coghlan | 720c7e2 | 2013-12-15 20:33:02 +1000 | [diff] [blame] | 257 | run_name, mod_spec, pkg_name).copy() |
Nick Coghlan | 260bd3e | 2009-11-16 06:49:25 +0000 | [diff] [blame] | 258 | finally: |
| 259 | try: |
| 260 | sys.path.remove(path_name) |
| 261 | except ValueError: |
| 262 | pass |
| 263 | |
| 264 | |
Thomas Wouters | a977329 | 2006-04-21 09:43:23 +0000 | [diff] [blame] | 265 | if __name__ == "__main__": |
| 266 | # Run the module specified as the next command line argument |
| 267 | if len(sys.argv) < 2: |
Guido van Rossum | be19ed7 | 2007-02-09 05:37:30 +0000 | [diff] [blame] | 268 | print("No module specified for execution", file=sys.stderr) |
Thomas Wouters | a977329 | 2006-04-21 09:43:23 +0000 | [diff] [blame] | 269 | else: |
| 270 | del sys.argv[0] # Make the requested module sys.argv[0] |
Thomas Wouters | ed03b41 | 2007-08-28 21:37:11 +0000 | [diff] [blame] | 271 | _run_module_as_main(sys.argv[0]) |