Python code coverage for Lib/runpy.py

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