1"""runpy.py - locating and running Python code using the module namespace 2 3Provides support for locating and running Python scripts using the Python 4module namespace instead of the native filesystem. 5 6This allows Python code to play nicely with non-filesystem based PEP 302 7importers 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 12 13import sys 14import importlib.machinery # importlib first so we can test #15386 via -m 15import importlib.util 16import io 17import types 18import os 19from pkgutil import read_code, get_importer 20 21__all__ = [ 22 "run_module", "run_path", 23] 24 25class _TempModule(object): 26 """Temporarily replace a module in sys.modules with an empty namespace""" 27 def __init__(self, mod_name): 28 self.mod_name = mod_name 29 self.module = types.ModuleType(mod_name) 30 self._saved_module = [] 31 32 def __enter__(self): 33 mod_name = self.mod_name 34 try: 35 self._saved_module.append(sys.modules[mod_name]) 36 except KeyError: 37 pass 38 sys.modules[mod_name] = self.module 39 return self 40 41 def __exit__(self, *args): 42 if self._saved_module: 43 sys.modules[self.mod_name] = self._saved_module[0] 44 else: 45 del sys.modules[self.mod_name] 46 self._saved_module = [] 47 48class _ModifiedArgv0(object): 49 def __init__(self, value): 50 self.value = value 51 self._saved_value = self._sentinel = object() 52 53 def __enter__(self): 54 if self._saved_value is not self._sentinel: 55 raise RuntimeError("Already preserving saved value") 56 self._saved_value = sys.argv[0] 57 sys.argv[0] = self.value 58 59 def __exit__(self, *args): 60 self.value = self._sentinel 61 sys.argv[0] = self._saved_value 62 63# TODO: Replace these helpers with importlib._bootstrap_external functions. 64def _run_code(code, run_globals, init_globals=None, 65 mod_name=None, mod_spec=None, 66 pkg_name=None, script_name=None): 67 """Helper to run code in nominated namespace""" 68 if init_globals is not None: 69 run_globals.update(init_globals) 70 if mod_spec is None: 71 loader = None 72 fname = script_name 73 cached = None 74 else: 75 loader = mod_spec.loader 76 fname = mod_spec.origin 77 cached = mod_spec.cached 78 if pkg_name is None: 79 pkg_name = mod_spec.parent 80 run_globals.update(__name__ = mod_name, 81 __file__ = fname, 82 __cached__ = cached, 83 __doc__ = None, 84 __loader__ = loader, 85 __package__ = pkg_name, 86 __spec__ = mod_spec) 87 exec(code, run_globals) 88 return run_globals 89 90def _run_module_code(code, init_globals=None, 91 mod_name=None, mod_spec=None, 92 pkg_name=None, script_name=None): 93 """Helper to run code in new namespace with sys modified""" 94 fname = script_name if mod_spec is None else mod_spec.origin 95 with _TempModule(mod_name) as temp_module, _ModifiedArgv0(fname): 96 mod_globals = temp_module.module.__dict__ 97 _run_code(code, mod_globals, init_globals, 98 mod_name, mod_spec, pkg_name, script_name) 99 # Copy the globals of the temporary module, as they 100 # may be cleared when the temporary module goes away 101 return mod_globals.copy() 102 103# Helper to get the full name, spec and code for a module 104def _get_module_details(mod_name, error=ImportError): 105 if mod_name.startswith("."): 106 raise error("Relative module names not supported") 107 pkg_name, _, _ = mod_name.rpartition(".") 108 if pkg_name: 109 # Try importing the parent to avoid catching initialization errors 110 try: 111 __import__(pkg_name) 112 except ImportError as e: 113 # If the parent or higher ancestor package is missing, let the 114 # error be raised by find_spec() below and then be caught. But do 115 # not allow other errors to be caught. 116 if e.name is None or (e.name != pkg_name and 117 not pkg_name.startswith(e.name + ".")): 118 raise 119 # Warn if the module has already been imported under its normal name 120 existing = sys.modules.get(mod_name) 121 if existing is not None and not hasattr(existing, "__path__"): 122 from warnings import warn 123 msg = "{mod_name!r} found in sys.modules after import of " \ 124 "package {pkg_name!r}, but prior to execution of " \ 125 "{mod_name!r}; this may result in unpredictable " \ 126 "behaviour".format(mod_name=mod_name, pkg_name=pkg_name) 127 warn(RuntimeWarning(msg)) 128 129 try: 130 spec = importlib.util.find_spec(mod_name) 131 except (ImportError, AttributeError, TypeError, ValueError) as ex: 132 # This hack fixes an impedance mismatch between pkgutil and 133 # importlib, where the latter raises other errors for cases where 134 # pkgutil previously raised ImportError 135 msg = "Error while finding module specification for {!r} ({}: {})" 136 if mod_name.endswith(".py"): 137 msg += (f". Try using '{mod_name[:-3]}' instead of " 138 f"'{mod_name}' as the module name.") 139 raise error(msg.format(mod_name, type(ex).__name__, ex)) from ex 140 if spec is None: 141 raise error("No module named %s" % mod_name) 142 if spec.submodule_search_locations is not None: 143 if mod_name == "__main__" or mod_name.endswith(".__main__"): 144 raise error("Cannot use package as __main__ module") 145 try: 146 pkg_main_name = mod_name + ".__main__" 147 return _get_module_details(pkg_main_name, error) 148 except error as e: 149 if mod_name not in sys.modules: 150 raise # No module loaded; being a package is irrelevant 151 raise error(("%s; %r is a package and cannot " + 152 "be directly executed") %(e, mod_name)) 153 loader = spec.loader 154 if loader is None: 155 raise error("%r is a namespace package and cannot be executed" 156 % mod_name) 157 try: 158 code = loader.get_code(mod_name) 159 except ImportError as e: 160 raise error(format(e)) from e 161 if code is None: 162 raise error("No code object available for %s" % mod_name) 163 return mod_name, spec, code 164 165class _Error(Exception): 166 """Error that _run_module_as_main() should report without a traceback""" 167 168# XXX ncoghlan: Should this be documented and made public? 169# (Current thoughts: don't repeat the mistake that lead to its 170# creation when run_module() no longer met the needs of 171# mainmodule.c, but couldn't be changed because it was public) 172def _run_module_as_main(mod_name, alter_argv=True): 173 """Runs the designated module in the __main__ namespace 174 175 Note that the executed module will have full access to the 176 __main__ namespace. If this is not desirable, the run_module() 177 function should be used to run the module code in a fresh namespace. 178 179 At the very least, these variables in __main__ will be overwritten: 180 __name__ 181 __file__ 182 __cached__ 183 __loader__ 184 __package__ 185 """ 186 try: 187 if alter_argv or mod_name != "__main__": # i.e. -m switch 188 mod_name, mod_spec, code = _get_module_details(mod_name, _Error) 189 else: # i.e. directory or zipfile execution 190 mod_name, mod_spec, code = _get_main_module_details(_Error) 191 except _Error as exc: 192 msg = "%s: %s" % (sys.executable, exc) 193 sys.exit(msg) 194 main_globals = sys.modules["__main__"].__dict__ 195 if alter_argv: 196 sys.argv[0] = mod_spec.origin 197 return _run_code(code, main_globals, None, 198 "__main__", mod_spec) 199 200def run_module(mod_name, init_globals=None, 201 run_name=None, alter_sys=False): 202 """Execute a module's code without importing it 203 204 Returns the resulting top level namespace dictionary 205 """ 206 mod_name, mod_spec, code = _get_module_details(mod_name) 207 if run_name is None: 208 run_name = mod_name 209 if alter_sys: 210 return _run_module_code(code, init_globals, run_name, mod_spec) 211 else: 212 # Leave the sys module alone 213 return _run_code(code, {}, init_globals, run_name, mod_spec) 214 215def _get_main_module_details(error=ImportError): 216 # Helper that gives a nicer error message when attempting to 217 # execute a zipfile or directory by invoking __main__.py 218 # Also moves the standard __main__ out of the way so that the 219 # preexisting __loader__ entry doesn't cause issues 220 main_name = "__main__" 221 saved_main = sys.modules[main_name] 222 del sys.modules[main_name] 223 try: 224 return _get_module_details(main_name) 225 except ImportError as exc: 226 if main_name in str(exc): 227 raise error("can't find %r module in %r" % 228 (main_name, sys.path[0])) from exc 229 raise 230 finally: 231 sys.modules[main_name] = saved_main 232 233 234def _get_code_from_file(run_name, fname): 235 # Check for a compiled file first 236 decoded_path = os.path.abspath(os.fsdecode(fname)) 237 with io.open_code(decoded_path) as f: 238 code = read_code(f) 239 if code is None: 240 # That didn't work, so try it as normal source code 241 with io.open_code(decoded_path) as f: 242 code = compile(f.read(), fname, 'exec') 243 return code, fname 244 245def run_path(path_name, init_globals=None, run_name=None): 246 """Execute code located at the specified filesystem location 247 248 Returns the resulting top level namespace dictionary 249 250 The file path may refer directly to a Python script (i.e. 251 one that could be directly executed with execfile) or else 252 it may refer to a zipfile or directory containing a top 253 level __main__.py script. 254 """ 255 if run_name is None: 256 run_name = "<run_path>" 257 pkg_name = run_name.rpartition(".")[0] 258 importer = get_importer(path_name) 259 # Trying to avoid importing imp so as to not consume the deprecation warning. 260 is_NullImporter = False 261 if type(importer).__module__ == 'imp': 262 if type(importer).__name__ == 'NullImporter': 263 is_NullImporter = True 264 if isinstance(importer, type(None)) or is_NullImporter: 265 # Not a valid sys.path entry, so run the code directly 266 # execfile() doesn't help as we want to allow compiled files 267 code, fname = _get_code_from_file(run_name, path_name) 268 return _run_module_code(code, init_globals, run_name, 269 pkg_name=pkg_name, script_name=fname) 270 else: 271 # Finder is defined for path, so add it to 272 # the start of sys.path 273 sys.path.insert(0, path_name) 274 try: 275 # Here's where things are a little different from the run_module 276 # case. There, we only had to replace the module in sys while the 277 # code was running and doing so was somewhat optional. Here, we 278 # have no choice and we have to remove it even while we read the 279 # code. If we don't do this, a __loader__ attribute in the 280 # existing __main__ module may prevent location of the new module. 281 mod_name, mod_spec, code = _get_main_module_details() 282 with _TempModule(run_name) as temp_module, \ 283 _ModifiedArgv0(path_name): 284 mod_globals = temp_module.module.__dict__ 285 return _run_code(code, mod_globals, init_globals, 286 run_name, mod_spec, pkg_name).copy() 287 finally: 288 try: 289 sys.path.remove(path_name) 290 except ValueError: 291 pass 292 293 294if __name__ == "__main__": 295 # Run the module specified as the next command line argument 296 if len(sys.argv) < 2: 297 print("No module specified for execution", file=sys.stderr) 298 else: 299 del sys.argv[0] # Make the requested module sys.argv[0] 300 _run_module_as_main(sys.argv[0]) 301