Debian Codegraph @

Lib/importlib/_bootstrap_external.py

raw
1 """Core implementation of path-based import.
2
3 This module is NOT meant to be directly imported! It has been designed such
4 that it can be bootstrapped into Python as the implementation of import. As
5 such it requires the injection of specific modules and attributes in order to
6 work. One should use importlib as the public-facing version of this module.
7
8 """
9 # IMPORTANT: Whenever making changes to this module, be sure to run a top-level
10 # `make regen-importlib` followed by `make` in order to get the frozen version
11 # of the module updated. Not doing so will result in the Makefile to fail for
12 # all others who don't have a ./python around to freeze the module in the early
13 # stages of compilation.
14 #
15
16 # See importlib._setup() for what is injected into the global namespace.
17
18 # When editing this code be aware that code executed at import time CANNOT
19 # reference any injected objects! This includes not only global code but also
20 # anything specified at the class level.
21
22 # Module injected manually by _set_bootstrap_module()
23 _bootstrap = None
24
25 # Import builtin modules
26 import _imp
27 import _io
28 import sys
29 import _warnings
30 import marshal
31
32
33 _MS_WINDOWS = (sys.platform == 'win32')
34 if _MS_WINDOWS:
35 import nt as _os
36 import winreg
37 else:
38 import posix as _os
39
40
41 if _MS_WINDOWS:
42 path_separators = ['\\', '/']
43 else:
44 path_separators = ['/']
45 # Assumption made in _path_join()
46 assert all(len(sep) == 1 for sep in path_separators)
47 path_sep = path_separators[0]
48 path_sep_tuple = tuple(path_separators)
49 path_separators = ''.join(path_separators)
50 _pathseps_with_colon = {f':{s}' for s in path_separators}
51
52
53 # Bootstrap-related code ######################################################
54 _CASE_INSENSITIVE_PLATFORMS_STR_KEY = 'win',
55 _CASE_INSENSITIVE_PLATFORMS_BYTES_KEY = 'cygwin', 'darwin', 'ios', 'tvos', 'watchos'
56 _CASE_INSENSITIVE_PLATFORMS = (_CASE_INSENSITIVE_PLATFORMS_BYTES_KEY
57 + _CASE_INSENSITIVE_PLATFORMS_STR_KEY)
58
59
60 def _make_relax_case():
61 if sys.platform.startswith(_CASE_INSENSITIVE_PLATFORMS):
62 if sys.platform.startswith(_CASE_INSENSITIVE_PLATFORMS_STR_KEY):
63 key = 'PYTHONCASEOK'
64 else:
65 key = b'PYTHONCASEOK'
66
67 def _relax_case():
68 """True if filenames must be checked case-insensitively and ignore environment flags are not set."""
69 return not sys.flags.ignore_environment and key in _os.environ
70 else:
71 def _relax_case():
72 """True if filenames must be checked case-insensitively."""
73 return False
74 return _relax_case
75
76 _relax_case = _make_relax_case()
77
78
79 def _pack_uint32(x):
80 """Convert a 32-bit integer to little-endian."""
81 return (int(x) & 0xFFFFFFFF).to_bytes(4, 'little')
82
83
84 def _unpack_uint64(data):
85 """Convert 8 bytes in little-endian to an integer."""
86 assert len(data) == 8
87 return int.from_bytes(data, 'little')
88
89 def _unpack_uint32(data):
90 """Convert 4 bytes in little-endian to an integer."""
91 assert len(data) == 4
92 return int.from_bytes(data, 'little')
93
94 def _unpack_uint16(data):
95 """Convert 2 bytes in little-endian to an integer."""
96 assert len(data) == 2
97 return int.from_bytes(data, 'little')
98
99
100 if _MS_WINDOWS:
101 def _path_join(*path_parts):
102 """Replacement for os.path.join()."""
103 if not path_parts:
104 return ""
105 if len(path_parts) == 1:
106 return path_parts[0]
107 root = ""
108 path = []
109 for new_root, tail in map(_os._path_splitroot, path_parts):
110 if new_root.startswith(path_sep_tuple) or new_root.endswith(path_sep_tuple):
111 root = new_root.rstrip(path_separators) or root
112 path = [path_sep + tail]
113 elif new_root.endswith(':'):
114 if root.casefold() != new_root.casefold():
115 # Drive relative paths have to be resolved by the OS, so we reset the
116 # tail but do not add a path_sep prefix.
117 root = new_root
118 path = [tail]
119 else:
120 path.append(tail)
121 else:
122 root = new_root or root
123 path.append(tail)
124 path = [p.rstrip(path_separators) for p in path if p]
125 if len(path) == 1 and not path[0]:
126 # Avoid losing the root's trailing separator when joining with nothing
127 return root + path_sep
128 return root + path_sep.join(path)
129
130 else:
131 def _path_join(*path_parts):
132 """Replacement for os.path.join()."""
133 return path_sep.join([part.rstrip(path_separators)
134 for part in path_parts if part])
135
136
137 def _path_split(path):
138 """Replacement for os.path.split()."""
139 i = max(path.rfind(p) for p in path_separators)
140 if i < 0:
141 return '', path
142 return path[:i], path[i + 1:]
143
144
145 def _path_stat(path):
146 """Stat the path.
147
148 Made a separate function to make it easier to override in experiments
149 (e.g. cache stat results).
150
151 """
152 return _os.stat(path)
153
154
155 def _path_is_mode_type(path, mode):
156 """Test whether the path is the specified mode type."""
157 try:
158 stat_info = _path_stat(path)
159 except OSError:
160 return False
161 return (stat_info.st_mode & 0o170000) == mode
162
163
164 def _path_isfile(path):
165 """Replacement for os.path.isfile."""
166 return _path_is_mode_type(path, 0o100000)
167
168
169 def _path_isdir(path):
170 """Replacement for os.path.isdir."""
171 if not path:
172 path = _os.getcwd()
173 return _path_is_mode_type(path, 0o040000)
174
175
176 if _MS_WINDOWS:
177 def _path_isabs(path):
178 """Replacement for os.path.isabs."""
179 if not path:
180 return False
181 root = _os._path_splitroot(path)[0].replace('/', '\\')
182 return len(root) > 1 and (root.startswith('\\\\') or root.endswith('\\'))
183
184 else:
185 def _path_isabs(path):
186 """Replacement for os.path.isabs."""
187 return path.startswith(path_separators)
188
189
190 def _path_abspath(path):
191 """Replacement for os.path.abspath."""
192 if not _path_isabs(path):
193 for sep in path_separators:
194 path = path.removeprefix(f".{sep}")
195 return _path_join(_os.getcwd(), path)
196 else:
197 return path
198
199
200 def _write_atomic(path, data, mode=0o666):
201 """Best-effort function to write data to a path atomically.
202 Be prepared to handle a FileExistsError if concurrent writing of the
203 temporary file is attempted."""
204 # id() is used to generate a pseudo-random filename.
205 path_tmp = f'{path}.{id(path)}'
206 fd = _os.open(path_tmp,
207 _os.O_EXCL | _os.O_CREAT | _os.O_WRONLY, mode & 0o666)
208 try:
209 # We first write data to a temporary file, and then use os.replace() to
210 # perform an atomic rename.
211 with _io.open(fd, 'wb') as file:
212 file.write(data)
213 _os.replace(path_tmp, path)
214 except OSError:
215 try:
216 _os.unlink(path_tmp)
217 except OSError:
218 pass
219 raise
220
221
222 _code_type = type(_write_atomic.__code__)
223
224 MAGIC_NUMBER = _imp.pyc_magic_number_token.to_bytes(4, 'little')
225
226 _PYCACHE = '__pycache__'
227 _OPT = 'opt-'
228
229 SOURCE_SUFFIXES = ['.py']
230 if _MS_WINDOWS:
231 SOURCE_SUFFIXES.append('.pyw')
232
233 EXTENSION_SUFFIXES = _imp.extension_suffixes()
234
235 BYTECODE_SUFFIXES = ['.pyc']
236 # Deprecated.
237 DEBUG_BYTECODE_SUFFIXES = OPTIMIZED_BYTECODE_SUFFIXES = BYTECODE_SUFFIXES
238
239 def cache_from_source(path, debug_override=None, *, optimization=None):
240 """Given the path to a .py file, return the path to its .pyc file.
241
242 The .py file does not need to exist; this simply returns the path to the
243 .pyc file calculated as if the .py file were imported.
244
245 The 'optimization' parameter controls the presumed optimization level of
246 the bytecode file. If 'optimization' is not None, the string representation
247 of the argument is taken and verified to be alphanumeric (else ValueError
248 is raised).
249
250 The debug_override parameter is deprecated. If debug_override is not None,
251 a True value is the same as setting 'optimization' to the empty string
252 while a False value is equivalent to setting 'optimization' to '1'.
253
254 If sys.implementation.cache_tag is None then NotImplementedError is raised.
255
256 """
257 if debug_override is not None:
258 _warnings.warn('the debug_override parameter is deprecated; use '
259 "'optimization' instead", DeprecationWarning)
260 if optimization is not None:
261 message = 'debug_override or optimization must be set to None'
262 raise TypeError(message)
263 optimization = '' if debug_override else 1
264 path = _os.fspath(path)
265 head, tail = _path_split(path)
266 base, sep, rest = tail.rpartition('.')
267 tag = sys.implementation.cache_tag
268 if tag is None:
269 raise NotImplementedError('sys.implementation.cache_tag is None')
270 almost_filename = ''.join([(base if base else rest), sep, tag])
271 if optimization is None:
272 if sys.flags.optimize == 0:
273 optimization = ''
274 else:
275 optimization = sys.flags.optimize
276 optimization = str(optimization)
277 if optimization != '':
278 if not optimization.isalnum():
279 raise ValueError(f'{optimization!r} is not alphanumeric')
280 almost_filename = f'{almost_filename}.{_OPT}{optimization}'
281 filename = almost_filename + BYTECODE_SUFFIXES[0]
282 if sys.pycache_prefix is not None:
283 # We need an absolute path to the py file to avoid the possibility of
284 # collisions within sys.pycache_prefix, if someone has two different
285 # `foo/bar.py` on their system and they import both of them using the
286 # same sys.pycache_prefix. Let's say sys.pycache_prefix is
287 # `C:\Bytecode`; the idea here is that if we get `Foo\Bar`, we first
288 # make it absolute (`C:\Somewhere\Foo\Bar`), then make it root-relative
289 # (`Somewhere\Foo\Bar`), so we end up placing the bytecode file in an
290 # unambiguous `C:\Bytecode\Somewhere\Foo\Bar\`.
291 head = _path_abspath(head)
292
293 # Strip initial drive from a Windows path. We know we have an absolute
294 # path here, so the second part of the check rules out a POSIX path that
295 # happens to contain a colon at the second character.
296 # Slicing avoids issues with an empty (or short) `head`.
297 if head[1:2] == ':' and head[0:1] not in path_separators:
298 head = head[2:]
299
300 # Strip initial path separator from `head` to complete the conversion
301 # back to a root-relative path before joining.
302 return _path_join(
303 sys.pycache_prefix,
304 head.lstrip(path_separators),
305 filename,
306 )
307 return _path_join(head, _PYCACHE, filename)
308
309
310 def source_from_cache(path):
311 """Given the path to a .pyc. file, return the path to its .py file.
312
313 The .pyc file does not need to exist; this simply returns the path to
314 the .py file calculated to correspond to the .pyc file. If path does
315 not conform to PEP 3147/488 format, ValueError will be raised. If
316 sys.implementation.cache_tag is None then NotImplementedError is raised.
317
318 """
319 if sys.implementation.cache_tag is None:
320 raise NotImplementedError('sys.implementation.cache_tag is None')
321 path = _os.fspath(path)
322 head, pycache_filename = _path_split(path)
323 found_in_pycache_prefix = False
324 if sys.pycache_prefix is not None:
325 stripped_path = sys.pycache_prefix.rstrip(path_separators)
326 if head.startswith(stripped_path + path_sep):
327 head = head[len(stripped_path):]
328 found_in_pycache_prefix = True
329 if not found_in_pycache_prefix:
330 head, pycache = _path_split(head)
331 if pycache != _PYCACHE:
332 raise ValueError(f'{_PYCACHE} not bottom-level directory in '
333 f'{path!r}')
334 dot_count = pycache_filename.count('.')
335 if dot_count not in {2, 3}:
336 raise ValueError(f'expected only 2 or 3 dots in {pycache_filename!r}')
337 elif dot_count == 3:
338 optimization = pycache_filename.rsplit('.', 2)[-2]
339 if not optimization.startswith(_OPT):
340 raise ValueError("optimization portion of filename does not start "
341 f"with {_OPT!r}")
342 opt_level = optimization[len(_OPT):]
343 if not opt_level.isalnum():
344 raise ValueError(f"optimization level {optimization!r} is not an "
345 "alphanumeric value")
346 base_filename = pycache_filename.partition('.')[0]
347 return _path_join(head, base_filename + SOURCE_SUFFIXES[0])
348
349
350 def _get_sourcefile(bytecode_path):
351 """Convert a bytecode file path to a source path (if possible).
352
353 This function exists purely for backwards-compatibility for
354 PyImport_ExecCodeModuleWithFilenames() in the C API.
355
356 """
357 if len(bytecode_path) == 0:
358 return None
359 rest, _, extension = bytecode_path.rpartition('.')
360 if not rest or extension.lower()[-3:-1] != 'py':
361 return bytecode_path
362 try:
363 source_path = source_from_cache(bytecode_path)
364 except (NotImplementedError, ValueError):
365 source_path = bytecode_path[:-1]
366 return source_path if _path_isfile(source_path) else bytecode_path
367
368
369 def _get_cached(filename):
370 if filename.endswith(tuple(SOURCE_SUFFIXES)):
371 try:
372 return cache_from_source(filename)
373 except NotImplementedError:
374 pass
375 elif filename.endswith(tuple(BYTECODE_SUFFIXES)):
376 return filename
377 else:
378 return None
379
380
381 def _calc_mode(path):
382 """Calculate the mode permissions for a bytecode file."""
383 try:
384 mode = _path_stat(path).st_mode
385 except OSError:
386 mode = 0o666
387 # We always ensure write access so we can update cached files
388 # later even when the source files are read-only on Windows (#6074)
389 mode |= 0o200
390 return mode
391
392
393 def _check_name(method):
394 """Decorator to verify that the module being requested matches the one the
395 loader can handle.
396
397 The first argument (self) must define _name which the second argument is
398 compared against. If the comparison fails then ImportError is raised.
399
400 """
401 def _check_name_wrapper(self, name=None, *args, **kwargs):
402 if name is None:
403 name = self.name
404 elif self.name != name:
405 raise ImportError('loader for %s cannot handle %s' %
406 (self.name, name), name=name)
407 return method(self, name, *args, **kwargs)
408
409 # FIXME: @_check_name is used to define class methods before the
410 # _bootstrap module is set by _set_bootstrap_module().
411 if _bootstrap is not None:
412 _wrap = _bootstrap._wrap
413 else:
414 def _wrap(new, old):
415 for replace in ['__module__', '__name__', '__qualname__', '__doc__']:
416 if hasattr(old, replace):
417 setattr(new, replace, getattr(old, replace))
418 new.__dict__.update(old.__dict__)
419
420 _wrap(_check_name_wrapper, method)
421 return _check_name_wrapper
422
423
424 def _classify_pyc(data, name, exc_details):
425 """Perform basic validity checking of a pyc header and return the flags field,
426 which determines how the pyc should be further validated against the source.
427
428 *data* is the contents of the pyc file. (Only the first 16 bytes are
429 required, though.)
430
431 *name* is the name of the module being imported. It is used for logging.
432
433 *exc_details* is a dictionary passed to ImportError if it raised for
434 improved debugging.
435
436 ImportError is raised when the magic number is incorrect or when the flags
437 field is invalid. EOFError is raised when the data is found to be truncated.
438
439 """
440 magic = data[:4]
441 if magic != MAGIC_NUMBER:
442 message = f'bad magic number in {name!r}: {magic!r}'
443 _bootstrap._verbose_message('{}', message)
444 raise ImportError(message, **exc_details)
445 if len(data) < 16:
446 message = f'reached EOF while reading pyc header of {name!r}'
447 _bootstrap._verbose_message('{}', message)
448 raise EOFError(message)
449 flags = _unpack_uint32(data[4:8])
450 # Only the first two flags are defined.
451 if flags & ~0b11:
452 message = f'invalid flags {flags!r} in {name!r}'
453 raise ImportError(message, **exc_details)
454 return flags
455
456
457 def _validate_timestamp_pyc(data, source_mtime, source_size, name,
458 exc_details):
459 """Validate a pyc against the source last-modified time.
460
461 *data* is the contents of the pyc file. (Only the first 16 bytes are
462 required.)
463
464 *source_mtime* is the last modified timestamp of the source file.
465
466 *source_size* is None or the size of the source file in bytes.
467
468 *name* is the name of the module being imported. It is used for logging.
469
470 *exc_details* is a dictionary passed to ImportError if it raised for
471 improved debugging.
472
473 An ImportError is raised if the bytecode is stale.
474
475 """
476 if _unpack_uint32(data[8:12]) != (source_mtime & 0xFFFFFFFF):
477 message = f'bytecode is stale for {name!r}'
478 _bootstrap._verbose_message('{}', message)
479 raise ImportError(message, **exc_details)
480 if (source_size is not None and
481 _unpack_uint32(data[12:16]) != (source_size & 0xFFFFFFFF)):
482 raise ImportError(f'bytecode is stale for {name!r}', **exc_details)
483
484
485 def _validate_hash_pyc(data, source_hash, name, exc_details):
486 """Validate a hash-based pyc by checking the real source hash against the one in
487 the pyc header.
488
489 *data* is the contents of the pyc file. (Only the first 16 bytes are
490 required.)
491
492 *source_hash* is the importlib.util.source_hash() of the source file.
493
494 *name* is the name of the module being imported. It is used for logging.
495
496 *exc_details* is a dictionary passed to ImportError if it raised for
497 improved debugging.
498
499 An ImportError is raised if the bytecode is stale.
500
501 """
502 if data[8:16] != source_hash:
503 raise ImportError(
504 f'hash in bytecode doesn\'t match hash of source {name!r}',
505 **exc_details,
506 )
507
508
509 def _compile_bytecode(data, name=None, bytecode_path=None, source_path=None):
510 """Compile bytecode as found in a pyc."""
511 code = marshal.loads(data)
512 if isinstance(code, _code_type):
513 _bootstrap._verbose_message('code object from {!r}', bytecode_path)
514 if source_path is not None:
515 _imp._fix_co_filename(code, source_path)
516 return code
517 else:
518 raise ImportError(f'Non-code object in {bytecode_path!r}',
519 name=name, path=bytecode_path)
520
521
522 def _code_to_timestamp_pyc(code, mtime=0, source_size=0):
523 "Produce the data for a timestamp-based pyc."
524 data = bytearray(MAGIC_NUMBER)
525 data.extend(_pack_uint32(0))
526 data.extend(_pack_uint32(mtime))
527 data.extend(_pack_uint32(source_size))
528 data.extend(marshal.dumps(code))
529 return data
530
531
532 def _code_to_hash_pyc(code, source_hash, checked=True):
533 "Produce the data for a hash-based pyc."
534 data = bytearray(MAGIC_NUMBER)
535 flags = 0b1 | checked << 1
536 data.extend(_pack_uint32(flags))
537 assert len(source_hash) == 8
538 data.extend(source_hash)
539 data.extend(marshal.dumps(code))
540 return data
541
542
543 def decode_source(source_bytes):
544 """Decode bytes representing source code and return the string.
545
546 Universal newline support is used in the decoding.
547 """
548 import tokenize # To avoid bootstrap issues.
549 source_bytes_readline = _io.BytesIO(source_bytes).readline
550 encoding = tokenize.detect_encoding(source_bytes_readline)
551 newline_decoder = _io.IncrementalNewlineDecoder(None, True)
552 return newline_decoder.decode(source_bytes.decode(encoding[0]))
553
554
555 # Module specifications #######################################################
556
557 _POPULATE = object()
558
559
560 def spec_from_file_location(name, location=None, *, loader=None,
561 submodule_search_locations=_POPULATE):
562 """Return a module spec based on a file location.
563
564 To indicate that the module is a package, set
565 submodule_search_locations to a list of directory paths. An
566 empty list is sufficient, though its not otherwise useful to the
567 import system.
568
569 The loader must take a spec as its only __init__() arg.
570
571 """
572 if location is None:
573 # The caller may simply want a partially populated location-
574 # oriented spec. So we set the location to a bogus value and
575 # fill in as much as we can.
576 location = '<unknown>'
577 if hasattr(loader, 'get_filename'):
578 # ExecutionLoader
579 try:
580 location = loader.get_filename(name)
581 except ImportError:
582 pass
583 else:
584 location = _os.fspath(location)
585 try:
586 location = _path_abspath(location)
587 except OSError:
588 pass
589
590 # If the location is on the filesystem, but doesn't actually exist,
591 # we could return None here, indicating that the location is not
592 # valid. However, we don't have a good way of testing since an
593 # indirect location (e.g. a zip file or URL) will look like a
594 # non-existent file relative to the filesystem.
595
596 spec = _bootstrap.ModuleSpec(name, loader, origin=location)
597 spec._set_fileattr = True
598
599 # Pick a loader if one wasn't provided.
600 if loader is None:
601 for loader_class, suffixes in _get_supported_file_loaders():
602 if location.endswith(tuple(suffixes)):
603 loader = loader_class(name, location)
604 spec.loader = loader
605 break
606 else:
607 return None
608
609 # Set submodule_search_paths appropriately.
610 if submodule_search_locations is _POPULATE:
611 # Check the loader.
612 if hasattr(loader, 'is_package'):
613 try:
614 is_package = loader.is_package(name)
615 except ImportError:
616 pass
617 else:
618 if is_package:
619 spec.submodule_search_locations = []
620 else:
621 spec.submodule_search_locations = submodule_search_locations
622 if spec.submodule_search_locations == []:
623 if location:
624 dirname = _path_split(location)[0]
625 spec.submodule_search_locations.append(dirname)
626
627 return spec
628
629
630 def _bless_my_loader(module_globals):
631 """Helper function for _warnings.c
632
633 See GH#97850 for details.
634 """
635 # 2022-10-06(warsaw): For now, this helper is only used in _warnings.c and
636 # that use case only has the module globals. This function could be
637 # extended to accept either that or a module object. However, in the
638 # latter case, it would be better to raise certain exceptions when looking
639 # at a module, which should have either a __loader__ or __spec__.loader.
640 # For backward compatibility, it is possible that we'll get an empty
641 # dictionary for the module globals, and that cannot raise an exception.
642 if not isinstance(module_globals, dict):
643 return None
644
645 missing = object()
646 loader = module_globals.get('__loader__', None)
647 spec = module_globals.get('__spec__', missing)
648
649 if loader is None:
650 if spec is missing:
651 # If working with a module:
652 # raise AttributeError('Module globals is missing a __spec__')
653 return None
654 elif spec is None:
655 raise ValueError('Module globals is missing a __spec__.loader')
656
657 spec_loader = getattr(spec, 'loader', missing)
658
659 if spec_loader in (missing, None):
660 if loader is None:
661 exc = AttributeError if spec_loader is missing else ValueError
662 raise exc('Module globals is missing a __spec__.loader')
663 _warnings.warn(
664 'Module globals is missing a __spec__.loader',
665 DeprecationWarning)
666 spec_loader = loader
667
668 assert spec_loader is not None
669 if loader is not None and loader != spec_loader:
670 _warnings.warn(
671 'Module globals; __loader__ != __spec__.loader',
672 DeprecationWarning)
673 return loader
674
675 return spec_loader
676
677
678 # Loaders #####################################################################
679
680 class WindowsRegistryFinder:
681
682 """Meta path finder for modules declared in the Windows registry."""
683
684 REGISTRY_KEY = (
685 'Software\\Python\\PythonCore\\{sys_version}'
686 '\\Modules\\{fullname}')
687 REGISTRY_KEY_DEBUG = (
688 'Software\\Python\\PythonCore\\{sys_version}'
689 '\\Modules\\{fullname}\\Debug')
690 DEBUG_BUILD = (_MS_WINDOWS and '_d.pyd' in EXTENSION_SUFFIXES)
691
692 @staticmethod
693 def _open_registry(key):
694 try:
695 return winreg.OpenKey(winreg.HKEY_CURRENT_USER, key)
696 except OSError:
697 return winreg.OpenKey(winreg.HKEY_LOCAL_MACHINE, key)
698
699 @classmethod
700 def _search_registry(cls, fullname):
701 if cls.DEBUG_BUILD:
702 registry_key = cls.REGISTRY_KEY_DEBUG
703 else:
704 registry_key = cls.REGISTRY_KEY
705 key = registry_key.format(fullname=fullname,
706 sys_version='%d.%d' % sys.version_info[:2])
707 try:
708 with cls._open_registry(key) as hkey:
709 filepath = winreg.QueryValue(hkey, '')
710 except OSError:
711 return None
712 return filepath
713
714 @classmethod
715 def find_spec(cls, fullname, path=None, target=None):
716 _warnings.warn('importlib.machinery.WindowsRegistryFinder is '
717 'deprecated; use site configuration instead. '
718 'Future versions of Python may not enable this '
719 'finder by default.',
720 DeprecationWarning, stacklevel=2)
721
722 filepath = cls._search_registry(fullname)
723 if filepath is None:
724 return None
725 try:
726 _path_stat(filepath)
727 except OSError:
728 return None
729 for loader, suffixes in _get_supported_file_loaders():
730 if filepath.endswith(tuple(suffixes)):
731 spec = _bootstrap.spec_from_loader(fullname,
732 loader(fullname, filepath),
733 origin=filepath)
734 return spec
735
736
737 class _LoaderBasics:
738
739 """Base class of common code needed by both SourceLoader and
740 SourcelessFileLoader."""
741
742 def is_package(self, fullname):
743 """Concrete implementation of InspectLoader.is_package by checking if
744 the path returned by get_filename has a filename of '__init__.py'."""
745 filename = _path_split(self.get_filename(fullname))[1]
746 filename_base = filename.rsplit('.', 1)[0]
747 tail_name = fullname.rpartition('.')[2]
748 return filename_base == '__init__' and tail_name != '__init__'
749
750 def create_module(self, spec):
751 """Use default semantics for module creation."""
752
753 def exec_module(self, module):
754 """Execute the module."""
755 code = self.get_code(module.__name__)
756 if code is None:
757 raise ImportError(f'cannot load module {module.__name__!r} when '
758 'get_code() returns None')
759 _bootstrap._call_with_frames_removed(exec, code, module.__dict__)
760
761 def load_module(self, fullname):
762 """This method is deprecated."""
763 # Warning implemented in _load_module_shim().
764 return _bootstrap._load_module_shim(self, fullname)
765
766
767 class SourceLoader(_LoaderBasics):
768
769 def path_mtime(self, path):
770 """Optional method that returns the modification time (an int) for the
771 specified path (a str).
772
773 Raises OSError when the path cannot be handled.
774 """
775 raise OSError
776
777 def path_stats(self, path):
778 """Optional method returning a metadata dict for the specified
779 path (a str).
780
781 Possible keys:
782 - 'mtime' (mandatory) is the numeric timestamp of last source
783 code modification;
784 - 'size' (optional) is the size in bytes of the source code.
785
786 Implementing this method allows the loader to read bytecode files.
787 Raises OSError when the path cannot be handled.
788 """
789 return {'mtime': self.path_mtime(path)}
790
791 def _cache_bytecode(self, source_path, cache_path, data):
792 """Optional method which writes data (bytes) to a file path (a str).
793
794 Implementing this method allows for the writing of bytecode files.
795
796 The source path is needed in order to correctly transfer permissions
797 """
798 # For backwards compatibility, we delegate to set_data()
799 return self.set_data(cache_path, data)
800
801 def set_data(self, path, data):
802 """Optional method which writes data (bytes) to a file path (a str).
803
804 Implementing this method allows for the writing of bytecode files.
805 """
806
807
808 def get_source(self, fullname):
809 """Concrete implementation of InspectLoader.get_source."""
810 path = self.get_filename(fullname)
811 try:
812 source_bytes = self.get_data(path)
813 except OSError as exc:
814 raise ImportError('source not available through get_data()',
815 name=fullname) from exc
816 return decode_source(source_bytes)
817
818 def source_to_code(self, data, path, *, _optimize=-1):
819 """Return the code object compiled from source.
820
821 The 'data' argument can be any object type that compile() supports.
822 """
823 return _bootstrap._call_with_frames_removed(compile, data, path, 'exec',
824 dont_inherit=True, optimize=_optimize)
825
826 def get_code(self, fullname):
827 """Concrete implementation of InspectLoader.get_code.
828
829 Reading of bytecode requires path_stats to be implemented. To write
830 bytecode, set_data must also be implemented.
831
832 """
833 source_path = self.get_filename(fullname)
834 source_mtime = None
835 source_bytes = None
836 source_hash = None
837 hash_based = False
838 check_source = True
839 try:
840 bytecode_path = cache_from_source(source_path)
841 except NotImplementedError:
842 bytecode_path = None
843 else:
844 try:
845 st = self.path_stats(source_path)
846 except OSError:
847 pass
848 else:
849 source_mtime = int(st['mtime'])
850 try:
851 data = self.get_data(bytecode_path)
852 except OSError:
853 pass
854 else:
855 exc_details = {
856 'name': fullname,
857 'path': bytecode_path,
858 }
859 try:
860 flags = _classify_pyc(data, fullname, exc_details)
861 bytes_data = memoryview(data)[16:]
862 hash_based = flags & 0b1 != 0
863 if hash_based:
864 check_source = flags & 0b10 != 0
865 if (_imp.check_hash_based_pycs != 'never' and
866 (check_source or
867 _imp.check_hash_based_pycs == 'always')):
868 source_bytes = self.get_data(source_path)
869 source_hash = _imp.source_hash(
870 _imp.pyc_magic_number_token,
871 source_bytes,
872 )
873 _validate_hash_pyc(data, source_hash, fullname,
874 exc_details)
875 else:
876 _validate_timestamp_pyc(
877 data,
878 source_mtime,
879 st['size'],
880 fullname,
881 exc_details,
882 )
883 except (ImportError, EOFError):
884 pass
885 else:
886 _bootstrap._verbose_message('{} matches {}', bytecode_path,
887 source_path)
888 return _compile_bytecode(bytes_data, name=fullname,
889 bytecode_path=bytecode_path,
890 source_path=source_path)
891 if source_bytes is None:
892 source_bytes = self.get_data(source_path)
893 code_object = self.source_to_code(source_bytes, source_path)
894 _bootstrap._verbose_message('code object from {}', source_path)
895 if (not sys.dont_write_bytecode and bytecode_path is not None and
896 source_mtime is not None):
897 if hash_based:
898 if source_hash is None:
899 source_hash = _imp.source_hash(_imp.pyc_magic_number_token,
900 source_bytes)
901 data = _code_to_hash_pyc(code_object, source_hash, check_source)
902 else:
903 data = _code_to_timestamp_pyc(code_object, source_mtime,
904 len(source_bytes))
905 try:
906 self._cache_bytecode(source_path, bytecode_path, data)
907 except NotImplementedError:
908 pass
909 return code_object
910
911
912 class FileLoader:
913
914 """Base file loader class which implements the loader protocol methods that
915 require file system usage."""
916
917 def __init__(self, fullname, path):
918 """Cache the module name and the path to the file found by the
919 finder."""
920 self.name = fullname
921 self.path = path
922
923 def __eq__(self, other):
924 return (self.__class__ == other.__class__ and
925 self.__dict__ == other.__dict__)
926
927 def __hash__(self):
928 return hash(self.name) ^ hash(self.path)
929
930 @_check_name
931 def load_module(self, fullname):
932 """Load a module from a file.
933
934 This method is deprecated. Use exec_module() instead.
935
936 """
937 # The only reason for this method is for the name check.
938 # Issue #14857: Avoid the zero-argument form of super so the implementation
939 # of that form can be updated without breaking the frozen module.
940 return super(FileLoader, self).load_module(fullname)
941
942 @_check_name
943 def get_filename(self, fullname):
944 """Return the path to the source file as found by the finder."""
945 return self.path
946
947 def get_data(self, path):
948 """Return the data from path as raw bytes."""
949 if isinstance(self, (SourceLoader, SourcelessFileLoader, ExtensionFileLoader)):
950 with _io.open_code(str(path)) as file:
951 return file.read()
952 else:
953 with _io.FileIO(path, 'r') as file:
954 return file.read()
955
956 @_check_name
957 def get_resource_reader(self, module):
958 from importlib.readers import FileReader
959 return FileReader(self)
960
961
962 class SourceFileLoader(FileLoader, SourceLoader):
963
964 """Concrete implementation of SourceLoader using the file system."""
965
966 def path_stats(self, path):
967 """Return the metadata for the path."""
968 st = _path_stat(path)
969 return {'mtime': st.st_mtime, 'size': st.st_size}
970
971 def _cache_bytecode(self, source_path, bytecode_path, data):
972 # Adapt between the two APIs
973 mode = _calc_mode(source_path)
974 return self.set_data(bytecode_path, data, _mode=mode)
975
976 def set_data(self, path, data, *, _mode=0o666):
977 """Write bytes data to a file."""
978 parent, filename = _path_split(path)
979 path_parts = []
980 # Figure out what directories are missing.
981 while parent and not _path_isdir(parent):
982 parent, part = _path_split(parent)
983 path_parts.append(part)
984 # Create needed directories.
985 for part in reversed(path_parts):
986 parent = _path_join(parent, part)
987 try:
988 _os.mkdir(parent)
989 except FileExistsError:
990 # Probably another Python process already created the dir.
991 continue
992 except OSError as exc:
993 # Could be a permission error, read-only filesystem: just forget
994 # about writing the data.
995 _bootstrap._verbose_message('could not create {!r}: {!r}',
996 parent, exc)
997 return
998 try:
999 _write_atomic(path, data, _mode)
1000 _bootstrap._verbose_message('created {!r}', path)
1001 except OSError as exc:
1002 # Same as above: just don't write the bytecode.
1003 _bootstrap._verbose_message('could not create {!r}: {!r}', path,
1004 exc)
1005
1006
1007 class SourcelessFileLoader(FileLoader, _LoaderBasics):
1008
1009 """Loader which handles sourceless file imports."""
1010
1011 def get_code(self, fullname):
1012 path = self.get_filename(fullname)
1013 data = self.get_data(path)
1014 # Call _classify_pyc to do basic validation of the pyc but ignore the
1015 # result. There's no source to check against.
1016 exc_details = {
1017 'name': fullname,
1018 'path': path,
1019 }
1020 _classify_pyc(data, fullname, exc_details)
1021 return _compile_bytecode(
1022 memoryview(data)[16:],
1023 name=fullname,
1024 bytecode_path=path,
1025 )
1026
1027 def get_source(self, fullname):
1028 """Return None as there is no source code."""
1029 return None
1030
1031
1032 class ExtensionFileLoader(FileLoader, _LoaderBasics):
1033
1034 """Loader for extension modules.
1035
1036 The constructor is designed to work with FileFinder.
1037
1038 """
1039
1040 def __init__(self, name, path):
1041 self.name = name
1042 self.path = path
1043
1044 def __eq__(self, other):
1045 return (self.__class__ == other.__class__ and
1046 self.__dict__ == other.__dict__)
1047
1048 def __hash__(self):
1049 return hash(self.name) ^ hash(self.path)
1050
1051 def create_module(self, spec):
1052 """Create an uninitialized extension module"""
1053 module = _bootstrap._call_with_frames_removed(
1054 _imp.create_dynamic, spec)
1055 _bootstrap._verbose_message('extension module {!r} loaded from {!r}',
1056 spec.name, self.path)
1057 return module
1058
1059 def exec_module(self, module):
1060 """Initialize an extension module"""
1061 _bootstrap._call_with_frames_removed(_imp.exec_dynamic, module)
1062 _bootstrap._verbose_message('extension module {!r} executed from {!r}',
1063 self.name, self.path)
1064
1065 def is_package(self, fullname):
1066 """Return True if the extension module is a package."""
1067 file_name = _path_split(self.path)[1]
1068 return any(file_name == '__init__' + suffix
1069 for suffix in EXTENSION_SUFFIXES)
1070
1071 def get_code(self, fullname):
1072 """Return None as an extension module cannot create a code object."""
1073 return None
1074
1075 def get_source(self, fullname):
1076 """Return None as extension modules have no source code."""
1077 return None
1078
1079 @_check_name
1080 def get_filename(self, fullname):
1081 """Return the path to the source file as found by the finder."""
1082 return self.path
1083
1084
1085 class _NamespacePath:
1086 """Represents a namespace package's path. It uses the module name
1087 to find its parent module, and from there it looks up the parent's
1088 __path__. When this changes, the module's own path is recomputed,
1089 using path_finder. For top-level modules, the parent module's path
1090 is sys.path."""
1091
1092 # When invalidate_caches() is called, this epoch is incremented
1093 # https://bugs.python.org/issue45703
1094 _epoch = 0
1095
1096 def __init__(self, name, path, path_finder):
1097 self._name = name
1098 self._path = path
1099 self._last_parent_path = tuple(self._get_parent_path())
1100 self._last_epoch = self._epoch
1101 self._path_finder = path_finder
1102
1103 def _find_parent_path_names(self):
1104 """Returns a tuple of (parent-module-name, parent-path-attr-name)"""
1105 parent, dot, me = self._name.rpartition('.')
1106 if dot == '':
1107 # This is a top-level module. sys.path contains the parent path.
1108 return 'sys', 'path'
1109 # Not a top-level module. parent-module.__path__ contains the
1110 # parent path.
1111 return parent, '__path__'
1112
1113 def _get_parent_path(self):
1114 parent_module_name, path_attr_name = self._find_parent_path_names()
1115 return getattr(sys.modules[parent_module_name], path_attr_name)
1116
1117 def _recalculate(self):
1118 # If the parent's path has changed, recalculate _path
1119 parent_path = tuple(self._get_parent_path()) # Make a copy
1120 if parent_path != self._last_parent_path or self._epoch != self._last_epoch:
1121 spec = self._path_finder(self._name, parent_path)
1122 # Note that no changes are made if a loader is returned, but we
1123 # do remember the new parent path
1124 if spec is not None and spec.loader is None:
1125 if spec.submodule_search_locations:
1126 self._path = spec.submodule_search_locations
1127 self._last_parent_path = parent_path # Save the copy
1128 self._last_epoch = self._epoch
1129 return self._path
1130
1131 def __iter__(self):
1132 return iter(self._recalculate())
1133
1134 def __getitem__(self, index):
1135 return self._recalculate()[index]
1136
1137 def __setitem__(self, index, path):
1138 self._path[index] = path
1139
1140 def __len__(self):
1141 return len(self._recalculate())
1142
1143 def __repr__(self):
1144 return f'_NamespacePath({self._path!r})'
1145
1146 def __contains__(self, item):
1147 return item in self._recalculate()
1148
1149 def append(self, item):
1150 self._path.append(item)
1151
1152
1153 # This class is actually exposed publicly in a namespace package's __loader__
1154 # attribute, so it should be available through a non-private name.
1155 # https://github.com/python/cpython/issues/92054
1156 class NamespaceLoader:
1157 def __init__(self, name, path, path_finder):
1158 self._path = _NamespacePath(name, path, path_finder)
1159
1160 def is_package(self, fullname):
1161 return True
1162
1163 def get_source(self, fullname):
1164 return ''
1165
1166 def get_code(self, fullname):
1167 return compile('', '<string>', 'exec', dont_inherit=True)
1168
1169 def create_module(self, spec):
1170 """Use default semantics for module creation."""
1171
1172 def exec_module(self, module):
1173 pass
1174
1175 def load_module(self, fullname):
1176 """Load a namespace module.
1177
1178 This method is deprecated. Use exec_module() instead.
1179
1180 """
1181 # The import system never calls this method.
1182 _bootstrap._verbose_message('namespace module loaded with path {!r}',
1183 self._path)
1184 # Warning implemented in _load_module_shim().
1185 return _bootstrap._load_module_shim(self, fullname)
1186
1187 def get_resource_reader(self, module):
1188 from importlib.readers import NamespaceReader
1189 return NamespaceReader(self._path)
1190
1191
1192 # We use this exclusively in module_from_spec() for backward-compatibility.
1193 _NamespaceLoader = NamespaceLoader
1194
1195
1196 # Finders #####################################################################
1197
1198 class PathFinder:
1199
1200 """Meta path finder for sys.path and package __path__ attributes."""
1201
1202 @staticmethod
1203 def invalidate_caches():
1204 """Call the invalidate_caches() method on all path entry finders
1205 stored in sys.path_importer_cache (where implemented)."""
1206 for name, finder in list(sys.path_importer_cache.items()):
1207 # Drop entry if finder name is a relative path. The current
1208 # working directory may have changed.
1209 if finder is None or not _path_isabs(name):
1210 del sys.path_importer_cache[name]
1211 elif hasattr(finder, 'invalidate_caches'):
1212 finder.invalidate_caches()
1213 # Also invalidate the caches of _NamespacePaths
1214 # https://bugs.python.org/issue45703
1215 _NamespacePath._epoch += 1
1216
1217 from importlib.metadata import MetadataPathFinder
1218 MetadataPathFinder.invalidate_caches()
1219
1220 @staticmethod
1221 def _path_hooks(path):
1222 """Search sys.path_hooks for a finder for 'path'."""
1223 if sys.path_hooks is not None and not sys.path_hooks:
1224 _warnings.warn('sys.path_hooks is empty', ImportWarning)
1225 for hook in sys.path_hooks:
1226 try:
1227 return hook(path)
1228 except ImportError:
1229 continue
1230 else:
1231 return None
1232
1233 @classmethod
1234 def _path_importer_cache(cls, path):
1235 """Get the finder for the path entry from sys.path_importer_cache.
1236
1237 If the path entry is not in the cache, find the appropriate finder
1238 and cache it. If no finder is available, store None.
1239
1240 """
1241 if path == '':
1242 try:
1243 path = _os.getcwd()
1244 except (FileNotFoundError, PermissionError):
1245 # Don't cache the failure as the cwd can easily change to
1246 # a valid directory later on.
1247 return None
1248 try:
1249 finder = sys.path_importer_cache[path]
1250 except KeyError:
1251 finder = cls._path_hooks(path)
1252 sys.path_importer_cache[path] = finder
1253 return finder
1254
1255 @classmethod
1256 def _get_spec(cls, fullname, path, target=None):
1257 """Find the loader or namespace_path for this module/package name."""
1258 # If this ends up being a namespace package, namespace_path is
1259 # the list of paths that will become its __path__
1260 namespace_path = []
1261 for entry in path:
1262 if not isinstance(entry, str):
1263 continue
1264 finder = cls._path_importer_cache(entry)
1265 if finder is not None:
1266 spec = finder.find_spec(fullname, target)
1267 if spec is None:
1268 continue
1269 if spec.loader is not None:
1270 return spec
1271 portions = spec.submodule_search_locations
1272 if portions is None:
1273 raise ImportError('spec missing loader')
1274 # This is possibly part of a namespace package.
1275 # Remember these path entries (if any) for when we
1276 # create a namespace package, and continue iterating
1277 # on path.
1278 namespace_path.extend(portions)
1279 else:
1280 spec = _bootstrap.ModuleSpec(fullname, None)
1281 spec.submodule_search_locations = namespace_path
1282 return spec
1283
1284 @classmethod
1285 def find_spec(cls, fullname, path=None, target=None):
1286 """Try to find a spec for 'fullname' on sys.path or 'path'.
1287
1288 The search is based on sys.path_hooks and sys.path_importer_cache.
1289 """
1290 if path is None:
1291 path = sys.path
1292 spec = cls._get_spec(fullname, path, target)
1293 if spec is None:
1294 return None
1295 elif spec.loader is None:
1296 namespace_path = spec.submodule_search_locations
1297 if namespace_path:
1298 # We found at least one namespace path. Return a spec which
1299 # can create the namespace package.
1300 spec.origin = None
1301 spec.submodule_search_locations = _NamespacePath(fullname, namespace_path, cls._get_spec)
1302 return spec
1303 else:
1304 return None
1305 else:
1306 return spec
1307
1308 @staticmethod
1309 def find_distributions(*args, **kwargs):
1310 """
1311 Find distributions.
1312
1313 Return an iterable of all Distribution instances capable of
1314 loading the metadata for packages matching ``context.name``
1315 (or all names if ``None`` indicated) along the paths in the list
1316 of directories ``context.path``.
1317 """
1318 from importlib.metadata import MetadataPathFinder
1319 return MetadataPathFinder.find_distributions(*args, **kwargs)
1320
1321
1322 class FileFinder:
1323
1324 """File-based finder.
1325
1326 Interactions with the file system are cached for performance, being
1327 refreshed when the directory the finder is handling has been modified.
1328
1329 """
1330
1331 def __init__(self, path, *loader_details):
1332 """Initialize with the path to search on and a variable number of
1333 2-tuples containing the loader and the file suffixes the loader
1334 recognizes."""
1335 loaders = []
1336 for loader, suffixes in loader_details:
1337 loaders.extend((suffix, loader) for suffix in suffixes)
1338 self._loaders = loaders
1339 # Base (directory) path
1340 if not path or path == '.':
1341 self.path = _os.getcwd()
1342 else:
1343 self.path = _path_abspath(path)
1344 self._path_mtime = -1
1345 self._path_cache = set()
1346 self._relaxed_path_cache = set()
1347
1348 def invalidate_caches(self):
1349 """Invalidate the directory mtime."""
1350 self._path_mtime = -1
1351
1352 def _get_spec(self, loader_class, fullname, path, smsl, target):
1353 loader = loader_class(fullname, path)
1354 return spec_from_file_location(fullname, path, loader=loader,
1355 submodule_search_locations=smsl)
1356
1357 def find_spec(self, fullname, target=None):
1358 """Try to find a spec for the specified module.
1359
1360 Returns the matching spec, or None if not found.
1361 """
1362 is_namespace = False
1363 tail_module = fullname.rpartition('.')[2]
1364 try:
1365 mtime = _path_stat(self.path or _os.getcwd()).st_mtime
1366 except OSError:
1367 mtime = -1
1368 if mtime != self._path_mtime:
1369 self._fill_cache()
1370 self._path_mtime = mtime
1371 # tail_module keeps the original casing, for __file__ and friends
1372 if _relax_case():
1373 cache = self._relaxed_path_cache
1374 cache_module = tail_module.lower()
1375 else:
1376 cache = self._path_cache
1377 cache_module = tail_module
1378 # Check if the module is the name of a directory (and thus a package).
1379 if cache_module in cache:
1380 base_path = _path_join(self.path, tail_module)
1381 for suffix, loader_class in self._loaders:
1382 init_filename = '__init__' + suffix
1383 full_path = _path_join(base_path, init_filename)
1384 if _path_isfile(full_path):
1385 return self._get_spec(loader_class, fullname, full_path, [base_path], target)
1386 else:
1387 # If a namespace package, return the path if we don't
1388 # find a module in the next section.
1389 is_namespace = _path_isdir(base_path)
1390 # Check for a file w/ a proper suffix exists.
1391 for suffix, loader_class in self._loaders:
1392 try:
1393 full_path = _path_join(self.path, tail_module + suffix)
1394 except ValueError:
1395 return None
1396 _bootstrap._verbose_message('trying {}', full_path, verbosity=2)
1397 if cache_module + suffix in cache:
1398 if _path_isfile(full_path):
1399 return self._get_spec(loader_class, fullname, full_path,
1400 None, target)
1401 if is_namespace:
1402 _bootstrap._verbose_message('possible namespace for {}', base_path)
1403 spec = _bootstrap.ModuleSpec(fullname, None)
1404 spec.submodule_search_locations = [base_path]
1405 return spec
1406 return None
1407
1408 def _fill_cache(self):
1409 """Fill the cache of potential modules and packages for this directory."""
1410 path = self.path
1411 try:
1412 contents = _os.listdir(path or _os.getcwd())
1413 except (FileNotFoundError, PermissionError, NotADirectoryError):
1414 # Directory has either been removed, turned into a file, or made
1415 # unreadable.
1416 contents = []
1417 # We store two cached versions, to handle runtime changes of the
1418 # PYTHONCASEOK environment variable.
1419 if not sys.platform.startswith('win'):
1420 self._path_cache = set(contents)
1421 else:
1422 # Windows users can import modules with case-insensitive file
1423 # suffixes (for legacy reasons). Make the suffix lowercase here
1424 # so it's done once instead of for every import. This is safe as
1425 # the specified suffixes to check against are always specified in a
1426 # case-sensitive manner.
1427 lower_suffix_contents = set()
1428 for item in contents:
1429 name, dot, suffix = item.partition('.')
1430 if dot:
1431 new_name = f'{name}.{suffix.lower()}'
1432 else:
1433 new_name = name
1434 lower_suffix_contents.add(new_name)
1435 self._path_cache = lower_suffix_contents
1436 if sys.platform.startswith(_CASE_INSENSITIVE_PLATFORMS):
1437 self._relaxed_path_cache = {fn.lower() for fn in contents}
1438
1439 @classmethod
1440 def path_hook(cls, *loader_details):
1441 """A class method which returns a closure to use on sys.path_hook
1442 which will return an instance using the specified loaders and the path
1443 called on the closure.
1444
1445 If the path called on the closure is not a directory, ImportError is
1446 raised.
1447
1448 """
1449 def path_hook_for_FileFinder(path):
1450 """Path hook for importlib.machinery.FileFinder."""
1451 if not _path_isdir(path):
1452 raise ImportError('only directories are supported', path=path)
1453 return cls(path, *loader_details)
1454
1455 return path_hook_for_FileFinder
1456
1457 def __repr__(self):
1458 return f'FileFinder({self.path!r})'
1459
1460
1461 class AppleFrameworkLoader(ExtensionFileLoader):
1462 """A loader for modules that have been packaged as frameworks for
1463 compatibility with Apple's iOS App Store policies.
1464 """
1465 def create_module(self, spec):
1466 # If the ModuleSpec has been created by the FileFinder, it will have
1467 # been created with an origin pointing to the .fwork file. We need to
1468 # redirect this to the location in the Frameworks folder, using the
1469 # content of the .fwork file.
1470 if spec.origin.endswith(".fwork"):
1471 with _io.FileIO(spec.origin, 'r') as file:
1472 framework_binary = file.read().decode().strip()
1473 bundle_path = _path_split(sys.executable)[0]
1474 spec.origin = _path_join(bundle_path, framework_binary)
1475
1476 # If the loader is created based on the spec for a loaded module, the
1477 # path will be pointing at the Framework location. If this occurs,
1478 # get the original .fwork location to use as the module's __file__.
1479 if self.path.endswith(".fwork"):
1480 path = self.path
1481 else:
1482 with _io.FileIO(self.path + ".origin", 'r') as file:
1483 origin = file.read().decode().strip()
1484 bundle_path = _path_split(sys.executable)[0]
1485 path = _path_join(bundle_path, origin)
1486
1487 module = _bootstrap._call_with_frames_removed(_imp.create_dynamic, spec)
1488
1489 _bootstrap._verbose_message(
1490 "Apple framework extension module {!r} loaded from {!r} (path {!r})",
1491 spec.name,
1492 spec.origin,
1493 path,
1494 )
1495
1496 # Ensure that the __file__ points at the .fwork location
1497 try:
1498 module.__file__ = path
1499 except AttributeError:
1500 # Not important enough to report.
1501 # (The error is also ignored in _bootstrap._init_module_attrs or
1502 # import_run_extension in import.c)
1503 pass
1504
1505 return module
1506
1507 # Import setup ###############################################################
1508
1509 def _fix_up_module(ns, name, pathname, cpathname=None):
1510 # This function is used by PyImport_ExecCodeModuleObject().
1511 loader = ns.get('__loader__')
1512 spec = ns.get('__spec__')
1513 if not loader:
1514 if spec:
1515 loader = spec.loader
1516 elif pathname == cpathname:
1517 loader = SourcelessFileLoader(name, pathname)
1518 else:
1519 loader = SourceFileLoader(name, pathname)
1520 if not spec:
1521 spec = spec_from_file_location(name, pathname, loader=loader)
1522 if cpathname:
1523 spec.cached = _path_abspath(cpathname)
1524 try:
1525 ns['__spec__'] = spec
1526 ns['__loader__'] = loader
1527 ns['__file__'] = pathname
1528 ns['__cached__'] = cpathname
1529 except Exception:
1530 # Not important enough to report.
1531 pass
1532
1533
1534 def _get_supported_file_loaders():
1535 """Returns a list of file-based module loaders.
1536
1537 Each item is a tuple (loader, suffixes).
1538 """
1539 extension_loaders = []
1540 if hasattr(_imp, 'create_dynamic'):
1541 if sys.platform in {"ios", "tvos", "watchos"}:
1542 extension_loaders = [(AppleFrameworkLoader, [
1543 suffix.replace(".so", ".fwork")
1544 for suffix in _imp.extension_suffixes()
1545 ])]
1546 extension_loaders.append((ExtensionFileLoader, _imp.extension_suffixes()))
1547 source = SourceFileLoader, SOURCE_SUFFIXES
1548 bytecode = SourcelessFileLoader, BYTECODE_SUFFIXES
1549 return extension_loaders + [source, bytecode]
1550
1551
1552 def _set_bootstrap_module(_bootstrap_module):
1553 global _bootstrap
1554 _bootstrap = _bootstrap_module
1555
1556
1557 def _install(_bootstrap_module):
1558 """Install the path-based import components."""
1559 _set_bootstrap_module(_bootstrap_module)
1560 supported_loaders = _get_supported_file_loaders()
1561 sys.path_hooks.extend([FileFinder.path_hook(*supported_loaders)])
1562 sys.meta_path.append(PathFinder)