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
397 .. method:: get_data(path)
398 :abstractmethod:
399
400 An abstract method to return the bytes for the data located at *path*.
401 Loaders that have a file-like storage back-end
402 that allows storing arbitrary data
403 can implement this abstract method to give direct access
404 to the data stored. :exc:`OSError` is to be raised if the *path* cannot
405 be found. The *path* is expected to be constructed using a module's
406 :attr:`~module.__file__` attribute or an item from a package's
407 :attr:`~module.__path__`.
408
409 .. versionchanged:: 3.4
410 Raises :exc:`OSError` instead of :exc:`NotImplementedError`.
411
412
413 .. class:: InspectLoader
414
415 An abstract base class for a :term:`loader` which implements the optional
416 :pep:`302` protocol for loaders that inspect modules.
417
418 .. method:: get_code(fullname)
419
420 Return the code object for a module, or ``None`` if the module does not
421 have a code object (as would be the case, for example, for a built-in
422 module). Raise an :exc:`ImportError` if loader cannot find the
423 requested module.
424
425 .. note::
426 While the method has a default implementation, it is suggested that
427 it be overridden if possible for performance.
428
429 .. index::
430 single: universal newlines; importlib.abc.InspectLoader.get_source method
431
432 .. versionchanged:: 3.4
433 No longer abstract and a concrete implementation is provided.
434
435 .. method:: get_source(fullname)
436 :abstractmethod:
437
438 An abstract method to return the source of a module. It is returned as
439 a text string using :term:`universal newlines`, translating all
440 recognized line separators into ``'\n'`` characters. Returns ``None``
441 if no source is available (e.g. a built-in module). Raises
442 :exc:`ImportError` if the loader cannot find the module specified.
443
444 .. versionchanged:: 3.4
445 Raises :exc:`ImportError` instead of :exc:`NotImplementedError`.
446
447 .. method:: is_package(fullname)
448
449 An optional method to return a true value if the module is a package, a
450 false value otherwise. :exc:`ImportError` is raised if the
451 :term:`loader` cannot find the module.
452
453 .. versionchanged:: 3.4
454 Raises :exc:`ImportError` instead of :exc:`NotImplementedError`.
455
456 .. staticmethod:: source_to_code(data, path='<string>')
457
458 Create a code object from Python source.
459
460 The *data* argument can be whatever the :func:`compile` function
461 supports (i.e. string or bytes). The *path* argument should be
462 the "path" to where the source code originated from, which can be an
463 abstract concept (e.g. location in a zip file).
464
465 With the subsequent code object one can execute it in a module by
466 running ``exec(code, module.__dict__)``.
467
468 .. versionadded:: 3.4
469
470 .. versionchanged:: 3.5
471 Made the method static.
472
473 .. method:: exec_module(module)
474
475 Implementation of :meth:`Loader.exec_module`.
476
477 .. versionadded:: 3.4
478
479 .. method:: load_module(fullname)
480
481 Implementation of :meth:`Loader.load_module`.
482
483 .. deprecated-removed:: 3.4 3.15
484 use :meth:`exec_module` instead.
485
486
487 .. class:: ExecutionLoader
488
489 An abstract base class which inherits from :class:`InspectLoader` that,
490 when implemented, helps a module to be executed as a script. The ABC
491 represents an optional :pep:`302` protocol.
492
493 .. method:: get_filename(fullname)
494 :abstractmethod:
495
496 An abstract method that is to return the value of
497 :attr:`~module.__file__` for the specified module. If no path is
498 available, :exc:`ImportError` is raised.
499
500 If source code is available, then the method should return the path to
501 the source file, regardless of whether a bytecode was used to load the
502 module.
503
504 .. versionchanged:: 3.4
505 Raises :exc:`ImportError` instead of :exc:`NotImplementedError`.
506
507
508 .. class:: FileLoader(fullname, path)
509
510 An abstract base class which inherits from :class:`ResourceLoader` and
511 :class:`ExecutionLoader`, providing concrete implementations of
512 :meth:`ResourceLoader.get_data` and :meth:`ExecutionLoader.get_filename`.
513
514 The *fullname* argument is a fully resolved name of the module the loader is
515 to handle. The *path* argument is the path to the file for the module.
516
517 .. versionadded:: 3.3
518
519 .. attribute:: name
520
521 The name of the module the loader can handle.
522
523 .. attribute:: path
524
525 Path to the file of the module.
526
527 .. method:: load_module(fullname)
528
529 Calls super's ``load_module()``.
530
531 .. deprecated-removed:: 3.4 3.15
532 Use :meth:`Loader.exec_module` instead.
533
534 .. method:: get_filename(fullname)
535 :abstractmethod:
536
537 Returns :attr:`path`.
538
539 .. method:: get_data(path)
540 :abstractmethod:
541
542 Reads *path* as a binary file and returns the bytes from it.
543
544
545 .. class:: SourceLoader
546
547 An abstract base class for implementing source (and optionally bytecode)
548 file loading. The class inherits from both :class:`ResourceLoader` and
549 :class:`ExecutionLoader`, requiring the implementation of:
550
551 * :meth:`ResourceLoader.get_data`
552 * :meth:`ExecutionLoader.get_filename`
553 Should only return the path to the source file; sourceless
554 loading is not supported.
555
556 The abstract methods defined by this class are to add optional bytecode
557 file support. Not implementing these optional methods (or causing them to
558 raise :exc:`NotImplementedError`) causes the loader to
559 only work with source code. Implementing the methods allows the loader to
560 work with source *and* bytecode files; it does not allow for *sourceless*
561 loading where only bytecode is provided. Bytecode files are an
562 optimization to speed up loading by removing the parsing step of Python's
563 compiler, and so no bytecode-specific API is exposed.
564
565 .. method:: path_stats(path)
566
567 Optional abstract method which returns a :class:`dict` containing
568 metadata about the specified path. Supported dictionary keys are:
569
570 - ``'mtime'`` (mandatory): an integer or floating-point number
571 representing the modification time of the source code;
572 - ``'size'`` (optional): the size in bytes of the source code.
573
574 Any other keys in the dictionary are ignored, to allow for future
575 extensions. If the path cannot be handled, :exc:`OSError` is raised.
576
577 .. versionadded:: 3.3
578
579 .. versionchanged:: 3.4
580 Raise :exc:`OSError` instead of :exc:`NotImplementedError`.
581
582 .. method:: path_mtime(path)
583
584 Optional abstract method which returns the modification time for the
585 specified path.
586
587 .. deprecated:: 3.3
588 This method is deprecated in favour of :meth:`path_stats`. You don't
589 have to implement it, but it is still available for compatibility
590 purposes. Raise :exc:`OSError` if the path cannot be handled.
591
592 .. versionchanged:: 3.4
593 Raise :exc:`OSError` instead of :exc:`NotImplementedError`.
594
595 .. method:: set_data(path, data)
596
597 Optional abstract method which writes the specified bytes to a file
598 path. Any intermediate directories which do not exist are to be created
599 automatically.
600
601 When writing to the path fails because the path is read-only
602 (:const:`errno.EACCES`/:exc:`PermissionError`), do not propagate the
603 exception.
604
605 .. versionchanged:: 3.4
606 No longer raises :exc:`NotImplementedError` when called.
607
608 .. method:: get_code(fullname)
609
610 Concrete implementation of :meth:`InspectLoader.get_code`.
611
612 .. method:: exec_module(module)
613
614 Concrete implementation of :meth:`Loader.exec_module`.
615
616 .. versionadded:: 3.4
617
618 .. method:: load_module(fullname)
619
620 Concrete implementation of :meth:`Loader.load_module`.
621
622 .. deprecated-removed:: 3.4 3.15
623 Use :meth:`exec_module` instead.
624
625 .. method:: get_source(fullname)
626
627 Concrete implementation of :meth:`InspectLoader.get_source`.
628
629 .. method:: is_package(fullname)
630
631 Concrete implementation of :meth:`InspectLoader.is_package`. A module
632 is determined to be a package if its file path (as provided by
633 :meth:`ExecutionLoader.get_filename`) is a file named
634 ``__init__`` when the file extension is removed **and** the module name
635 itself does not end in ``__init__``.
636
637
638 .. class:: ResourceReader
639
640 *Superseded by TraversableResources*
641
642 An :term:`abstract base class` to provide the ability to read
643 *resources*.
644
645 From the perspective of this ABC, a *resource* is a binary
646 artifact that is shipped within a package. Typically this is
647 something like a data file that lives next to the ``__init__.py``
648 file of the package. The purpose of this class is to help abstract
649 out the accessing of such data files so that it does not matter if
650 the package and its data file(s) are stored e.g. in a zip file
651 versus on the file system.
652
653 For any of methods of this class, a *resource* argument is
654 expected to be a :term:`path-like object` which represents
655 conceptually just a file name. This means that no subdirectory
656 paths should be included in the *resource* argument. This is
657 because the location of the package the reader is for, acts as the
658 "directory". Hence the metaphor for directories and file
659 names is packages and resources, respectively. This is also why
660 instances of this class are expected to directly correlate to
661 a specific package (instead of potentially representing multiple
662 packages or a module).
663
664 Loaders that wish to support resource reading are expected to
665 provide a method called ``get_resource_reader(fullname)`` which
666 returns an object implementing this ABC's interface. If the module
667 specified by fullname is not a package, this method should return
668 :const:`None`. An object compatible with this ABC should only be
669 returned when the specified module is a package.
670
671 .. versionadded:: 3.7
672
673 .. deprecated-removed:: 3.12 3.14
674 Use :class:`importlib.resources.abc.TraversableResources` instead.
675
676 .. method:: open_resource(resource)
677 :abstractmethod:
678
679 Returns an opened, :term:`file-like object` for binary reading
680 of the *resource*.
681
682 If the resource cannot be found, :exc:`FileNotFoundError` is
683 raised.
684
685 .. method:: resource_path(resource)
686 :abstractmethod:
687
688 Returns the file system path to the *resource*.
689
690 If the resource does not concretely exist on the file system,
691 raise :exc:`FileNotFoundError`.
692
693 .. method:: is_resource(name)
694 :abstractmethod:
695
696 Returns ``True`` if the named *name* is considered a resource.
697 :exc:`FileNotFoundError` is raised if *name* does not exist.
698
699 .. method:: contents()
700 :abstractmethod:
701
702 Returns an :term:`iterable` of strings over the contents of
703 the package. Do note that it is not required that all names
704 returned by the iterator be actual resources, e.g. it is
705 acceptable to return names for which :meth:`is_resource` would
706 be false.
707
708 Allowing non-resource names to be returned is to allow for
709 situations where how a package and its resources are stored
710 are known a priori and the non-resource names would be useful.
711 For instance, returning subdirectory names is allowed so that
712 when it is known that the package and resources are stored on
713 the file system then those subdirectory names can be used
714 directly.
715
716 The abstract method returns an iterable of no items.
717
718
719 .. class:: Traversable
720
721 An object with a subset of :class:`pathlib.Path` methods suitable for
722 traversing directories and opening files.
723
724 For a representation of the object on the file-system, use
725 :meth:`importlib.resources.as_file`.
726
727 .. versionadded:: 3.9
728
729 .. deprecated-removed:: 3.12 3.14
730 Use :class:`importlib.resources.abc.Traversable` instead.
731
732 .. attribute:: name
733
734 Abstract. The base name of this object without any parent references.
735
736 .. method:: iterdir()
737 :abstractmethod:
738
739 Yield ``Traversable`` objects in ``self``.
740
741 .. method:: is_dir()
742 :abstractmethod:
743
744 Return ``True`` if ``self`` is a directory.
745
746 .. method:: is_file()
747 :abstractmethod:
748
749 Return ``True`` if ``self`` is a file.
750
751 .. method:: joinpath(child)
752 :abstractmethod:
753
754 Return Traversable child in ``self``.
755
756 .. method:: __truediv__(child)
757 :abstractmethod:
758
759 Return ``Traversable`` child in ``self``.
760
761 .. method:: open(mode='r', *args, **kwargs)
762 :abstractmethod:
763
764 *mode* may be 'r' or 'rb' to open as text or binary. Return a handle
765 suitable for reading (same as :attr:`pathlib.Path.open`).
766
767 When opening as text, accepts encoding parameters such as those
768 accepted by :class:`io.TextIOWrapper`.
769
770 .. method:: read_bytes()
771
772 Read contents of ``self`` as bytes.
773
774 .. method:: read_text(encoding=None)
775
776 Read contents of ``self`` as text.
777
778
779 .. class:: TraversableResources
780
781 An abstract base class for resource readers capable of serving
782 the :meth:`importlib.resources.files` interface. Subclasses
783 :class:`importlib.resources.abc.ResourceReader` and provides
784 concrete implementations of the :class:`importlib.resources.abc.ResourceReader`'s
785 abstract methods. Therefore, any loader supplying
786 :class:`importlib.abc.TraversableResources` also supplies ResourceReader.
787
788 Loaders that wish to support resource reading are expected to
789 implement this interface.
790
791 .. versionadded:: 3.9
792
793 .. deprecated-removed:: 3.12 3.14
794 Use :class:`importlib.resources.abc.TraversableResources` instead.
795
796 .. method:: files()
797 :abstractmethod:
798
799 Returns a :class:`importlib.resources.abc.Traversable` object for the loaded
800 package.
801
802
803
804 :mod:`importlib.machinery` -- Importers and path hooks
805 ------------------------------------------------------
806
807 .. module:: importlib.machinery
808 :synopsis: Importers and path hooks
809
810 **Source code:** :source:`Lib/importlib/machinery.py`
811
812 --------------
813
814 This module contains the various objects that help :keyword:`import`
815 find and load modules.
816
817 .. data:: SOURCE_SUFFIXES
818
819 A list of strings representing the recognized file suffixes for source
820 modules.
821
822 .. versionadded:: 3.3
823
824 .. data:: DEBUG_BYTECODE_SUFFIXES
825
826 A list of strings representing the file suffixes for non-optimized bytecode
827 modules.
828
829 .. versionadded:: 3.3
830
831 .. deprecated:: 3.5
832 Use :const:`BYTECODE_SUFFIXES` instead.
833
834 .. data:: OPTIMIZED_BYTECODE_SUFFIXES
835
836 A list of strings representing the file suffixes for optimized bytecode
837 modules.
838
839 .. versionadded:: 3.3
840
841 .. deprecated:: 3.5
842 Use :const:`BYTECODE_SUFFIXES` instead.
843
844 .. data:: BYTECODE_SUFFIXES
845
846 A list of strings representing the recognized file suffixes for bytecode
847 modules (including the leading dot).
848
849 .. versionadded:: 3.3
850
851 .. versionchanged:: 3.5
852 The value is no longer dependent on ``__debug__``.
853
854 .. data:: EXTENSION_SUFFIXES
855
856 A list of strings representing the recognized file suffixes for
857 extension modules.
858
859 .. versionadded:: 3.3
860
861 .. function:: all_suffixes()
862
863 Returns a combined list of strings representing all file suffixes for
864 modules recognized by the standard import machinery. This is a
865 helper for code which simply needs to know if a filesystem path
866 potentially refers to a module without needing any details on the kind
867 of module (for example, :func:`inspect.getmodulename`).
868
869 .. versionadded:: 3.3
870
871
872 .. class:: BuiltinImporter
873
874 An :term:`importer` for built-in modules. All known built-in modules are
875 listed in :data:`sys.builtin_module_names`. This class implements the
876 :class:`importlib.abc.MetaPathFinder` and
877 :class:`importlib.abc.InspectLoader` ABCs.
878
879 Only class methods are defined by this class to alleviate the need for
880 instantiation.
881
882 .. versionchanged:: 3.5
883 As part of :pep:`489`, the builtin importer now implements
884 :meth:`Loader.create_module` and :meth:`Loader.exec_module`
885
886
887 .. class:: FrozenImporter
888
889 An :term:`importer` for frozen modules. This class implements the
890 :class:`importlib.abc.MetaPathFinder` and
891 :class:`importlib.abc.InspectLoader` ABCs.
892
893 Only class methods are defined by this class to alleviate the need for
894 instantiation.
895
896 .. versionchanged:: 3.4
897 Gained :meth:`~Loader.create_module` and :meth:`~Loader.exec_module`
898 methods.
899
900
901 .. class:: WindowsRegistryFinder
902
903 :term:`Finder <finder>` for modules declared in the Windows registry. This class
904 implements the :class:`importlib.abc.MetaPathFinder` ABC.
905
906 Only class methods are defined by this class to alleviate the need for
907 instantiation.
908
909 .. versionadded:: 3.3
910
911 .. deprecated:: 3.6
912 Use :mod:`site` configuration instead. Future versions of Python may
913 not enable this finder by default.
914
915
916 .. class:: PathFinder
917
918 A :term:`Finder <finder>` for :data:`sys.path` and package ``__path__`` attributes.
919 This class implements the :class:`importlib.abc.MetaPathFinder` ABC.
920
921 Only class methods are defined by this class to alleviate the need for
922 instantiation.
923
924 .. classmethod:: find_spec(fullname, path=None, target=None)
925
926 Class method that attempts to find a :term:`spec <module spec>`
927 for the module specified by *fullname* on :data:`sys.path` or, if
928 defined, on *path*. For each path entry that is searched,
929 :data:`sys.path_importer_cache` is checked. If a non-false object
930 is found then it is used as the :term:`path entry finder` to look
931 for the module being searched for. If no entry is found in
932 :data:`sys.path_importer_cache`, then :data:`sys.path_hooks` is
933 searched for a finder for the path entry and, if found, is stored
934 in :data:`sys.path_importer_cache` along with being queried about
935 the module. If no finder is ever found then ``None`` is both
936 stored in the cache and returned.
937
938 .. versionadded:: 3.4
939
940 .. versionchanged:: 3.5
941 If the current working directory -- represented by an empty string --
942 is no longer valid then ``None`` is returned but no value is cached
943 in :data:`sys.path_importer_cache`.
944
945 .. classmethod:: invalidate_caches()
946
947 Calls :meth:`importlib.abc.PathEntryFinder.invalidate_caches` on all
948 finders stored in :data:`sys.path_importer_cache` that define the method.
949 Otherwise entries in :data:`sys.path_importer_cache` set to ``None`` are
950 deleted.
951
952 .. versionchanged:: 3.7
953 Entries of ``None`` in :data:`sys.path_importer_cache` are deleted.
954
955 .. versionchanged:: 3.4
956 Calls objects in :data:`sys.path_hooks` with the current working
957 directory for ``''`` (i.e. the empty string).
958
959
960 .. class:: FileFinder(path, *loader_details)
961
962 A concrete implementation of :class:`importlib.abc.PathEntryFinder` which
963 caches results from the file system.
964
965 The *path* argument is the directory for which the finder is in charge of
966 searching.
967
968 The *loader_details* argument is a variable number of 2-item tuples each
969 containing a loader and a sequence of file suffixes the loader recognizes.
970 The loaders are expected to be callables which accept two arguments of
971 the module's name and the path to the file found.
972
973 The finder will cache the directory contents as necessary, making stat calls
974 for each module search to verify the cache is not outdated. Because cache
975 staleness relies upon the granularity of the operating system's state
976 information of the file system, there is a potential race condition of
977 searching for a module, creating a new file, and then searching for the
978 module the new file represents. If the operations happen fast enough to fit
979 within the granularity of stat calls, then the module search will fail. To
980 prevent this from happening, when you create a module dynamically, make sure
981 to call :func:`importlib.invalidate_caches`.
982
983 .. versionadded:: 3.3
984
985 .. attribute:: path
986
987 The path the finder will search in.
988
989 .. method:: find_spec(fullname, target=None)
990
991 Attempt to find the spec to handle *fullname* within :attr:`path`.
992
993 .. versionadded:: 3.4
994
995 .. method:: invalidate_caches()
996
997 Clear out the internal cache.
998
999 .. classmethod:: path_hook(*loader_details)
1000
1001 A class method which returns a closure for use on :data:`sys.path_hooks`.
1002 An instance of :class:`FileFinder` is returned by the closure using the
1003 path argument given to the closure directly and *loader_details*
1004 indirectly.
1005
1006 If the argument to the closure is not an existing directory,
1007 :exc:`ImportError` is raised.
1008
1009
1010 .. class:: SourceFileLoader(fullname, path)
1011
1012 A concrete implementation of :class:`importlib.abc.SourceLoader` by
1013 subclassing :class:`importlib.abc.FileLoader` and providing some concrete
1014 implementations of other methods.
1015
1016 .. versionadded:: 3.3
1017
1018 .. attribute:: name
1019
1020 The name of the module that this loader will handle.
1021
1022 .. attribute:: path
1023
1024 The path to the source file.
1025
1026 .. method:: is_package(fullname)
1027
1028 Return ``True`` if :attr:`path` appears to be for a package.
1029
1030 .. method:: path_stats(path)
1031
1032 Concrete implementation of :meth:`importlib.abc.SourceLoader.path_stats`.
1033
1034 .. method:: set_data(path, data)
1035
1036 Concrete implementation of :meth:`importlib.abc.SourceLoader.set_data`.
1037
1038 .. method:: load_module(name=None)
1039
1040 Concrete implementation of :meth:`importlib.abc.Loader.load_module` where
1041 specifying the name of the module to load is optional.
1042
1043 .. deprecated-removed:: 3.6 3.15
1044
1045 Use :meth:`importlib.abc.Loader.exec_module` instead.
1046
1047
1048 .. class:: SourcelessFileLoader(fullname, path)
1049
1050 A concrete implementation of :class:`importlib.abc.FileLoader` which can
1051 import bytecode files (i.e. no source code files exist).
1052
1053 Please note that direct use of bytecode files (and thus not source code
1054 files) inhibits your modules from being usable by all Python
1055 implementations or new versions of Python which change the bytecode
1056 format.
1057
1058 .. versionadded:: 3.3
1059
1060 .. attribute:: name
1061
1062 The name of the module the loader will handle.
1063
1064 .. attribute:: path
1065
1066 The path to the bytecode file.
1067
1068 .. method:: is_package(fullname)
1069
1070 Determines if the module is a package based on :attr:`path`.
1071
1072 .. method:: get_code(fullname)
1073
1074 Returns the code object for :attr:`name` created from :attr:`path`.
1075
1076 .. method:: get_source(fullname)
1077
1078 Returns ``None`` as bytecode files have no source when this loader is
1079 used.
1080
1081 .. method:: load_module(name=None)
1082
1083 Concrete implementation of :meth:`importlib.abc.Loader.load_module` where
1084 specifying the name of the module to load is optional.
1085
1086 .. deprecated-removed:: 3.6 3.15
1087
1088 Use :meth:`importlib.abc.Loader.exec_module` instead.
1089
1090
1091 .. class:: ExtensionFileLoader(fullname, path)
1092
1093 A concrete implementation of :class:`importlib.abc.ExecutionLoader` for
1094 extension modules.
1095
1096 The *fullname* argument specifies the name of the module the loader is to
1097 support. The *path* argument is the path to the extension module's file.
1098
1099 Note that, by default, importing an extension module will fail
1100 in subinterpreters if it doesn't implement multi-phase init
1101 (see :pep:`489`), even if it would otherwise import successfully.
1102
1103 .. versionadded:: 3.3
1104
1105 .. versionchanged:: 3.12
1106 Multi-phase init is now required for use in subinterpreters.
1107
1108 .. attribute:: name
1109
1110 Name of the module the loader supports.
1111
1112 .. attribute:: path
1113
1114 Path to the extension module.
1115
1116 .. method:: create_module(spec)
1117
1118 Creates the module object from the given specification in accordance
1119 with :pep:`489`.
1120
1121 .. versionadded:: 3.5
1122
1123 .. method:: exec_module(module)
1124
1125 Initializes the given module object in accordance with :pep:`489`.
1126
1127 .. versionadded:: 3.5
1128
1129 .. method:: is_package(fullname)
1130
1131 Returns ``True`` if the file path points to a package's ``__init__``
1132 module based on :const:`EXTENSION_SUFFIXES`.
1133
1134 .. method:: get_code(fullname)
1135
1136 Returns ``None`` as extension modules lack a code object.
1137
1138 .. method:: get_source(fullname)
1139
1140 Returns ``None`` as extension modules do not have source code.
1141
1142 .. method:: get_filename(fullname)
1143
1144 Returns :attr:`path`.
1145
1146 .. versionadded:: 3.4
1147
1148
1149 .. class:: NamespaceLoader(name, path, path_finder)
1150
1151 A concrete implementation of :class:`importlib.abc.InspectLoader` for
1152 namespace packages. This is an alias for a private class and is only made
1153 public for introspecting the ``__loader__`` attribute on namespace
1154 packages::
1155
1156 >>> from importlib.machinery import NamespaceLoader
1157 >>> import my_namespace
1158 >>> isinstance(my_namespace.__loader__, NamespaceLoader)
1159 True
1160 >>> import importlib.abc
1161 >>> isinstance(my_namespace.__loader__, importlib.abc.Loader)
1162 True
1163
1164 .. versionadded:: 3.11
1165
1166
1167 .. class:: ModuleSpec(name, loader, *, origin=None, loader_state=None, is_package=None)
1168
1169 A specification for a module's import-system-related state. This is
1170 typically exposed as the module's :attr:`~module.__spec__` attribute. Many
1171 of these attributes are also available directly on a module: for example,
1172 ``module.__spec__.origin == module.__file__``. Note, however, that
1173 while the *values* are usually equivalent, they can differ since there is
1174 no synchronization between the two objects. For example, it is possible to
1175 update the module's :attr:`~module.__file__` at runtime and this will not be
1176 automatically reflected in the module's
1177 :attr:`__spec__.origin <ModuleSpec.origin>`, and vice versa.
1178
1179 .. versionadded:: 3.4
1180
1181 .. attribute:: name
1182
1183 The module's fully qualified name (see :attr:`module.__name__`).
1184 The :term:`finder` should always set this attribute to a non-empty string.
1185
1186 .. attribute:: loader
1187
1188 The :term:`loader` used to load the module (see :attr:`module.__loader__`).
1189 The :term:`finder` should always set this attribute.
1190
1191 .. attribute:: origin
1192
1193 The location the :term:`loader` should use to load the module
1194 (see :attr:`module.__file__`).
1195 For example, for modules loaded from a ``.py`` file this is the filename.
1196 The :term:`finder` should always set this attribute to a meaningful value
1197 for the :term:`loader` to use. In the uncommon case that there is not one
1198 (like for namespace packages), it should be set to ``None``.
1199
1200 .. attribute:: submodule_search_locations
1201
1202 A (possibly empty) :term:`sequence` of strings enumerating the locations
1203 in which a package's submodules will be found
1204 (see :attr:`module.__path__`). Most of the time there will only be a
1205 single directory in this list.
1206
1207 The :term:`finder` should set this attribute to a sequence, even an empty
1208 one, to indicate
1209 to the import system that the module is a package. It should be set to ``None`` for
1210 non-package modules. It is set automatically later to a special object for
1211 namespace packages.
1212
1213 .. attribute:: loader_state
1214
1215 The :term:`finder` may set this attribute to an object containing additional,
1216 module-specific data to use when loading the module. Otherwise it should be
1217 set to ``None``.
1218
1219 .. attribute:: cached
1220
1221 The filename of a compiled version of the module's code
1222 (see :attr:`module.__cached__`).
1223 The :term:`finder` should always set this attribute but it may be ``None``
1224 for modules that do not need compiled code stored.
1225
1226 .. attribute:: parent
1227
1228 (Read-only) The fully qualified name of the package the module is in (or the
1229 empty string for a top-level module).
1230 See :attr:`module.__package__`.
1231 If the module is a package then this is the same as :attr:`name`.
1232
1233 .. attribute:: has_location
1234
1235 ``True`` if the spec's :attr:`origin` refers to a loadable location,
1236 ``False`` otherwise. This value impacts how :attr:`!origin` is interpreted
1237 and how the module's :attr:`~module.__file__` is populated.
1238
1239
1240 .. class:: AppleFrameworkLoader(name, path)
1241
1242 A specialization of :class:`importlib.machinery.ExtensionFileLoader` that
1243 is able to load extension modules in Framework format.
1244
1245 For compatibility with the iOS App Store, *all* binary modules in an iOS app
1246 must be dynamic libraries, contained in a framework with appropriate
1247 metadata, stored in the ``Frameworks`` folder of the packaged app. There can
1248 be only a single binary per framework, and there can be no executable binary
1249 material outside the Frameworks folder.
1250
1251 To accommodate this requirement, when running on iOS, extension module
1252 binaries are *not* packaged as ``.so`` files on ``sys.path``, but as
1253 individual standalone frameworks. To discover those frameworks, this loader
1254 is registered against the ``.fwork`` file extension, with a ``.fwork``
1255 file acting as a placeholder in the original location of the binary on
1256 ``sys.path``. The ``.fwork`` file contains the path of the actual binary in
1257 the ``Frameworks`` folder, relative to the app bundle. To allow for
1258 resolving a framework-packaged binary back to the original location, the
1259 framework is expected to contain a ``.origin`` file that contains the
1260 location of the ``.fwork`` file, relative to the app bundle.
1261
1262 For example, consider the case of an import ``from foo.bar import _whiz``,
1263 where ``_whiz`` is implemented with the binary module
1264 ``sources/foo/bar/_whiz.abi3.so``, with ``sources`` being the location
1265 registered on ``sys.path``, relative to the application bundle. This module
1266 *must* be distributed as
1267 ``Frameworks/foo.bar._whiz.framework/foo.bar._whiz`` (creating the framework
1268 name from the full import path of the module), with an ``Info.plist`` file
1269 in the ``.framework`` directory identifying the binary as a framework. The
1270 ``foo.bar._whiz`` module would be represented in the original location with
1271 a ``sources/foo/bar/_whiz.abi3.fwork`` marker file, containing the path
1272 ``Frameworks/foo.bar._whiz/foo.bar._whiz``. The framework would also contain
1273 ``Frameworks/foo.bar._whiz.framework/foo.bar._whiz.origin``, containing the
1274 path to the ``.fwork`` file.
1275
1276 When a module is loaded with this loader, the ``__file__`` for the module
1277 will report as the location of the ``.fwork`` file. This allows code to use
1278 the ``__file__`` of a module as an anchor for file system traveral.
1279 However, the spec origin will reference the location of the *actual* binary
1280 in the ``.framework`` folder.
1281
1282 The Xcode project building the app is responsible for converting any ``.so``
1283 files from wherever they exist in the ``PYTHONPATH`` into frameworks in the
1284 ``Frameworks`` folder (including stripping extensions from the module file,
1285 the addition of framework metadata, and signing the resulting framework),
1286 and creating the ``.fwork`` and ``.origin`` files. This will usually be done
1287 with a build step in the Xcode project; see the iOS documentation for
1288 details on how to construct this build step.
1289
1290 .. versionadded:: 3.13
1291
1292 .. availability:: iOS.
1293
1294 .. attribute:: name
1295
1296 Name of the module the loader supports.
1297
1298 .. attribute:: path
1299
1300 Path to the ``.fwork`` file for the extension module.
1301
1302
1303 :mod:`importlib.util` -- Utility code for importers
1304 ---------------------------------------------------
1305
1306 .. module:: importlib.util
1307 :synopsis: Utility code for importers
1308
1309
1310 **Source code:** :source:`Lib/importlib/util.py`
1311
1312 --------------
1313
1314 This module contains the various objects that help in the construction of
1315 an :term:`importer`.
1316
1317 .. data:: MAGIC_NUMBER
1318
1319 The bytes which represent the bytecode version number. If you need help with
1320 loading/writing bytecode then consider :class:`importlib.abc.SourceLoader`.
1321
1322 .. versionadded:: 3.4
1323
1324 .. function:: cache_from_source(path, debug_override=None, *, optimization=None)
1325
1326 Return the :pep:`3147`/:pep:`488` path to the byte-compiled file associated
1327 with the source *path*. For example, if *path* is ``/foo/bar/baz.py`` the return
1328 value would be ``/foo/bar/__pycache__/baz.cpython-32.pyc`` for Python 3.2.
1329 The ``cpython-32`` string comes from the current magic tag (see
1330 :func:`get_tag`; if :attr:`sys.implementation.cache_tag` is not defined then
1331 :exc:`NotImplementedError` will be raised).
1332
1333 The *optimization* parameter is used to specify the optimization level of the
1334 bytecode file. An empty string represents no optimization, so
1335 ``/foo/bar/baz.py`` with an *optimization* of ``''`` will result in a
1336 bytecode path of ``/foo/bar/__pycache__/baz.cpython-32.pyc``. ``None`` causes
1337 the interpreter's optimization level to be used. Any other value's string
1338 representation is used, so ``/foo/bar/baz.py`` with an *optimization* of
1339 ``2`` will lead to the bytecode path of
1340 ``/foo/bar/__pycache__/baz.cpython-32.opt-2.pyc``. The string representation
1341 of *optimization* can only be alphanumeric, else :exc:`ValueError` is raised.
1342
1343 The *debug_override* parameter is deprecated and can be used to override
1344 the system's value for ``__debug__``. A ``True`` value is the equivalent of
1345 setting *optimization* to the empty string. A ``False`` value is the same as
1346 setting *optimization* to ``1``. If both *debug_override* an *optimization*
1347 are not ``None`` then :exc:`TypeError` is raised.
1348
1349 .. versionadded:: 3.4
1350
1351 .. versionchanged:: 3.5
1352 The *optimization* parameter was added and the *debug_override* parameter
1353 was deprecated.
1354
1355 .. versionchanged:: 3.6
1356 Accepts a :term:`path-like object`.
1357
1358
1359 .. function:: source_from_cache(path)
1360
1361 Given the *path* to a :pep:`3147` file name, return the associated source code
1362 file path. For example, if *path* is
1363 ``/foo/bar/__pycache__/baz.cpython-32.pyc`` the returned path would be
1364 ``/foo/bar/baz.py``. *path* need not exist, however if it does not conform
1365 to :pep:`3147` or :pep:`488` format, a :exc:`ValueError` is raised. If
1366 :attr:`sys.implementation.cache_tag` is not defined,
1367 :exc:`NotImplementedError` is raised.
1368
1369 .. versionadded:: 3.4
1370
1371 .. versionchanged:: 3.6
1372 Accepts a :term:`path-like object`.
1373
1374 .. function:: decode_source(source_bytes)
1375
1376 Decode the given bytes representing source code and return it as a string
1377 with universal newlines (as required by
1378 :meth:`importlib.abc.InspectLoader.get_source`).
1379
1380 .. versionadded:: 3.4
1381
1382 .. function:: resolve_name(name, package)
1383
1384 Resolve a relative module name to an absolute one.
1385
1386 If **name** has no leading dots, then **name** is simply returned. This
1387 allows for usage such as
1388 ``importlib.util.resolve_name('sys', __spec__.parent)`` without doing a
1389 check to see if the **package** argument is needed.
1390
1391 :exc:`ImportError` is raised if **name** is a relative module name but
1392 **package** is a false value (e.g. ``None`` or the empty string).
1393 :exc:`ImportError` is also raised if a relative name would escape its
1394 containing package (e.g. requesting ``..bacon`` from within the ``spam``
1395 package).
1396
1397 .. versionadded:: 3.3
1398
1399 .. versionchanged:: 3.9
1400 To improve consistency with import statements, raise
1401 :exc:`ImportError` instead of :exc:`ValueError` for invalid relative
1402 import attempts.
1403
1404 .. function:: find_spec(name, package=None)
1405
1406 Find the :term:`spec <module spec>` for a module, optionally relative to
1407 the specified **package** name. If the module is in :data:`sys.modules`,
1408 then ``sys.modules[name].__spec__`` is returned (unless the spec would be
1409 ``None`` or is not set, in which case :exc:`ValueError` is raised).
1410 Otherwise a search using :data:`sys.meta_path` is done. ``None`` is
1411 returned if no spec is found.
1412
1413 If **name** is for a submodule (contains a dot), the parent module is
1414 automatically imported.
1415
1416 **name** and **package** work the same as for :func:`import_module`.
1417
1418 .. versionadded:: 3.4
1419
1420 .. versionchanged:: 3.7
1421 Raises :exc:`ModuleNotFoundError` instead of :exc:`AttributeError` if
1422 **package** is in fact not a package (i.e. lacks a
1423 :attr:`~module.__path__` attribute).
1424
1425 .. function:: module_from_spec(spec)
1426
1427 Create a new module based on **spec** and
1428 :meth:`spec.loader.create_module <importlib.abc.Loader.create_module>`.
1429
1430 If :meth:`spec.loader.create_module <importlib.abc.Loader.create_module>`
1431 does not return ``None``, then any pre-existing attributes will not be reset.
1432 Also, no :exc:`AttributeError` will be raised if triggered while accessing
1433 **spec** or setting an attribute on the module.
1434
1435 This function is preferred over using :class:`types.ModuleType` to create a
1436 new module as **spec** is used to set as many import-controlled attributes on
1437 the module as possible.
1438
1439 .. versionadded:: 3.5
1440
1441 .. function:: spec_from_loader(name, loader, *, origin=None, is_package=None)
1442
1443 A factory function for creating a :class:`~importlib.machinery.ModuleSpec`
1444 instance based on a loader. The parameters have the same meaning as they do
1445 for ModuleSpec. The function uses available :term:`loader` APIs, such as
1446 :meth:`InspectLoader.is_package`, to fill in any missing
1447 information on the spec.
1448
1449 .. versionadded:: 3.4
1450
1451 .. function:: spec_from_file_location(name, location, *, loader=None, submodule_search_locations=None)
1452
1453 A factory function for creating a :class:`~importlib.machinery.ModuleSpec`
1454 instance based on the path to a file. Missing information will be filled in
1455 on the spec by making use of loader APIs and by the implication that the
1456 module will be file-based.
1457
1458 .. versionadded:: 3.4
1459
1460 .. versionchanged:: 3.6
1461 Accepts a :term:`path-like object`.
1462
1463 .. function:: source_hash(source_bytes)
1464
1465 Return the hash of *source_bytes* as bytes. A hash-based ``.pyc`` file embeds
1466 the :func:`source_hash` of the corresponding source file's contents in its
1467 header.
1468
1469 .. versionadded:: 3.7
1470
1471 .. function:: _incompatible_extension_module_restrictions(*, disable_check)
1472
1473 A context manager that can temporarily skip the compatibility check
1474 for extension modules. By default the check is enabled and will fail
1475 when a single-phase init module is imported in a subinterpreter.
1476 It will also fail for a multi-phase init module that doesn't
1477 explicitly support a per-interpreter GIL, when imported
1478 in an interpreter with its own GIL.
1479
1480 Note that this function is meant to accommodate an unusual case;
1481 one which is likely to eventually go away. There's is a pretty good
1482 chance this is not what you were looking for.
1483
1484 You can get the same effect as this function by implementing the
1485 basic interface of multi-phase init (:pep:`489`) and lying about
1486 support for multiple interpreters (or per-interpreter GIL).
1487
1488 .. warning::
1489 Using this function to disable the check can lead to
1490 unexpected behavior and even crashes. It should only be used during
1491 extension module development.
1492
1493 .. versionadded:: 3.12
1494
1495 .. class:: LazyLoader(loader)
1496
1497 A class which postpones the execution of the loader of a module until the
1498 module has an attribute accessed.
1499
1500 This class **only** works with loaders that define
1501 :meth:`~importlib.abc.Loader.exec_module` as control over what module type
1502 is used for the module is required. For those same reasons, the loader's
1503 :meth:`~importlib.abc.Loader.create_module` method must return ``None`` or a
1504 type for which its ``__class__`` attribute can be mutated along with not
1505 using :term:`slots <__slots__>`. Finally, modules which substitute the object
1506 placed into :data:`sys.modules` will not work as there is no way to properly
1507 replace the module references throughout the interpreter safely;
1508 :exc:`ValueError` is raised if such a substitution is detected.
1509
1510 .. note::
1511 For projects where startup time is critical, this class allows for
1512 potentially minimizing the cost of loading a module if it is never used.
1513 For projects where startup time is not essential then use of this class is
1514 **heavily** discouraged due to error messages created during loading being
1515 postponed and thus occurring out of context.
1516
1517 .. versionadded:: 3.5
1518
1519 .. versionchanged:: 3.6
1520 Began calling :meth:`~importlib.abc.Loader.create_module`, removing the
1521 compatibility warning for :class:`importlib.machinery.BuiltinImporter` and
1522 :class:`importlib.machinery.ExtensionFileLoader`.
1523
1524 .. classmethod:: factory(loader)
1525
1526 A class method which returns a callable that creates a lazy loader. This
1527 is meant to be used in situations where the loader is passed by class
1528 instead of by instance.
1529 ::
1530
1531 suffixes = importlib.machinery.SOURCE_SUFFIXES
1532 loader = importlib.machinery.SourceFileLoader
1533 lazy_loader = importlib.util.LazyLoader.factory(loader)
1534 finder = importlib.machinery.FileFinder(path, (lazy_loader, suffixes))
1535
1536 .. _importlib-examples:
1537
1538 Examples
1539 --------
1540
1541 Importing programmatically
1542 ''''''''''''''''''''''''''
1543
1544 To programmatically import a module, use :func:`importlib.import_module`.
1545 ::
1546
1547 import importlib
1548
1549 itertools = importlib.import_module('itertools')
1550
1551
1552 Checking if a module can be imported
1553 ''''''''''''''''''''''''''''''''''''
1554
1555 If you need to find out if a module can be imported without actually doing the
1556 import, then you should use :func:`importlib.util.find_spec`.
1557
1558 Note that if ``name`` is a submodule (contains a dot),
1559 :func:`importlib.util.find_spec` will import the parent module.
1560 ::
1561
1562 import importlib.util
1563 import sys
1564
1565 # For illustrative purposes.
1566 name = 'itertools'
1567
1568 if name in sys.modules:
1569 print(f"{name!r} already in sys.modules")
1570 elif (spec := importlib.util.find_spec(name)) is not None:
1571 # If you chose to perform the actual import ...
1572 module = importlib.util.module_from_spec(spec)
1573 sys.modules[name] = module
1574 spec.loader.exec_module(module)
1575 print(f"{name!r} has been imported")
1576 else:
1577 print(f"can't find the {name!r} module")
1578
1579
1580 Importing a source file directly
1581 ''''''''''''''''''''''''''''''''
1582
1583 This recipe should be used with caution: it is an approximation of an import
1584 statement where the file path is specified directly, rather than
1585 :data:`sys.path` being searched. Alternatives should first be considered first,
1586 such as modifying :data:`sys.path` when a proper module is required, or using
1587 :func:`runpy.run_path` when the global namespace resulting from running a Python
1588 file is appropriate.
1589
1590 To import a Python source file directly from a path, use the following recipe::
1591
1592 import importlib.util
1593 import sys
1594
1595
1596 def import_from_path(module_name, file_path):
1597 spec = importlib.util.spec_from_file_location(module_name, file_path)
1598 module = importlib.util.module_from_spec(spec)
1599 sys.modules[module_name] = module
1600 spec.loader.exec_module(module)
1601 return module
1602
1603
1604 # For illustrative purposes only (use of `json` is arbitrary).
1605 import json
1606 file_path = json.__file__
1607 module_name = json.__name__
1608
1609 # Similar outcome as `import json`.
1610 json = import_from_path(module_name, file_path)
1611
1612
1613 Implementing lazy imports
1614 '''''''''''''''''''''''''
1615
1616 The example below shows how to implement lazy imports::
1617
1618 >>> import importlib.util
1619 >>> import sys
1620 >>> def lazy_import(name):
1621 ... spec = importlib.util.find_spec(name)
1622 ... loader = importlib.util.LazyLoader(spec.loader)
1623 ... spec.loader = loader
1624 ... module = importlib.util.module_from_spec(spec)
1625 ... sys.modules[name] = module
1626 ... loader.exec_module(module)
1627 ... return module
1628 ...
1629 >>> lazy_typing = lazy_import("typing")
1630 >>> #lazy_typing is a real module object,
1631 >>> #but it is not loaded in memory yet.
1632 >>> lazy_typing.TYPE_CHECKING
1633 False
1634
1635
1636 Setting up an importer
1637 ''''''''''''''''''''''
1638
1639 For deep customizations of import, you typically want to implement an
1640 :term:`importer`. This means managing both the :term:`finder` and :term:`loader`
1641 side of things. For finders there are two flavours to choose from depending on
1642 your needs: a :term:`meta path finder` or a :term:`path entry finder`. The
1643 former is what you would put on :data:`sys.meta_path` while the latter is what
1644 you create using a :term:`path entry hook` on :data:`sys.path_hooks` which works
1645 with :data:`sys.path` entries to potentially create a finder. This example will
1646 show you how to register your own importers so that import will use them (for
1647 creating an importer for yourself, read the documentation for the appropriate
1648 classes defined within this package)::
1649
1650 import importlib.machinery
1651 import sys
1652
1653 # For illustrative purposes only.
1654 SpamMetaPathFinder = importlib.machinery.PathFinder
1655 SpamPathEntryFinder = importlib.machinery.FileFinder
1656 loader_details = (importlib.machinery.SourceFileLoader,
1657 importlib.machinery.SOURCE_SUFFIXES)
1658
1659 # Setting up a meta path finder.
1660 # Make sure to put the finder in the proper location in the list in terms of
1661 # priority.
1662 sys.meta_path.append(SpamMetaPathFinder)
1663
1664 # Setting up a path entry finder.
1665 # Make sure to put the path hook in the proper location in the list in terms
1666 # of priority.
1667 sys.path_hooks.append(SpamPathEntryFinder.path_hook(loader_details))
1668
1669
1670 Approximating :func:`importlib.import_module`
1671 '''''''''''''''''''''''''''''''''''''''''''''
1672
1673 Import itself is implemented in Python code, making it possible to
1674 expose most of the import machinery through importlib. The following
1675 helps illustrate the various APIs that importlib exposes by providing an
1676 approximate implementation of
1677 :func:`importlib.import_module`::
1678
1679 import importlib.util
1680 import sys
1681
1682 def import_module(name, package=None):
1683 """An approximate implementation of import."""
1684 absolute_name = importlib.util.resolve_name(name, package)
1685 try:
1686 return sys.modules[absolute_name]
1687 except KeyError:
1688 pass
1689
1690 path = None
1691 if '.' in absolute_name:
1692 parent_name, _, child_name = absolute_name.rpartition('.')
1693 parent_module = import_module(parent_name)
1694 path = parent_module.__spec__.submodule_search_locations
1695 for finder in sys.meta_path:
1696 spec = finder.find_spec(absolute_name, path)
1697 if spec is not None:
1698 break
1699 else:
1700 msg = f'No module named {absolute_name!r}'
1701 raise ModuleNotFoundError(msg, name=absolute_name)
1702 module = importlib.util.module_from_spec(spec)
1703 sys.modules[absolute_name] = module
1704 spec.loader.exec_module(module)
1705 if path is not None:
1706 setattr(parent_module, child_name, module)
1707 return module