Python code coverage for Lib/importlib/_bootstrap_external.py

#	count	content
1	n/a	"""Core implementation of path-based import.
2	n/a
3	n/a	This module is NOT meant to be directly imported! It has been designed such
4	n/a	that it can be bootstrapped into Python as the implementation of import. As
5	n/a	such it requires the injection of specific modules and attributes in order to
6	n/a	work. One should use importlib as the public-facing version of this module.
7	n/a
8	n/a	"""
9	n/a	#
10	n/a	# IMPORTANT: Whenever making changes to this module, be sure to run
11	n/a	# a top-level make in order to get the frozen version of the module
12	n/a	# updated. Not doing so will result in the Makefile to fail for
13	n/a	# all others who don't have a ./python around to freeze the module
14	n/a	# in the early stages of compilation.
15	n/a	#
16	n/a
17	n/a	# See importlib._setup() for what is injected into the global namespace.
18	n/a
19	n/a	# When editing this code be aware that code executed at import time CANNOT
20	n/a	# reference any injected objects! This includes not only global code but also
21	n/a	# anything specified at the class level.
22	n/a
23	n/a	# Bootstrap-related code ######################################################
24	n/a	_CASE_INSENSITIVE_PLATFORMS_STR_KEY = 'win',
25	n/a	_CASE_INSENSITIVE_PLATFORMS_BYTES_KEY = 'cygwin', 'darwin'
26	n/a	_CASE_INSENSITIVE_PLATFORMS = (_CASE_INSENSITIVE_PLATFORMS_BYTES_KEY
27	n/a	+ _CASE_INSENSITIVE_PLATFORMS_STR_KEY)
28	n/a
29	n/a
30	n/a	def _make_relax_case():
31	n/a	if sys.platform.startswith(_CASE_INSENSITIVE_PLATFORMS):
32	n/a	if sys.platform.startswith(_CASE_INSENSITIVE_PLATFORMS_STR_KEY):
33	n/a	key = 'PYTHONCASEOK'
34	n/a	else:
35	n/a	key = b'PYTHONCASEOK'
36	n/a
37	n/a	def _relax_case():
38	n/a	"""True if filenames must be checked case-insensitively."""
39	n/a	return key in _os.environ
40	n/a	else:
41	n/a	def _relax_case():
42	n/a	"""True if filenames must be checked case-insensitively."""
43	n/a	return False
44	n/a	return _relax_case
45	n/a
46	n/a
47	n/a	def _w_long(x):
48	n/a	"""Convert a 32-bit integer to little-endian."""
49	n/a	return (int(x) & 0xFFFFFFFF).to_bytes(4, 'little')
50	n/a
51	n/a
52	n/a	def _r_long(int_bytes):
53	n/a	"""Convert 4 bytes in little-endian to an integer."""
54	n/a	return int.from_bytes(int_bytes, 'little')
55	n/a
56	n/a
57	n/a	def _path_join(*path_parts):
58	n/a	"""Replacement for os.path.join()."""
59	n/a	return path_sep.join([part.rstrip(path_separators)
60	n/a	for part in path_parts if part])
61	n/a
62	n/a
63	n/a	def _path_split(path):
64	n/a	"""Replacement for os.path.split()."""
65	n/a	if len(path_separators) == 1:
66	n/a	front, _, tail = path.rpartition(path_sep)
67	n/a	return front, tail
68	n/a	for x in reversed(path):
69	n/a	if x in path_separators:
70	n/a	front, tail = path.rsplit(x, maxsplit=1)
71	n/a	return front, tail
72	n/a	return '', path
73	n/a
74	n/a
75	n/a	def _path_stat(path):
76	n/a	"""Stat the path.
77	n/a
78	n/a	Made a separate function to make it easier to override in experiments
79	n/a	(e.g. cache stat results).
80	n/a
81	n/a	"""
82	n/a	return _os.stat(path)
83	n/a
84	n/a
85	n/a	def _path_is_mode_type(path, mode):
86	n/a	"""Test whether the path is the specified mode type."""
87	n/a	try:
88	n/a	stat_info = _path_stat(path)
89	n/a	except OSError:
90	n/a	return False
91	n/a	return (stat_info.st_mode & 0o170000) == mode
92	n/a
93	n/a
94	n/a	def _path_isfile(path):
95	n/a	"""Replacement for os.path.isfile."""
96	n/a	return _path_is_mode_type(path, 0o100000)
97	n/a
98	n/a
99	n/a	def _path_isdir(path):
100	n/a	"""Replacement for os.path.isdir."""
101	n/a	if not path:
102	n/a	path = _os.getcwd()
103	n/a	return _path_is_mode_type(path, 0o040000)
104	n/a
105	n/a
106	n/a	def _write_atomic(path, data, mode=0o666):
107	n/a	"""Best-effort function to write data to a path atomically.
108	n/a	Be prepared to handle a FileExistsError if concurrent writing of the
109	n/a	temporary file is attempted."""
110	n/a	# id() is used to generate a pseudo-random filename.
111	n/a	path_tmp = '{}.{}'.format(path, id(path))
112	n/a	fd = _os.open(path_tmp,
113	n/a	_os.O_EXCL \| _os.O_CREAT \| _os.O_WRONLY, mode & 0o666)
114	n/a	try:
115	n/a	# We first write data to a temporary file, and then use os.replace() to
116	n/a	# perform an atomic rename.
117	n/a	with _io.FileIO(fd, 'wb') as file:
118	n/a	file.write(data)
119	n/a	_os.replace(path_tmp, path)
120	n/a	except OSError:
121	n/a	try:
122	n/a	_os.unlink(path_tmp)
123	n/a	except OSError:
124	n/a	pass
125	n/a	raise
126	n/a
127	n/a
128	n/a	_code_type = type(_write_atomic.__code__)
129	n/a
130	n/a
131	n/a	# Finder/loader utility code ###############################################
132	n/a
133	n/a	# Magic word to reject .pyc files generated by other Python versions.
134	n/a	# It should change for each incompatible change to the bytecode.
135	n/a	#
136	n/a	# The value of CR and LF is incorporated so if you ever read or write
137	n/a	# a .pyc file in text mode the magic number will be wrong; also, the
138	n/a	# Apple MPW compiler swaps their values, botching string constants.
139	n/a	#
140	n/a	# There were a variety of old schemes for setting the magic number.
141	n/a	# The current working scheme is to increment the previous value by
142	n/a	# 10.
143	n/a	#
144	n/a	# Starting with the adoption of PEP 3147 in Python 3.2, every bump in magic
145	n/a	# number also includes a new "magic tag", i.e. a human readable string used
146	n/a	# to represent the magic number in __pycache__ directories. When you change
147	n/a	# the magic number, you must also set a new unique magic tag. Generally this
148	n/a	# can be named after the Python major version of the magic number bump, but
149	n/a	# it can really be anything, as long as it's different than anything else
150	n/a	# that's come before. The tags are included in the following table, starting
151	n/a	# with Python 3.2a0.
152	n/a	#
153	n/a	# Known values:
154	n/a	# Python 1.5: 20121
155	n/a	# Python 1.5.1: 20121
156	n/a	# Python 1.5.2: 20121
157	n/a	# Python 1.6: 50428
158	n/a	# Python 2.0: 50823
159	n/a	# Python 2.0.1: 50823
160	n/a	# Python 2.1: 60202
161	n/a	# Python 2.1.1: 60202
162	n/a	# Python 2.1.2: 60202
163	n/a	# Python 2.2: 60717
164	n/a	# Python 2.3a0: 62011
165	n/a	# Python 2.3a0: 62021
166	n/a	# Python 2.3a0: 62011 (!)
167	n/a	# Python 2.4a0: 62041
168	n/a	# Python 2.4a3: 62051
169	n/a	# Python 2.4b1: 62061
170	n/a	# Python 2.5a0: 62071
171	n/a	# Python 2.5a0: 62081 (ast-branch)
172	n/a	# Python 2.5a0: 62091 (with)
173	n/a	# Python 2.5a0: 62092 (changed WITH_CLEANUP opcode)
174	n/a	# Python 2.5b3: 62101 (fix wrong code: for x, in ...)
175	n/a	# Python 2.5b3: 62111 (fix wrong code: x += yield)
176	n/a	# Python 2.5c1: 62121 (fix wrong lnotab with for loops and
177	n/a	# storing constants that should have been removed)
178	n/a	# Python 2.5c2: 62131 (fix wrong code: for x, in ... in listcomp/genexp)
179	n/a	# Python 2.6a0: 62151 (peephole optimizations and STORE_MAP opcode)
180	n/a	# Python 2.6a1: 62161 (WITH_CLEANUP optimization)
181	n/a	# Python 2.7a0: 62171 (optimize list comprehensions/change LIST_APPEND)
182	n/a	# Python 2.7a0: 62181 (optimize conditional branches:
183	n/a	# introduce POP_JUMP_IF_FALSE and POP_JUMP_IF_TRUE)
184	n/a	# Python 2.7a0 62191 (introduce SETUP_WITH)
185	n/a	# Python 2.7a0 62201 (introduce BUILD_SET)
186	n/a	# Python 2.7a0 62211 (introduce MAP_ADD and SET_ADD)
187	n/a	# Python 3000: 3000
188	n/a	# 3010 (removed UNARY_CONVERT)
189	n/a	# 3020 (added BUILD_SET)
190	n/a	# 3030 (added keyword-only parameters)
191	n/a	# 3040 (added signature annotations)
192	n/a	# 3050 (print becomes a function)
193	n/a	# 3060 (PEP 3115 metaclass syntax)
194	n/a	# 3061 (string literals become unicode)
195	n/a	# 3071 (PEP 3109 raise changes)
196	n/a	# 3081 (PEP 3137 make __file__ and __name__ unicode)
197	n/a	# 3091 (kill str8 interning)
198	n/a	# 3101 (merge from 2.6a0, see 62151)
199	n/a	# 3103 (__file__ points to source file)
200	n/a	# Python 3.0a4: 3111 (WITH_CLEANUP optimization).
201	n/a	# Python 3.0a5: 3131 (lexical exception stacking, including POP_EXCEPT)
202	n/a	# Python 3.1a0: 3141 (optimize list, set and dict comprehensions:
203	n/a	# change LIST_APPEND and SET_ADD, add MAP_ADD)
204	n/a	# Python 3.1a0: 3151 (optimize conditional branches:
205	n/a	# introduce POP_JUMP_IF_FALSE and POP_JUMP_IF_TRUE)
206	n/a	# Python 3.2a0: 3160 (add SETUP_WITH)
207	n/a	# tag: cpython-32
208	n/a	# Python 3.2a1: 3170 (add DUP_TOP_TWO, remove DUP_TOPX and ROT_FOUR)
209	n/a	# tag: cpython-32
210	n/a	# Python 3.2a2 3180 (add DELETE_DEREF)
211	n/a	# Python 3.3a0 3190 __class__ super closure changed
212	n/a	# Python 3.3a0 3200 (__qualname__ added)
213	n/a	# 3210 (added size modulo 2**32 to the pyc header)
214	n/a	# Python 3.3a1 3220 (changed PEP 380 implementation)
215	n/a	# Python 3.3a4 3230 (revert changes to implicit __class__ closure)
216	n/a	# Python 3.4a1 3250 (evaluate positional default arguments before
217	n/a	# keyword-only defaults)
218	n/a	# Python 3.4a1 3260 (add LOAD_CLASSDEREF; allow locals of class to override
219	n/a	# free vars)
220	n/a	# Python 3.4a1 3270 (various tweaks to the __class__ closure)
221	n/a	# Python 3.4a1 3280 (remove implicit class argument)
222	n/a	# Python 3.4a4 3290 (changes to __qualname__ computation)
223	n/a	# Python 3.4a4 3300 (more changes to __qualname__ computation)
224	n/a	# Python 3.4rc2 3310 (alter __qualname__ computation)
225	n/a	# Python 3.5a0 3320 (matrix multiplication operator)
226	n/a	# Python 3.5b1 3330 (PEP 448: Additional Unpacking Generalizations)
227	n/a	# Python 3.5b2 3340 (fix dictionary display evaluation order #11205)
228	n/a	# Python 3.5b2 3350 (add GET_YIELD_FROM_ITER opcode #24400)
229	n/a	# Python 3.5.2 3351 (fix BUILD_MAP_UNPACK_WITH_CALL opcode #27286)
230	n/a	# Python 3.6a0 3360 (add FORMAT_VALUE opcode #25483
231	n/a	# Python 3.6a0 3361 (lineno delta of code.co_lnotab becomes signed)
232	n/a	# Python 3.6a1 3370 (16 bit wordcode)
233	n/a	# Python 3.6a1 3371 (add BUILD_CONST_KEY_MAP opcode #27140)
234	n/a	# Python 3.6a1 3372 (MAKE_FUNCTION simplification, remove MAKE_CLOSURE
235	n/a	# #27095)
236	n/a	# Python 3.6b1 3373 (add BUILD_STRING opcode #27078)
237	n/a	# Python 3.6b1 3375 (add SETUP_ANNOTATIONS and STORE_ANNOTATION opcodes
238	n/a	# #27985)
239	n/a	# Python 3.6b1 3376 (simplify CALL_FUNCTIONs & BUILD_MAP_UNPACK_WITH_CALL)
240	n/a	# Python 3.6b1 3377 (set __class__ cell from type.__new__ #23722)
241	n/a	# Python 3.6b2 3378 (add BUILD_TUPLE_UNPACK_WITH_CALL #28257)
242	n/a	# Python 3.6rc1 3379 (more thorough __class__ validation #23722)
243	n/a	# Python 3.7a0 3390 (add LOAD_METHOD and CALL_METHOD opcodes)
244	n/a	#
245	n/a	# MAGIC must change whenever the bytecode emitted by the compiler may no
246	n/a	# longer be understood by older implementations of the eval loop (usually
247	n/a	# due to the addition of new opcodes).
248	n/a	#
249	n/a	# Whenever MAGIC_NUMBER is changed, the ranges in the magic_values array
250	n/a	# in PC/launcher.c must also be updated.
251	n/a
252	n/a	MAGIC_NUMBER = (3390).to_bytes(2, 'little') + b'\r\n'
253	n/a	_RAW_MAGIC_NUMBER = int.from_bytes(MAGIC_NUMBER, 'little') # For import.c
254	n/a
255	n/a	_PYCACHE = '__pycache__'
256	n/a	_OPT = 'opt-'
257	n/a
258	n/a	SOURCE_SUFFIXES = ['.py'] # _setup() adds .pyw as needed.
259	n/a
260	n/a	BYTECODE_SUFFIXES = ['.pyc']
261	n/a	# Deprecated.
262	n/a	DEBUG_BYTECODE_SUFFIXES = OPTIMIZED_BYTECODE_SUFFIXES = BYTECODE_SUFFIXES
263	n/a
264	n/a	def cache_from_source(path, debug_override=None, *, optimization=None):
265	n/a	"""Given the path to a .py file, return the path to its .pyc file.
266	n/a
267	n/a	The .py file does not need to exist; this simply returns the path to the
268	n/a	.pyc file calculated as if the .py file were imported.
269	n/a
270	n/a	The 'optimization' parameter controls the presumed optimization level of
271	n/a	the bytecode file. If 'optimization' is not None, the string representation
272	n/a	of the argument is taken and verified to be alphanumeric (else ValueError
273	n/a	is raised).
274	n/a
275	n/a	The debug_override parameter is deprecated. If debug_override is not None,
276	n/a	a True value is the same as setting 'optimization' to the empty string
277	n/a	while a False value is equivalent to setting 'optimization' to '1'.
278	n/a
279	n/a	If sys.implementation.cache_tag is None then NotImplementedError is raised.
280	n/a
281	n/a	"""
282	n/a	if debug_override is not None:
283	n/a	_warnings.warn('the debug_override parameter is deprecated; use '
284	n/a	"'optimization' instead", DeprecationWarning)
285	n/a	if optimization is not None:
286	n/a	message = 'debug_override or optimization must be set to None'
287	n/a	raise TypeError(message)
288	n/a	optimization = '' if debug_override else 1
289	n/a	path = _os.fspath(path)
290	n/a	head, tail = _path_split(path)
291	n/a	base, sep, rest = tail.rpartition('.')
292	n/a	tag = sys.implementation.cache_tag
293	n/a	if tag is None:
294	n/a	raise NotImplementedError('sys.implementation.cache_tag is None')
295	n/a	almost_filename = ''.join([(base if base else rest), sep, tag])
296	n/a	if optimization is None:
297	n/a	if sys.flags.optimize == 0:
298	n/a	optimization = ''
299	n/a	else:
300	n/a	optimization = sys.flags.optimize
301	n/a	optimization = str(optimization)
302	n/a	if optimization != '':
303	n/a	if not optimization.isalnum():
304	n/a	raise ValueError('{!r} is not alphanumeric'.format(optimization))
305	n/a	almost_filename = '{}.{}{}'.format(almost_filename, _OPT, optimization)
306	n/a	return _path_join(head, _PYCACHE, almost_filename + BYTECODE_SUFFIXES[0])
307	n/a
308	n/a
309	n/a	def source_from_cache(path):
310	n/a	"""Given the path to a .pyc. file, return the path to its .py file.
311	n/a
312	n/a	The .pyc file does not need to exist; this simply returns the path to
313	n/a	the .py file calculated to correspond to the .pyc file. If path does
314	n/a	not conform to PEP 3147/488 format, ValueError will be raised. If
315	n/a	sys.implementation.cache_tag is None then NotImplementedError is raised.
316	n/a
317	n/a	"""
318	n/a	if sys.implementation.cache_tag is None:
319	n/a	raise NotImplementedError('sys.implementation.cache_tag is None')
320	n/a	path = _os.fspath(path)
321	n/a	head, pycache_filename = _path_split(path)
322	n/a	head, pycache = _path_split(head)
323	n/a	if pycache != _PYCACHE:
324	n/a	raise ValueError('{} not bottom-level directory in '
325	n/a	'{!r}'.format(_PYCACHE, path))
326	n/a	dot_count = pycache_filename.count('.')
327	n/a	if dot_count not in {2, 3}:
328	n/a	raise ValueError('expected only 2 or 3 dots in '
329	n/a	'{!r}'.format(pycache_filename))
330	n/a	elif dot_count == 3:
331	n/a	optimization = pycache_filename.rsplit('.', 2)[-2]
332	n/a	if not optimization.startswith(_OPT):
333	n/a	raise ValueError("optimization portion of filename does not start "
334	n/a	"with {!r}".format(_OPT))
335	n/a	opt_level = optimization[len(_OPT):]
336	n/a	if not opt_level.isalnum():
337	n/a	raise ValueError("optimization level {!r} is not an alphanumeric "
338	n/a	"value".format(optimization))
339	n/a	base_filename = pycache_filename.partition('.')[0]
340	n/a	return _path_join(head, base_filename + SOURCE_SUFFIXES[0])
341	n/a
342	n/a
343	n/a	def _get_sourcefile(bytecode_path):
344	n/a	"""Convert a bytecode file path to a source path (if possible).
345	n/a
346	n/a	This function exists purely for backwards-compatibility for
347	n/a	PyImport_ExecCodeModuleWithFilenames() in the C API.
348	n/a
349	n/a	"""
350	n/a	if len(bytecode_path) == 0:
351	n/a	return None
352	n/a	rest, _, extension = bytecode_path.rpartition('.')
353	n/a	if not rest or extension.lower()[-3:-1] != 'py':
354	n/a	return bytecode_path
355	n/a	try:
356	n/a	source_path = source_from_cache(bytecode_path)
357	n/a	except (NotImplementedError, ValueError):
358	n/a	source_path = bytecode_path[:-1]
359	n/a	return source_path if _path_isfile(source_path) else bytecode_path
360	n/a
361	n/a
362	n/a	def _get_cached(filename):
363	n/a	if filename.endswith(tuple(SOURCE_SUFFIXES)):
364	n/a	try:
365	n/a	return cache_from_source(filename)
366	n/a	except NotImplementedError:
367	n/a	pass
368	n/a	elif filename.endswith(tuple(BYTECODE_SUFFIXES)):
369	n/a	return filename
370	n/a	else:
371	n/a	return None
372	n/a
373	n/a
374	n/a	def _calc_mode(path):
375	n/a	"""Calculate the mode permissions for a bytecode file."""
376	n/a	try:
377	n/a	mode = _path_stat(path).st_mode
378	n/a	except OSError:
379	n/a	mode = 0o666
380	n/a	# We always ensure write access so we can update cached files
381	n/a	# later even when the source files are read-only on Windows (#6074)
382	n/a	mode \|= 0o200
383	n/a	return mode
384	n/a
385	n/a
386	n/a	def _check_name(method):
387	n/a	"""Decorator to verify that the module being requested matches the one the
388	n/a	loader can handle.
389	n/a
390	n/a	The first argument (self) must define _name which the second argument is
391	n/a	compared against. If the comparison fails then ImportError is raised.
392	n/a
393	n/a	"""
394	n/a	def _check_name_wrapper(self, name=None, args, *kwargs):
395	n/a	if name is None:
396	n/a	name = self.name
397	n/a	elif self.name != name:
398	n/a	raise ImportError('loader for %s cannot handle %s' %
399	n/a	(self.name, name), name=name)
400	n/a	return method(self, name, args, *kwargs)
401	n/a	try:
402	n/a	_wrap = _bootstrap._wrap
403	n/a	except NameError:
404	n/a	# XXX yuck
405	n/a	def _wrap(new, old):
406	n/a	for replace in ['__module__', '__name__', '__qualname__', '__doc__']:
407	n/a	if hasattr(old, replace):
408	n/a	setattr(new, replace, getattr(old, replace))
409	n/a	new.__dict__.update(old.__dict__)
410	n/a	_wrap(_check_name_wrapper, method)
411	n/a	return _check_name_wrapper
412	n/a
413	n/a
414	n/a	def _find_module_shim(self, fullname):
415	n/a	"""Try to find a loader for the specified module by delegating to
416	n/a	self.find_loader().
417	n/a
418	n/a	This method is deprecated in favor of finder.find_spec().
419	n/a
420	n/a	"""
421	n/a	# Call find_loader(). If it returns a string (indicating this
422	n/a	# is a namespace package portion), generate a warning and
423	n/a	# return None.
424	n/a	loader, portions = self.find_loader(fullname)
425	n/a	if loader is None and len(portions):
426	n/a	msg = 'Not importing directory {}: missing __init__'
427	n/a	_warnings.warn(msg.format(portions[0]), ImportWarning)
428	n/a	return loader
429	n/a
430	n/a
431	n/a	def _validate_bytecode_header(data, source_stats=None, name=None, path=None):
432	n/a	"""Validate the header of the passed-in bytecode against source_stats (if
433	n/a	given) and returning the bytecode that can be compiled by compile().
434	n/a
435	n/a	All other arguments are used to enhance error reporting.
436	n/a
437	n/a	ImportError is raised when the magic number is incorrect or the bytecode is
438	n/a	found to be stale. EOFError is raised when the data is found to be
439	n/a	truncated.
440	n/a
441	n/a	"""
442	n/a	exc_details = {}
443	n/a	if name is not None:
444	n/a	exc_details['name'] = name
445	n/a	else:
446	n/a	# To prevent having to make all messages have a conditional name.
447	n/a	name = '<bytecode>'
448	n/a	if path is not None:
449	n/a	exc_details['path'] = path
450	n/a	magic = data[:4]
451	n/a	raw_timestamp = data[4:8]
452	n/a	raw_size = data[8:12]
453	n/a	if magic != MAGIC_NUMBER:
454	n/a	message = 'bad magic number in {!r}: {!r}'.format(name, magic)
455	n/a	_bootstrap._verbose_message('{}', message)
456	n/a	raise ImportError(message, **exc_details)
457	n/a	elif len(raw_timestamp) != 4:
458	n/a	message = 'reached EOF while reading timestamp in {!r}'.format(name)
459	n/a	_bootstrap._verbose_message('{}', message)
460	n/a	raise EOFError(message)
461	n/a	elif len(raw_size) != 4:
462	n/a	message = 'reached EOF while reading size of source in {!r}'.format(name)
463	n/a	_bootstrap._verbose_message('{}', message)
464	n/a	raise EOFError(message)
465	n/a	if source_stats is not None:
466	n/a	try:
467	n/a	source_mtime = int(source_stats['mtime'])
468	n/a	except KeyError:
469	n/a	pass
470	n/a	else:
471	n/a	if _r_long(raw_timestamp) != source_mtime:
472	n/a	message = 'bytecode is stale for {!r}'.format(name)
473	n/a	_bootstrap._verbose_message('{}', message)
474	n/a	raise ImportError(message, **exc_details)
475	n/a	try:
476	n/a	source_size = source_stats['size'] & 0xFFFFFFFF
477	n/a	except KeyError:
478	n/a	pass
479	n/a	else:
480	n/a	if _r_long(raw_size) != source_size:
481	n/a	raise ImportError('bytecode is stale for {!r}'.format(name),
482	n/a	**exc_details)
483	n/a	return data[12:]
484	n/a
485	n/a
486	n/a	def _compile_bytecode(data, name=None, bytecode_path=None, source_path=None):
487	n/a	"""Compile bytecode as returned by _validate_bytecode_header()."""
488	n/a	code = marshal.loads(data)
489	n/a	if isinstance(code, _code_type):
490	n/a	_bootstrap._verbose_message('code object from {!r}', bytecode_path)
491	n/a	if source_path is not None:
492	n/a	_imp._fix_co_filename(code, source_path)
493	n/a	return code
494	n/a	else:
495	n/a	raise ImportError('Non-code object in {!r}'.format(bytecode_path),
496	n/a	name=name, path=bytecode_path)
497	n/a
498	n/a	def _code_to_bytecode(code, mtime=0, source_size=0):
499	n/a	"""Compile a code object into bytecode for writing out to a byte-compiled
500	n/a	file."""
501	n/a	data = bytearray(MAGIC_NUMBER)
502	n/a	data.extend(_w_long(mtime))
503	n/a	data.extend(_w_long(source_size))
504	n/a	data.extend(marshal.dumps(code))
505	n/a	return data
506	n/a
507	n/a
508	n/a	def decode_source(source_bytes):
509	n/a	"""Decode bytes representing source code and return the string.
510	n/a
511	n/a	Universal newline support is used in the decoding.
512	n/a	"""
513	n/a	import tokenize # To avoid bootstrap issues.
514	n/a	source_bytes_readline = _io.BytesIO(source_bytes).readline
515	n/a	encoding = tokenize.detect_encoding(source_bytes_readline)
516	n/a	newline_decoder = _io.IncrementalNewlineDecoder(None, True)
517	n/a	return newline_decoder.decode(source_bytes.decode(encoding[0]))
518	n/a
519	n/a
520	n/a	# Module specifications #######################################################
521	n/a
522	n/a	_POPULATE = object()
523	n/a
524	n/a
525	n/a	def spec_from_file_location(name, location=None, *, loader=None,
526	n/a	submodule_search_locations=_POPULATE):
527	n/a	"""Return a module spec based on a file location.
528	n/a
529	n/a	To indicate that the module is a package, set
530	n/a	submodule_search_locations to a list of directory paths. An
531	n/a	empty list is sufficient, though its not otherwise useful to the
532	n/a	import system.
533	n/a
534	n/a	The loader must take a spec as its only __init__() arg.
535	n/a
536	n/a	"""
537	n/a	if location is None:
538	n/a	# The caller may simply want a partially populated location-
539	n/a	# oriented spec. So we set the location to a bogus value and
540	n/a	# fill in as much as we can.
541	n/a	location = '<unknown>'
542	n/a	if hasattr(loader, 'get_filename'):
543	n/a	# ExecutionLoader
544	n/a	try:
545	n/a	location = loader.get_filename(name)
546	n/a	except ImportError:
547	n/a	pass
548	n/a	else:
549	n/a	location = _os.fspath(location)
550	n/a
551	n/a	# If the location is on the filesystem, but doesn't actually exist,
552	n/a	# we could return None here, indicating that the location is not
553	n/a	# valid. However, we don't have a good way of testing since an
554	n/a	# indirect location (e.g. a zip file or URL) will look like a
555	n/a	# non-existent file relative to the filesystem.
556	n/a
557	n/a	spec = _bootstrap.ModuleSpec(name, loader, origin=location)
558	n/a	spec._set_fileattr = True
559	n/a
560	n/a	# Pick a loader if one wasn't provided.
561	n/a	if loader is None:
562	n/a	for loader_class, suffixes in _get_supported_file_loaders():
563	n/a	if location.endswith(tuple(suffixes)):
564	n/a	loader = loader_class(name, location)
565	n/a	spec.loader = loader
566	n/a	break
567	n/a	else:
568	n/a	return None
569	n/a
570	n/a	# Set submodule_search_paths appropriately.
571	n/a	if submodule_search_locations is _POPULATE:
572	n/a	# Check the loader.
573	n/a	if hasattr(loader, 'is_package'):
574	n/a	try:
575	n/a	is_package = loader.is_package(name)
576	n/a	except ImportError:
577	n/a	pass
578	n/a	else:
579	n/a	if is_package:
580	n/a	spec.submodule_search_locations = []
581	n/a	else:
582	n/a	spec.submodule_search_locations = submodule_search_locations
583	n/a	if spec.submodule_search_locations == []:
584	n/a	if location:
585	n/a	dirname = _path_split(location)[0]
586	n/a	spec.submodule_search_locations.append(dirname)
587	n/a
588	n/a	return spec
589	n/a
590	n/a
591	n/a	# Loaders #####################################################################
592	n/a
593	n/a	class WindowsRegistryFinder:
594	n/a
595	n/a	"""Meta path finder for modules declared in the Windows registry."""
596	n/a
597	n/a	REGISTRY_KEY = (
598	n/a	'Software\\Python\\PythonCore\\{sys_version}'
599	n/a	'\\Modules\\{fullname}')
600	n/a	REGISTRY_KEY_DEBUG = (
601	n/a	'Software\\Python\\PythonCore\\{sys_version}'
602	n/a	'\\Modules\\{fullname}\\Debug')
603	n/a	DEBUG_BUILD = False # Changed in _setup()
604	n/a
605	n/a	@classmethod
606	n/a	def _open_registry(cls, key):
607	n/a	try:
608	n/a	return _winreg.OpenKey(_winreg.HKEY_CURRENT_USER, key)
609	n/a	except OSError:
610	n/a	return _winreg.OpenKey(_winreg.HKEY_LOCAL_MACHINE, key)
611	n/a
612	n/a	@classmethod
613	n/a	def _search_registry(cls, fullname):
614	n/a	if cls.DEBUG_BUILD:
615	n/a	registry_key = cls.REGISTRY_KEY_DEBUG
616	n/a	else:
617	n/a	registry_key = cls.REGISTRY_KEY
618	n/a	key = registry_key.format(fullname=fullname,
619	n/a	sys_version='%d.%d' % sys.version_info[:2])
620	n/a	try:
621	n/a	with cls._open_registry(key) as hkey:
622	n/a	filepath = _winreg.QueryValue(hkey, '')
623	n/a	except OSError:
624	n/a	return None
625	n/a	return filepath
626	n/a
627	n/a	@classmethod
628	n/a	def find_spec(cls, fullname, path=None, target=None):
629	n/a	filepath = cls._search_registry(fullname)
630	n/a	if filepath is None:
631	n/a	return None
632	n/a	try:
633	n/a	_path_stat(filepath)
634	n/a	except OSError:
635	n/a	return None
636	n/a	for loader, suffixes in _get_supported_file_loaders():
637	n/a	if filepath.endswith(tuple(suffixes)):
638	n/a	spec = _bootstrap.spec_from_loader(fullname,
639	n/a	loader(fullname, filepath),
640	n/a	origin=filepath)
641	n/a	return spec
642	n/a
643	n/a	@classmethod
644	n/a	def find_module(cls, fullname, path=None):
645	n/a	"""Find module named in the registry.
646	n/a
647	n/a	This method is deprecated. Use exec_module() instead.
648	n/a
649	n/a	"""
650	n/a	spec = cls.find_spec(fullname, path)
651	n/a	if spec is not None:
652	n/a	return spec.loader
653	n/a	else:
654	n/a	return None
655	n/a
656	n/a
657	n/a	class _LoaderBasics:
658	n/a
659	n/a	"""Base class of common code needed by both SourceLoader and
660	n/a	SourcelessFileLoader."""
661	n/a
662	n/a	def is_package(self, fullname):
663	n/a	"""Concrete implementation of InspectLoader.is_package by checking if
664	n/a	the path returned by get_filename has a filename of '__init__.py'."""
665	n/a	filename = _path_split(self.get_filename(fullname))[1]
666	n/a	filename_base = filename.rsplit('.', 1)[0]
667	n/a	tail_name = fullname.rpartition('.')[2]
668	n/a	return filename_base == '__init__' and tail_name != '__init__'
669	n/a
670	n/a	def create_module(self, spec):
671	n/a	"""Use default semantics for module creation."""
672	n/a
673	n/a	def exec_module(self, module):
674	n/a	"""Execute the module."""
675	n/a	code = self.get_code(module.__name__)
676	n/a	if code is None:
677	n/a	raise ImportError('cannot load module {!r} when get_code() '
678	n/a	'returns None'.format(module.__name__))
679	n/a	_bootstrap._call_with_frames_removed(exec, code, module.__dict__)
680	n/a
681	n/a	def load_module(self, fullname):
682	n/a	"""This module is deprecated."""
683	n/a	return _bootstrap._load_module_shim(self, fullname)
684	n/a
685	n/a
686	n/a	class SourceLoader(_LoaderBasics):
687	n/a
688	n/a	def path_mtime(self, path):
689	n/a	"""Optional method that returns the modification time (an int) for the
690	n/a	specified path, where path is a str.
691	n/a
692	n/a	Raises IOError when the path cannot be handled.
693	n/a	"""
694	n/a	raise IOError
695	n/a
696	n/a	def path_stats(self, path):
697	n/a	"""Optional method returning a metadata dict for the specified path
698	n/a	to by the path (str).
699	n/a	Possible keys:
700	n/a	- 'mtime' (mandatory) is the numeric timestamp of last source
701	n/a	code modification;
702	n/a	- 'size' (optional) is the size in bytes of the source code.
703	n/a
704	n/a	Implementing this method allows the loader to read bytecode files.
705	n/a	Raises IOError when the path cannot be handled.
706	n/a	"""
707	n/a	return {'mtime': self.path_mtime(path)}
708	n/a
709	n/a	def _cache_bytecode(self, source_path, cache_path, data):
710	n/a	"""Optional method which writes data (bytes) to a file path (a str).
711	n/a
712	n/a	Implementing this method allows for the writing of bytecode files.
713	n/a
714	n/a	The source path is needed in order to correctly transfer permissions
715	n/a	"""
716	n/a	# For backwards compatibility, we delegate to set_data()
717	n/a	return self.set_data(cache_path, data)
718	n/a
719	n/a	def set_data(self, path, data):
720	n/a	"""Optional method which writes data (bytes) to a file path (a str).
721	n/a
722	n/a	Implementing this method allows for the writing of bytecode files.
723	n/a	"""
724	n/a
725	n/a
726	n/a	def get_source(self, fullname):
727	n/a	"""Concrete implementation of InspectLoader.get_source."""
728	n/a	path = self.get_filename(fullname)
729	n/a	try:
730	n/a	source_bytes = self.get_data(path)
731	n/a	except OSError as exc:
732	n/a	raise ImportError('source not available through get_data()',
733	n/a	name=fullname) from exc
734	n/a	return decode_source(source_bytes)
735	n/a
736	n/a	def source_to_code(self, data, path, *, _optimize=-1):
737	n/a	"""Return the code object compiled from source.
738	n/a
739	n/a	The 'data' argument can be any object type that compile() supports.
740	n/a	"""
741	n/a	return _bootstrap._call_with_frames_removed(compile, data, path, 'exec',
742	n/a	dont_inherit=True, optimize=_optimize)
743	n/a
744	n/a	def get_code(self, fullname):
745	n/a	"""Concrete implementation of InspectLoader.get_code.
746	n/a
747	n/a	Reading of bytecode requires path_stats to be implemented. To write
748	n/a	bytecode, set_data must also be implemented.
749	n/a
750	n/a	"""
751	n/a	source_path = self.get_filename(fullname)
752	n/a	source_mtime = None
753	n/a	try:
754	n/a	bytecode_path = cache_from_source(source_path)
755	n/a	except NotImplementedError:
756	n/a	bytecode_path = None
757	n/a	else:
758	n/a	try:
759	n/a	st = self.path_stats(source_path)
760	n/a	except IOError:
761	n/a	pass
762	n/a	else:
763	n/a	source_mtime = int(st['mtime'])
764	n/a	try:
765	n/a	data = self.get_data(bytecode_path)
766	n/a	except OSError:
767	n/a	pass
768	n/a	else:
769	n/a	try:
770	n/a	bytes_data = _validate_bytecode_header(data,
771	n/a	source_stats=st, name=fullname,
772	n/a	path=bytecode_path)
773	n/a	except (ImportError, EOFError):
774	n/a	pass
775	n/a	else:
776	n/a	_bootstrap._verbose_message('{} matches {}', bytecode_path,
777	n/a	source_path)
778	n/a	return _compile_bytecode(bytes_data, name=fullname,
779	n/a	bytecode_path=bytecode_path,
780	n/a	source_path=source_path)
781	n/a	source_bytes = self.get_data(source_path)
782	n/a	code_object = self.source_to_code(source_bytes, source_path)
783	n/a	_bootstrap._verbose_message('code object from {}', source_path)
784	n/a	if (not sys.dont_write_bytecode and bytecode_path is not None and
785	n/a	source_mtime is not None):
786	n/a	data = _code_to_bytecode(code_object, source_mtime,
787	n/a	len(source_bytes))
788	n/a	try:
789	n/a	self._cache_bytecode(source_path, bytecode_path, data)
790	n/a	_bootstrap._verbose_message('wrote {!r}', bytecode_path)
791	n/a	except NotImplementedError:
792	n/a	pass
793	n/a	return code_object
794	n/a
795	n/a
796	n/a	class FileLoader:
797	n/a
798	n/a	"""Base file loader class which implements the loader protocol methods that
799	n/a	require file system usage."""
800	n/a
801	n/a	def __init__(self, fullname, path):
802	n/a	"""Cache the module name and the path to the file found by the
803	n/a	finder."""
804	n/a	self.name = fullname
805	n/a	self.path = path
806	n/a
807	n/a	def __eq__(self, other):
808	n/a	return (self.__class__ == other.__class__ and
809	n/a	self.__dict__ == other.__dict__)
810	n/a
811	n/a	def __hash__(self):
812	n/a	return hash(self.name) ^ hash(self.path)
813	n/a
814	n/a	@_check_name
815	n/a	def load_module(self, fullname):
816	n/a	"""Load a module from a file.
817	n/a
818	n/a	This method is deprecated. Use exec_module() instead.
819	n/a
820	n/a	"""
821	n/a	# The only reason for this method is for the name check.
822	n/a	# Issue #14857: Avoid the zero-argument form of super so the implementation
823	n/a	# of that form can be updated without breaking the frozen module
824	n/a	return super(FileLoader, self).load_module(fullname)
825	n/a
826	n/a	@_check_name
827	n/a	def get_filename(self, fullname):
828	n/a	"""Return the path to the source file as found by the finder."""
829	n/a	return self.path
830	n/a
831	n/a	def get_data(self, path):
832	n/a	"""Return the data from path as raw bytes."""
833	n/a	with _io.FileIO(path, 'r') as file:
834	n/a	return file.read()
835	n/a
836	n/a
837	n/a	class SourceFileLoader(FileLoader, SourceLoader):
838	n/a
839	n/a	"""Concrete implementation of SourceLoader using the file system."""
840	n/a
841	n/a	def path_stats(self, path):
842	n/a	"""Return the metadata for the path."""
843	n/a	st = _path_stat(path)
844	n/a	return {'mtime': st.st_mtime, 'size': st.st_size}
845	n/a
846	n/a	def _cache_bytecode(self, source_path, bytecode_path, data):
847	n/a	# Adapt between the two APIs
848	n/a	mode = _calc_mode(source_path)
849	n/a	return self.set_data(bytecode_path, data, _mode=mode)
850	n/a
851	n/a	def set_data(self, path, data, *, _mode=0o666):
852	n/a	"""Write bytes data to a file."""
853	n/a	parent, filename = _path_split(path)
854	n/a	path_parts = []
855	n/a	# Figure out what directories are missing.
856	n/a	while parent and not _path_isdir(parent):
857	n/a	parent, part = _path_split(parent)
858	n/a	path_parts.append(part)
859	n/a	# Create needed directories.
860	n/a	for part in reversed(path_parts):
861	n/a	parent = _path_join(parent, part)
862	n/a	try:
863	n/a	_os.mkdir(parent)
864	n/a	except FileExistsError:
865	n/a	# Probably another Python process already created the dir.
866	n/a	continue
867	n/a	except OSError as exc:
868	n/a	# Could be a permission error, read-only filesystem: just forget
869	n/a	# about writing the data.
870	n/a	_bootstrap._verbose_message('could not create {!r}: {!r}',
871	n/a	parent, exc)
872	n/a	return
873	n/a	try:
874	n/a	_write_atomic(path, data, _mode)
875	n/a	_bootstrap._verbose_message('created {!r}', path)
876	n/a	except OSError as exc:
877	n/a	# Same as above: just don't write the bytecode.
878	n/a	_bootstrap._verbose_message('could not create {!r}: {!r}', path,
879	n/a	exc)
880	n/a
881	n/a
882	n/a	class SourcelessFileLoader(FileLoader, _LoaderBasics):
883	n/a
884	n/a	"""Loader which handles sourceless file imports."""
885	n/a
886	n/a	def get_code(self, fullname):
887	n/a	path = self.get_filename(fullname)
888	n/a	data = self.get_data(path)
889	n/a	bytes_data = _validate_bytecode_header(data, name=fullname, path=path)
890	n/a	return _compile_bytecode(bytes_data, name=fullname, bytecode_path=path)
891	n/a
892	n/a	def get_source(self, fullname):
893	n/a	"""Return None as there is no source code."""
894	n/a	return None
895	n/a
896	n/a
897	n/a	# Filled in by _setup().
898	n/a	EXTENSION_SUFFIXES = []
899	n/a
900	n/a
901	n/a	class ExtensionFileLoader(FileLoader, _LoaderBasics):
902	n/a
903	n/a	"""Loader for extension modules.
904	n/a
905	n/a	The constructor is designed to work with FileFinder.
906	n/a
907	n/a	"""
908	n/a
909	n/a	def __init__(self, name, path):
910	n/a	self.name = name
911	n/a	self.path = path
912	n/a
913	n/a	def __eq__(self, other):
914	n/a	return (self.__class__ == other.__class__ and
915	n/a	self.__dict__ == other.__dict__)
916	n/a
917	n/a	def __hash__(self):
918	n/a	return hash(self.name) ^ hash(self.path)
919	n/a
920	n/a	def create_module(self, spec):
921	n/a	"""Create an unitialized extension module"""
922	n/a	module = _bootstrap._call_with_frames_removed(
923	n/a	_imp.create_dynamic, spec)
924	n/a	_bootstrap._verbose_message('extension module {!r} loaded from {!r}',
925	n/a	spec.name, self.path)
926	n/a	return module
927	n/a
928	n/a	def exec_module(self, module):
929	n/a	"""Initialize an extension module"""
930	n/a	_bootstrap._call_with_frames_removed(_imp.exec_dynamic, module)
931	n/a	_bootstrap._verbose_message('extension module {!r} executed from {!r}',
932	n/a	self.name, self.path)
933	n/a
934	n/a	def is_package(self, fullname):
935	n/a	"""Return True if the extension module is a package."""
936	n/a	file_name = _path_split(self.path)[1]
937	n/a	return any(file_name == '__init__' + suffix
938	n/a	for suffix in EXTENSION_SUFFIXES)
939	n/a
940	n/a	def get_code(self, fullname):
941	n/a	"""Return None as an extension module cannot create a code object."""
942	n/a	return None
943	n/a
944	n/a	def get_source(self, fullname):
945	n/a	"""Return None as extension modules have no source code."""
946	n/a	return None
947	n/a
948	n/a	@_check_name
949	n/a	def get_filename(self, fullname):
950	n/a	"""Return the path to the source file as found by the finder."""
951	n/a	return self.path
952	n/a
953	n/a
954	n/a	class _NamespacePath:
955	n/a	"""Represents a namespace package's path. It uses the module name
956	n/a	to find its parent module, and from there it looks up the parent's
957	n/a	__path__. When this changes, the module's own path is recomputed,
958	n/a	using path_finder. For top-level modules, the parent module's path
959	n/a	is sys.path."""
960	n/a
961	n/a	def __init__(self, name, path, path_finder):
962	n/a	self._name = name
963	n/a	self._path = path
964	n/a	self._last_parent_path = tuple(self._get_parent_path())
965	n/a	self._path_finder = path_finder
966	n/a
967	n/a	def _find_parent_path_names(self):
968	n/a	"""Returns a tuple of (parent-module-name, parent-path-attr-name)"""
969	n/a	parent, dot, me = self._name.rpartition('.')
970	n/a	if dot == '':
971	n/a	# This is a top-level module. sys.path contains the parent path.
972	n/a	return 'sys', 'path'
973	n/a	# Not a top-level module. parent-module.__path__ contains the
974	n/a	# parent path.
975	n/a	return parent, '__path__'
976	n/a
977	n/a	def _get_parent_path(self):
978	n/a	parent_module_name, path_attr_name = self._find_parent_path_names()
979	n/a	return getattr(sys.modules[parent_module_name], path_attr_name)
980	n/a
981	n/a	def _recalculate(self):
982	n/a	# If the parent's path has changed, recalculate _path
983	n/a	parent_path = tuple(self._get_parent_path()) # Make a copy
984	n/a	if parent_path != self._last_parent_path:
985	n/a	spec = self._path_finder(self._name, parent_path)
986	n/a	# Note that no changes are made if a loader is returned, but we
987	n/a	# do remember the new parent path
988	n/a	if spec is not None and spec.loader is None:
989	n/a	if spec.submodule_search_locations:
990	n/a	self._path = spec.submodule_search_locations
991	n/a	self._last_parent_path = parent_path # Save the copy
992	n/a	return self._path
993	n/a
994	n/a	def __iter__(self):
995	n/a	return iter(self._recalculate())
996	n/a
997	n/a	def __setitem__(self, index, path):
998	n/a	self._path[index] = path
999	n/a
1000	n/a	def __len__(self):
1001	n/a	return len(self._recalculate())
1002	n/a
1003	n/a	def __repr__(self):
1004	n/a	return '_NamespacePath({!r})'.format(self._path)
1005	n/a
1006	n/a	def __contains__(self, item):
1007	n/a	return item in self._recalculate()
1008	n/a
1009	n/a	def append(self, item):
1010	n/a	self._path.append(item)
1011	n/a
1012	n/a
1013	n/a	# We use this exclusively in module_from_spec() for backward-compatibility.
1014	n/a	class _NamespaceLoader:
1015	n/a	def __init__(self, name, path, path_finder):
1016	n/a	self._path = _NamespacePath(name, path, path_finder)
1017	n/a
1018	n/a	@classmethod
1019	n/a	def module_repr(cls, module):
1020	n/a	"""Return repr for the module.
1021	n/a
1022	n/a	The method is deprecated. The import machinery does the job itself.
1023	n/a
1024	n/a	"""
1025	n/a	return '<module {!r} (namespace)>'.format(module.__name__)
1026	n/a
1027	n/a	def is_package(self, fullname):
1028	n/a	return True
1029	n/a
1030	n/a	def get_source(self, fullname):
1031	n/a	return ''
1032	n/a
1033	n/a	def get_code(self, fullname):
1034	n/a	return compile('', '<string>', 'exec', dont_inherit=True)
1035	n/a
1036	n/a	def create_module(self, spec):
1037	n/a	"""Use default semantics for module creation."""
1038	n/a
1039	n/a	def exec_module(self, module):
1040	n/a	pass
1041	n/a
1042	n/a	def load_module(self, fullname):
1043	n/a	"""Load a namespace module.
1044	n/a
1045	n/a	This method is deprecated. Use exec_module() instead.
1046	n/a
1047	n/a	"""
1048	n/a	# The import system never calls this method.
1049	n/a	_bootstrap._verbose_message('namespace module loaded with path {!r}',
1050	n/a	self._path)
1051	n/a	return _bootstrap._load_module_shim(self, fullname)
1052	n/a
1053	n/a
1054	n/a	# Finders #####################################################################
1055	n/a
1056	n/a	class PathFinder:
1057	n/a
1058	n/a	"""Meta path finder for sys.path and package __path__ attributes."""
1059	n/a
1060	n/a	@classmethod
1061	n/a	def invalidate_caches(cls):
1062	n/a	"""Call the invalidate_caches() method on all path entry finders
1063	n/a	stored in sys.path_importer_caches (where implemented)."""
1064	n/a	for finder in sys.path_importer_cache.values():
1065	n/a	if hasattr(finder, 'invalidate_caches'):
1066	n/a	finder.invalidate_caches()
1067	n/a
1068	n/a	@classmethod
1069	n/a	def _path_hooks(cls, path):
1070	n/a	"""Search sys.path_hooks for a finder for 'path'."""
1071	n/a	if sys.path_hooks is not None and not sys.path_hooks:
1072	n/a	_warnings.warn('sys.path_hooks is empty', ImportWarning)
1073	n/a	for hook in sys.path_hooks:
1074	n/a	try:
1075	n/a	return hook(path)
1076	n/a	except ImportError:
1077	n/a	continue
1078	n/a	else:
1079	n/a	return None
1080	n/a
1081	n/a	@classmethod
1082	n/a	def _path_importer_cache(cls, path):
1083	n/a	"""Get the finder for the path entry from sys.path_importer_cache.
1084	n/a
1085	n/a	If the path entry is not in the cache, find the appropriate finder
1086	n/a	and cache it. If no finder is available, store None.
1087	n/a
1088	n/a	"""
1089	n/a	if path == '':
1090	n/a	try:
1091	n/a	path = _os.getcwd()
1092	n/a	except FileNotFoundError:
1093	n/a	# Don't cache the failure as the cwd can easily change to
1094	n/a	# a valid directory later on.
1095	n/a	return None
1096	n/a	try:
1097	n/a	finder = sys.path_importer_cache[path]
1098	n/a	except KeyError:
1099	n/a	finder = cls._path_hooks(path)
1100	n/a	sys.path_importer_cache[path] = finder
1101	n/a	return finder
1102	n/a
1103	n/a	@classmethod
1104	n/a	def _legacy_get_spec(cls, fullname, finder):
1105	n/a	# This would be a good place for a DeprecationWarning if
1106	n/a	# we ended up going that route.
1107	n/a	if hasattr(finder, 'find_loader'):
1108	n/a	loader, portions = finder.find_loader(fullname)
1109	n/a	else:
1110	n/a	loader = finder.find_module(fullname)
1111	n/a	portions = []
1112	n/a	if loader is not None:
1113	n/a	return _bootstrap.spec_from_loader(fullname, loader)
1114	n/a	spec = _bootstrap.ModuleSpec(fullname, None)
1115	n/a	spec.submodule_search_locations = portions
1116	n/a	return spec
1117	n/a
1118	n/a	@classmethod
1119	n/a	def _get_spec(cls, fullname, path, target=None):
1120	n/a	"""Find the loader or namespace_path for this module/package name."""
1121	n/a	# If this ends up being a namespace package, namespace_path is
1122	n/a	# the list of paths that will become its __path__
1123	n/a	namespace_path = []
1124	n/a	for entry in path:
1125	n/a	if not isinstance(entry, (str, bytes)):
1126	n/a	continue
1127	n/a	finder = cls._path_importer_cache(entry)
1128	n/a	if finder is not None:
1129	n/a	if hasattr(finder, 'find_spec'):
1130	n/a	spec = finder.find_spec(fullname, target)
1131	n/a	else:
1132	n/a	spec = cls._legacy_get_spec(fullname, finder)
1133	n/a	if spec is None:
1134	n/a	continue
1135	n/a	if spec.loader is not None:
1136	n/a	return spec
1137	n/a	portions = spec.submodule_search_locations
1138	n/a	if portions is None:
1139	n/a	raise ImportError('spec missing loader')
1140	n/a	# This is possibly part of a namespace package.
1141	n/a	# Remember these path entries (if any) for when we
1142	n/a	# create a namespace package, and continue iterating
1143	n/a	# on path.
1144	n/a	namespace_path.extend(portions)
1145	n/a	else:
1146	n/a	spec = _bootstrap.ModuleSpec(fullname, None)
1147	n/a	spec.submodule_search_locations = namespace_path
1148	n/a	return spec
1149	n/a
1150	n/a	@classmethod
1151	n/a	def find_spec(cls, fullname, path=None, target=None):
1152	n/a	"""Try to find a spec for 'fullname' on sys.path or 'path'.
1153	n/a
1154	n/a	The search is based on sys.path_hooks and sys.path_importer_cache.
1155	n/a	"""
1156	n/a	if path is None:
1157	n/a	path = sys.path
1158	n/a	spec = cls._get_spec(fullname, path, target)
1159	n/a	if spec is None:
1160	n/a	return None
1161	n/a	elif spec.loader is None:
1162	n/a	namespace_path = spec.submodule_search_locations
1163	n/a	if namespace_path:
1164	n/a	# We found at least one namespace path. Return a
1165	n/a	# spec which can create the namespace package.
1166	n/a	spec.origin = 'namespace'
1167	n/a	spec.submodule_search_locations = _NamespacePath(fullname, namespace_path, cls._get_spec)
1168	n/a	return spec
1169	n/a	else:
1170	n/a	return None
1171	n/a	else:
1172	n/a	return spec
1173	n/a
1174	n/a	@classmethod
1175	n/a	def find_module(cls, fullname, path=None):
1176	n/a	"""find the module on sys.path or 'path' based on sys.path_hooks and
1177	n/a	sys.path_importer_cache.
1178	n/a
1179	n/a	This method is deprecated. Use find_spec() instead.
1180	n/a
1181	n/a	"""
1182	n/a	spec = cls.find_spec(fullname, path)
1183	n/a	if spec is None:
1184	n/a	return None
1185	n/a	return spec.loader
1186	n/a
1187	n/a
1188	n/a	class FileFinder:
1189	n/a
1190	n/a	"""File-based finder.
1191	n/a
1192	n/a	Interactions with the file system are cached for performance, being
1193	n/a	refreshed when the directory the finder is handling has been modified.
1194	n/a
1195	n/a	"""
1196	n/a
1197	n/a	def __init__(self, path, *loader_details):
1198	n/a	"""Initialize with the path to search on and a variable number of
1199	n/a	2-tuples containing the loader and the file suffixes the loader
1200	n/a	recognizes."""
1201	n/a	loaders = []
1202	n/a	for loader, suffixes in loader_details:
1203	n/a	loaders.extend((suffix, loader) for suffix in suffixes)
1204	n/a	self._loaders = loaders
1205	n/a	# Base (directory) path
1206	n/a	self.path = path or '.'
1207	n/a	self._path_mtime = -1
1208	n/a	self._path_cache = set()
1209	n/a	self._relaxed_path_cache = set()
1210	n/a
1211	n/a	def invalidate_caches(self):
1212	n/a	"""Invalidate the directory mtime."""
1213	n/a	self._path_mtime = -1
1214	n/a
1215	n/a	find_module = _find_module_shim
1216	n/a
1217	n/a	def find_loader(self, fullname):
1218	n/a	"""Try to find a loader for the specified module, or the namespace
1219	n/a	package portions. Returns (loader, list-of-portions).
1220	n/a
1221	n/a	This method is deprecated. Use find_spec() instead.
1222	n/a
1223	n/a	"""
1224	n/a	spec = self.find_spec(fullname)
1225	n/a	if spec is None:
1226	n/a	return None, []
1227	n/a	return spec.loader, spec.submodule_search_locations or []
1228	n/a
1229	n/a	def _get_spec(self, loader_class, fullname, path, smsl, target):
1230	n/a	loader = loader_class(fullname, path)
1231	n/a	return spec_from_file_location(fullname, path, loader=loader,
1232	n/a	submodule_search_locations=smsl)
1233	n/a
1234	n/a	def find_spec(self, fullname, target=None):
1235	n/a	"""Try to find a spec for the specified module.
1236	n/a
1237	n/a	Returns the matching spec, or None if not found.
1238	n/a	"""
1239	n/a	is_namespace = False
1240	n/a	tail_module = fullname.rpartition('.')[2]
1241	n/a	try:
1242	n/a	mtime = _path_stat(self.path or _os.getcwd()).st_mtime
1243	n/a	except OSError:
1244	n/a	mtime = -1
1245	n/a	if mtime != self._path_mtime:
1246	n/a	self._fill_cache()
1247	n/a	self._path_mtime = mtime
1248	n/a	# tail_module keeps the original casing, for __file__ and friends
1249	n/a	if _relax_case():
1250	n/a	cache = self._relaxed_path_cache
1251	n/a	cache_module = tail_module.lower()
1252	n/a	else:
1253	n/a	cache = self._path_cache
1254	n/a	cache_module = tail_module
1255	n/a	# Check if the module is the name of a directory (and thus a package).
1256	n/a	if cache_module in cache:
1257	n/a	base_path = _path_join(self.path, tail_module)
1258	n/a	for suffix, loader_class in self._loaders:
1259	n/a	init_filename = '__init__' + suffix
1260	n/a	full_path = _path_join(base_path, init_filename)
1261	n/a	if _path_isfile(full_path):
1262	n/a	return self._get_spec(loader_class, fullname, full_path, [base_path], target)
1263	n/a	else:
1264	n/a	# If a namespace package, return the path if we don't
1265	n/a	# find a module in the next section.
1266	n/a	is_namespace = _path_isdir(base_path)
1267	n/a	# Check for a file w/ a proper suffix exists.
1268	n/a	for suffix, loader_class in self._loaders:
1269	n/a	full_path = _path_join(self.path, tail_module + suffix)
1270	n/a	_bootstrap._verbose_message('trying {}', full_path, verbosity=2)
1271	n/a	if cache_module + suffix in cache:
1272	n/a	if _path_isfile(full_path):
1273	n/a	return self._get_spec(loader_class, fullname, full_path,
1274	n/a	None, target)
1275	n/a	if is_namespace:
1276	n/a	_bootstrap._verbose_message('possible namespace for {}', base_path)
1277	n/a	spec = _bootstrap.ModuleSpec(fullname, None)
1278	n/a	spec.submodule_search_locations = [base_path]
1279	n/a	return spec
1280	n/a	return None
1281	n/a
1282	n/a	def _fill_cache(self):
1283	n/a	"""Fill the cache of potential modules and packages for this directory."""
1284	n/a	path = self.path
1285	n/a	try:
1286	n/a	contents = _os.listdir(path or _os.getcwd())
1287	n/a	except (FileNotFoundError, PermissionError, NotADirectoryError):
1288	n/a	# Directory has either been removed, turned into a file, or made
1289	n/a	# unreadable.
1290	n/a	contents = []
1291	n/a	# We store two cached versions, to handle runtime changes of the
1292	n/a	# PYTHONCASEOK environment variable.
1293	n/a	if not sys.platform.startswith('win'):
1294	n/a	self._path_cache = set(contents)
1295	n/a	else:
1296	n/a	# Windows users can import modules with case-insensitive file
1297	n/a	# suffixes (for legacy reasons). Make the suffix lowercase here
1298	n/a	# so it's done once instead of for every import. This is safe as
1299	n/a	# the specified suffixes to check against are always specified in a
1300	n/a	# case-sensitive manner.
1301	n/a	lower_suffix_contents = set()
1302	n/a	for item in contents:
1303	n/a	name, dot, suffix = item.partition('.')
1304	n/a	if dot:
1305	n/a	new_name = '{}.{}'.format(name, suffix.lower())
1306	n/a	else:
1307	n/a	new_name = name
1308	n/a	lower_suffix_contents.add(new_name)
1309	n/a	self._path_cache = lower_suffix_contents
1310	n/a	if sys.platform.startswith(_CASE_INSENSITIVE_PLATFORMS):
1311	n/a	self._relaxed_path_cache = {fn.lower() for fn in contents}
1312	n/a
1313	n/a	@classmethod
1314	n/a	def path_hook(cls, *loader_details):
1315	n/a	"""A class method which returns a closure to use on sys.path_hook
1316	n/a	which will return an instance using the specified loaders and the path
1317	n/a	called on the closure.
1318	n/a
1319	n/a	If the path called on the closure is not a directory, ImportError is
1320	n/a	raised.
1321	n/a
1322	n/a	"""
1323	n/a	def path_hook_for_FileFinder(path):
1324	n/a	"""Path hook for importlib.machinery.FileFinder."""
1325	n/a	if not _path_isdir(path):
1326	n/a	raise ImportError('only directories are supported', path=path)
1327	n/a	return cls(path, *loader_details)
1328	n/a
1329	n/a	return path_hook_for_FileFinder
1330	n/a
1331	n/a	def __repr__(self):
1332	n/a	return 'FileFinder({!r})'.format(self.path)
1333	n/a
1334	n/a
1335	n/a	# Import setup ###############################################################
1336	n/a
1337	n/a	def _fix_up_module(ns, name, pathname, cpathname=None):
1338	n/a	# This function is used by PyImport_ExecCodeModuleObject().
1339	n/a	loader = ns.get('__loader__')
1340	n/a	spec = ns.get('__spec__')
1341	n/a	if not loader:
1342	n/a	if spec:
1343	n/a	loader = spec.loader
1344	n/a	elif pathname == cpathname:
1345	n/a	loader = SourcelessFileLoader(name, pathname)
1346	n/a	else:
1347	n/a	loader = SourceFileLoader(name, pathname)
1348	n/a	if not spec:
1349	n/a	spec = spec_from_file_location(name, pathname, loader=loader)
1350	n/a	try:
1351	n/a	ns['__spec__'] = spec
1352	n/a	ns['__loader__'] = loader
1353	n/a	ns['__file__'] = pathname
1354	n/a	ns['__cached__'] = cpathname
1355	n/a	except Exception:
1356	n/a	# Not important enough to report.
1357	n/a	pass
1358	n/a
1359	n/a
1360	n/a	def _get_supported_file_loaders():
1361	n/a	"""Returns a list of file-based module loaders.
1362	n/a
1363	n/a	Each item is a tuple (loader, suffixes).
1364	n/a	"""
1365	n/a	extensions = ExtensionFileLoader, _imp.extension_suffixes()
1366	n/a	source = SourceFileLoader, SOURCE_SUFFIXES
1367	n/a	bytecode = SourcelessFileLoader, BYTECODE_SUFFIXES
1368	n/a	return [extensions, source, bytecode]
1369	n/a
1370	n/a
1371	n/a	def _setup(_bootstrap_module):
1372	n/a	"""Setup the path-based importers for importlib by importing needed
1373	n/a	built-in modules and injecting them into the global namespace.
1374	n/a
1375	n/a	Other components are extracted from the core bootstrap module.
1376	n/a
1377	n/a	"""
1378	n/a	global sys, _imp, _bootstrap
1379	n/a	_bootstrap = _bootstrap_module
1380	n/a	sys = _bootstrap.sys
1381	n/a	_imp = _bootstrap._imp
1382	n/a
1383	n/a	# Directly load built-in modules needed during bootstrap.
1384	n/a	self_module = sys.modules[__name__]
1385	n/a	for builtin_name in ('_io', '_warnings', 'builtins', 'marshal'):
1386	n/a	if builtin_name not in sys.modules:
1387	n/a	builtin_module = _bootstrap._builtin_from_name(builtin_name)
1388	n/a	else:
1389	n/a	builtin_module = sys.modules[builtin_name]
1390	n/a	setattr(self_module, builtin_name, builtin_module)
1391	n/a
1392	n/a	# Directly load the os module (needed during bootstrap).
1393	n/a	os_details = ('posix', ['/']), ('nt', ['\\', '/'])
1394	n/a	for builtin_os, path_separators in os_details:
1395	n/a	# Assumption made in _path_join()
1396	n/a	assert all(len(sep) == 1 for sep in path_separators)
1397	n/a	path_sep = path_separators[0]
1398	n/a	if builtin_os in sys.modules:
1399	n/a	os_module = sys.modules[builtin_os]
1400	n/a	break
1401	n/a	else:
1402	n/a	try:
1403	n/a	os_module = _bootstrap._builtin_from_name(builtin_os)
1404	n/a	break
1405	n/a	except ImportError:
1406	n/a	continue
1407	n/a	else:
1408	n/a	raise ImportError('importlib requires posix or nt')
1409	n/a	setattr(self_module, '_os', os_module)
1410	n/a	setattr(self_module, 'path_sep', path_sep)
1411	n/a	setattr(self_module, 'path_separators', ''.join(path_separators))
1412	n/a
1413	n/a	# Directly load the _thread module (needed during bootstrap).
1414	n/a	try:
1415	n/a	thread_module = _bootstrap._builtin_from_name('_thread')
1416	n/a	except ImportError:
1417	n/a	# Python was built without threads
1418	n/a	thread_module = None
1419	n/a	setattr(self_module, '_thread', thread_module)
1420	n/a
1421	n/a	# Directly load the _weakref module (needed during bootstrap).
1422	n/a	weakref_module = _bootstrap._builtin_from_name('_weakref')
1423	n/a	setattr(self_module, '_weakref', weakref_module)
1424	n/a
1425	n/a	# Directly load the winreg module (needed during bootstrap).
1426	n/a	if builtin_os == 'nt':
1427	n/a	winreg_module = _bootstrap._builtin_from_name('winreg')
1428	n/a	setattr(self_module, '_winreg', winreg_module)
1429	n/a
1430	n/a	# Constants
1431	n/a	setattr(self_module, '_relax_case', _make_relax_case())
1432	n/a	EXTENSION_SUFFIXES.extend(_imp.extension_suffixes())
1433	n/a	if builtin_os == 'nt':
1434	n/a	SOURCE_SUFFIXES.append('.pyw')
1435	n/a	if '_d.pyd' in EXTENSION_SUFFIXES:
1436	n/a	WindowsRegistryFinder.DEBUG_BUILD = True
1437	n/a
1438	n/a
1439	n/a	def _install(_bootstrap_module):
1440	n/a	"""Install the path-based import components."""
1441	n/a	_setup(_bootstrap_module)
1442	n/a	supported_loaders = _get_supported_file_loaders()
1443	n/a	sys.path_hooks.extend([FileFinder.path_hook(*supported_loaders)])
1444	n/a	sys.meta_path.append(PathFinder)