Debian Codegraph @

Doc/library/importlib.rst

raw
1 :mod:`!importlib` --- The implementation of :keyword:`!import`
2 ==============================================================
3
4 .. module:: importlib
5 :synopsis: The implementation of the import machinery.
6
7 .. moduleauthor:: Brett Cannon <[email protected]>
8 .. sectionauthor:: Brett Cannon <[email protected]>
9
10 .. versionadded:: 3.1
11
12 **Source code:** :source:`Lib/importlib/__init__.py`
13
14 --------------
15
16
17 Introduction
18 ------------
19
20 The purpose of the :mod:`!importlib` package is three-fold.
21
22 One is to provide the
23 implementation of the :keyword:`import` statement (and thus, by extension, the
24 :func:`__import__` function) in Python source code. This provides an
25 implementation of :keyword:`!import` which is portable to any Python
26 interpreter. This also provides an implementation which is easier to
27 comprehend than one implemented in a programming language other than Python.
28
29 Two, the components to implement :keyword:`import` are exposed in this
30 package, making it easier for users to create their own custom objects (known
31 generically as an :term:`importer`) to participate in the import process.
32
33 Three, the package contains modules exposing additional functionality for
34 managing aspects of Python packages:
35
36 * :mod:`importlib.metadata` presents access to metadata from third-party
37 distributions.
38 * :mod:`importlib.resources` provides routines for accessing non-code
39 "resources" from Python packages.
40
41 .. seealso::
42
43 :ref:`import`
44 The language reference for the :keyword:`import` statement.
45
46 `Packages specification <https://www.python.org/doc/essays/packages/>`__
47 Original specification of packages. Some semantics have changed since
48 the writing of this document (e.g. redirecting based on ``None``
49 in :data:`sys.modules`).
50
51 The :func:`.__import__` function
52 The :keyword:`import` statement is syntactic sugar for this function.
53
54 :ref:`sys-path-init`
55 The initialization of :data:`sys.path`.
56
57 :pep:`235`
58 Import on Case-Insensitive Platforms
59
60 :pep:`263`
61 Defining Python Source Code Encodings
62
63 :pep:`302`
64 New Import Hooks
65
66 :pep:`328`
67 Imports: Multi-Line and Absolute/Relative
68
69 :pep:`366`
70 Main module explicit relative imports
71
72 :pep:`420`
73 Implicit namespace packages
74
75 :pep:`451`
76 A ModuleSpec Type for the Import System
77
78 :pep:`488`
79 Elimination of PYO files
80
81 :pep:`489`
82 Multi-phase extension module initialization
83
84 :pep:`552`
85 Deterministic pycs
86
87 :pep:`3120`
88 Using UTF-8 as the Default Source Encoding
89
90 :pep:`3147`
91 PYC Repository Directories
92
93
94 Functions
95 ---------
96
97 .. function:: __import__(name, globals=None, locals=None, fromlist=(), level=0)
98
99 An implementation of the built-in :func:`__import__` function.
100
101 .. note::
102 Programmatic importing of modules should use :func:`import_module`
103 instead of this function.
104
105 .. function:: import_module(name, package=None)
106
107 Import a module. The *name* argument specifies what module to
108 import in absolute or relative terms
109 (e.g. either ``pkg.mod`` or ``..mod``). If the name is
110 specified in relative terms, then the *package* argument must be set to
111 the name of the package which is to act as the anchor for resolving the
112 package name (e.g. ``import_module('..mod', 'pkg.subpkg')`` will import
113 ``pkg.mod``).
114
115 The :func:`import_module` function acts as a simplifying wrapper around
116 :func:`importlib.__import__`. This means all semantics of the function are
117 derived from :func:`importlib.__import__`. The most important difference
118 between these two functions is that :func:`import_module` returns the
119 specified package or module (e.g. ``pkg.mod``), while :func:`__import__`
120 returns the top-level package or module (e.g. ``pkg``).
121
122 If you are dynamically importing a module that was created since the
123 interpreter began execution (e.g., created a Python source file), you may
124 need to call :func:`invalidate_caches` in order for the new module to be
125 noticed by the import system.
126
127 .. versionchanged:: 3.3
128 Parent packages are automatically imported.
129
130 .. function:: invalidate_caches()
131
132 Invalidate the internal caches of finders stored at
133 :data:`sys.meta_path`. If a finder implements ``invalidate_caches()`` then it
134 will be called to perform the invalidation. This function should be called
135 if any modules are created/installed while your program is running to
136 guarantee all finders will notice the new module's existence.
137
138 .. versionadded:: 3.3
139
140 .. versionchanged:: 3.10
141 Namespace packages created/installed in a different :data:`sys.path`
142 location after the same namespace was already imported are noticed.
143
144 .. function:: reload(module)
145
146 Reload a previously imported *module*. The argument must be a module object,
147 so it must have been successfully imported before. This is useful if you
148 have edited the module source file using an external editor and want to try
149 out the new version without leaving the Python interpreter. The return value
150 is the module object (which can be different if re-importing causes a
151 different object to be placed in :data:`sys.modules`).
152
153 When :func:`reload` is executed:
154
155 * Python module's code is recompiled and the module-level code re-executed,
156 defining a new set of objects which are bound to names in the module's
157 dictionary by reusing the :term:`loader` which originally loaded the
158 module. The ``init`` function of extension modules is not called a second
159 time.
160
161 * As with all other objects in Python the old objects are only reclaimed
162 after their reference counts drop to zero.
163
164 * The names in the module namespace are updated to point to any new or
165 changed objects.
166
167 * Other references to the old objects (such as names external to the module) are
168 not rebound to refer to the new objects and must be updated in each namespace
169 where they occur if that is desired.
170
171 There are a number of other caveats:
172
173 When a module is reloaded, its dictionary (containing the module's global
174 variables) is retained. Redefinitions of names will override the old
175 definitions, so this is generally not a problem. If the new version of a
176 module does not define a name that was defined by the old version, the old
177 definition remains. This feature can be used to the module's advantage if it
178 maintains a global table or cache of objects --- with a :keyword:`try`
179 statement it can test for the table's presence and skip its initialization if
180 desired::
181
182 try:
183 cache
184 except NameError:
185 cache = {}
186
187 It is generally not very useful to reload built-in or dynamically loaded
188 modules. Reloading :mod:`sys`, :mod:`__main__`, :mod:`builtins` and other
189 key modules is not recommended. In many cases extension modules are not
190 designed to be initialized more than once, and may fail in arbitrary ways
191 when reloaded.
192
193 If a module imports objects from another module using :keyword:`from` ...
194 :keyword:`import` ..., calling :func:`reload` for the other module does not
195 redefine the objects imported from it --- one way around this is to
196 re-execute the :keyword:`!from` statement, another is to use :keyword:`!import`
197 and qualified names (*module.name*) instead.
198
199 If a module instantiates instances of a class, reloading the module that
200 defines the class does not affect the method definitions of the instances ---
201 they continue to use the old class definition. The same is true for derived
202 classes.
203
204 .. versionadded:: 3.4
205 .. versionchanged:: 3.7
206 :exc:`ModuleNotFoundError` is raised when the module being reloaded lacks
207 a :class:`~importlib.machinery.ModuleSpec`.
208
209 .. warning::
210 This function is not thread-safe. Calling it from multiple threads can result
211 in unexpected behavior. It's recommended to use the :class:`threading.Lock`
212 or other synchronization primitives for thread-safe module reloading.
213
214 :mod:`!importlib.abc` -- Abstract base classes related to import
215 ----------------------------------------------------------------
216
217 .. module:: importlib.abc
218 :synopsis: Abstract base classes related to import
219
220 **Source code:** :source:`Lib/importlib/abc.py`
221
222 --------------
223
224
225 The :mod:`!importlib.abc` module contains all of the core abstract base classes
226 used by :keyword:`import`. Some subclasses of the core abstract base classes
227 are also provided to help in implementing the core ABCs.
228
229 ABC hierarchy::
230
231 object
232 +-- MetaPathFinder
233 +-- PathEntryFinder
234 +-- Loader
235 +-- ResourceLoader --------+
236 +-- InspectLoader |
237 +-- ExecutionLoader --+
238 +-- FileLoader
239 +-- SourceLoader
240
241
242 .. class:: MetaPathFinder
243
244 An abstract base class representing a :term:`meta path finder`.
245
246 .. versionadded:: 3.3
247
248 .. versionchanged:: 3.10
249 No longer a subclass of :class:`!Finder`.
250
251 .. method:: find_spec(fullname, path, target=None)
252
253 An abstract method for finding a :term:`spec <module spec>` for
254 the specified module. If this is a top-level import, *path* will
255 be ``None``. Otherwise, this is a search for a subpackage or
256 module and *path* will be the value of :attr:`~module.__path__` from the
257 parent package. If a spec cannot be found, ``None`` is returned.
258 When passed in, ``target`` is a module object that the finder may
259 use to make a more educated guess about what spec to return.
260 :func:`importlib.util.spec_from_loader` may be useful for implementing
261 concrete ``MetaPathFinders``.
262
263 .. versionadded:: 3.4
264
265 .. method:: invalidate_caches()
266
267 An optional method which, when called, should invalidate any internal
268 cache used by the finder. Used by :func:`importlib.invalidate_caches`
269 when invalidating the caches of all finders on :data:`sys.meta_path`.
270
271 .. versionchanged:: 3.4
272 Returns ``None`` when called instead of :data:`NotImplemented`.
273
274
275 .. class:: PathEntryFinder
276
277 An abstract base class representing a :term:`path entry finder`. Though
278 it bears some similarities to :class:`MetaPathFinder`, ``PathEntryFinder``
279 is meant for use only within the path-based import subsystem provided
280 by :class:`importlib.machinery.PathFinder`.
281
282 .. versionadded:: 3.3
283
284 .. versionchanged:: 3.10
285 No longer a subclass of :class:`!Finder`.
286
287 .. method:: find_spec(fullname, target=None)
288
289 An abstract method for finding a :term:`spec <module spec>` for
290 the specified module. The finder will search for the module only
291 within the :term:`path entry` to which it is assigned. If a spec
292 cannot be found, ``None`` is returned. When passed in, ``target``
293 is a module object that the finder may use to make a more educated
294 guess about what spec to return. :func:`importlib.util.spec_from_loader`
295 may be useful for implementing concrete ``PathEntryFinders``.
296
297 .. versionadded:: 3.4
298
299 .. method:: invalidate_caches()
300
301 An optional method which, when called, should invalidate any internal
302 cache used by the finder. Used by
303 :meth:`importlib.machinery.PathFinder.invalidate_caches`
304 when invalidating the caches of all cached finders.
305
306
307 .. class:: Loader
308
309 An abstract base class for a :term:`loader`.
310 See :pep:`302` for the exact definition for a loader.
311
312 Loaders that wish to support resource reading should implement a
313 :meth:`get_resource_reader` method as specified by
314 :class:`importlib.resources.abc.ResourceReader`.
315
316 .. versionchanged:: 3.7
317 Introduced the optional :meth:`get_resource_reader` method.
318
319 .. method:: create_module(spec)
320
321 A method that returns the module object to use when
322 importing a module. This method may return ``None``,
323 indicating that default module creation semantics should take place.
324
325 .. versionadded:: 3.4
326
327 .. versionchanged:: 3.6
328 This method is no longer optional when
329 :meth:`exec_module` is defined.
330
331 .. method:: exec_module(module)
332
333 An abstract method that executes the module in its own namespace
334 when a module is imported or reloaded. The module should already
335 be initialized when :meth:`exec_module` is called. When this method exists,
336 :meth:`create_module` must be defined.
337
338 .. versionadded:: 3.4
339
340 .. versionchanged:: 3.6
341 :meth:`create_module` must also be defined.
342
343 .. method:: load_module(fullname)
344
345 A legacy method for loading a module. If the module cannot be
346 loaded, :exc:`ImportError` is raised, otherwise the loaded module is
347 returned.
348
349 If the requested module already exists in :data:`sys.modules`, that
350 module should be used and reloaded.
351 Otherwise the loader should create a new module and insert it into
352 :data:`sys.modules` before any loading begins, to prevent recursion
353 from the import. If the loader inserted a module and the load fails, it
354 must be removed by the loader from :data:`sys.modules`; modules already
355 in :data:`sys.modules` before the loader began execution should be left
356 alone.
357
358 The loader should set several attributes on the module
359 (note that some of these attributes can change when a module is
360 reloaded):
361
362 - :attr:`module.__name__`
363 - :attr:`module.__file__`
364 - :attr:`module.__cached__` *(deprecated)*
365 - :attr:`module.__path__`
366 - :attr:`module.__package__` *(deprecated)*
367 - :attr:`module.__loader__` *(deprecated)*
368
369 When :meth:`exec_module` is available then backwards-compatible
370 functionality is provided.
371
372 .. versionchanged:: 3.4
373 Raise :exc:`ImportError` when called instead of
374 :exc:`NotImplementedError`. Functionality provided when
375 :meth:`exec_module` is available.
376
377 .. deprecated-removed:: 3.4 3.15
378 The recommended API for loading a module is :meth:`exec_module`
379 (and :meth:`create_module`). Loaders should implement it instead of
380 :meth:`load_module`. The import machinery takes care of all the
381 other responsibilities of :meth:`load_module` when
382 :meth:`exec_module` is implemented.
383
384
385 .. class:: ResourceLoader
386
387 *Superseded by TraversableResources*
388
389 An abstract base class for a :term:`loader` which implements the optional
390 :pep:`302` protocol for loading arbitrary resources from the storage
391 back-end.
392
393 .. deprecated:: 3.7
394 This ABC is deprecated in favour of supporting resource loading
395 through :class:`importlib.resources.abc.TraversableResources`.
396 This class exists for backwards compatibility only with other ABCs in
397 this module.
398
399 .. method:: get_data(path)
400 :abstractmethod:
401
402 An abstract method to return the bytes for the data located at *path*.
403 Loaders that have a file-like storage back-end
404 that allows storing arbitrary data
405 can implement this abstract method to give direct access
406 to the data stored. :exc:`OSError` is to be raised if the *path* cannot
407 be found. The *path* is expected to be constructed using a module's
408 :attr:`~module.__file__` attribute or an item from a package's
409 :attr:`~module.__path__`.
410
411 .. versionchanged:: 3.4
412 Raises :exc:`OSError` instead of :exc:`NotImplementedError`.
413
414
415 .. class:: InspectLoader
416
417 An abstract base class for a :term:`loader` which implements the optional
418 :pep:`302` protocol for loaders that inspect modules.
419
420 .. method:: get_code(fullname)
421
422 Return the code object for a module, or ``None`` if the module does not
423 have a code object (as would be the case, for example, for a built-in
424 module). Raise an :exc:`ImportError` if loader cannot find the
425 requested module.
426
427 .. note::
428 While the method has a default implementation, it is suggested that
429 it be overridden if possible for performance.
430
431 .. index::
432 single: universal newlines; importlib.abc.InspectLoader.get_source method
433
434 .. versionchanged:: 3.4
435 No longer abstract and a concrete implementation is provided.
436
437 .. method:: get_source(fullname)
438 :abstractmethod:
439
440 An abstract method to return the source of a module. It is returned as
441 a text string using :term:`universal newlines`, translating all
442 recognized line separators into ``'\n'`` characters. Returns ``None``
443 if no source is available (e.g. a built-in module). Raises
444 :exc:`ImportError` if the loader cannot find the module specified.
445
446 .. versionchanged:: 3.4
447 Raises :exc:`ImportError` instead of :exc:`NotImplementedError`.
448
449 .. method:: is_package(fullname)
450
451 An optional method to return a true value if the module is a package, a
452 false value otherwise. :exc:`ImportError` is raised if the
453 :term:`loader` cannot find the module.
454
455 .. versionchanged:: 3.4
456 Raises :exc:`ImportError` instead of :exc:`NotImplementedError`.
457
458 .. staticmethod:: source_to_code(data, path='<string>')
459
460 Create a code object from Python source.
461
462 The *data* argument can be whatever the :func:`compile` function
463 supports (i.e. string or bytes). The *path* argument should be
464 the "path" to where the source code originated from, which can be an
465 abstract concept (e.g. location in a zip file).
466
467 With the subsequent code object one can execute it in a module by
468 running ``exec(code, module.__dict__)``.
469
470 .. versionadded:: 3.4
471
472 .. versionchanged:: 3.5
473 Made the method static.
474
475 .. method:: exec_module(module)
476
477 Implementation of :meth:`Loader.exec_module`.
478
479 .. versionadded:: 3.4
480
481 .. method:: load_module(fullname)
482
483 Implementation of :meth:`Loader.load_module`.
484
485 .. deprecated-removed:: 3.4 3.15
486 use :meth:`exec_module` instead.
487
488
489 .. class:: ExecutionLoader
490
491 An abstract base class which inherits from :class:`InspectLoader` that,
492 when implemented, helps a module to be executed as a script. The ABC
493 represents an optional :pep:`302` protocol.
494
495 .. method:: get_filename(fullname)
496 :abstractmethod:
497
498 An abstract method that is to return the value of
499 :attr:`~module.__file__` for the specified module. If no path is
500 available, :exc:`ImportError` is raised.
501
502 If source code is available, then the method should return the path to
503 the source file, regardless of whether a bytecode was used to load the
504 module.
505
506 .. versionchanged:: 3.4
507 Raises :exc:`ImportError` instead of :exc:`NotImplementedError`.
508
509
510 .. class:: FileLoader(fullname, path)
511
512 An abstract base class which inherits from :class:`ResourceLoader` and
513 :class:`ExecutionLoader`, providing concrete implementations of
514 :meth:`ResourceLoader.get_data` and :meth:`ExecutionLoader.get_filename`.
515
516 The *fullname* argument is a fully resolved name of the module the loader is
517 to handle. The *path* argument is the path to the file for the module.
518
519 .. versionadded:: 3.3
520
521 .. attribute:: name
522
523 The name of the module the loader can handle.
524
525 .. attribute:: path
526
527 Path to the file of the module.
528
529 .. method:: load_module(fullname)
530
531 Calls super's ``load_module()``.
532
533 .. deprecated-removed:: 3.4 3.15
534 Use :meth:`Loader.exec_module` instead.
535
536 .. method:: get_filename(fullname)
537 :abstractmethod:
538
539 Returns :attr:`path`.
540
541 .. method:: get_data(path)
542 :abstractmethod:
543
544 Reads *path* as a binary file and returns the bytes from it.
545
546
547 .. class:: SourceLoader
548
549 An abstract base class for implementing source (and optionally bytecode)
550 file loading. The class inherits from both :class:`ResourceLoader` and
551 :class:`ExecutionLoader`, requiring the implementation of:
552
553 * :meth:`ResourceLoader.get_data`
554 * :meth:`ExecutionLoader.get_filename`
555 Should only return the path to the source file; sourceless
556 loading is not supported.
557
558 The abstract methods defined by this class are to add optional bytecode
559 file support. Not implementing these optional methods (or causing them to
560 raise :exc:`NotImplementedError`) causes the loader to
561 only work with source code. Implementing the methods allows the loader to
562 work with source *and* bytecode files; it does not allow for *sourceless*
563 loading where only bytecode is provided. Bytecode files are an
564 optimization to speed up loading by removing the parsing step of Python's
565 compiler, and so no bytecode-specific API is exposed.
566
567 .. method:: path_stats(path)
568
569 Optional abstract method which returns a :class:`dict` containing
570 metadata about the specified path. Supported dictionary keys are:
571
572 - ``'mtime'`` (mandatory): an integer or floating-point number
573 representing the modification time of the source code;
574 - ``'size'`` (optional): the size in bytes of the source code.
575
576 Any other keys in the dictionary are ignored, to allow for future
577 extensions. If the path cannot be handled, :exc:`OSError` is raised.
578
579 .. versionadded:: 3.3
580
581 .. versionchanged:: 3.4
582 Raise :exc:`OSError` instead of :exc:`NotImplementedError`.
583
584 .. method:: path_mtime(path)
585
586 Optional abstract method which returns the modification time for the
587 specified path.
588
589 .. deprecated:: 3.3
590 This method is deprecated in favour of :meth:`path_stats`. You don't
591 have to implement it, but it is still available for compatibility
592 purposes. Raise :exc:`OSError` if the path cannot be handled.
593
594 .. versionchanged:: 3.4
595 Raise :exc:`OSError` instead of :exc:`NotImplementedError`.
596
597 .. method:: set_data(path, data)
598
599 Optional abstract method which writes the specified bytes to a file
600 path. Any intermediate directories which do not exist are to be created
601 automatically.
602
603 When writing to the path fails because the path is read-only
604 (:const:`errno.EACCES`/:exc:`PermissionError`), do not propagate the
605 exception.
606
607 .. versionchanged:: 3.4
608 No longer raises :exc:`NotImplementedError` when called.
609
610 .. method:: get_code(fullname)
611
612 Concrete implementation of :meth:`InspectLoader.get_code`.
613
614 .. method:: exec_module(module)
615
616 Concrete implementation of :meth:`Loader.exec_module`.
617
618 .. versionadded:: 3.4
619
620 .. method:: load_module(fullname)
621
622 Concrete implementation of :meth:`Loader.load_module`.
623
624 .. deprecated-removed:: 3.4 3.15
625 Use :meth:`exec_module` instead.
626
627 .. method:: get_source(fullname)
628
629 Concrete implementation of :meth:`InspectLoader.get_source`.
630
631 .. method:: is_package(fullname)
632
633 Concrete implementation of :meth:`InspectLoader.is_package`. A module
634 is determined to be a package if its file path (as provided by
635 :meth:`ExecutionLoader.get_filename`) is a file named
636 ``__init__`` when the file extension is removed **and** the module name
637 itself does not end in ``__init__``.
638
639
640 :mod:`!importlib.machinery` -- Importers and path hooks
641 -------------------------------------------------------
642
643 .. module:: importlib.machinery
644 :synopsis: Importers and path hooks
645
646 **Source code:** :source:`Lib/importlib/machinery.py`
647
648 --------------
649
650 This module contains the various objects that help :keyword:`import`
651 find and load modules.
652
653 .. data:: SOURCE_SUFFIXES
654
655 A list of strings representing the recognized file suffixes for source
656 modules.
657
658 .. versionadded:: 3.3
659
660 .. data:: DEBUG_BYTECODE_SUFFIXES
661
662 A list of strings representing the file suffixes for non-optimized bytecode
663 modules.
664
665 .. versionadded:: 3.3
666
667 .. deprecated:: 3.5
668 Use :const:`BYTECODE_SUFFIXES` instead.
669
670 .. data:: OPTIMIZED_BYTECODE_SUFFIXES
671
672 A list of strings representing the file suffixes for optimized bytecode
673 modules.
674
675 .. versionadded:: 3.3
676
677 .. deprecated:: 3.5
678 Use :const:`BYTECODE_SUFFIXES` instead.
679
680 .. data:: BYTECODE_SUFFIXES
681
682 A list of strings representing the recognized file suffixes for bytecode
683 modules (including the leading dot).
684
685 .. versionadded:: 3.3
686
687 .. versionchanged:: 3.5
688 The value is no longer dependent on ``__debug__``.
689
690 .. data:: EXTENSION_SUFFIXES
691
692 A list of strings representing the recognized file suffixes for
693 extension modules.
694
695 .. versionadded:: 3.3
696
697 .. function:: all_suffixes()
698
699 Returns a combined list of strings representing all file suffixes for
700 modules recognized by the standard import machinery. This is a
701 helper for code which simply needs to know if a filesystem path
702 potentially refers to a module without needing any details on the kind
703 of module (for example, :func:`inspect.getmodulename`).
704
705 .. versionadded:: 3.3
706
707
708 .. class:: BuiltinImporter
709
710 An :term:`importer` for built-in modules. All known built-in modules are
711 listed in :data:`sys.builtin_module_names`. This class implements the
712 :class:`importlib.abc.MetaPathFinder` and
713 :class:`importlib.abc.InspectLoader` ABCs.
714
715 Only class methods are defined by this class to alleviate the need for
716 instantiation.
717
718 .. versionchanged:: 3.5
719 As part of :pep:`489`, the builtin importer now implements
720 :meth:`Loader.create_module` and :meth:`Loader.exec_module`
721
722
723 .. class:: FrozenImporter
724
725 An :term:`importer` for frozen modules. This class implements the
726 :class:`importlib.abc.MetaPathFinder` and
727 :class:`importlib.abc.InspectLoader` ABCs.
728
729 Only class methods are defined by this class to alleviate the need for
730 instantiation.
731
732 .. versionchanged:: 3.4
733 Gained :meth:`~Loader.create_module` and :meth:`~Loader.exec_module`
734 methods.
735
736
737 .. class:: WindowsRegistryFinder
738
739 :term:`Finder <finder>` for modules declared in the Windows registry. This class
740 implements the :class:`importlib.abc.MetaPathFinder` ABC.
741
742 Only class methods are defined by this class to alleviate the need for
743 instantiation.
744
745 .. versionadded:: 3.3
746
747 .. deprecated:: 3.6
748 Use :mod:`site` configuration instead. Future versions of Python may
749 not enable this finder by default.
750
751
752 .. class:: PathFinder
753
754 A :term:`Finder <finder>` for :data:`sys.path` and package ``__path__`` attributes.
755 This class implements the :class:`importlib.abc.MetaPathFinder` ABC.
756
757 Only class methods are defined by this class to alleviate the need for
758 instantiation.
759
760 .. classmethod:: find_spec(fullname, path=None, target=None)
761
762 Class method that attempts to find a :term:`spec <module spec>`
763 for the module specified by *fullname* on :data:`sys.path` or, if
764 defined, on *path*. For each path entry that is searched,
765 :data:`sys.path_importer_cache` is checked. If a non-false object
766 is found then it is used as the :term:`path entry finder` to look
767 for the module being searched for. If no entry is found in
768 :data:`sys.path_importer_cache`, then :data:`sys.path_hooks` is
769 searched for a finder for the path entry and, if found, is stored
770 in :data:`sys.path_importer_cache` along with being queried about
771 the module. If no finder is ever found then ``None`` is both
772 stored in the cache and returned.
773
774 .. versionadded:: 3.4
775
776 .. versionchanged:: 3.5
777 If the current working directory -- represented by an empty string --
778 is no longer valid then ``None`` is returned but no value is cached
779 in :data:`sys.path_importer_cache`.
780
781 .. classmethod:: invalidate_caches()
782
783 Calls :meth:`importlib.abc.PathEntryFinder.invalidate_caches` on all
784 finders stored in :data:`sys.path_importer_cache` that define the method.
785 Otherwise entries in :data:`sys.path_importer_cache` set to ``None`` are
786 deleted.
787
788 .. versionchanged:: 3.7
789 Entries of ``None`` in :data:`sys.path_importer_cache` are deleted.
790
791 .. versionchanged:: 3.4
792 Calls objects in :data:`sys.path_hooks` with the current working
793 directory for ``''`` (i.e. the empty string).
794
795
796 .. class:: FileFinder(path, *loader_details)
797
798 A concrete implementation of :class:`importlib.abc.PathEntryFinder` which
799 caches results from the file system.
800
801 The *path* argument is the directory for which the finder is in charge of
802 searching.
803
804 The *loader_details* argument is a variable number of 2-item tuples each
805 containing a loader and a sequence of file suffixes the loader recognizes.
806 The loaders are expected to be callables which accept two arguments of
807 the module's name and the path to the file found.
808
809 The finder will cache the directory contents as necessary, making stat calls
810 for each module search to verify the cache is not outdated. Because cache
811 staleness relies upon the granularity of the operating system's state
812 information of the file system, there is a potential race condition of
813 searching for a module, creating a new file, and then searching for the
814 module the new file represents. If the operations happen fast enough to fit
815 within the granularity of stat calls, then the module search will fail. To
816 prevent this from happening, when you create a module dynamically, make sure
817 to call :func:`importlib.invalidate_caches`.
818
819 .. versionadded:: 3.3
820
821 .. attribute:: path
822
823 The path the finder will search in.
824
825 .. method:: find_spec(fullname, target=None)
826
827 Attempt to find the spec to handle *fullname* within :attr:`path`.
828
829 .. versionadded:: 3.4
830
831 .. method:: invalidate_caches()
832
833 Clear out the internal cache.
834
835 .. classmethod:: path_hook(*loader_details)
836
837 A class method which returns a closure for use on :data:`sys.path_hooks`.
838 An instance of :class:`FileFinder` is returned by the closure using the
839 path argument given to the closure directly and *loader_details*
840 indirectly.
841
842 If the argument to the closure is not an existing directory,
843 :exc:`ImportError` is raised.
844
845
846 .. class:: SourceFileLoader(fullname, path)
847
848 A concrete implementation of :class:`importlib.abc.SourceLoader` by
849 subclassing :class:`importlib.abc.FileLoader` and providing some concrete
850 implementations of other methods.
851
852 .. versionadded:: 3.3
853
854 .. attribute:: name
855
856 The name of the module that this loader will handle.
857
858 .. attribute:: path
859
860 The path to the source file.
861
862 .. method:: is_package(fullname)
863
864 Return ``True`` if :attr:`path` appears to be for a package.
865
866 .. method:: path_stats(path)
867
868 Concrete implementation of :meth:`importlib.abc.SourceLoader.path_stats`.
869
870 .. method:: set_data(path, data)
871
872 Concrete implementation of :meth:`importlib.abc.SourceLoader.set_data`.
873
874 .. method:: load_module(name=None)
875
876 Concrete implementation of :meth:`importlib.abc.Loader.load_module` where
877 specifying the name of the module to load is optional.
878
879 .. deprecated-removed:: 3.6 3.15
880
881 Use :meth:`importlib.abc.Loader.exec_module` instead.
882
883
884 .. class:: SourcelessFileLoader(fullname, path)
885
886 A concrete implementation of :class:`importlib.abc.FileLoader` which can
887 import bytecode files (i.e. no source code files exist).
888
889 Please note that direct use of bytecode files (and thus not source code
890 files) inhibits your modules from being usable by all Python
891 implementations or new versions of Python which change the bytecode
892 format.
893
894 .. versionadded:: 3.3
895
896 .. attribute:: name
897
898 The name of the module the loader will handle.
899
900 .. attribute:: path
901
902 The path to the bytecode file.
903
904 .. method:: is_package(fullname)
905
906 Determines if the module is a package based on :attr:`path`.
907
908 .. method:: get_code(fullname)
909
910 Returns the code object for :attr:`name` created from :attr:`path`.
911
912 .. method:: get_source(fullname)
913
914 Returns ``None`` as bytecode files have no source when this loader is
915 used.
916
917 .. method:: load_module(name=None)
918
919 Concrete implementation of :meth:`importlib.abc.Loader.load_module` where
920 specifying the name of the module to load is optional.
921
922 .. deprecated-removed:: 3.6 3.15
923
924 Use :meth:`importlib.abc.Loader.exec_module` instead.
925
926
927 .. class:: ExtensionFileLoader(fullname, path)
928
929 A concrete implementation of :class:`importlib.abc.ExecutionLoader` for
930 extension modules.
931
932 The *fullname* argument specifies the name of the module the loader is to
933 support. The *path* argument is the path to the extension module's file.
934
935 Note that, by default, importing an extension module will fail
936 in subinterpreters if it doesn't implement multi-phase init
937 (see :pep:`489`), even if it would otherwise import successfully.
938
939 .. versionadded:: 3.3
940
941 .. versionchanged:: 3.12
942 Multi-phase init is now required for use in subinterpreters.
943
944 .. attribute:: name
945
946 Name of the module the loader supports.
947
948 .. attribute:: path
949
950 Path to the extension module.
951
952 .. method:: create_module(spec)
953
954 Creates the module object from the given specification in accordance
955 with :pep:`489`.
956
957 .. versionadded:: 3.5
958
959 .. method:: exec_module(module)
960
961 Initializes the given module object in accordance with :pep:`489`.
962
963 .. versionadded:: 3.5
964
965 .. method:: is_package(fullname)
966
967 Returns ``True`` if the file path points to a package's ``__init__``
968 module based on :const:`EXTENSION_SUFFIXES`.
969
970 .. method:: get_code(fullname)
971
972 Returns ``None`` as extension modules lack a code object.
973
974 .. method:: get_source(fullname)
975
976 Returns ``None`` as extension modules do not have source code.
977
978 .. method:: get_filename(fullname)
979
980 Returns :attr:`path`.
981
982 .. versionadded:: 3.4
983
984
985 .. class:: NamespaceLoader(name, path, path_finder)
986
987 A concrete implementation of :class:`importlib.abc.InspectLoader` for
988 namespace packages. This is an alias for a private class and is only made
989 public for introspecting the ``__loader__`` attribute on namespace
990 packages::
991
992 >>> from importlib.machinery import NamespaceLoader
993 >>> import my_namespace
994 >>> isinstance(my_namespace.__loader__, NamespaceLoader)
995 True
996 >>> import importlib.abc
997 >>> isinstance(my_namespace.__loader__, importlib.abc.Loader)
998 True
999
1000 .. versionadded:: 3.11
1001
1002
1003 .. class:: ModuleSpec(name, loader, *, origin=None, loader_state=None, is_package=None)
1004
1005 A specification for a module's import-system-related state. This is
1006 typically exposed as the module's :attr:`~module.__spec__` attribute. Many
1007 of these attributes are also available directly on a module: for example,
1008 ``module.__spec__.origin == module.__file__``. Note, however, that
1009 while the *values* are usually equivalent, they can differ since there is
1010 no synchronization between the two objects. For example, it is possible to
1011 update the module's :attr:`~module.__file__` at runtime and this will not be
1012 automatically reflected in the module's
1013 :attr:`__spec__.origin <ModuleSpec.origin>`, and vice versa.
1014
1015 .. versionadded:: 3.4
1016
1017 .. attribute:: name
1018
1019 The module's fully qualified name (see :attr:`module.__name__`).
1020 The :term:`finder` should always set this attribute to a non-empty string.
1021
1022 .. attribute:: loader
1023
1024 The :term:`loader` used to load the module (see :attr:`module.__loader__`).
1025 The :term:`finder` should always set this attribute.
1026
1027 .. attribute:: origin
1028
1029 The location the :term:`loader` should use to load the module
1030 (see :attr:`module.__file__`).
1031 For example, for modules loaded from a ``.py`` file this is the filename.
1032 The :term:`finder` should always set this attribute to a meaningful value
1033 for the :term:`loader` to use. In the uncommon case that there is not one
1034 (like for namespace packages), it should be set to ``None``.
1035
1036 .. attribute:: submodule_search_locations
1037
1038 A (possibly empty) :term:`sequence` of strings enumerating the locations
1039 in which a package's submodules will be found
1040 (see :attr:`module.__path__`). Most of the time there will only be a
1041 single directory in this list.
1042
1043 The :term:`finder` should set this attribute to a sequence, even an empty
1044 one, to indicate
1045 to the import system that the module is a package. It should be set to ``None`` for
1046 non-package modules. It is set automatically later to a special object for
1047 namespace packages.
1048
1049 .. attribute:: loader_state
1050
1051 The :term:`finder` may set this attribute to an object containing additional,
1052 module-specific data to use when loading the module. Otherwise it should be
1053 set to ``None``.
1054
1055 .. attribute:: cached
1056
1057 The filename of a compiled version of the module's code
1058 (see :attr:`module.__cached__`).
1059 The :term:`finder` should always set this attribute but it may be ``None``
1060 for modules that do not need compiled code stored.
1061
1062 .. attribute:: parent
1063
1064 (Read-only) The fully qualified name of the package the module is in (or the
1065 empty string for a top-level module).
1066 See :attr:`module.__package__`.
1067 If the module is a package then this is the same as :attr:`name`.
1068
1069 .. attribute:: has_location
1070
1071 ``True`` if the spec's :attr:`origin` refers to a loadable location,
1072 ``False`` otherwise. This value impacts how :attr:`!origin` is interpreted
1073 and how the module's :attr:`~module.__file__` is populated.
1074
1075
1076 .. class:: AppleFrameworkLoader(name, path)
1077
1078 A specialization of :class:`importlib.machinery.ExtensionFileLoader` that
1079 is able to load extension modules in Framework format.
1080
1081 For compatibility with the iOS App Store, *all* binary modules in an iOS app
1082 must be dynamic libraries, contained in a framework with appropriate
1083 metadata, stored in the ``Frameworks`` folder of the packaged app. There can
1084 be only a single binary per framework, and there can be no executable binary
1085 material outside the Frameworks folder.
1086
1087 To accommodate this requirement, when running on iOS, extension module
1088 binaries are *not* packaged as ``.so`` files on ``sys.path``, but as
1089 individual standalone frameworks. To discover those frameworks, this loader
1090 is registered against the ``.fwork`` file extension, with a ``.fwork``
1091 file acting as a placeholder in the original location of the binary on
1092 ``sys.path``. The ``.fwork`` file contains the path of the actual binary in
1093 the ``Frameworks`` folder, relative to the app bundle. To allow for
1094 resolving a framework-packaged binary back to the original location, the
1095 framework is expected to contain a ``.origin`` file that contains the
1096 location of the ``.fwork`` file, relative to the app bundle.
1097
1098 For example, consider the case of an import ``from foo.bar import _whiz``,
1099 where ``_whiz`` is implemented with the binary module
1100 ``sources/foo/bar/_whiz.abi3.so``, with ``sources`` being the location
1101 registered on ``sys.path``, relative to the application bundle. This module
1102 *must* be distributed as
1103 ``Frameworks/foo.bar._whiz.framework/foo.bar._whiz`` (creating the framework
1104 name from the full import path of the module), with an ``Info.plist`` file
1105 in the ``.framework`` directory identifying the binary as a framework. The
1106 ``foo.bar._whiz`` module would be represented in the original location with
1107 a ``sources/foo/bar/_whiz.abi3.fwork`` marker file, containing the path
1108 ``Frameworks/foo.bar._whiz/foo.bar._whiz``. The framework would also contain
1109 ``Frameworks/foo.bar._whiz.framework/foo.bar._whiz.origin``, containing the
1110 path to the ``.fwork`` file.
1111
1112 When a module is loaded with this loader, the ``__file__`` for the module
1113 will report as the location of the ``.fwork`` file. This allows code to use
1114 the ``__file__`` of a module as an anchor for file system traversal.
1115 However, the spec origin will reference the location of the *actual* binary
1116 in the ``.framework`` folder.
1117
1118 The Xcode project building the app is responsible for converting any ``.so``
1119 files from wherever they exist in the ``PYTHONPATH`` into frameworks in the
1120 ``Frameworks`` folder (including stripping extensions from the module file,
1121 the addition of framework metadata, and signing the resulting framework),
1122 and creating the ``.fwork`` and ``.origin`` files. This will usually be done
1123 with a build step in the Xcode project; see the iOS documentation for
1124 details on how to construct this build step.
1125
1126 .. versionadded:: 3.13
1127
1128 .. availability:: iOS.
1129
1130 .. attribute:: name
1131
1132 Name of the module the loader supports.
1133
1134 .. attribute:: path
1135
1136 Path to the ``.fwork`` file for the extension module.
1137
1138
1139 :mod:`!importlib.util` -- Utility code for importers
1140 ----------------------------------------------------
1141
1142 .. module:: importlib.util
1143 :synopsis: Utility code for importers
1144
1145
1146 **Source code:** :source:`Lib/importlib/util.py`
1147
1148 --------------
1149
1150 This module contains the various objects that help in the construction of
1151 an :term:`importer`.
1152
1153 .. data:: MAGIC_NUMBER
1154
1155 The bytes which represent the bytecode version number. If you need help with
1156 loading/writing bytecode then consider :class:`importlib.abc.SourceLoader`.
1157
1158 .. versionadded:: 3.4
1159
1160 .. function:: cache_from_source(path, debug_override=None, *, optimization=None)
1161
1162 Return the :pep:`3147`/:pep:`488` path to the byte-compiled file associated
1163 with the source *path*. For example, if *path* is ``/foo/bar/baz.py`` the return
1164 value would be ``/foo/bar/__pycache__/baz.cpython-32.pyc`` for Python 3.2.
1165 The ``cpython-32`` string comes from the current magic tag (see
1166 :func:`get_tag`; if :attr:`sys.implementation.cache_tag` is not defined then
1167 :exc:`NotImplementedError` will be raised).
1168
1169 The *optimization* parameter is used to specify the optimization level of the
1170 bytecode file. An empty string represents no optimization, so
1171 ``/foo/bar/baz.py`` with an *optimization* of ``''`` will result in a
1172 bytecode path of ``/foo/bar/__pycache__/baz.cpython-32.pyc``. ``None`` causes
1173 the interpreter's optimization level to be used. Any other value's string
1174 representation is used, so ``/foo/bar/baz.py`` with an *optimization* of
1175 ``2`` will lead to the bytecode path of
1176 ``/foo/bar/__pycache__/baz.cpython-32.opt-2.pyc``. The string representation
1177 of *optimization* can only be alphanumeric, else :exc:`ValueError` is raised.
1178
1179 The *debug_override* parameter is deprecated and can be used to override
1180 the system's value for ``__debug__``. A ``True`` value is the equivalent of
1181 setting *optimization* to the empty string. A ``False`` value is the same as
1182 setting *optimization* to ``1``. If both *debug_override* an *optimization*
1183 are not ``None`` then :exc:`TypeError` is raised.
1184
1185 .. versionadded:: 3.4
1186
1187 .. versionchanged:: 3.5
1188 The *optimization* parameter was added and the *debug_override* parameter
1189 was deprecated.
1190
1191 .. versionchanged:: 3.6
1192 Accepts a :term:`path-like object`.
1193
1194
1195 .. function:: source_from_cache(path)
1196
1197 Given the *path* to a :pep:`3147` file name, return the associated source code
1198 file path. For example, if *path* is
1199 ``/foo/bar/__pycache__/baz.cpython-32.pyc`` the returned path would be
1200 ``/foo/bar/baz.py``. *path* need not exist, however if it does not conform
1201 to :pep:`3147` or :pep:`488` format, a :exc:`ValueError` is raised. If
1202 :attr:`sys.implementation.cache_tag` is not defined,
1203 :exc:`NotImplementedError` is raised.
1204
1205 .. versionadded:: 3.4
1206
1207 .. versionchanged:: 3.6
1208 Accepts a :term:`path-like object`.
1209
1210 .. function:: decode_source(source_bytes)
1211
1212 Decode the given bytes representing source code and return it as a string
1213 with universal newlines (as required by
1214 :meth:`importlib.abc.InspectLoader.get_source`).
1215
1216 .. versionadded:: 3.4
1217
1218 .. function:: resolve_name(name, package)
1219
1220 Resolve a relative module name to an absolute one.
1221
1222 If **name** has no leading dots, then **name** is simply returned. This
1223 allows for usage such as
1224 ``importlib.util.resolve_name('sys', __spec__.parent)`` without doing a
1225 check to see if the **package** argument is needed.
1226
1227 :exc:`ImportError` is raised if **name** is a relative module name but
1228 **package** is a false value (e.g. ``None`` or the empty string).
1229 :exc:`ImportError` is also raised if a relative name would escape its
1230 containing package (e.g. requesting ``..bacon`` from within the ``spam``
1231 package).
1232
1233 .. versionadded:: 3.3
1234
1235 .. versionchanged:: 3.9
1236 To improve consistency with import statements, raise
1237 :exc:`ImportError` instead of :exc:`ValueError` for invalid relative
1238 import attempts.
1239
1240 .. function:: find_spec(name, package=None)
1241
1242 Find the :term:`spec <module spec>` for a module, optionally relative to
1243 the specified **package** name. If the module is in :data:`sys.modules`,
1244 then ``sys.modules[name].__spec__`` is returned (unless the spec would be
1245 ``None`` or is not set, in which case :exc:`ValueError` is raised).
1246 Otherwise a search using :data:`sys.meta_path` is done. ``None`` is
1247 returned if no spec is found.
1248
1249 If **name** is for a submodule (contains a dot), the parent module is
1250 automatically imported.
1251
1252 **name** and **package** work the same as for :func:`import_module`.
1253
1254 .. versionadded:: 3.4
1255
1256 .. versionchanged:: 3.7
1257 Raises :exc:`ModuleNotFoundError` instead of :exc:`AttributeError` if
1258 **package** is in fact not a package (i.e. lacks a
1259 :attr:`~module.__path__` attribute).
1260
1261 .. function:: module_from_spec(spec)
1262
1263 Create a new module based on **spec** and
1264 :meth:`spec.loader.create_module <importlib.abc.Loader.create_module>`.
1265
1266 If :meth:`spec.loader.create_module <importlib.abc.Loader.create_module>`
1267 does not return ``None``, then any pre-existing attributes will not be reset.
1268 Also, no :exc:`AttributeError` will be raised if triggered while accessing
1269 **spec** or setting an attribute on the module.
1270
1271 This function is preferred over using :class:`types.ModuleType` to create a
1272 new module as **spec** is used to set as many import-controlled attributes on
1273 the module as possible.
1274
1275 .. versionadded:: 3.5
1276
1277 .. function:: spec_from_loader(name, loader, *, origin=None, is_package=None)
1278
1279 A factory function for creating a :class:`~importlib.machinery.ModuleSpec`
1280 instance based on a loader. The parameters have the same meaning as they do
1281 for ModuleSpec. The function uses available :term:`loader` APIs, such as
1282 :meth:`InspectLoader.is_package`, to fill in any missing
1283 information on the spec.
1284
1285 .. versionadded:: 3.4
1286
1287 .. function:: spec_from_file_location(name, location, *, loader=None, submodule_search_locations=None)
1288
1289 A factory function for creating a :class:`~importlib.machinery.ModuleSpec`
1290 instance based on the path to a file. Missing information will be filled in
1291 on the spec by making use of loader APIs and by the implication that the
1292 module will be file-based.
1293
1294 .. versionadded:: 3.4
1295
1296 .. versionchanged:: 3.6
1297 Accepts a :term:`path-like object`.
1298
1299 .. function:: source_hash(source_bytes)
1300
1301 Return the hash of *source_bytes* as bytes. A hash-based ``.pyc`` file embeds
1302 the :func:`source_hash` of the corresponding source file's contents in its
1303 header.
1304
1305 .. versionadded:: 3.7
1306
1307 .. function:: _incompatible_extension_module_restrictions(*, disable_check)
1308
1309 A context manager that can temporarily skip the compatibility check
1310 for extension modules. By default the check is enabled and will fail
1311 when a single-phase init module is imported in a subinterpreter.
1312 It will also fail for a multi-phase init module that doesn't
1313 explicitly support a per-interpreter GIL, when imported
1314 in an interpreter with its own GIL.
1315
1316 Note that this function is meant to accommodate an unusual case;
1317 one which is likely to eventually go away. There's is a pretty good
1318 chance this is not what you were looking for.
1319
1320 You can get the same effect as this function by implementing the
1321 basic interface of multi-phase init (:pep:`489`) and lying about
1322 support for multiple interpreters (or per-interpreter GIL).
1323
1324 .. warning::
1325 Using this function to disable the check can lead to
1326 unexpected behavior and even crashes. It should only be used during
1327 extension module development.
1328
1329 .. versionadded:: 3.12
1330
1331 .. class:: LazyLoader(loader)
1332
1333 A class which postpones the execution of the loader of a module until the
1334 module has an attribute accessed.
1335
1336 This class **only** works with loaders that define
1337 :meth:`~importlib.abc.Loader.exec_module` as control over what module type
1338 is used for the module is required. For those same reasons, the loader's
1339 :meth:`~importlib.abc.Loader.create_module` method must return ``None`` or a
1340 type for which its ``__class__`` attribute can be mutated along with not
1341 using :term:`slots <__slots__>`. Finally, modules which substitute the object
1342 placed into :data:`sys.modules` will not work as there is no way to properly
1343 replace the module references throughout the interpreter safely;
1344 :exc:`ValueError` is raised if such a substitution is detected.
1345
1346 .. note::
1347 For projects where startup time is critical, this class allows for
1348 potentially minimizing the cost of loading a module if it is never used.
1349 For projects where startup time is not essential then use of this class is
1350 **heavily** discouraged due to error messages created during loading being
1351 postponed and thus occurring out of context.
1352
1353 .. versionadded:: 3.5
1354
1355 .. versionchanged:: 3.6
1356 Began calling :meth:`~importlib.abc.Loader.create_module`, removing the
1357 compatibility warning for :class:`importlib.machinery.BuiltinImporter` and
1358 :class:`importlib.machinery.ExtensionFileLoader`.
1359
1360 .. classmethod:: factory(loader)
1361
1362 A class method which returns a callable that creates a lazy loader. This
1363 is meant to be used in situations where the loader is passed by class
1364 instead of by instance.
1365 ::
1366
1367 suffixes = importlib.machinery.SOURCE_SUFFIXES
1368 loader = importlib.machinery.SourceFileLoader
1369 lazy_loader = importlib.util.LazyLoader.factory(loader)
1370 finder = importlib.machinery.FileFinder(path, (lazy_loader, suffixes))
1371
1372 .. _importlib-examples:
1373
1374 Examples
1375 --------
1376
1377 Importing programmatically
1378 ''''''''''''''''''''''''''
1379
1380 To programmatically import a module, use :func:`importlib.import_module`.
1381 ::
1382
1383 import importlib
1384
1385 itertools = importlib.import_module('itertools')
1386
1387
1388 Checking if a module can be imported
1389 ''''''''''''''''''''''''''''''''''''
1390
1391 If you need to find out if a module can be imported without actually doing the
1392 import, then you should use :func:`importlib.util.find_spec`.
1393
1394 Note that if ``name`` is a submodule (contains a dot),
1395 :func:`importlib.util.find_spec` will import the parent module.
1396 ::
1397
1398 import importlib.util
1399 import sys
1400
1401 # For illustrative purposes.
1402 name = 'itertools'
1403
1404 if name in sys.modules:
1405 print(f"{name!r} already in sys.modules")
1406 elif (spec := importlib.util.find_spec(name)) is not None:
1407 # If you chose to perform the actual import ...
1408 module = importlib.util.module_from_spec(spec)
1409 sys.modules[name] = module
1410 spec.loader.exec_module(module)
1411 print(f"{name!r} has been imported")
1412 else:
1413 print(f"can't find the {name!r} module")
1414
1415
1416 Importing a source file directly
1417 ''''''''''''''''''''''''''''''''
1418
1419 This recipe should be used with caution: it is an approximation of an import
1420 statement where the file path is specified directly, rather than
1421 :data:`sys.path` being searched. Alternatives should first be considered first,
1422 such as modifying :data:`sys.path` when a proper module is required, or using
1423 :func:`runpy.run_path` when the global namespace resulting from running a Python
1424 file is appropriate.
1425
1426 To import a Python source file directly from a path, use the following recipe::
1427
1428 import importlib.util
1429 import sys
1430
1431
1432 def import_from_path(module_name, file_path):
1433 spec = importlib.util.spec_from_file_location(module_name, file_path)
1434 module = importlib.util.module_from_spec(spec)
1435 sys.modules[module_name] = module
1436 spec.loader.exec_module(module)
1437 return module
1438
1439
1440 # For illustrative purposes only (use of `json` is arbitrary).
1441 import json
1442 file_path = json.__file__
1443 module_name = json.__name__
1444
1445 # Similar outcome as `import json`.
1446 json = import_from_path(module_name, file_path)
1447
1448
1449 Implementing lazy imports
1450 '''''''''''''''''''''''''
1451
1452 The example below shows how to implement lazy imports::
1453
1454 >>> import importlib.util
1455 >>> import sys
1456 >>> def lazy_import(name):
1457 ... spec = importlib.util.find_spec(name)
1458 ... loader = importlib.util.LazyLoader(spec.loader)
1459 ... spec.loader = loader
1460 ... module = importlib.util.module_from_spec(spec)
1461 ... sys.modules[name] = module
1462 ... loader.exec_module(module)
1463 ... return module
1464 ...
1465 >>> lazy_typing = lazy_import("typing")
1466 >>> #lazy_typing is a real module object,
1467 >>> #but it is not loaded in memory yet.
1468 >>> lazy_typing.TYPE_CHECKING
1469 False
1470
1471
1472 Setting up an importer
1473 ''''''''''''''''''''''
1474
1475 For deep customizations of import, you typically want to implement an
1476 :term:`importer`. This means managing both the :term:`finder` and :term:`loader`
1477 side of things. For finders there are two flavours to choose from depending on
1478 your needs: a :term:`meta path finder` or a :term:`path entry finder`. The
1479 former is what you would put on :data:`sys.meta_path` while the latter is what
1480 you create using a :term:`path entry hook` on :data:`sys.path_hooks` which works
1481 with :data:`sys.path` entries to potentially create a finder. This example will
1482 show you how to register your own importers so that import will use them (for
1483 creating an importer for yourself, read the documentation for the appropriate
1484 classes defined within this package)::
1485
1486 import importlib.machinery
1487 import sys
1488
1489 # For illustrative purposes only.
1490 SpamMetaPathFinder = importlib.machinery.PathFinder
1491 SpamPathEntryFinder = importlib.machinery.FileFinder
1492 loader_details = (importlib.machinery.SourceFileLoader,
1493 importlib.machinery.SOURCE_SUFFIXES)
1494
1495 # Setting up a meta path finder.
1496 # Make sure to put the finder in the proper location in the list in terms of
1497 # priority.
1498 sys.meta_path.append(SpamMetaPathFinder)
1499
1500 # Setting up a path entry finder.
1501 # Make sure to put the path hook in the proper location in the list in terms
1502 # of priority.
1503 sys.path_hooks.append(SpamPathEntryFinder.path_hook(loader_details))
1504
1505
1506 Approximating :func:`importlib.import_module`
1507 '''''''''''''''''''''''''''''''''''''''''''''
1508
1509 Import itself is implemented in Python code, making it possible to
1510 expose most of the import machinery through importlib. The following
1511 helps illustrate the various APIs that importlib exposes by providing an
1512 approximate implementation of
1513 :func:`importlib.import_module`::
1514
1515 import importlib.util
1516 import sys
1517
1518 def import_module(name, package=None):
1519 """An approximate implementation of import."""
1520 absolute_name = importlib.util.resolve_name(name, package)
1521 try:
1522 return sys.modules[absolute_name]
1523 except KeyError:
1524 pass
1525
1526 path = None
1527 if '.' in absolute_name:
1528 parent_name, _, child_name = absolute_name.rpartition('.')
1529 parent_module = import_module(parent_name)
1530 path = parent_module.__spec__.submodule_search_locations
1531 for finder in sys.meta_path:
1532 spec = finder.find_spec(absolute_name, path)
1533 if spec is not None:
1534 break
1535 else:
1536 msg = f'No module named {absolute_name!r}'
1537 raise ModuleNotFoundError(msg, name=absolute_name)
1538 module = importlib.util.module_from_spec(spec)
1539 sys.modules[absolute_name] = module
1540 spec.loader.exec_module(module)
1541 if path is not None:
1542 setattr(parent_module, child_name, module)
1543 return module