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