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