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