bernsteinbear.com
this repo has no description
1#!/usr/bin/env python3
2# Copyright (c) Facebook, Inc. and its affiliates. (http://www.facebook.com)
3"""Core implementation of import.
4
5This module is NOT meant to be directly imported! It has been designed such
6that it can be bootstrapped into Python as the implementation of import. As
7such it requires the injection of specific modules and attributes in order to
8work. One should use importlib as the public-facing version of this module.
9
10"""
11import _imp
12import _thread
13import _warnings
14import _weakref
15
16#
17# IMPORTANT: Whenever making changes to this module, be sure to run
18# a top-level make in order to get the frozen version of the module
19# updated. Not doing so will result in the Makefile to fail for
20# all others who don't have a ./python around to freeze the module
21# in the early stages of compilation.
22#
23
24# See importlib._setup() for what is injected into the global namespace.
25
26# When editing this code be aware that code executed at import time CANNOT
27# reference any injected objects! This includes not only global code but also
28# anything specified at the class level.
29
30# Bootstrap-related code ######################################################
31
32import sys
33from _imp import _import_fastpath
34
35from _builtins import _address
36
37
38def _wrap(new, old):
39 """Simple substitute for functools.update_wrapper."""
40 for replace in ["__module__", "__name__", "__qualname__", "__doc__"]:
41 if hasattr(old, replace):
42 setattr(new, replace, getattr(old, replace))
43 new.__dict__.update(old.__dict__)
44
45
46def _new_module(name):
47 return type(sys)(name)
48
49
50# Module-level locking ########################################################
51
52# A dict mapping module names to weakrefs of _ModuleLock instances
53# Dictionary protected by the global import lock
54_module_locks = {}
55# A dict mapping thread ids to _ModuleLock instances
56_blocking_on = {}
57
58
59class _DeadlockError(RuntimeError):
60 pass
61
62
63class _ModuleLock:
64 """A recursive lock implementation which is able to detect deadlocks
65 (e.g. thread 1 trying to take locks A then B, and thread 2 trying to
66 take locks B then A).
67 """
68
69 def __init__(self, name):
70 self.lock = _thread.allocate_lock()
71 self.wakeup = _thread.allocate_lock()
72 self.name = name
73 self.owner = None
74 self.count = 0
75 self.waiters = 0
76
77 def has_deadlock(self):
78 # Deadlock avoidance for concurrent circular imports.
79 me = _thread.get_ident()
80 tid = self.owner
81 while True:
82 lock = _blocking_on.get(tid)
83 if lock is None:
84 return False
85 tid = lock.owner
86 if tid == me:
87 return True
88
89 def acquire(self):
90 """
91 Acquire the module lock. If a potential deadlock is detected,
92 a _DeadlockError is raised.
93 Otherwise, the lock is always acquired and True is returned.
94 """
95 tid = _thread.get_ident()
96 _blocking_on[tid] = self
97 try:
98 while True:
99 with self.lock:
100 if self.count == 0 or self.owner == tid:
101 self.owner = tid
102 self.count += 1
103 return True
104 if self.has_deadlock():
105 raise _DeadlockError("deadlock detected by %r" % self)
106 if self.wakeup.acquire(False):
107 self.waiters += 1
108 # Wait for a release() call
109 self.wakeup.acquire()
110 self.wakeup.release()
111 finally:
112 del _blocking_on[tid]
113
114 def release(self):
115 tid = _thread.get_ident()
116 with self.lock:
117 if self.owner != tid:
118 raise RuntimeError("cannot release un-acquired lock")
119 assert self.count > 0
120 self.count -= 1
121 if self.count == 0:
122 self.owner = None
123 if self.waiters:
124 self.waiters -= 1
125 self.wakeup.release()
126
127 def __repr__(self):
128 return f"_ModuleLock({self.name!r}) at {_address(self):#x}"
129
130
131class _DummyModuleLock:
132 """A simple _ModuleLock equivalent for Python builds without
133 multi-threading support."""
134
135 def __init__(self, name):
136 self.name = name
137 self.count = 0
138
139 def acquire(self):
140 self.count += 1
141 return True
142
143 def release(self):
144 if self.count == 0:
145 raise RuntimeError("cannot release un-acquired lock")
146 self.count -= 1
147
148 def __repr__(self):
149 return f"_DummyModuleLock({self.name!r}) at {_address(self):#x}"
150
151
152class _ModuleLockManager:
153 def __init__(self, name):
154 self._name = name
155 self._lock = None
156
157 def __enter__(self):
158 self._lock = _get_module_lock(self._name)
159 self._lock.acquire()
160
161 def __exit__(self, *args, **kwargs):
162 self._lock.release()
163
164
165# The following two functions are for consumption by Python/import.c.
166
167
168def _get_module_lock(name):
169 """Get or create the module lock for a given module name.
170
171 Acquire/release internally the global import lock to protect
172 _module_locks."""
173
174 _imp.acquire_lock()
175 try:
176 try:
177 lock = _module_locks[name]()
178 except KeyError:
179 lock = None
180
181 if lock is None:
182 if _thread is None:
183 lock = _DummyModuleLock(name)
184 else:
185 lock = _ModuleLock(name)
186
187 def cb(ref, name=name):
188 _imp.acquire_lock()
189 try:
190 # bpo-31070: Check if another thread created a new lock
191 # after the previous lock was destroyed
192 # but before the weakref callback was called.
193 if _module_locks.get(name) is ref:
194 del _module_locks[name]
195 finally:
196 _imp.release_lock()
197
198 _module_locks[name] = _weakref.ref(lock, cb)
199 finally:
200 _imp.release_lock()
201
202 return lock
203
204
205def _lock_unlock_module(name):
206 """Acquires then releases the module lock for a given module name.
207
208 This is used to ensure a module is completely initialized, in the
209 event it is being imported by another thread.
210 """
211 lock = _get_module_lock(name)
212 try:
213 lock.acquire()
214 except _DeadlockError:
215 # Concurrent circular import, we'll accept a partially initialized
216 # module object.
217 pass
218 else:
219 lock.release()
220
221
222# Frame stripping magic ###############################################
223def _call_with_frames_removed(f, *args, **kwds):
224 """remove_importlib_frames in import.c will always remove sequences
225 of importlib frames that end with a call to this function
226
227 Use it instead of a normal call in places where including the importlib
228 frames introduces unwanted noise into the traceback (e.g. when executing
229 module code)
230 """
231 return f(*args, **kwds)
232
233
234def _verbose_message(message, *args, verbosity=1):
235 """Print the message to stderr if -v/PYTHONVERBOSE is turned on."""
236 if sys.flags.verbose >= verbosity:
237 if not message.startswith(("#", "import ")):
238 message = "# " + message
239 print(message, str(args), file=sys.stderr)
240
241
242def _requires_builtin(fxn):
243 """Decorator to verify the named module is built-in."""
244
245 def _requires_builtin_wrapper(self, fullname):
246 if fullname not in sys.builtin_module_names:
247 raise ImportError(f"{fullname!r} is not a built-in module", name=fullname)
248 return fxn(self, fullname)
249
250 _wrap(_requires_builtin_wrapper, fxn)
251 return _requires_builtin_wrapper
252
253
254def _requires_frozen(fxn):
255 """Decorator to verify the named module is frozen."""
256
257 def _requires_frozen_wrapper(self, fullname):
258 if not _imp.is_frozen(fullname):
259 raise ImportError(f"{fullname!r} is not a frozen module", name=fullname)
260 return fxn(self, fullname)
261
262 _wrap(_requires_frozen_wrapper, fxn)
263 return _requires_frozen_wrapper
264
265
266# Typically used by loader classes as a method replacement.
267def _load_module_shim(self, fullname):
268 """Load the specified module into sys.modules and return it.
269
270 This method is deprecated. Use loader.exec_module instead.
271
272 """
273 spec = spec_from_loader(fullname, self)
274 if fullname in sys.modules:
275 module = sys.modules[fullname]
276 _exec(spec, module)
277 return sys.modules[fullname]
278 else:
279 return _load(spec)
280
281
282# Module specifications #######################################################
283
284
285def _module_repr(module):
286 # The implementation of ModuleType.__repr__().
287 loader = getattr(module, "__loader__", None)
288 if hasattr(loader, "module_repr"):
289 # As soon as BuiltinImporter, FrozenImporter, and NamespaceLoader
290 # drop their implementations for module_repr. we can add a
291 # deprecation warning here.
292 try:
293 return loader.module_repr(module)
294 except Exception:
295 pass
296 try:
297 spec = module.__spec__
298 except AttributeError:
299 pass
300 else:
301 if spec is not None:
302 return _module_repr_from_spec(spec)
303
304 # We could use module.__class__.__name__ instead of 'module' in the
305 # various repr permutations.
306 try:
307 name = module.__name__
308 except AttributeError:
309 name = "?"
310 try:
311 filename = module.__file__
312 except AttributeError:
313 if loader is None:
314 return f"<module {name!r}>"
315 else:
316 return f"<module {name!r} ({loader!r})>"
317 else:
318 return f"<module {name!r} from {filename!r}>"
319
320
321class _installed_safely:
322 def __init__(self, module):
323 self._module = module
324 self._spec = module.__spec__
325
326 def __enter__(self):
327 # This must be done before putting the module in sys.modules
328 # (otherwise an optimization shortcut in import.c becomes
329 # wrong)
330 self._spec._initializing = True
331 sys.modules[self._spec.name] = self._module
332
333 def __exit__(self, *args):
334 try:
335 spec = self._spec
336 if any(arg is not None for arg in args):
337 try:
338 del sys.modules[spec.name]
339 except KeyError:
340 pass
341 else:
342 _verbose_message(f"import {spec.name!r} # {spec.loader!r}")
343 finally:
344 self._spec._initializing = False
345
346
347class ModuleSpec:
348 """The specification for a module, used for loading.
349
350 A module's spec is the source for information about the module. For
351 data associated with the module, including source, use the spec's
352 loader.
353
354 `name` is the absolute name of the module. `loader` is the loader
355 to use when loading the module. `parent` is the name of the
356 package the module is in. The parent is derived from the name.
357
358 `is_package` determines if the module is considered a package or
359 not. On modules this is reflected by the `__path__` attribute.
360
361 `origin` is the specific location used by the loader from which to
362 load the module, if that information is available. When filename is
363 set, origin will match.
364
365 `has_location` indicates that a spec's "origin" reflects a location.
366 When this is True, `__file__` attribute of the module is set.
367
368 `cached` is the location of the cached bytecode file, if any. It
369 corresponds to the `__cached__` attribute.
370
371 `submodule_search_locations` is the sequence of path entries to
372 search when importing submodules. If set, is_package should be
373 True--and False otherwise.
374
375 Packages are simply modules that (may) have submodules. If a spec
376 has a non-None value in `submodule_search_locations`, the import
377 system will consider modules loaded from the spec as packages.
378
379 Only finders (see importlib.abc.MetaPathFinder and
380 importlib.abc.PathEntryFinder) should modify ModuleSpec instances.
381
382 """
383
384 def __init__(
385 self, name, loader, *, origin=None, loader_state=None, is_package=None
386 ):
387 self.name = name
388 self.loader = loader
389 self.origin = origin
390 self.loader_state = loader_state
391 self.submodule_search_locations = [] if is_package else None
392
393 # file-location attributes
394 self._set_fileattr = False
395 self._cached = None
396
397 def __repr__(self):
398 args = [f"name={self.name!r}", f"loader={self.loader!r}"]
399 if self.origin is not None:
400 args.append(f"origin={self.origin!r}")
401 if self.submodule_search_locations is not None:
402 args.append(f"submodule_search_locations={self.submodule_search_locations}")
403 return f"{self.__class__.__name__}({', '.join(args)})"
404
405 def __eq__(self, other):
406 smsl = self.submodule_search_locations
407 try:
408 return (
409 self.name == other.name
410 and self.loader == other.loader
411 and self.origin == other.origin
412 and smsl == other.submodule_search_locations
413 and self.cached == other.cached
414 and self.has_location == other.has_location
415 )
416 except AttributeError:
417 return False
418
419 @property
420 def cached(self):
421 if self._cached is None:
422 if self.origin is not None and self._set_fileattr:
423 if _bootstrap_external is None:
424 raise NotImplementedError
425 self._cached = _bootstrap_external._get_cached(self.origin)
426 return self._cached
427
428 @cached.setter
429 def cached(self, cached):
430 self._cached = cached
431
432 @property
433 def parent(self):
434 """The name of the module's parent."""
435 if self.submodule_search_locations is None:
436 return self.name.rpartition(".")[0]
437 else:
438 return self.name
439
440 @property
441 def has_location(self):
442 return self._set_fileattr
443
444 @has_location.setter
445 def has_location(self, value):
446 self._set_fileattr = bool(value)
447
448
449def spec_from_loader(name, loader, *, origin=None, is_package=None):
450 """Return a module spec based on various loader methods."""
451 if hasattr(loader, "get_filename"):
452 if _bootstrap_external is None:
453 raise NotImplementedError
454 spec_from_file_location = _bootstrap_external.spec_from_file_location
455
456 if is_package is None:
457 return spec_from_file_location(name, loader=loader)
458 search = [] if is_package else None
459 return spec_from_file_location(
460 name, loader=loader, submodule_search_locations=search
461 )
462
463 if is_package is None:
464 if hasattr(loader, "is_package"):
465 try:
466 is_package = loader.is_package(name)
467 except ImportError:
468 is_package = None # aka, undefined
469 else:
470 # the default
471 is_package = False
472
473 return ModuleSpec(name, loader, origin=origin, is_package=is_package)
474
475
476def _spec_from_module(module, loader=None, origin=None):
477 # This function is meant for use in _setup().
478 try:
479 spec = module.__spec__
480 except AttributeError:
481 pass
482 else:
483 if spec is not None:
484 return spec
485
486 name = module.__name__
487 if loader is None:
488 try:
489 loader = module.__loader__
490 except AttributeError:
491 # loader will stay None.
492 pass
493 try:
494 location = module.__file__
495 except AttributeError:
496 location = None
497 if origin is None:
498 if location is None:
499 try:
500 origin = loader._ORIGIN
501 except AttributeError:
502 origin = None
503 else:
504 origin = location
505 try:
506 cached = module.__cached__
507 except AttributeError:
508 cached = None
509 try:
510 submodule_search_locations = list(module.__path__)
511 except AttributeError:
512 submodule_search_locations = None
513
514 spec = ModuleSpec(name, loader, origin=origin)
515 spec._set_fileattr = False if location is None else True
516 spec.cached = cached
517 spec.submodule_search_locations = submodule_search_locations
518 return spec
519
520
521def _init_module_attrs(spec, module, *, override=False):
522 # The passed-in module may be not support attribute assignment,
523 # in which case we simply don't set the attributes.
524 # __name__
525 if override or getattr(module, "__name__", None) is None:
526 try:
527 module.__name__ = spec.name
528 except AttributeError:
529 pass
530 # __loader__
531 if override or getattr(module, "__loader__", None) is None:
532 loader = spec.loader
533 if loader is None:
534 # A backward compatibility hack.
535 if spec.submodule_search_locations is not None:
536 if _bootstrap_external is None:
537 raise NotImplementedError
538 _NamespaceLoader = _bootstrap_external._NamespaceLoader
539
540 loader = _NamespaceLoader.__new__(_NamespaceLoader)
541 loader._path = spec.submodule_search_locations
542 spec.loader = loader
543 # While the docs say that module.__file__ is not set for
544 # built-in modules, and the code below will avoid setting it if
545 # spec.has_location is false, this is incorrect for namespace
546 # packages. Namespace packages have no location, but their
547 # __spec__.origin is None, and thus their module.__file__
548 # should also be None for consistency. While a bit of a hack,
549 # this is the best place to ensure this consistency.
550 #
551 # See # https://docs.python.org/3/library/importlib.html#importlib.abc.Loader.load_module # noqa:B950
552 # and bpo-32305
553 module.__file__ = None
554 try:
555 module.__loader__ = loader
556 except AttributeError:
557 pass
558 # __package__
559 if override or getattr(module, "__package__", None) is None:
560 try:
561 module.__package__ = spec.parent
562 except AttributeError:
563 pass
564 # __spec__
565 try:
566 module.__spec__ = spec
567 except AttributeError:
568 pass
569 # __path__
570 if override or getattr(module, "__path__", None) is None:
571 if spec.submodule_search_locations is not None:
572 try:
573 module.__path__ = spec.submodule_search_locations
574 except AttributeError:
575 pass
576 # __file__/__cached__
577 if spec.has_location:
578 if override or getattr(module, "__file__", None) is None:
579 try:
580 module.__file__ = spec.origin
581 except AttributeError:
582 pass
583
584 if override or getattr(module, "__cached__", None) is None:
585 if spec.cached is not None:
586 try:
587 module.__cached__ = spec.cached
588 except AttributeError:
589 pass
590 return module
591
592
593def module_from_spec(spec):
594 """Create a module based on the provided spec."""
595 # Typically loaders will not implement create_module().
596 module = None
597 if hasattr(spec.loader, "create_module"):
598 # If create_module() returns `None` then it means default
599 # module creation should be used.
600 module = spec.loader.create_module(spec)
601 elif hasattr(spec.loader, "exec_module"):
602 raise ImportError(
603 "loaders that define exec_module() " "must also define create_module()"
604 )
605 if module is None:
606 module = _new_module(spec.name)
607 _init_module_attrs(spec, module)
608 return module
609
610
611def _module_repr_from_spec(spec):
612 """Return the repr to use for the module."""
613 # We mostly replicate _module_repr() using the spec attributes.
614 name = "?" if spec.name is None else spec.name
615 if spec.origin is None:
616 if spec.loader is None:
617 return f"<module {name!r}>"
618 else:
619 return f"<module {name!r} ({spec.loader!r})>"
620 else:
621 if spec.has_location:
622 return f"<module {name!r} from {spec.origin!r}>"
623 else:
624 return f"<module {spec.name!r} ({spec.origin})>"
625
626
627# Used by importlib.reload() and _load_module_shim().
628def _exec(spec, module):
629 """Execute the spec's specified module in an existing module's namespace."""
630 name = spec.name
631 with _ModuleLockManager(name):
632 if sys.modules.get(name) is not module:
633 msg = f"module {name!r} not in sys.modules"
634 raise ImportError(msg, name=name)
635 if spec.loader is None:
636 if spec.submodule_search_locations is None:
637 raise ImportError("missing loader", name=spec.name)
638 # namespace package
639 _init_module_attrs(spec, module, override=True)
640 return module
641 _init_module_attrs(spec, module, override=True)
642 if not hasattr(spec.loader, "exec_module"):
643 # (issue19713) Once BuiltinImporter and ExtensionFileLoader
644 # have exec_module() implemented, we can add a deprecation
645 # warning here.
646 spec.loader.load_module(name)
647 else:
648 spec.loader.exec_module(module)
649 return sys.modules[name]
650
651
652def _load_backward_compatible(spec):
653 # (issue19713) Once BuiltinImporter and ExtensionFileLoader
654 # have exec_module() implemented, we can add a deprecation
655 # warning here.
656 spec.loader.load_module(spec.name)
657 # The module must be in sys.modules at this point!
658 module = sys.modules[spec.name]
659 if getattr(module, "__loader__", None) is None:
660 try:
661 module.__loader__ = spec.loader
662 except AttributeError:
663 pass
664 if getattr(module, "__package__", None) is None:
665 try:
666 # Since module.__path__ may not line up with
667 # spec.submodule_search_paths, we can't necessarily rely
668 # on spec.parent here.
669 module.__package__ = module.__name__
670 if not hasattr(module, "__path__"):
671 module.__package__ = spec.name.rpartition(".")[0]
672 except AttributeError:
673 pass
674 if getattr(module, "__spec__", None) is None:
675 try:
676 module.__spec__ = spec
677 except AttributeError:
678 pass
679 return module
680
681
682def _load_unlocked(spec):
683 # A helper for direct use by the import system.
684 if spec.loader is not None:
685 # not a namespace package
686 if not hasattr(spec.loader, "exec_module"):
687 return _load_backward_compatible(spec)
688
689 module = module_from_spec(spec)
690 with _installed_safely(module):
691 if spec.loader is None:
692 if spec.submodule_search_locations is None:
693 raise ImportError("missing loader", name=spec.name)
694 # A namespace package so do nothing.
695 else:
696 spec.loader.exec_module(module)
697
698 # We don't ensure that the import-related module attributes get
699 # set in the sys.modules replacement case. Such modules are on
700 # their own.
701 return sys.modules[spec.name]
702
703
704# A method used during testing of _load_unlocked() and by
705# _load_module_shim().
706def _load(spec):
707 """Return a new module object, loaded by the spec's loader.
708
709 The module is not added to its parent.
710
711 If a module is already in sys.modules, that existing module gets
712 clobbered.
713
714 """
715 with _ModuleLockManager(spec.name):
716 return _load_unlocked(spec)
717
718
719# Loaders #####################################################################
720
721
722class BuiltinImporter:
723
724 """Meta path import for built-in modules.
725
726 All methods are either class or static methods to avoid the need to
727 instantiate the class.
728
729 """
730
731 @staticmethod
732 def module_repr(module):
733 """Return repr for the module.
734
735 The method is deprecated. The import machinery does the job itself.
736
737 """
738 return f"<module {module.__name__!r} (built-in)>"
739
740 @classmethod
741 def find_spec(cls, fullname, path=None, target=None):
742 if path is not None:
743 return None
744 if _imp.is_builtin(fullname):
745 return spec_from_loader(fullname, cls, origin="built-in")
746 else:
747 return None
748
749 @classmethod
750 def find_module(cls, fullname, path=None):
751 """Find the built-in module.
752
753 If 'path' is ever specified then the search is considered a failure.
754
755 This method is deprecated. Use find_spec() instead.
756
757 """
758 spec = cls.find_spec(fullname, path)
759 return spec.loader if spec is not None else None
760
761 @classmethod
762 def create_module(self, spec):
763 """Create a built-in module"""
764 if spec.name not in sys.builtin_module_names:
765 raise ImportError(f"{spec.name!r} is not a built-in module", name=spec.name)
766 return _call_with_frames_removed(_imp.create_builtin, spec)
767
768 @classmethod
769 def exec_module(self, module):
770 """Exec a built-in module"""
771 _call_with_frames_removed(_imp.exec_builtin, module)
772
773 @classmethod
774 @_requires_builtin
775 def get_code(cls, fullname):
776 """Return None as built-in modules do not have code objects."""
777 return None
778
779 @classmethod
780 @_requires_builtin
781 def get_source(cls, fullname):
782 """Return None as built-in modules do not have source code."""
783 return None
784
785 @classmethod
786 @_requires_builtin
787 def is_package(cls, fullname):
788 """Return False as built-in modules are never packages."""
789 return False
790
791 load_module = classmethod(_load_module_shim)
792
793
794class FrozenImporter:
795
796 """Meta path import for frozen modules.
797
798 All methods are either class or static methods to avoid the need to
799 instantiate the class.
800
801 """
802
803 @staticmethod
804 def module_repr(m):
805 """Return repr for the module.
806
807 The method is deprecated. The import machinery does the job itself.
808
809 """
810 return f"<module {m.__name__!r} (frozen)>"
811
812 @classmethod
813 def find_spec(cls, fullname, path=None, target=None):
814 if _imp.is_frozen(fullname):
815 return spec_from_loader(fullname, cls, origin="frozen")
816 else:
817 return None
818
819 @classmethod
820 def find_module(cls, fullname, path=None):
821 """Find a frozen module.
822
823 This method is deprecated. Use find_spec() instead.
824
825 """
826 return cls if _imp.is_frozen(fullname) else None
827
828 @classmethod
829 def create_module(cls, spec):
830 """Use default semantics for module creation."""
831
832 @staticmethod
833 def exec_module(module):
834 name = module.__spec__.name
835 if not _imp.is_frozen(name):
836 raise ImportError(f"{name!r} is not a frozen module", name=name)
837 code = _call_with_frames_removed(_imp.get_frozen_object, name)
838 exec(code, module.__dict__)
839
840 @classmethod
841 def load_module(cls, fullname):
842 """Load a frozen module.
843
844 This method is deprecated. Use exec_module() instead.
845
846 """
847 return _load_module_shim(cls, fullname)
848
849 @classmethod
850 @_requires_frozen
851 def get_code(cls, fullname):
852 """Return the code object for the frozen module."""
853 return _imp.get_frozen_object(fullname)
854
855 @classmethod
856 @_requires_frozen
857 def get_source(cls, fullname):
858 """Return None as frozen modules do not have source code."""
859 return None
860
861 @classmethod
862 @_requires_frozen
863 def is_package(cls, fullname):
864 """Return True if the frozen module is a package."""
865 return _imp.is_frozen_package(fullname)
866
867
868# Import itself ###############################################################
869
870
871class _ImportLockContext:
872
873 """Context manager for the import lock."""
874
875 def __enter__(self):
876 """Acquire the import lock."""
877 _imp.acquire_lock()
878
879 def __exit__(self, exc_type, exc_value, exc_traceback):
880 """Release the import lock regardless of any raised exceptions."""
881 _imp.release_lock()
882
883
884def _resolve_name(name, package, level):
885 """Resolve a relative module name to an absolute one."""
886 bits = package.rsplit(".", level - 1)
887 if len(bits) < level:
888 raise ValueError("attempted relative import beyond top-level package")
889 base = bits[0]
890 return f"{base}.{name}" if name else base
891
892
893def _find_spec_legacy(finder, name, path):
894 # This would be a good place for a DeprecationWarning if
895 # we ended up going that route.
896 loader = finder.find_module(name, path)
897 if loader is None:
898 return None
899 return spec_from_loader(name, loader)
900
901
902def _find_spec(name, path, target=None):
903 """Find a module's spec."""
904 meta_path = sys.meta_path
905 if meta_path is None:
906 # PyImport_Cleanup() is running or has been called.
907 raise ImportError("sys.meta_path is None, Python is likely " "shutting down")
908
909 if not meta_path:
910 _warnings.warn("sys.meta_path is empty", ImportWarning)
911
912 # We check sys.modules here for the reload case. While a passed-in
913 # target will usually indicate a reload there is no guarantee, whereas
914 # sys.modules provides one.
915 is_reload = name in sys.modules
916 for finder in meta_path:
917 with _ImportLockContext():
918 try:
919 find_spec = finder.find_spec
920 except AttributeError:
921 spec = _find_spec_legacy(finder, name, path)
922 if spec is None:
923 continue
924 else:
925 spec = find_spec(name, path, target)
926 if spec is not None:
927 # The parent import may have already imported this module.
928 if not is_reload and name in sys.modules:
929 module = sys.modules[name]
930 try:
931 __spec__ = module.__spec__
932 except AttributeError:
933 # We use the found spec since that is the one that
934 # we would have used if the parent module hadn't
935 # beaten us to the punch.
936 return spec
937 else:
938 if __spec__ is None:
939 return spec
940 else:
941 return __spec__
942 else:
943 return spec
944 else:
945 return None
946
947
948def _sanity_check(name, package, level):
949 """Verify arguments are "sane"."""
950 if not isinstance(name, str):
951 raise TypeError(f"module name must be str, not {type(name)}")
952 if level < 0:
953 raise ValueError("level must be >= 0")
954 if level > 0:
955 if not isinstance(package, str):
956 raise TypeError("__package__ not set to a string")
957 elif not package:
958 raise ImportError(
959 "attempted relative import with no known parent " "package"
960 )
961 if not name and level == 0:
962 raise ValueError("Empty module name")
963
964
965_ERR_MSG_PREFIX = "No module named "
966_ERR_MSG = _ERR_MSG_PREFIX + "{!r}"
967
968
969def _find_and_load_unlocked(name, import_):
970 path = None
971 parent = name.rpartition(".")[0]
972 if parent:
973 if parent not in sys.modules:
974 _call_with_frames_removed(import_, parent)
975 # Crazy side-effects!
976 if name in sys.modules:
977 return sys.modules[name]
978 parent_module = sys.modules[parent]
979 try:
980 path = parent_module.__path__
981 except AttributeError:
982 msg = _ERR_MSG_PREFIX + f"{name!r}; {parent!r} is not a package"
983 raise ModuleNotFoundError(msg, name=name) from None
984 spec = _find_spec(name, path)
985 if spec is None:
986 raise ModuleNotFoundError(_ERR_MSG_PREFIX + f"{name!r}", name=name)
987 else:
988 module = _load_unlocked(spec)
989 if parent:
990 # Set the module as an attribute on its parent.
991 parent_module = sys.modules[parent]
992 setattr(parent_module, name.rpartition(".")[2], module)
993 return module
994
995
996_NEEDS_LOADING = object()
997
998
999def _find_and_load(name, import_):
1000 """Find and load the module."""
1001 with _ModuleLockManager(name):
1002 module = sys.modules.get(name, _NEEDS_LOADING)
1003 if module is _NEEDS_LOADING:
1004 return _find_and_load_unlocked(name, import_)
1005
1006 if module is None:
1007 message = f"import of {name} halted; None in sys.modules"
1008 raise ModuleNotFoundError(message, name=name)
1009
1010 _lock_unlock_module(name)
1011 return module
1012
1013
1014def _gcd_import(name, package=None, level=0):
1015 """Import and return the module based on its name, the package the call is
1016 being made from, and the level adjustment.
1017
1018 This function represents the greatest common denominator of functionality
1019 between import_module and __import__. This includes setting __package__ if
1020 the loader did not.
1021
1022 """
1023 _sanity_check(name, package, level)
1024 if level > 0:
1025 name = _resolve_name(name, package, level)
1026 return _find_and_load(name, _gcd_import)
1027
1028
1029def _handle_fromlist(module, fromlist, import_, *, recursive=False):
1030 """Figure out what __import__ should return.
1031
1032 The import_ parameter is a callable which takes the name of module to
1033 import. It is required to decouple the function from assuming importlib's
1034 import implementation is desired.
1035
1036 """
1037 # The hell that is fromlist ...
1038 # If a package was imported, try to import stuff from fromlist.
1039 if hasattr(module, "__path__"):
1040 for x in fromlist:
1041 if not isinstance(x, str):
1042 if recursive:
1043 where = module.__name__ + ".__all__"
1044 else:
1045 where = "``from list''"
1046 raise TypeError(
1047 f"Item in {where} must be str, " f"not {type(x).__name__}"
1048 )
1049 elif x == "*":
1050 if not recursive and hasattr(module, "__all__"):
1051 _handle_fromlist(module, module.__all__, import_, recursive=True)
1052 elif not hasattr(module, x):
1053 from_name = f"{module.__name__}.{x}"
1054 try:
1055 _call_with_frames_removed(import_, from_name)
1056 except ModuleNotFoundError as exc:
1057 # Backwards-compatibility dictates we ignore failed
1058 # imports triggered by fromlist for modules that don't
1059 # exist.
1060 if (
1061 exc.name == from_name
1062 and sys.modules.get(from_name, _NEEDS_LOADING) is not None
1063 ):
1064 continue
1065 raise
1066 return module
1067
1068
1069def _calc___package__(globals):
1070 """Calculate what __package__ should be.
1071
1072 __package__ is not guaranteed to be defined or could be set to None
1073 to represent that its proper value is unknown.
1074
1075 """
1076 package = globals.get("__package__")
1077 spec = globals.get("__spec__")
1078 if package is not None:
1079 if spec is not None and package != spec.parent:
1080 _warnings.warn(
1081 "__package__ != __spec__.parent " f"({package!r} != {spec.parent!r})",
1082 ImportWarning,
1083 stacklevel=3,
1084 )
1085 return package
1086 elif spec is not None:
1087 return spec.parent
1088 else:
1089 _warnings.warn(
1090 "can't resolve package from __spec__ or __package__, "
1091 "falling back on __name__ and __path__",
1092 ImportWarning,
1093 stacklevel=3,
1094 )
1095 package = globals["__name__"]
1096 if "__path__" not in globals:
1097 package = package.rpartition(".")[0]
1098 return package
1099
1100
1101def __import__(name, globals=None, locals=None, fromlist=(), level=0):
1102 """Import a module.
1103
1104 The 'globals' argument is used to infer where the import is occurring from
1105 to handle relative imports. The 'locals' argument is ignored. The
1106 'fromlist' argument specifies what should exist as attributes on the module
1107 being imported (e.g. ``from module import <fromlist>``). The 'level'
1108 argument represents the package location to import from in a relative
1109 import (e.g. ``from ..pkg import mod`` would have a 'level' of 2).
1110
1111 """
1112 module = _import_fastpath(name, fromlist, level)
1113 if module is not None:
1114 return module
1115
1116 if level == 0:
1117 module = _gcd_import(name)
1118 else:
1119 globals_ = globals if globals is not None else {}
1120 package = _calc___package__(globals_)
1121 module = _gcd_import(name, package, level)
1122 if not fromlist:
1123 # Return up to the first dot in 'name'. This is complicated by the fact
1124 # that 'name' may be relative.
1125 if level == 0:
1126 return _gcd_import(name.partition(".")[0])
1127 elif not name:
1128 return module
1129 else:
1130 # Figure out where to slice the module's name up to the first dot
1131 # in 'name'.
1132 cut_off = len(name) - len(name.partition(".")[0])
1133 # Slice end needs to be positive to alleviate need to special-case
1134 # when ``'.' not in name``.
1135 return sys.modules[module.__name__[: len(module.__name__) - cut_off]]
1136 else:
1137 return _handle_fromlist(module, fromlist, _gcd_import)
1138
1139
1140def _builtin_from_name(name):
1141 spec = BuiltinImporter.find_spec(name)
1142 if spec is None:
1143 raise ImportError("no built-in module named " + name)
1144 return _load_unlocked(spec)
1145
1146
1147def _init():
1148 # Set up the spec for existing builtin/frozen modules.
1149 module_type = type(sys)
1150 for name, module in sys.modules.items():
1151 if isinstance(module, module_type):
1152 if name in sys.builtin_module_names:
1153 loader = BuiltinImporter
1154 elif _imp.is_frozen(name):
1155 loader = FrozenImporter
1156 else:
1157 continue
1158 spec = _spec_from_module(module, loader)
1159 _init_module_attrs(spec, module)
1160
1161 sys.meta_path.append(BuiltinImporter)
1162 sys.meta_path.append(FrozenImporter)
1163
1164
1165import _frozen_importlib_external as _bootstrap_external