17db96d56Sopenharmony_ci:mod:`!importlib` --- The implementation of :keyword:`!import`
27db96d56Sopenharmony_ci==============================================================
37db96d56Sopenharmony_ci
47db96d56Sopenharmony_ci.. module:: importlib
57db96d56Sopenharmony_ci   :synopsis: The implementation of the import machinery.
67db96d56Sopenharmony_ci
77db96d56Sopenharmony_ci.. moduleauthor:: Brett Cannon <brett@python.org>
87db96d56Sopenharmony_ci.. sectionauthor:: Brett Cannon <brett@python.org>
97db96d56Sopenharmony_ci
107db96d56Sopenharmony_ci.. versionadded:: 3.1
117db96d56Sopenharmony_ci
127db96d56Sopenharmony_ci**Source code:** :source:`Lib/importlib/__init__.py`
137db96d56Sopenharmony_ci
147db96d56Sopenharmony_ci--------------
157db96d56Sopenharmony_ci
167db96d56Sopenharmony_ci
177db96d56Sopenharmony_ciIntroduction
187db96d56Sopenharmony_ci------------
197db96d56Sopenharmony_ci
207db96d56Sopenharmony_ciThe purpose of the :mod:`importlib` package is three-fold.
217db96d56Sopenharmony_ci
227db96d56Sopenharmony_ciOne is to provide the
237db96d56Sopenharmony_ciimplementation of the :keyword:`import` statement (and thus, by extension, the
247db96d56Sopenharmony_ci:func:`__import__` function) in Python source code. This provides an
257db96d56Sopenharmony_ciimplementation of :keyword:`!import` which is portable to any Python
267db96d56Sopenharmony_ciinterpreter. This also provides an implementation which is easier to
277db96d56Sopenharmony_cicomprehend than one implemented in a programming language other than Python.
287db96d56Sopenharmony_ci
297db96d56Sopenharmony_ciTwo, the components to implement :keyword:`import` are exposed in this
307db96d56Sopenharmony_cipackage, making it easier for users to create their own custom objects (known
317db96d56Sopenharmony_cigenerically as an :term:`importer`) to participate in the import process.
327db96d56Sopenharmony_ci
337db96d56Sopenharmony_ciThree, the package contains modules exposing additional functionality for
347db96d56Sopenharmony_cimanaging aspects of Python packages:
357db96d56Sopenharmony_ci
367db96d56Sopenharmony_ci* :mod:`importlib.metadata` presents access to metadata from third-party
377db96d56Sopenharmony_ci  distributions.
387db96d56Sopenharmony_ci* :mod:`importlib.resources` provides routines for accessing non-code
397db96d56Sopenharmony_ci  "resources" from Python packages.
407db96d56Sopenharmony_ci
417db96d56Sopenharmony_ci.. seealso::
427db96d56Sopenharmony_ci
437db96d56Sopenharmony_ci    :ref:`import`
447db96d56Sopenharmony_ci        The language reference for the :keyword:`import` statement.
457db96d56Sopenharmony_ci
467db96d56Sopenharmony_ci    `Packages specification <https://www.python.org/doc/essays/packages/>`__
477db96d56Sopenharmony_ci        Original specification of packages. Some semantics have changed since
487db96d56Sopenharmony_ci        the writing of this document (e.g. redirecting based on ``None``
497db96d56Sopenharmony_ci        in :data:`sys.modules`).
507db96d56Sopenharmony_ci
517db96d56Sopenharmony_ci    The :func:`.__import__` function
527db96d56Sopenharmony_ci        The :keyword:`import` statement is syntactic sugar for this function.
537db96d56Sopenharmony_ci
547db96d56Sopenharmony_ci    :ref:`sys-path-init`
557db96d56Sopenharmony_ci        The initialization of :data:`sys.path`.
567db96d56Sopenharmony_ci
577db96d56Sopenharmony_ci    :pep:`235`
587db96d56Sopenharmony_ci        Import on Case-Insensitive Platforms
597db96d56Sopenharmony_ci
607db96d56Sopenharmony_ci    :pep:`263`
617db96d56Sopenharmony_ci        Defining Python Source Code Encodings
627db96d56Sopenharmony_ci
637db96d56Sopenharmony_ci    :pep:`302`
647db96d56Sopenharmony_ci        New Import Hooks
657db96d56Sopenharmony_ci
667db96d56Sopenharmony_ci    :pep:`328`
677db96d56Sopenharmony_ci        Imports: Multi-Line and Absolute/Relative
687db96d56Sopenharmony_ci
697db96d56Sopenharmony_ci    :pep:`366`
707db96d56Sopenharmony_ci        Main module explicit relative imports
717db96d56Sopenharmony_ci
727db96d56Sopenharmony_ci    :pep:`420`
737db96d56Sopenharmony_ci        Implicit namespace packages
747db96d56Sopenharmony_ci
757db96d56Sopenharmony_ci    :pep:`451`
767db96d56Sopenharmony_ci        A ModuleSpec Type for the Import System
777db96d56Sopenharmony_ci
787db96d56Sopenharmony_ci    :pep:`488`
797db96d56Sopenharmony_ci        Elimination of PYO files
807db96d56Sopenharmony_ci
817db96d56Sopenharmony_ci    :pep:`489`
827db96d56Sopenharmony_ci        Multi-phase extension module initialization
837db96d56Sopenharmony_ci
847db96d56Sopenharmony_ci    :pep:`552`
857db96d56Sopenharmony_ci        Deterministic pycs
867db96d56Sopenharmony_ci
877db96d56Sopenharmony_ci    :pep:`3120`
887db96d56Sopenharmony_ci        Using UTF-8 as the Default Source Encoding
897db96d56Sopenharmony_ci
907db96d56Sopenharmony_ci    :pep:`3147`
917db96d56Sopenharmony_ci        PYC Repository Directories
927db96d56Sopenharmony_ci
937db96d56Sopenharmony_ci
947db96d56Sopenharmony_ciFunctions
957db96d56Sopenharmony_ci---------
967db96d56Sopenharmony_ci
977db96d56Sopenharmony_ci.. function:: __import__(name, globals=None, locals=None, fromlist=(), level=0)
987db96d56Sopenharmony_ci
997db96d56Sopenharmony_ci    An implementation of the built-in :func:`__import__` function.
1007db96d56Sopenharmony_ci
1017db96d56Sopenharmony_ci    .. note::
1027db96d56Sopenharmony_ci       Programmatic importing of modules should use :func:`import_module`
1037db96d56Sopenharmony_ci       instead of this function.
1047db96d56Sopenharmony_ci
1057db96d56Sopenharmony_ci.. function:: import_module(name, package=None)
1067db96d56Sopenharmony_ci
1077db96d56Sopenharmony_ci    Import a module. The *name* argument specifies what module to
1087db96d56Sopenharmony_ci    import in absolute or relative terms
1097db96d56Sopenharmony_ci    (e.g. either ``pkg.mod`` or ``..mod``). If the name is
1107db96d56Sopenharmony_ci    specified in relative terms, then the *package* argument must be set to
1117db96d56Sopenharmony_ci    the name of the package which is to act as the anchor for resolving the
1127db96d56Sopenharmony_ci    package name (e.g. ``import_module('..mod', 'pkg.subpkg')`` will import
1137db96d56Sopenharmony_ci    ``pkg.mod``).
1147db96d56Sopenharmony_ci
1157db96d56Sopenharmony_ci    The :func:`import_module` function acts as a simplifying wrapper around
1167db96d56Sopenharmony_ci    :func:`importlib.__import__`. This means all semantics of the function are
1177db96d56Sopenharmony_ci    derived from :func:`importlib.__import__`. The most important difference
1187db96d56Sopenharmony_ci    between these two functions is that :func:`import_module` returns the
1197db96d56Sopenharmony_ci    specified package or module (e.g. ``pkg.mod``), while :func:`__import__`
1207db96d56Sopenharmony_ci    returns the top-level package or module (e.g. ``pkg``).
1217db96d56Sopenharmony_ci
1227db96d56Sopenharmony_ci    If you are dynamically importing a module that was created since the
1237db96d56Sopenharmony_ci    interpreter began execution (e.g., created a Python source file), you may
1247db96d56Sopenharmony_ci    need to call :func:`invalidate_caches` in order for the new module to be
1257db96d56Sopenharmony_ci    noticed by the import system.
1267db96d56Sopenharmony_ci
1277db96d56Sopenharmony_ci    .. versionchanged:: 3.3
1287db96d56Sopenharmony_ci       Parent packages are automatically imported.
1297db96d56Sopenharmony_ci
1307db96d56Sopenharmony_ci.. function:: find_loader(name, path=None)
1317db96d56Sopenharmony_ci
1327db96d56Sopenharmony_ci   Find the loader for a module, optionally within the specified *path*. If the
1337db96d56Sopenharmony_ci   module is in :attr:`sys.modules`, then ``sys.modules[name].__loader__`` is
1347db96d56Sopenharmony_ci   returned (unless the loader would be ``None`` or is not set, in which case
1357db96d56Sopenharmony_ci   :exc:`ValueError` is raised). Otherwise a search using :attr:`sys.meta_path`
1367db96d56Sopenharmony_ci   is done. ``None`` is returned if no loader is found.
1377db96d56Sopenharmony_ci
1387db96d56Sopenharmony_ci   A dotted name does not have its parents implicitly imported as that requires
1397db96d56Sopenharmony_ci   loading them and that may not be desired. To properly import a submodule you
1407db96d56Sopenharmony_ci   will need to import all parent packages of the submodule and use the correct
1417db96d56Sopenharmony_ci   argument to *path*.
1427db96d56Sopenharmony_ci
1437db96d56Sopenharmony_ci   .. versionadded:: 3.3
1447db96d56Sopenharmony_ci
1457db96d56Sopenharmony_ci   .. versionchanged:: 3.4
1467db96d56Sopenharmony_ci      If ``__loader__`` is not set, raise :exc:`ValueError`, just like when the
1477db96d56Sopenharmony_ci      attribute is set to ``None``.
1487db96d56Sopenharmony_ci
1497db96d56Sopenharmony_ci   .. deprecated:: 3.4
1507db96d56Sopenharmony_ci      Use :func:`importlib.util.find_spec` instead.
1517db96d56Sopenharmony_ci
1527db96d56Sopenharmony_ci.. function:: invalidate_caches()
1537db96d56Sopenharmony_ci
1547db96d56Sopenharmony_ci   Invalidate the internal caches of finders stored at
1557db96d56Sopenharmony_ci   :data:`sys.meta_path`. If a finder implements ``invalidate_caches()`` then it
1567db96d56Sopenharmony_ci   will be called to perform the invalidation.  This function should be called
1577db96d56Sopenharmony_ci   if any modules are created/installed while your program is running to
1587db96d56Sopenharmony_ci   guarantee all finders will notice the new module's existence.
1597db96d56Sopenharmony_ci
1607db96d56Sopenharmony_ci   .. versionadded:: 3.3
1617db96d56Sopenharmony_ci
1627db96d56Sopenharmony_ci   .. versionchanged:: 3.10
1637db96d56Sopenharmony_ci      Namespace packages created/installed in a different :data:`sys.path`
1647db96d56Sopenharmony_ci      location after the same namespace was already imported are noticed.
1657db96d56Sopenharmony_ci
1667db96d56Sopenharmony_ci.. function:: reload(module)
1677db96d56Sopenharmony_ci
1687db96d56Sopenharmony_ci   Reload a previously imported *module*.  The argument must be a module object,
1697db96d56Sopenharmony_ci   so it must have been successfully imported before.  This is useful if you
1707db96d56Sopenharmony_ci   have edited the module source file using an external editor and want to try
1717db96d56Sopenharmony_ci   out the new version without leaving the Python interpreter.  The return value
1727db96d56Sopenharmony_ci   is the module object (which can be different if re-importing causes a
1737db96d56Sopenharmony_ci   different object to be placed in :data:`sys.modules`).
1747db96d56Sopenharmony_ci
1757db96d56Sopenharmony_ci   When :func:`reload` is executed:
1767db96d56Sopenharmony_ci
1777db96d56Sopenharmony_ci   * Python module's code is recompiled and the module-level code re-executed,
1787db96d56Sopenharmony_ci     defining a new set of objects which are bound to names in the module's
1797db96d56Sopenharmony_ci     dictionary by reusing the :term:`loader` which originally loaded the
1807db96d56Sopenharmony_ci     module.  The ``init`` function of extension modules is not called a second
1817db96d56Sopenharmony_ci     time.
1827db96d56Sopenharmony_ci
1837db96d56Sopenharmony_ci   * As with all other objects in Python the old objects are only reclaimed
1847db96d56Sopenharmony_ci     after their reference counts drop to zero.
1857db96d56Sopenharmony_ci
1867db96d56Sopenharmony_ci   * The names in the module namespace are updated to point to any new or
1877db96d56Sopenharmony_ci     changed objects.
1887db96d56Sopenharmony_ci
1897db96d56Sopenharmony_ci   * Other references to the old objects (such as names external to the module) are
1907db96d56Sopenharmony_ci     not rebound to refer to the new objects and must be updated in each namespace
1917db96d56Sopenharmony_ci     where they occur if that is desired.
1927db96d56Sopenharmony_ci
1937db96d56Sopenharmony_ci   There are a number of other caveats:
1947db96d56Sopenharmony_ci
1957db96d56Sopenharmony_ci   When a module is reloaded, its dictionary (containing the module's global
1967db96d56Sopenharmony_ci   variables) is retained.  Redefinitions of names will override the old
1977db96d56Sopenharmony_ci   definitions, so this is generally not a problem.  If the new version of a
1987db96d56Sopenharmony_ci   module does not define a name that was defined by the old version, the old
1997db96d56Sopenharmony_ci   definition remains.  This feature can be used to the module's advantage if it
2007db96d56Sopenharmony_ci   maintains a global table or cache of objects --- with a :keyword:`try`
2017db96d56Sopenharmony_ci   statement it can test for the table's presence and skip its initialization if
2027db96d56Sopenharmony_ci   desired::
2037db96d56Sopenharmony_ci
2047db96d56Sopenharmony_ci      try:
2057db96d56Sopenharmony_ci          cache
2067db96d56Sopenharmony_ci      except NameError:
2077db96d56Sopenharmony_ci          cache = {}
2087db96d56Sopenharmony_ci
2097db96d56Sopenharmony_ci   It is generally not very useful to reload built-in or dynamically loaded
2107db96d56Sopenharmony_ci   modules.  Reloading :mod:`sys`, :mod:`__main__`, :mod:`builtins` and other
2117db96d56Sopenharmony_ci   key modules is not recommended.  In many cases extension modules are not
2127db96d56Sopenharmony_ci   designed to be initialized more than once, and may fail in arbitrary ways
2137db96d56Sopenharmony_ci   when reloaded.
2147db96d56Sopenharmony_ci
2157db96d56Sopenharmony_ci   If a module imports objects from another module using :keyword:`from` ...
2167db96d56Sopenharmony_ci   :keyword:`import` ..., calling :func:`reload` for the other module does not
2177db96d56Sopenharmony_ci   redefine the objects imported from it --- one way around this is to
2187db96d56Sopenharmony_ci   re-execute the :keyword:`!from` statement, another is to use :keyword:`!import`
2197db96d56Sopenharmony_ci   and qualified names (*module.name*) instead.
2207db96d56Sopenharmony_ci
2217db96d56Sopenharmony_ci   If a module instantiates instances of a class, reloading the module that
2227db96d56Sopenharmony_ci   defines the class does not affect the method definitions of the instances ---
2237db96d56Sopenharmony_ci   they continue to use the old class definition.  The same is true for derived
2247db96d56Sopenharmony_ci   classes.
2257db96d56Sopenharmony_ci
2267db96d56Sopenharmony_ci   .. versionadded:: 3.4
2277db96d56Sopenharmony_ci   .. versionchanged:: 3.7
2287db96d56Sopenharmony_ci       :exc:`ModuleNotFoundError` is raised when the module being reloaded lacks
2297db96d56Sopenharmony_ci       a :class:`~importlib.machinery.ModuleSpec`.
2307db96d56Sopenharmony_ci
2317db96d56Sopenharmony_ci
2327db96d56Sopenharmony_ci:mod:`importlib.abc` -- Abstract base classes related to import
2337db96d56Sopenharmony_ci---------------------------------------------------------------
2347db96d56Sopenharmony_ci
2357db96d56Sopenharmony_ci.. module:: importlib.abc
2367db96d56Sopenharmony_ci    :synopsis: Abstract base classes related to import
2377db96d56Sopenharmony_ci
2387db96d56Sopenharmony_ci**Source code:** :source:`Lib/importlib/abc.py`
2397db96d56Sopenharmony_ci
2407db96d56Sopenharmony_ci--------------
2417db96d56Sopenharmony_ci
2427db96d56Sopenharmony_ci
2437db96d56Sopenharmony_ciThe :mod:`importlib.abc` module contains all of the core abstract base classes
2447db96d56Sopenharmony_ciused by :keyword:`import`. Some subclasses of the core abstract base classes
2457db96d56Sopenharmony_ciare also provided to help in implementing the core ABCs.
2467db96d56Sopenharmony_ci
2477db96d56Sopenharmony_ciABC hierarchy::
2487db96d56Sopenharmony_ci
2497db96d56Sopenharmony_ci    object
2507db96d56Sopenharmony_ci     +-- Finder (deprecated)
2517db96d56Sopenharmony_ci     +-- MetaPathFinder
2527db96d56Sopenharmony_ci     +-- PathEntryFinder
2537db96d56Sopenharmony_ci     +-- Loader
2547db96d56Sopenharmony_ci          +-- ResourceLoader --------+
2557db96d56Sopenharmony_ci          +-- InspectLoader          |
2567db96d56Sopenharmony_ci               +-- ExecutionLoader --+
2577db96d56Sopenharmony_ci                                     +-- FileLoader
2587db96d56Sopenharmony_ci                                     +-- SourceLoader
2597db96d56Sopenharmony_ci
2607db96d56Sopenharmony_ci
2617db96d56Sopenharmony_ci.. class:: Finder
2627db96d56Sopenharmony_ci
2637db96d56Sopenharmony_ci   An abstract base class representing a :term:`finder`.
2647db96d56Sopenharmony_ci
2657db96d56Sopenharmony_ci   .. deprecated:: 3.3
2667db96d56Sopenharmony_ci      Use :class:`MetaPathFinder` or :class:`PathEntryFinder` instead.
2677db96d56Sopenharmony_ci
2687db96d56Sopenharmony_ci   .. abstractmethod:: find_module(fullname, path=None)
2697db96d56Sopenharmony_ci
2707db96d56Sopenharmony_ci      An abstract method for finding a :term:`loader` for the specified
2717db96d56Sopenharmony_ci      module.  Originally specified in :pep:`302`, this method was meant
2727db96d56Sopenharmony_ci      for use in :data:`sys.meta_path` and in the path-based import subsystem.
2737db96d56Sopenharmony_ci
2747db96d56Sopenharmony_ci      .. versionchanged:: 3.4
2757db96d56Sopenharmony_ci         Returns ``None`` when called instead of raising
2767db96d56Sopenharmony_ci         :exc:`NotImplementedError`.
2777db96d56Sopenharmony_ci
2787db96d56Sopenharmony_ci      .. deprecated:: 3.10
2797db96d56Sopenharmony_ci         Implement :meth:`MetaPathFinder.find_spec` or
2807db96d56Sopenharmony_ci         :meth:`PathEntryFinder.find_spec` instead.
2817db96d56Sopenharmony_ci
2827db96d56Sopenharmony_ci
2837db96d56Sopenharmony_ci.. class:: MetaPathFinder
2847db96d56Sopenharmony_ci
2857db96d56Sopenharmony_ci   An abstract base class representing a :term:`meta path finder`.
2867db96d56Sopenharmony_ci
2877db96d56Sopenharmony_ci   .. versionadded:: 3.3
2887db96d56Sopenharmony_ci
2897db96d56Sopenharmony_ci   .. versionchanged:: 3.10
2907db96d56Sopenharmony_ci      No longer a subclass of :class:`Finder`.
2917db96d56Sopenharmony_ci
2927db96d56Sopenharmony_ci   .. method:: find_spec(fullname, path, target=None)
2937db96d56Sopenharmony_ci
2947db96d56Sopenharmony_ci      An abstract method for finding a :term:`spec <module spec>` for
2957db96d56Sopenharmony_ci      the specified module.  If this is a top-level import, *path* will
2967db96d56Sopenharmony_ci      be ``None``.  Otherwise, this is a search for a subpackage or
2977db96d56Sopenharmony_ci      module and *path* will be the value of :attr:`__path__` from the
2987db96d56Sopenharmony_ci      parent package. If a spec cannot be found, ``None`` is returned.
2997db96d56Sopenharmony_ci      When passed in, ``target`` is a module object that the finder may
3007db96d56Sopenharmony_ci      use to make a more educated guess about what spec to return.
3017db96d56Sopenharmony_ci      :func:`importlib.util.spec_from_loader` may be useful for implementing
3027db96d56Sopenharmony_ci      concrete ``MetaPathFinders``.
3037db96d56Sopenharmony_ci
3047db96d56Sopenharmony_ci      .. versionadded:: 3.4
3057db96d56Sopenharmony_ci
3067db96d56Sopenharmony_ci   .. method:: find_module(fullname, path)
3077db96d56Sopenharmony_ci
3087db96d56Sopenharmony_ci      A legacy method for finding a :term:`loader` for the specified
3097db96d56Sopenharmony_ci      module.  If this is a top-level import, *path* will be ``None``.
3107db96d56Sopenharmony_ci      Otherwise, this is a search for a subpackage or module and *path*
3117db96d56Sopenharmony_ci      will be the value of :attr:`__path__` from the parent
3127db96d56Sopenharmony_ci      package. If a loader cannot be found, ``None`` is returned.
3137db96d56Sopenharmony_ci
3147db96d56Sopenharmony_ci      If :meth:`find_spec` is defined, backwards-compatible functionality is
3157db96d56Sopenharmony_ci      provided.
3167db96d56Sopenharmony_ci
3177db96d56Sopenharmony_ci      .. versionchanged:: 3.4
3187db96d56Sopenharmony_ci         Returns ``None`` when called instead of raising
3197db96d56Sopenharmony_ci         :exc:`NotImplementedError`. Can use :meth:`find_spec` to provide
3207db96d56Sopenharmony_ci         functionality.
3217db96d56Sopenharmony_ci
3227db96d56Sopenharmony_ci      .. deprecated:: 3.4
3237db96d56Sopenharmony_ci         Use :meth:`find_spec` instead.
3247db96d56Sopenharmony_ci
3257db96d56Sopenharmony_ci   .. method:: invalidate_caches()
3267db96d56Sopenharmony_ci
3277db96d56Sopenharmony_ci      An optional method which, when called, should invalidate any internal
3287db96d56Sopenharmony_ci      cache used by the finder. Used by :func:`importlib.invalidate_caches`
3297db96d56Sopenharmony_ci      when invalidating the caches of all finders on :data:`sys.meta_path`.
3307db96d56Sopenharmony_ci
3317db96d56Sopenharmony_ci      .. versionchanged:: 3.4
3327db96d56Sopenharmony_ci         Returns ``None`` when called instead of ``NotImplemented``.
3337db96d56Sopenharmony_ci
3347db96d56Sopenharmony_ci
3357db96d56Sopenharmony_ci.. class:: PathEntryFinder
3367db96d56Sopenharmony_ci
3377db96d56Sopenharmony_ci   An abstract base class representing a :term:`path entry finder`.  Though
3387db96d56Sopenharmony_ci   it bears some similarities to :class:`MetaPathFinder`, ``PathEntryFinder``
3397db96d56Sopenharmony_ci   is meant for use only within the path-based import subsystem provided
3407db96d56Sopenharmony_ci   by :class:`importlib.machinery.PathFinder`.
3417db96d56Sopenharmony_ci
3427db96d56Sopenharmony_ci   .. versionadded:: 3.3
3437db96d56Sopenharmony_ci
3447db96d56Sopenharmony_ci   .. versionchanged:: 3.10
3457db96d56Sopenharmony_ci      No longer a subclass of :class:`Finder`.
3467db96d56Sopenharmony_ci
3477db96d56Sopenharmony_ci   .. method:: find_spec(fullname, target=None)
3487db96d56Sopenharmony_ci
3497db96d56Sopenharmony_ci      An abstract method for finding a :term:`spec <module spec>` for
3507db96d56Sopenharmony_ci      the specified module.  The finder will search for the module only
3517db96d56Sopenharmony_ci      within the :term:`path entry` to which it is assigned.  If a spec
3527db96d56Sopenharmony_ci      cannot be found, ``None`` is returned.  When passed in, ``target``
3537db96d56Sopenharmony_ci      is a module object that the finder may use to make a more educated
3547db96d56Sopenharmony_ci      guess about what spec to return. :func:`importlib.util.spec_from_loader`
3557db96d56Sopenharmony_ci      may be useful for implementing concrete ``PathEntryFinders``.
3567db96d56Sopenharmony_ci
3577db96d56Sopenharmony_ci      .. versionadded:: 3.4
3587db96d56Sopenharmony_ci
3597db96d56Sopenharmony_ci   .. method:: find_loader(fullname)
3607db96d56Sopenharmony_ci
3617db96d56Sopenharmony_ci      A legacy method for finding a :term:`loader` for the specified
3627db96d56Sopenharmony_ci      module.  Returns a 2-tuple of ``(loader, portion)`` where ``portion``
3637db96d56Sopenharmony_ci      is a sequence of file system locations contributing to part of a namespace
3647db96d56Sopenharmony_ci      package. The loader may be ``None`` while specifying ``portion`` to
3657db96d56Sopenharmony_ci      signify the contribution of the file system locations to a namespace
3667db96d56Sopenharmony_ci      package. An empty list can be used for ``portion`` to signify the loader
3677db96d56Sopenharmony_ci      is not part of a namespace package. If ``loader`` is ``None`` and
3687db96d56Sopenharmony_ci      ``portion`` is the empty list then no loader or location for a namespace
3697db96d56Sopenharmony_ci      package were found (i.e. failure to find anything for the module).
3707db96d56Sopenharmony_ci
3717db96d56Sopenharmony_ci      If :meth:`find_spec` is defined then backwards-compatible functionality is
3727db96d56Sopenharmony_ci      provided.
3737db96d56Sopenharmony_ci
3747db96d56Sopenharmony_ci      .. versionchanged:: 3.4
3757db96d56Sopenharmony_ci         Returns ``(None, [])`` instead of raising :exc:`NotImplementedError`.
3767db96d56Sopenharmony_ci         Uses :meth:`find_spec` when available to provide functionality.
3777db96d56Sopenharmony_ci
3787db96d56Sopenharmony_ci      .. deprecated:: 3.4
3797db96d56Sopenharmony_ci         Use :meth:`find_spec` instead.
3807db96d56Sopenharmony_ci
3817db96d56Sopenharmony_ci   .. method:: find_module(fullname)
3827db96d56Sopenharmony_ci
3837db96d56Sopenharmony_ci      A concrete implementation of :meth:`Finder.find_module` which is
3847db96d56Sopenharmony_ci      equivalent to ``self.find_loader(fullname)[0]``.
3857db96d56Sopenharmony_ci
3867db96d56Sopenharmony_ci      .. deprecated:: 3.4
3877db96d56Sopenharmony_ci         Use :meth:`find_spec` instead.
3887db96d56Sopenharmony_ci
3897db96d56Sopenharmony_ci   .. method:: invalidate_caches()
3907db96d56Sopenharmony_ci
3917db96d56Sopenharmony_ci      An optional method which, when called, should invalidate any internal
3927db96d56Sopenharmony_ci      cache used by the finder. Used by
3937db96d56Sopenharmony_ci      :meth:`importlib.machinery.PathFinder.invalidate_caches`
3947db96d56Sopenharmony_ci      when invalidating the caches of all cached finders.
3957db96d56Sopenharmony_ci
3967db96d56Sopenharmony_ci
3977db96d56Sopenharmony_ci.. class:: Loader
3987db96d56Sopenharmony_ci
3997db96d56Sopenharmony_ci    An abstract base class for a :term:`loader`.
4007db96d56Sopenharmony_ci    See :pep:`302` for the exact definition for a loader.
4017db96d56Sopenharmony_ci
4027db96d56Sopenharmony_ci    Loaders that wish to support resource reading should implement a
4037db96d56Sopenharmony_ci    :meth:`get_resource_reader` method as specified by
4047db96d56Sopenharmony_ci    :class:`importlib.resources.abc.ResourceReader`.
4057db96d56Sopenharmony_ci
4067db96d56Sopenharmony_ci    .. versionchanged:: 3.7
4077db96d56Sopenharmony_ci       Introduced the optional :meth:`get_resource_reader` method.
4087db96d56Sopenharmony_ci
4097db96d56Sopenharmony_ci    .. method:: create_module(spec)
4107db96d56Sopenharmony_ci
4117db96d56Sopenharmony_ci       A method that returns the module object to use when
4127db96d56Sopenharmony_ci       importing a module.  This method may return ``None``,
4137db96d56Sopenharmony_ci       indicating that default module creation semantics should take place.
4147db96d56Sopenharmony_ci
4157db96d56Sopenharmony_ci       .. versionadded:: 3.4
4167db96d56Sopenharmony_ci
4177db96d56Sopenharmony_ci       .. versionchanged:: 3.6
4187db96d56Sopenharmony_ci          This method is no longer optional when
4197db96d56Sopenharmony_ci          :meth:`exec_module` is defined.
4207db96d56Sopenharmony_ci
4217db96d56Sopenharmony_ci    .. method:: exec_module(module)
4227db96d56Sopenharmony_ci
4237db96d56Sopenharmony_ci       An abstract method that executes the module in its own namespace
4247db96d56Sopenharmony_ci       when a module is imported or reloaded.  The module should already
4257db96d56Sopenharmony_ci       be initialized when :meth:`exec_module` is called.  When this method exists,
4267db96d56Sopenharmony_ci       :meth:`create_module` must be defined.
4277db96d56Sopenharmony_ci
4287db96d56Sopenharmony_ci       .. versionadded:: 3.4
4297db96d56Sopenharmony_ci
4307db96d56Sopenharmony_ci       .. versionchanged:: 3.6
4317db96d56Sopenharmony_ci          :meth:`create_module` must also be defined.
4327db96d56Sopenharmony_ci
4337db96d56Sopenharmony_ci    .. method:: load_module(fullname)
4347db96d56Sopenharmony_ci
4357db96d56Sopenharmony_ci        A legacy method for loading a module.  If the module cannot be
4367db96d56Sopenharmony_ci        loaded, :exc:`ImportError` is raised, otherwise the loaded module is
4377db96d56Sopenharmony_ci        returned.
4387db96d56Sopenharmony_ci
4397db96d56Sopenharmony_ci        If the requested module already exists in :data:`sys.modules`, that
4407db96d56Sopenharmony_ci        module should be used and reloaded.
4417db96d56Sopenharmony_ci        Otherwise the loader should create a new module and insert it into
4427db96d56Sopenharmony_ci        :data:`sys.modules` before any loading begins, to prevent recursion
4437db96d56Sopenharmony_ci        from the import.  If the loader inserted a module and the load fails, it
4447db96d56Sopenharmony_ci        must be removed by the loader from :data:`sys.modules`; modules already
4457db96d56Sopenharmony_ci        in :data:`sys.modules` before the loader began execution should be left
4467db96d56Sopenharmony_ci        alone (see :func:`importlib.util.module_for_loader`).
4477db96d56Sopenharmony_ci
4487db96d56Sopenharmony_ci        The loader should set several attributes on the module
4497db96d56Sopenharmony_ci        (note that some of these attributes can change when a module is
4507db96d56Sopenharmony_ci        reloaded):
4517db96d56Sopenharmony_ci
4527db96d56Sopenharmony_ci        - :attr:`__name__`
4537db96d56Sopenharmony_ci            The module's fully qualified name.
4547db96d56Sopenharmony_ci            It is ``'__main__'`` for an executed module.
4557db96d56Sopenharmony_ci
4567db96d56Sopenharmony_ci        - :attr:`__file__`
4577db96d56Sopenharmony_ci            The location the :term:`loader` used to load the module.
4587db96d56Sopenharmony_ci            For example, for modules loaded from a .py file this is the filename.
4597db96d56Sopenharmony_ci            It is not set on all modules (e.g. built-in modules).
4607db96d56Sopenharmony_ci
4617db96d56Sopenharmony_ci        - :attr:`__cached__`
4627db96d56Sopenharmony_ci            The filename of a compiled version of the module's code.
4637db96d56Sopenharmony_ci            It is not set on all modules (e.g. built-in modules).
4647db96d56Sopenharmony_ci
4657db96d56Sopenharmony_ci        - :attr:`__path__`
4667db96d56Sopenharmony_ci            The list of locations where the package's submodules will be found.
4677db96d56Sopenharmony_ci            Most of the time this is a single directory.
4687db96d56Sopenharmony_ci            The import system passes this attribute to ``__import__()`` and to finders
4697db96d56Sopenharmony_ci            in the same way as :attr:`sys.path` but just for the package.
4707db96d56Sopenharmony_ci            It is not set on non-package modules so it can be used
4717db96d56Sopenharmony_ci            as an indicator that the module is a package.
4727db96d56Sopenharmony_ci
4737db96d56Sopenharmony_ci        - :attr:`__package__`
4747db96d56Sopenharmony_ci            The fully qualified name of the package the module is in (or the
4757db96d56Sopenharmony_ci            empty string for a top-level module).
4767db96d56Sopenharmony_ci            If the module is a package then this is the same as :attr:`__name__`.
4777db96d56Sopenharmony_ci
4787db96d56Sopenharmony_ci        - :attr:`__loader__`
4797db96d56Sopenharmony_ci            The :term:`loader` used to load the module.
4807db96d56Sopenharmony_ci
4817db96d56Sopenharmony_ci        When :meth:`exec_module` is available then backwards-compatible
4827db96d56Sopenharmony_ci        functionality is provided.
4837db96d56Sopenharmony_ci
4847db96d56Sopenharmony_ci        .. versionchanged:: 3.4
4857db96d56Sopenharmony_ci           Raise :exc:`ImportError` when called instead of
4867db96d56Sopenharmony_ci           :exc:`NotImplementedError`.  Functionality provided when
4877db96d56Sopenharmony_ci           :meth:`exec_module` is available.
4887db96d56Sopenharmony_ci
4897db96d56Sopenharmony_ci        .. deprecated:: 3.4
4907db96d56Sopenharmony_ci           The recommended API for loading a module is :meth:`exec_module`
4917db96d56Sopenharmony_ci           (and :meth:`create_module`).  Loaders should implement it instead of
4927db96d56Sopenharmony_ci           :meth:`load_module`.  The import machinery takes care of all the
4937db96d56Sopenharmony_ci           other responsibilities of :meth:`load_module` when
4947db96d56Sopenharmony_ci           :meth:`exec_module` is implemented.
4957db96d56Sopenharmony_ci
4967db96d56Sopenharmony_ci    .. method:: module_repr(module)
4977db96d56Sopenharmony_ci
4987db96d56Sopenharmony_ci        A legacy method which when implemented calculates and returns the given
4997db96d56Sopenharmony_ci        module's representation, as a string.  The module type's default
5007db96d56Sopenharmony_ci        :meth:`__repr__` will use the result of this method as appropriate.
5017db96d56Sopenharmony_ci
5027db96d56Sopenharmony_ci        .. versionadded:: 3.3
5037db96d56Sopenharmony_ci
5047db96d56Sopenharmony_ci        .. versionchanged:: 3.4
5057db96d56Sopenharmony_ci           Made optional instead of an abstractmethod.
5067db96d56Sopenharmony_ci
5077db96d56Sopenharmony_ci        .. deprecated:: 3.4
5087db96d56Sopenharmony_ci           The import machinery now takes care of this automatically.
5097db96d56Sopenharmony_ci
5107db96d56Sopenharmony_ci
5117db96d56Sopenharmony_ci.. class:: ResourceLoader
5127db96d56Sopenharmony_ci
5137db96d56Sopenharmony_ci    An abstract base class for a :term:`loader` which implements the optional
5147db96d56Sopenharmony_ci    :pep:`302` protocol for loading arbitrary resources from the storage
5157db96d56Sopenharmony_ci    back-end.
5167db96d56Sopenharmony_ci
5177db96d56Sopenharmony_ci    .. deprecated:: 3.7
5187db96d56Sopenharmony_ci       This ABC is deprecated in favour of supporting resource loading
5197db96d56Sopenharmony_ci       through :class:`importlib.resources.abc.ResourceReader`.
5207db96d56Sopenharmony_ci
5217db96d56Sopenharmony_ci    .. abstractmethod:: get_data(path)
5227db96d56Sopenharmony_ci
5237db96d56Sopenharmony_ci        An abstract method to return the bytes for the data located at *path*.
5247db96d56Sopenharmony_ci        Loaders that have a file-like storage back-end
5257db96d56Sopenharmony_ci        that allows storing arbitrary data
5267db96d56Sopenharmony_ci        can implement this abstract method to give direct access
5277db96d56Sopenharmony_ci        to the data stored. :exc:`OSError` is to be raised if the *path* cannot
5287db96d56Sopenharmony_ci        be found. The *path* is expected to be constructed using a module's
5297db96d56Sopenharmony_ci        :attr:`__file__` attribute or an item from a package's :attr:`__path__`.
5307db96d56Sopenharmony_ci
5317db96d56Sopenharmony_ci        .. versionchanged:: 3.4
5327db96d56Sopenharmony_ci           Raises :exc:`OSError` instead of :exc:`NotImplementedError`.
5337db96d56Sopenharmony_ci
5347db96d56Sopenharmony_ci
5357db96d56Sopenharmony_ci.. class:: InspectLoader
5367db96d56Sopenharmony_ci
5377db96d56Sopenharmony_ci    An abstract base class for a :term:`loader` which implements the optional
5387db96d56Sopenharmony_ci    :pep:`302` protocol for loaders that inspect modules.
5397db96d56Sopenharmony_ci
5407db96d56Sopenharmony_ci    .. method:: get_code(fullname)
5417db96d56Sopenharmony_ci
5427db96d56Sopenharmony_ci        Return the code object for a module, or ``None`` if the module does not
5437db96d56Sopenharmony_ci        have a code object (as would be the case, for example, for a built-in
5447db96d56Sopenharmony_ci        module).  Raise an :exc:`ImportError` if loader cannot find the
5457db96d56Sopenharmony_ci        requested module.
5467db96d56Sopenharmony_ci
5477db96d56Sopenharmony_ci        .. note::
5487db96d56Sopenharmony_ci           While the method has a default implementation, it is suggested that
5497db96d56Sopenharmony_ci           it be overridden if possible for performance.
5507db96d56Sopenharmony_ci
5517db96d56Sopenharmony_ci        .. index::
5527db96d56Sopenharmony_ci           single: universal newlines; importlib.abc.InspectLoader.get_source method
5537db96d56Sopenharmony_ci
5547db96d56Sopenharmony_ci        .. versionchanged:: 3.4
5557db96d56Sopenharmony_ci           No longer abstract and a concrete implementation is provided.
5567db96d56Sopenharmony_ci
5577db96d56Sopenharmony_ci    .. abstractmethod:: get_source(fullname)
5587db96d56Sopenharmony_ci
5597db96d56Sopenharmony_ci        An abstract method to return the source of a module. It is returned as
5607db96d56Sopenharmony_ci        a text string using :term:`universal newlines`, translating all
5617db96d56Sopenharmony_ci        recognized line separators into ``'\n'`` characters.  Returns ``None``
5627db96d56Sopenharmony_ci        if no source is available (e.g. a built-in module). Raises
5637db96d56Sopenharmony_ci        :exc:`ImportError` if the loader cannot find the module specified.
5647db96d56Sopenharmony_ci
5657db96d56Sopenharmony_ci        .. versionchanged:: 3.4
5667db96d56Sopenharmony_ci           Raises :exc:`ImportError` instead of :exc:`NotImplementedError`.
5677db96d56Sopenharmony_ci
5687db96d56Sopenharmony_ci    .. method:: is_package(fullname)
5697db96d56Sopenharmony_ci
5707db96d56Sopenharmony_ci        An optional method to return a true value if the module is a package, a
5717db96d56Sopenharmony_ci        false value otherwise. :exc:`ImportError` is raised if the
5727db96d56Sopenharmony_ci        :term:`loader` cannot find the module.
5737db96d56Sopenharmony_ci
5747db96d56Sopenharmony_ci        .. versionchanged:: 3.4
5757db96d56Sopenharmony_ci           Raises :exc:`ImportError` instead of :exc:`NotImplementedError`.
5767db96d56Sopenharmony_ci
5777db96d56Sopenharmony_ci    .. staticmethod:: source_to_code(data, path='<string>')
5787db96d56Sopenharmony_ci
5797db96d56Sopenharmony_ci        Create a code object from Python source.
5807db96d56Sopenharmony_ci
5817db96d56Sopenharmony_ci        The *data* argument can be whatever the :func:`compile` function
5827db96d56Sopenharmony_ci        supports (i.e. string or bytes). The *path* argument should be
5837db96d56Sopenharmony_ci        the "path" to where the source code originated from, which can be an
5847db96d56Sopenharmony_ci        abstract concept (e.g. location in a zip file).
5857db96d56Sopenharmony_ci
5867db96d56Sopenharmony_ci        With the subsequent code object one can execute it in a module by
5877db96d56Sopenharmony_ci        running ``exec(code, module.__dict__)``.
5887db96d56Sopenharmony_ci
5897db96d56Sopenharmony_ci        .. versionadded:: 3.4
5907db96d56Sopenharmony_ci
5917db96d56Sopenharmony_ci        .. versionchanged:: 3.5
5927db96d56Sopenharmony_ci           Made the method static.
5937db96d56Sopenharmony_ci
5947db96d56Sopenharmony_ci    .. method:: exec_module(module)
5957db96d56Sopenharmony_ci
5967db96d56Sopenharmony_ci       Implementation of :meth:`Loader.exec_module`.
5977db96d56Sopenharmony_ci
5987db96d56Sopenharmony_ci       .. versionadded:: 3.4
5997db96d56Sopenharmony_ci
6007db96d56Sopenharmony_ci    .. method:: load_module(fullname)
6017db96d56Sopenharmony_ci
6027db96d56Sopenharmony_ci       Implementation of :meth:`Loader.load_module`.
6037db96d56Sopenharmony_ci
6047db96d56Sopenharmony_ci       .. deprecated:: 3.4
6057db96d56Sopenharmony_ci          use :meth:`exec_module` instead.
6067db96d56Sopenharmony_ci
6077db96d56Sopenharmony_ci
6087db96d56Sopenharmony_ci.. class:: ExecutionLoader
6097db96d56Sopenharmony_ci
6107db96d56Sopenharmony_ci    An abstract base class which inherits from :class:`InspectLoader` that,
6117db96d56Sopenharmony_ci    when implemented, helps a module to be executed as a script. The ABC
6127db96d56Sopenharmony_ci    represents an optional :pep:`302` protocol.
6137db96d56Sopenharmony_ci
6147db96d56Sopenharmony_ci    .. abstractmethod:: get_filename(fullname)
6157db96d56Sopenharmony_ci
6167db96d56Sopenharmony_ci        An abstract method that is to return the value of :attr:`__file__` for
6177db96d56Sopenharmony_ci        the specified module. If no path is available, :exc:`ImportError` is
6187db96d56Sopenharmony_ci        raised.
6197db96d56Sopenharmony_ci
6207db96d56Sopenharmony_ci        If source code is available, then the method should return the path to
6217db96d56Sopenharmony_ci        the source file, regardless of whether a bytecode was used to load the
6227db96d56Sopenharmony_ci        module.
6237db96d56Sopenharmony_ci
6247db96d56Sopenharmony_ci        .. versionchanged:: 3.4
6257db96d56Sopenharmony_ci           Raises :exc:`ImportError` instead of :exc:`NotImplementedError`.
6267db96d56Sopenharmony_ci
6277db96d56Sopenharmony_ci
6287db96d56Sopenharmony_ci.. class:: FileLoader(fullname, path)
6297db96d56Sopenharmony_ci
6307db96d56Sopenharmony_ci   An abstract base class which inherits from :class:`ResourceLoader` and
6317db96d56Sopenharmony_ci   :class:`ExecutionLoader`, providing concrete implementations of
6327db96d56Sopenharmony_ci   :meth:`ResourceLoader.get_data` and :meth:`ExecutionLoader.get_filename`.
6337db96d56Sopenharmony_ci
6347db96d56Sopenharmony_ci   The *fullname* argument is a fully resolved name of the module the loader is
6357db96d56Sopenharmony_ci   to handle. The *path* argument is the path to the file for the module.
6367db96d56Sopenharmony_ci
6377db96d56Sopenharmony_ci   .. versionadded:: 3.3
6387db96d56Sopenharmony_ci
6397db96d56Sopenharmony_ci   .. attribute:: name
6407db96d56Sopenharmony_ci
6417db96d56Sopenharmony_ci      The name of the module the loader can handle.
6427db96d56Sopenharmony_ci
6437db96d56Sopenharmony_ci   .. attribute:: path
6447db96d56Sopenharmony_ci
6457db96d56Sopenharmony_ci      Path to the file of the module.
6467db96d56Sopenharmony_ci
6477db96d56Sopenharmony_ci   .. method:: load_module(fullname)
6487db96d56Sopenharmony_ci
6497db96d56Sopenharmony_ci      Calls super's ``load_module()``.
6507db96d56Sopenharmony_ci
6517db96d56Sopenharmony_ci      .. deprecated:: 3.4
6527db96d56Sopenharmony_ci         Use :meth:`Loader.exec_module` instead.
6537db96d56Sopenharmony_ci
6547db96d56Sopenharmony_ci   .. abstractmethod:: get_filename(fullname)
6557db96d56Sopenharmony_ci
6567db96d56Sopenharmony_ci      Returns :attr:`path`.
6577db96d56Sopenharmony_ci
6587db96d56Sopenharmony_ci   .. abstractmethod:: get_data(path)
6597db96d56Sopenharmony_ci
6607db96d56Sopenharmony_ci      Reads *path* as a binary file and returns the bytes from it.
6617db96d56Sopenharmony_ci
6627db96d56Sopenharmony_ci
6637db96d56Sopenharmony_ci.. class:: SourceLoader
6647db96d56Sopenharmony_ci
6657db96d56Sopenharmony_ci    An abstract base class for implementing source (and optionally bytecode)
6667db96d56Sopenharmony_ci    file loading. The class inherits from both :class:`ResourceLoader` and
6677db96d56Sopenharmony_ci    :class:`ExecutionLoader`, requiring the implementation of:
6687db96d56Sopenharmony_ci
6697db96d56Sopenharmony_ci    * :meth:`ResourceLoader.get_data`
6707db96d56Sopenharmony_ci    * :meth:`ExecutionLoader.get_filename`
6717db96d56Sopenharmony_ci          Should only return the path to the source file; sourceless
6727db96d56Sopenharmony_ci          loading is not supported.
6737db96d56Sopenharmony_ci
6747db96d56Sopenharmony_ci    The abstract methods defined by this class are to add optional bytecode
6757db96d56Sopenharmony_ci    file support. Not implementing these optional methods (or causing them to
6767db96d56Sopenharmony_ci    raise :exc:`NotImplementedError`) causes the loader to
6777db96d56Sopenharmony_ci    only work with source code. Implementing the methods allows the loader to
6787db96d56Sopenharmony_ci    work with source *and* bytecode files; it does not allow for *sourceless*
6797db96d56Sopenharmony_ci    loading where only bytecode is provided.  Bytecode files are an
6807db96d56Sopenharmony_ci    optimization to speed up loading by removing the parsing step of Python's
6817db96d56Sopenharmony_ci    compiler, and so no bytecode-specific API is exposed.
6827db96d56Sopenharmony_ci
6837db96d56Sopenharmony_ci    .. method:: path_stats(path)
6847db96d56Sopenharmony_ci
6857db96d56Sopenharmony_ci        Optional abstract method which returns a :class:`dict` containing
6867db96d56Sopenharmony_ci        metadata about the specified path.  Supported dictionary keys are:
6877db96d56Sopenharmony_ci
6887db96d56Sopenharmony_ci        - ``'mtime'`` (mandatory): an integer or floating-point number
6897db96d56Sopenharmony_ci          representing the modification time of the source code;
6907db96d56Sopenharmony_ci        - ``'size'`` (optional): the size in bytes of the source code.
6917db96d56Sopenharmony_ci
6927db96d56Sopenharmony_ci        Any other keys in the dictionary are ignored, to allow for future
6937db96d56Sopenharmony_ci        extensions. If the path cannot be handled, :exc:`OSError` is raised.
6947db96d56Sopenharmony_ci
6957db96d56Sopenharmony_ci        .. versionadded:: 3.3
6967db96d56Sopenharmony_ci
6977db96d56Sopenharmony_ci        .. versionchanged:: 3.4
6987db96d56Sopenharmony_ci           Raise :exc:`OSError` instead of :exc:`NotImplementedError`.
6997db96d56Sopenharmony_ci
7007db96d56Sopenharmony_ci    .. method:: path_mtime(path)
7017db96d56Sopenharmony_ci
7027db96d56Sopenharmony_ci        Optional abstract method which returns the modification time for the
7037db96d56Sopenharmony_ci        specified path.
7047db96d56Sopenharmony_ci
7057db96d56Sopenharmony_ci        .. deprecated:: 3.3
7067db96d56Sopenharmony_ci           This method is deprecated in favour of :meth:`path_stats`.  You don't
7077db96d56Sopenharmony_ci           have to implement it, but it is still available for compatibility
7087db96d56Sopenharmony_ci           purposes. Raise :exc:`OSError` if the path cannot be handled.
7097db96d56Sopenharmony_ci
7107db96d56Sopenharmony_ci        .. versionchanged:: 3.4
7117db96d56Sopenharmony_ci           Raise :exc:`OSError` instead of :exc:`NotImplementedError`.
7127db96d56Sopenharmony_ci
7137db96d56Sopenharmony_ci    .. method:: set_data(path, data)
7147db96d56Sopenharmony_ci
7157db96d56Sopenharmony_ci        Optional abstract method which writes the specified bytes to a file
7167db96d56Sopenharmony_ci        path. Any intermediate directories which do not exist are to be created
7177db96d56Sopenharmony_ci        automatically.
7187db96d56Sopenharmony_ci
7197db96d56Sopenharmony_ci        When writing to the path fails because the path is read-only
7207db96d56Sopenharmony_ci        (:attr:`errno.EACCES`/:exc:`PermissionError`), do not propagate the
7217db96d56Sopenharmony_ci        exception.
7227db96d56Sopenharmony_ci
7237db96d56Sopenharmony_ci        .. versionchanged:: 3.4
7247db96d56Sopenharmony_ci           No longer raises :exc:`NotImplementedError` when called.
7257db96d56Sopenharmony_ci
7267db96d56Sopenharmony_ci    .. method:: get_code(fullname)
7277db96d56Sopenharmony_ci
7287db96d56Sopenharmony_ci        Concrete implementation of :meth:`InspectLoader.get_code`.
7297db96d56Sopenharmony_ci
7307db96d56Sopenharmony_ci    .. method:: exec_module(module)
7317db96d56Sopenharmony_ci
7327db96d56Sopenharmony_ci       Concrete implementation of :meth:`Loader.exec_module`.
7337db96d56Sopenharmony_ci
7347db96d56Sopenharmony_ci       .. versionadded:: 3.4
7357db96d56Sopenharmony_ci
7367db96d56Sopenharmony_ci    .. method:: load_module(fullname)
7377db96d56Sopenharmony_ci
7387db96d56Sopenharmony_ci       Concrete implementation of :meth:`Loader.load_module`.
7397db96d56Sopenharmony_ci
7407db96d56Sopenharmony_ci       .. deprecated:: 3.4
7417db96d56Sopenharmony_ci          Use :meth:`exec_module` instead.
7427db96d56Sopenharmony_ci
7437db96d56Sopenharmony_ci    .. method:: get_source(fullname)
7447db96d56Sopenharmony_ci
7457db96d56Sopenharmony_ci        Concrete implementation of :meth:`InspectLoader.get_source`.
7467db96d56Sopenharmony_ci
7477db96d56Sopenharmony_ci    .. method:: is_package(fullname)
7487db96d56Sopenharmony_ci
7497db96d56Sopenharmony_ci        Concrete implementation of :meth:`InspectLoader.is_package`. A module
7507db96d56Sopenharmony_ci        is determined to be a package if its file path (as provided by
7517db96d56Sopenharmony_ci        :meth:`ExecutionLoader.get_filename`) is a file named
7527db96d56Sopenharmony_ci        ``__init__`` when the file extension is removed **and** the module name
7537db96d56Sopenharmony_ci        itself does not end in ``__init__``.
7547db96d56Sopenharmony_ci
7557db96d56Sopenharmony_ci
7567db96d56Sopenharmony_ci
7577db96d56Sopenharmony_ci:mod:`importlib.machinery` -- Importers and path hooks
7587db96d56Sopenharmony_ci------------------------------------------------------
7597db96d56Sopenharmony_ci
7607db96d56Sopenharmony_ci.. module:: importlib.machinery
7617db96d56Sopenharmony_ci    :synopsis: Importers and path hooks
7627db96d56Sopenharmony_ci
7637db96d56Sopenharmony_ci**Source code:** :source:`Lib/importlib/machinery.py`
7647db96d56Sopenharmony_ci
7657db96d56Sopenharmony_ci--------------
7667db96d56Sopenharmony_ci
7677db96d56Sopenharmony_ciThis module contains the various objects that help :keyword:`import`
7687db96d56Sopenharmony_cifind and load modules.
7697db96d56Sopenharmony_ci
7707db96d56Sopenharmony_ci.. attribute:: SOURCE_SUFFIXES
7717db96d56Sopenharmony_ci
7727db96d56Sopenharmony_ci   A list of strings representing the recognized file suffixes for source
7737db96d56Sopenharmony_ci   modules.
7747db96d56Sopenharmony_ci
7757db96d56Sopenharmony_ci   .. versionadded:: 3.3
7767db96d56Sopenharmony_ci
7777db96d56Sopenharmony_ci.. attribute:: DEBUG_BYTECODE_SUFFIXES
7787db96d56Sopenharmony_ci
7797db96d56Sopenharmony_ci   A list of strings representing the file suffixes for non-optimized bytecode
7807db96d56Sopenharmony_ci   modules.
7817db96d56Sopenharmony_ci
7827db96d56Sopenharmony_ci   .. versionadded:: 3.3
7837db96d56Sopenharmony_ci
7847db96d56Sopenharmony_ci   .. deprecated:: 3.5
7857db96d56Sopenharmony_ci      Use :attr:`BYTECODE_SUFFIXES` instead.
7867db96d56Sopenharmony_ci
7877db96d56Sopenharmony_ci.. attribute:: OPTIMIZED_BYTECODE_SUFFIXES
7887db96d56Sopenharmony_ci
7897db96d56Sopenharmony_ci   A list of strings representing the file suffixes for optimized bytecode
7907db96d56Sopenharmony_ci   modules.
7917db96d56Sopenharmony_ci
7927db96d56Sopenharmony_ci   .. versionadded:: 3.3
7937db96d56Sopenharmony_ci
7947db96d56Sopenharmony_ci   .. deprecated:: 3.5
7957db96d56Sopenharmony_ci      Use :attr:`BYTECODE_SUFFIXES` instead.
7967db96d56Sopenharmony_ci
7977db96d56Sopenharmony_ci.. attribute:: BYTECODE_SUFFIXES
7987db96d56Sopenharmony_ci
7997db96d56Sopenharmony_ci   A list of strings representing the recognized file suffixes for bytecode
8007db96d56Sopenharmony_ci   modules (including the leading dot).
8017db96d56Sopenharmony_ci
8027db96d56Sopenharmony_ci   .. versionadded:: 3.3
8037db96d56Sopenharmony_ci
8047db96d56Sopenharmony_ci   .. versionchanged:: 3.5
8057db96d56Sopenharmony_ci      The value is no longer dependent on ``__debug__``.
8067db96d56Sopenharmony_ci
8077db96d56Sopenharmony_ci.. attribute:: EXTENSION_SUFFIXES
8087db96d56Sopenharmony_ci
8097db96d56Sopenharmony_ci   A list of strings representing the recognized file suffixes for
8107db96d56Sopenharmony_ci   extension modules.
8117db96d56Sopenharmony_ci
8127db96d56Sopenharmony_ci   .. versionadded:: 3.3
8137db96d56Sopenharmony_ci
8147db96d56Sopenharmony_ci.. function:: all_suffixes()
8157db96d56Sopenharmony_ci
8167db96d56Sopenharmony_ci   Returns a combined list of strings representing all file suffixes for
8177db96d56Sopenharmony_ci   modules recognized by the standard import machinery. This is a
8187db96d56Sopenharmony_ci   helper for code which simply needs to know if a filesystem path
8197db96d56Sopenharmony_ci   potentially refers to a module without needing any details on the kind
8207db96d56Sopenharmony_ci   of module (for example, :func:`inspect.getmodulename`).
8217db96d56Sopenharmony_ci
8227db96d56Sopenharmony_ci   .. versionadded:: 3.3
8237db96d56Sopenharmony_ci
8247db96d56Sopenharmony_ci
8257db96d56Sopenharmony_ci.. class:: BuiltinImporter
8267db96d56Sopenharmony_ci
8277db96d56Sopenharmony_ci    An :term:`importer` for built-in modules. All known built-in modules are
8287db96d56Sopenharmony_ci    listed in :data:`sys.builtin_module_names`. This class implements the
8297db96d56Sopenharmony_ci    :class:`importlib.abc.MetaPathFinder` and
8307db96d56Sopenharmony_ci    :class:`importlib.abc.InspectLoader` ABCs.
8317db96d56Sopenharmony_ci
8327db96d56Sopenharmony_ci    Only class methods are defined by this class to alleviate the need for
8337db96d56Sopenharmony_ci    instantiation.
8347db96d56Sopenharmony_ci
8357db96d56Sopenharmony_ci    .. versionchanged:: 3.5
8367db96d56Sopenharmony_ci       As part of :pep:`489`, the builtin importer now implements
8377db96d56Sopenharmony_ci       :meth:`Loader.create_module` and :meth:`Loader.exec_module`
8387db96d56Sopenharmony_ci
8397db96d56Sopenharmony_ci
8407db96d56Sopenharmony_ci.. class:: FrozenImporter
8417db96d56Sopenharmony_ci
8427db96d56Sopenharmony_ci    An :term:`importer` for frozen modules. This class implements the
8437db96d56Sopenharmony_ci    :class:`importlib.abc.MetaPathFinder` and
8447db96d56Sopenharmony_ci    :class:`importlib.abc.InspectLoader` ABCs.
8457db96d56Sopenharmony_ci
8467db96d56Sopenharmony_ci    Only class methods are defined by this class to alleviate the need for
8477db96d56Sopenharmony_ci    instantiation.
8487db96d56Sopenharmony_ci
8497db96d56Sopenharmony_ci    .. versionchanged:: 3.4
8507db96d56Sopenharmony_ci       Gained :meth:`~Loader.create_module` and :meth:`~Loader.exec_module`
8517db96d56Sopenharmony_ci       methods.
8527db96d56Sopenharmony_ci
8537db96d56Sopenharmony_ci
8547db96d56Sopenharmony_ci.. class:: WindowsRegistryFinder
8557db96d56Sopenharmony_ci
8567db96d56Sopenharmony_ci   :term:`Finder <finder>` for modules declared in the Windows registry.  This class
8577db96d56Sopenharmony_ci   implements the :class:`importlib.abc.MetaPathFinder` ABC.
8587db96d56Sopenharmony_ci
8597db96d56Sopenharmony_ci   Only class methods are defined by this class to alleviate the need for
8607db96d56Sopenharmony_ci   instantiation.
8617db96d56Sopenharmony_ci
8627db96d56Sopenharmony_ci   .. versionadded:: 3.3
8637db96d56Sopenharmony_ci
8647db96d56Sopenharmony_ci   .. deprecated:: 3.6
8657db96d56Sopenharmony_ci      Use :mod:`site` configuration instead. Future versions of Python may
8667db96d56Sopenharmony_ci      not enable this finder by default.
8677db96d56Sopenharmony_ci
8687db96d56Sopenharmony_ci
8697db96d56Sopenharmony_ci.. class:: PathFinder
8707db96d56Sopenharmony_ci
8717db96d56Sopenharmony_ci   A :term:`Finder <finder>` for :data:`sys.path` and package ``__path__`` attributes.
8727db96d56Sopenharmony_ci   This class implements the :class:`importlib.abc.MetaPathFinder` ABC.
8737db96d56Sopenharmony_ci
8747db96d56Sopenharmony_ci   Only class methods are defined by this class to alleviate the need for
8757db96d56Sopenharmony_ci   instantiation.
8767db96d56Sopenharmony_ci
8777db96d56Sopenharmony_ci   .. classmethod:: find_spec(fullname, path=None, target=None)
8787db96d56Sopenharmony_ci
8797db96d56Sopenharmony_ci      Class method that attempts to find a :term:`spec <module spec>`
8807db96d56Sopenharmony_ci      for the module specified by *fullname* on :data:`sys.path` or, if
8817db96d56Sopenharmony_ci      defined, on *path*. For each path entry that is searched,
8827db96d56Sopenharmony_ci      :data:`sys.path_importer_cache` is checked. If a non-false object
8837db96d56Sopenharmony_ci      is found then it is used as the :term:`path entry finder` to look
8847db96d56Sopenharmony_ci      for the module being searched for. If no entry is found in
8857db96d56Sopenharmony_ci      :data:`sys.path_importer_cache`, then :data:`sys.path_hooks` is
8867db96d56Sopenharmony_ci      searched for a finder for the path entry and, if found, is stored
8877db96d56Sopenharmony_ci      in :data:`sys.path_importer_cache` along with being queried about
8887db96d56Sopenharmony_ci      the module. If no finder is ever found then ``None`` is both
8897db96d56Sopenharmony_ci      stored in the cache and returned.
8907db96d56Sopenharmony_ci
8917db96d56Sopenharmony_ci      .. versionadded:: 3.4
8927db96d56Sopenharmony_ci
8937db96d56Sopenharmony_ci      .. versionchanged:: 3.5
8947db96d56Sopenharmony_ci         If the current working directory -- represented by an empty string --
8957db96d56Sopenharmony_ci         is no longer valid then ``None`` is returned but no value is cached
8967db96d56Sopenharmony_ci         in :data:`sys.path_importer_cache`.
8977db96d56Sopenharmony_ci
8987db96d56Sopenharmony_ci   .. classmethod:: find_module(fullname, path=None)
8997db96d56Sopenharmony_ci
9007db96d56Sopenharmony_ci      A legacy wrapper around :meth:`find_spec`.
9017db96d56Sopenharmony_ci
9027db96d56Sopenharmony_ci      .. deprecated:: 3.4
9037db96d56Sopenharmony_ci         Use :meth:`find_spec` instead.
9047db96d56Sopenharmony_ci
9057db96d56Sopenharmony_ci   .. classmethod:: invalidate_caches()
9067db96d56Sopenharmony_ci
9077db96d56Sopenharmony_ci      Calls :meth:`importlib.abc.PathEntryFinder.invalidate_caches` on all
9087db96d56Sopenharmony_ci      finders stored in :data:`sys.path_importer_cache` that define the method.
9097db96d56Sopenharmony_ci      Otherwise entries in :data:`sys.path_importer_cache` set to ``None`` are
9107db96d56Sopenharmony_ci      deleted.
9117db96d56Sopenharmony_ci
9127db96d56Sopenharmony_ci      .. versionchanged:: 3.7
9137db96d56Sopenharmony_ci         Entries of ``None`` in :data:`sys.path_importer_cache` are deleted.
9147db96d56Sopenharmony_ci
9157db96d56Sopenharmony_ci   .. versionchanged:: 3.4
9167db96d56Sopenharmony_ci      Calls objects in :data:`sys.path_hooks` with the current working
9177db96d56Sopenharmony_ci      directory for ``''`` (i.e. the empty string).
9187db96d56Sopenharmony_ci
9197db96d56Sopenharmony_ci
9207db96d56Sopenharmony_ci.. class:: FileFinder(path, *loader_details)
9217db96d56Sopenharmony_ci
9227db96d56Sopenharmony_ci   A concrete implementation of :class:`importlib.abc.PathEntryFinder` which
9237db96d56Sopenharmony_ci   caches results from the file system.
9247db96d56Sopenharmony_ci
9257db96d56Sopenharmony_ci   The *path* argument is the directory for which the finder is in charge of
9267db96d56Sopenharmony_ci   searching.
9277db96d56Sopenharmony_ci
9287db96d56Sopenharmony_ci   The *loader_details* argument is a variable number of 2-item tuples each
9297db96d56Sopenharmony_ci   containing a loader and a sequence of file suffixes the loader recognizes.
9307db96d56Sopenharmony_ci   The loaders are expected to be callables which accept two arguments of
9317db96d56Sopenharmony_ci   the module's name and the path to the file found.
9327db96d56Sopenharmony_ci
9337db96d56Sopenharmony_ci   The finder will cache the directory contents as necessary, making stat calls
9347db96d56Sopenharmony_ci   for each module search to verify the cache is not outdated. Because cache
9357db96d56Sopenharmony_ci   staleness relies upon the granularity of the operating system's state
9367db96d56Sopenharmony_ci   information of the file system, there is a potential race condition of
9377db96d56Sopenharmony_ci   searching for a module, creating a new file, and then searching for the
9387db96d56Sopenharmony_ci   module the new file represents. If the operations happen fast enough to fit
9397db96d56Sopenharmony_ci   within the granularity of stat calls, then the module search will fail. To
9407db96d56Sopenharmony_ci   prevent this from happening, when you create a module dynamically, make sure
9417db96d56Sopenharmony_ci   to call :func:`importlib.invalidate_caches`.
9427db96d56Sopenharmony_ci
9437db96d56Sopenharmony_ci   .. versionadded:: 3.3
9447db96d56Sopenharmony_ci
9457db96d56Sopenharmony_ci   .. attribute:: path
9467db96d56Sopenharmony_ci
9477db96d56Sopenharmony_ci      The path the finder will search in.
9487db96d56Sopenharmony_ci
9497db96d56Sopenharmony_ci   .. method:: find_spec(fullname, target=None)
9507db96d56Sopenharmony_ci
9517db96d56Sopenharmony_ci      Attempt to find the spec to handle *fullname* within :attr:`path`.
9527db96d56Sopenharmony_ci
9537db96d56Sopenharmony_ci      .. versionadded:: 3.4
9547db96d56Sopenharmony_ci
9557db96d56Sopenharmony_ci   .. method:: find_loader(fullname)
9567db96d56Sopenharmony_ci
9577db96d56Sopenharmony_ci      Attempt to find the loader to handle *fullname* within :attr:`path`.
9587db96d56Sopenharmony_ci
9597db96d56Sopenharmony_ci      .. deprecated:: 3.10
9607db96d56Sopenharmony_ci         Use :meth:`find_spec` instead.
9617db96d56Sopenharmony_ci
9627db96d56Sopenharmony_ci   .. method:: invalidate_caches()
9637db96d56Sopenharmony_ci
9647db96d56Sopenharmony_ci      Clear out the internal cache.
9657db96d56Sopenharmony_ci
9667db96d56Sopenharmony_ci   .. classmethod:: path_hook(*loader_details)
9677db96d56Sopenharmony_ci
9687db96d56Sopenharmony_ci      A class method which returns a closure for use on :attr:`sys.path_hooks`.
9697db96d56Sopenharmony_ci      An instance of :class:`FileFinder` is returned by the closure using the
9707db96d56Sopenharmony_ci      path argument given to the closure directly and *loader_details*
9717db96d56Sopenharmony_ci      indirectly.
9727db96d56Sopenharmony_ci
9737db96d56Sopenharmony_ci      If the argument to the closure is not an existing directory,
9747db96d56Sopenharmony_ci      :exc:`ImportError` is raised.
9757db96d56Sopenharmony_ci
9767db96d56Sopenharmony_ci
9777db96d56Sopenharmony_ci.. class:: SourceFileLoader(fullname, path)
9787db96d56Sopenharmony_ci
9797db96d56Sopenharmony_ci   A concrete implementation of :class:`importlib.abc.SourceLoader` by
9807db96d56Sopenharmony_ci   subclassing :class:`importlib.abc.FileLoader` and providing some concrete
9817db96d56Sopenharmony_ci   implementations of other methods.
9827db96d56Sopenharmony_ci
9837db96d56Sopenharmony_ci   .. versionadded:: 3.3
9847db96d56Sopenharmony_ci
9857db96d56Sopenharmony_ci   .. attribute:: name
9867db96d56Sopenharmony_ci
9877db96d56Sopenharmony_ci      The name of the module that this loader will handle.
9887db96d56Sopenharmony_ci
9897db96d56Sopenharmony_ci   .. attribute:: path
9907db96d56Sopenharmony_ci
9917db96d56Sopenharmony_ci      The path to the source file.
9927db96d56Sopenharmony_ci
9937db96d56Sopenharmony_ci   .. method:: is_package(fullname)
9947db96d56Sopenharmony_ci
9957db96d56Sopenharmony_ci      Return ``True`` if :attr:`path` appears to be for a package.
9967db96d56Sopenharmony_ci
9977db96d56Sopenharmony_ci   .. method:: path_stats(path)
9987db96d56Sopenharmony_ci
9997db96d56Sopenharmony_ci      Concrete implementation of :meth:`importlib.abc.SourceLoader.path_stats`.
10007db96d56Sopenharmony_ci
10017db96d56Sopenharmony_ci   .. method:: set_data(path, data)
10027db96d56Sopenharmony_ci
10037db96d56Sopenharmony_ci      Concrete implementation of :meth:`importlib.abc.SourceLoader.set_data`.
10047db96d56Sopenharmony_ci
10057db96d56Sopenharmony_ci   .. method:: load_module(name=None)
10067db96d56Sopenharmony_ci
10077db96d56Sopenharmony_ci      Concrete implementation of :meth:`importlib.abc.Loader.load_module` where
10087db96d56Sopenharmony_ci      specifying the name of the module to load is optional.
10097db96d56Sopenharmony_ci
10107db96d56Sopenharmony_ci      .. deprecated:: 3.6
10117db96d56Sopenharmony_ci
10127db96d56Sopenharmony_ci         Use :meth:`importlib.abc.Loader.exec_module` instead.
10137db96d56Sopenharmony_ci
10147db96d56Sopenharmony_ci
10157db96d56Sopenharmony_ci.. class:: SourcelessFileLoader(fullname, path)
10167db96d56Sopenharmony_ci
10177db96d56Sopenharmony_ci   A concrete implementation of :class:`importlib.abc.FileLoader` which can
10187db96d56Sopenharmony_ci   import bytecode files (i.e. no source code files exist).
10197db96d56Sopenharmony_ci
10207db96d56Sopenharmony_ci   Please note that direct use of bytecode files (and thus not source code
10217db96d56Sopenharmony_ci   files) inhibits your modules from being usable by all Python
10227db96d56Sopenharmony_ci   implementations or new versions of Python which change the bytecode
10237db96d56Sopenharmony_ci   format.
10247db96d56Sopenharmony_ci
10257db96d56Sopenharmony_ci   .. versionadded:: 3.3
10267db96d56Sopenharmony_ci
10277db96d56Sopenharmony_ci   .. attribute:: name
10287db96d56Sopenharmony_ci
10297db96d56Sopenharmony_ci      The name of the module the loader will handle.
10307db96d56Sopenharmony_ci
10317db96d56Sopenharmony_ci   .. attribute:: path
10327db96d56Sopenharmony_ci
10337db96d56Sopenharmony_ci      The path to the bytecode file.
10347db96d56Sopenharmony_ci
10357db96d56Sopenharmony_ci   .. method:: is_package(fullname)
10367db96d56Sopenharmony_ci
10377db96d56Sopenharmony_ci      Determines if the module is a package based on :attr:`path`.
10387db96d56Sopenharmony_ci
10397db96d56Sopenharmony_ci   .. method:: get_code(fullname)
10407db96d56Sopenharmony_ci
10417db96d56Sopenharmony_ci      Returns the code object for :attr:`name` created from :attr:`path`.
10427db96d56Sopenharmony_ci
10437db96d56Sopenharmony_ci   .. method:: get_source(fullname)
10447db96d56Sopenharmony_ci
10457db96d56Sopenharmony_ci      Returns ``None`` as bytecode files have no source when this loader is
10467db96d56Sopenharmony_ci      used.
10477db96d56Sopenharmony_ci
10487db96d56Sopenharmony_ci   .. method:: load_module(name=None)
10497db96d56Sopenharmony_ci
10507db96d56Sopenharmony_ci   Concrete implementation of :meth:`importlib.abc.Loader.load_module` where
10517db96d56Sopenharmony_ci   specifying the name of the module to load is optional.
10527db96d56Sopenharmony_ci
10537db96d56Sopenharmony_ci   .. deprecated:: 3.6
10547db96d56Sopenharmony_ci
10557db96d56Sopenharmony_ci      Use :meth:`importlib.abc.Loader.exec_module` instead.
10567db96d56Sopenharmony_ci
10577db96d56Sopenharmony_ci
10587db96d56Sopenharmony_ci.. class:: ExtensionFileLoader(fullname, path)
10597db96d56Sopenharmony_ci
10607db96d56Sopenharmony_ci   A concrete implementation of :class:`importlib.abc.ExecutionLoader` for
10617db96d56Sopenharmony_ci   extension modules.
10627db96d56Sopenharmony_ci
10637db96d56Sopenharmony_ci   The *fullname* argument specifies the name of the module the loader is to
10647db96d56Sopenharmony_ci   support. The *path* argument is the path to the extension module's file.
10657db96d56Sopenharmony_ci
10667db96d56Sopenharmony_ci   .. versionadded:: 3.3
10677db96d56Sopenharmony_ci
10687db96d56Sopenharmony_ci   .. attribute:: name
10697db96d56Sopenharmony_ci
10707db96d56Sopenharmony_ci      Name of the module the loader supports.
10717db96d56Sopenharmony_ci
10727db96d56Sopenharmony_ci   .. attribute:: path
10737db96d56Sopenharmony_ci
10747db96d56Sopenharmony_ci      Path to the extension module.
10757db96d56Sopenharmony_ci
10767db96d56Sopenharmony_ci   .. method:: create_module(spec)
10777db96d56Sopenharmony_ci
10787db96d56Sopenharmony_ci      Creates the module object from the given specification in accordance
10797db96d56Sopenharmony_ci      with :pep:`489`.
10807db96d56Sopenharmony_ci
10817db96d56Sopenharmony_ci      .. versionadded:: 3.5
10827db96d56Sopenharmony_ci
10837db96d56Sopenharmony_ci   .. method:: exec_module(module)
10847db96d56Sopenharmony_ci
10857db96d56Sopenharmony_ci      Initializes the given module object in accordance with :pep:`489`.
10867db96d56Sopenharmony_ci
10877db96d56Sopenharmony_ci      .. versionadded:: 3.5
10887db96d56Sopenharmony_ci
10897db96d56Sopenharmony_ci   .. method:: is_package(fullname)
10907db96d56Sopenharmony_ci
10917db96d56Sopenharmony_ci      Returns ``True`` if the file path points to a package's ``__init__``
10927db96d56Sopenharmony_ci      module based on :attr:`EXTENSION_SUFFIXES`.
10937db96d56Sopenharmony_ci
10947db96d56Sopenharmony_ci   .. method:: get_code(fullname)
10957db96d56Sopenharmony_ci
10967db96d56Sopenharmony_ci      Returns ``None`` as extension modules lack a code object.
10977db96d56Sopenharmony_ci
10987db96d56Sopenharmony_ci   .. method:: get_source(fullname)
10997db96d56Sopenharmony_ci
11007db96d56Sopenharmony_ci      Returns ``None`` as extension modules do not have source code.
11017db96d56Sopenharmony_ci
11027db96d56Sopenharmony_ci   .. method:: get_filename(fullname)
11037db96d56Sopenharmony_ci
11047db96d56Sopenharmony_ci      Returns :attr:`path`.
11057db96d56Sopenharmony_ci
11067db96d56Sopenharmony_ci      .. versionadded:: 3.4
11077db96d56Sopenharmony_ci
11087db96d56Sopenharmony_ci
11097db96d56Sopenharmony_ci.. class:: NamespaceLoader(name, path, path_finder):
11107db96d56Sopenharmony_ci
11117db96d56Sopenharmony_ci   A concrete implementation of :class:`importlib.abc.InspectLoader` for
11127db96d56Sopenharmony_ci   namespace packages.  This is an alias for a private class and is only made
11137db96d56Sopenharmony_ci   public for introspecting the ``__loader__`` attribute on namespace
11147db96d56Sopenharmony_ci   packages::
11157db96d56Sopenharmony_ci
11167db96d56Sopenharmony_ci       >>> from importlib.machinery import NamespaceLoader
11177db96d56Sopenharmony_ci       >>> import my_namespace
11187db96d56Sopenharmony_ci       >>> isinstance(my_namespace.__loader__, NamespaceLoader)
11197db96d56Sopenharmony_ci       True
11207db96d56Sopenharmony_ci       >>> import importlib.abc
11217db96d56Sopenharmony_ci       >>> isinstance(my_namespace.__loader__, importlib.abc.Loader)
11227db96d56Sopenharmony_ci       True
11237db96d56Sopenharmony_ci
11247db96d56Sopenharmony_ci   .. versionadded:: 3.11
11257db96d56Sopenharmony_ci
11267db96d56Sopenharmony_ci
11277db96d56Sopenharmony_ci.. class:: ModuleSpec(name, loader, *, origin=None, loader_state=None, is_package=None)
11287db96d56Sopenharmony_ci
11297db96d56Sopenharmony_ci   A specification for a module's import-system-related state.  This is
11307db96d56Sopenharmony_ci   typically exposed as the module's :attr:`__spec__` attribute.  In the
11317db96d56Sopenharmony_ci   descriptions below, the names in parentheses give the corresponding
11327db96d56Sopenharmony_ci   attribute available directly on the module object,
11337db96d56Sopenharmony_ci   e.g. ``module.__spec__.origin == module.__file__``.  Note, however, that
11347db96d56Sopenharmony_ci   while the *values* are usually equivalent, they can differ since there is
11357db96d56Sopenharmony_ci   no synchronization between the two objects.  For example, it is possible to update
11367db96d56Sopenharmony_ci   the module's :attr:`__file__` at runtime and this will not be automatically
11377db96d56Sopenharmony_ci   reflected in the module's :attr:`__spec__.origin`, and vice versa.
11387db96d56Sopenharmony_ci
11397db96d56Sopenharmony_ci   .. versionadded:: 3.4
11407db96d56Sopenharmony_ci
11417db96d56Sopenharmony_ci   .. attribute:: name
11427db96d56Sopenharmony_ci
11437db96d56Sopenharmony_ci   (:attr:`__name__`)
11447db96d56Sopenharmony_ci
11457db96d56Sopenharmony_ci   The module's fully qualified name.
11467db96d56Sopenharmony_ci   The :term:`finder` should always set this attribute to a non-empty string.
11477db96d56Sopenharmony_ci
11487db96d56Sopenharmony_ci   .. attribute:: loader
11497db96d56Sopenharmony_ci
11507db96d56Sopenharmony_ci   (:attr:`__loader__`)
11517db96d56Sopenharmony_ci
11527db96d56Sopenharmony_ci   The :term:`loader` used to load the module.
11537db96d56Sopenharmony_ci   The :term:`finder` should always set this attribute.
11547db96d56Sopenharmony_ci
11557db96d56Sopenharmony_ci   .. attribute:: origin
11567db96d56Sopenharmony_ci
11577db96d56Sopenharmony_ci   (:attr:`__file__`)
11587db96d56Sopenharmony_ci
11597db96d56Sopenharmony_ci   The location the :term:`loader` should use to load the module.
11607db96d56Sopenharmony_ci   For example, for modules loaded from a .py file this is the filename.
11617db96d56Sopenharmony_ci   The :term:`finder` should always set this attribute to a meaningful value
11627db96d56Sopenharmony_ci   for the :term:`loader` to use.  In the uncommon case that there is not one
11637db96d56Sopenharmony_ci   (like for namespace packages), it should be set to ``None``.
11647db96d56Sopenharmony_ci
11657db96d56Sopenharmony_ci   .. attribute:: submodule_search_locations
11667db96d56Sopenharmony_ci
11677db96d56Sopenharmony_ci   (:attr:`__path__`)
11687db96d56Sopenharmony_ci
11697db96d56Sopenharmony_ci   The list of locations where the package's submodules will be found.
11707db96d56Sopenharmony_ci   Most of the time this is a single directory.
11717db96d56Sopenharmony_ci   The :term:`finder` should set this attribute to a list, even an empty one, to indicate
11727db96d56Sopenharmony_ci   to the import system that the module is a package.  It should be set to ``None`` for
11737db96d56Sopenharmony_ci   non-package modules.  It is set automatically later to a special object for
11747db96d56Sopenharmony_ci   namespace packages.
11757db96d56Sopenharmony_ci
11767db96d56Sopenharmony_ci   .. attribute:: loader_state
11777db96d56Sopenharmony_ci
11787db96d56Sopenharmony_ci   The :term:`finder` may set this attribute to an object containing additional,
11797db96d56Sopenharmony_ci   module-specific data to use when loading the module.  Otherwise it should be
11807db96d56Sopenharmony_ci   set to ``None``.
11817db96d56Sopenharmony_ci
11827db96d56Sopenharmony_ci   .. attribute:: cached
11837db96d56Sopenharmony_ci
11847db96d56Sopenharmony_ci   (:attr:`__cached__`)
11857db96d56Sopenharmony_ci
11867db96d56Sopenharmony_ci   The filename of a compiled version of the module's code.
11877db96d56Sopenharmony_ci   The :term:`finder` should always set this attribute but it may be ``None``
11887db96d56Sopenharmony_ci   for modules that do not need compiled code stored.
11897db96d56Sopenharmony_ci
11907db96d56Sopenharmony_ci   .. attribute:: parent
11917db96d56Sopenharmony_ci
11927db96d56Sopenharmony_ci   (:attr:`__package__`)
11937db96d56Sopenharmony_ci
11947db96d56Sopenharmony_ci   (Read-only) The fully qualified name of the package the module is in (or the
11957db96d56Sopenharmony_ci   empty string for a top-level module).
11967db96d56Sopenharmony_ci   If the module is a package then this is the same as :attr:`name`.
11977db96d56Sopenharmony_ci
11987db96d56Sopenharmony_ci   .. attribute:: has_location
11997db96d56Sopenharmony_ci
12007db96d56Sopenharmony_ci   ``True`` if the spec's :attr:`origin` refers to a loadable location,
12017db96d56Sopenharmony_ci    ``False`` otherwise.  This value impacts how :attr:`origin` is interpreted
12027db96d56Sopenharmony_ci    and how the module's :attr:`__file__` is populated.
12037db96d56Sopenharmony_ci
12047db96d56Sopenharmony_ci
12057db96d56Sopenharmony_ci:mod:`importlib.util` -- Utility code for importers
12067db96d56Sopenharmony_ci---------------------------------------------------
12077db96d56Sopenharmony_ci
12087db96d56Sopenharmony_ci.. module:: importlib.util
12097db96d56Sopenharmony_ci    :synopsis: Utility code for importers
12107db96d56Sopenharmony_ci
12117db96d56Sopenharmony_ci
12127db96d56Sopenharmony_ci**Source code:** :source:`Lib/importlib/util.py`
12137db96d56Sopenharmony_ci
12147db96d56Sopenharmony_ci--------------
12157db96d56Sopenharmony_ci
12167db96d56Sopenharmony_ciThis module contains the various objects that help in the construction of
12177db96d56Sopenharmony_cian :term:`importer`.
12187db96d56Sopenharmony_ci
12197db96d56Sopenharmony_ci.. attribute:: MAGIC_NUMBER
12207db96d56Sopenharmony_ci
12217db96d56Sopenharmony_ci   The bytes which represent the bytecode version number. If you need help with
12227db96d56Sopenharmony_ci   loading/writing bytecode then consider :class:`importlib.abc.SourceLoader`.
12237db96d56Sopenharmony_ci
12247db96d56Sopenharmony_ci   .. versionadded:: 3.4
12257db96d56Sopenharmony_ci
12267db96d56Sopenharmony_ci.. function:: cache_from_source(path, debug_override=None, *, optimization=None)
12277db96d56Sopenharmony_ci
12287db96d56Sopenharmony_ci   Return the :pep:`3147`/:pep:`488` path to the byte-compiled file associated
12297db96d56Sopenharmony_ci   with the source *path*.  For example, if *path* is ``/foo/bar/baz.py`` the return
12307db96d56Sopenharmony_ci   value would be ``/foo/bar/__pycache__/baz.cpython-32.pyc`` for Python 3.2.
12317db96d56Sopenharmony_ci   The ``cpython-32`` string comes from the current magic tag (see
12327db96d56Sopenharmony_ci   :func:`get_tag`; if :attr:`sys.implementation.cache_tag` is not defined then
12337db96d56Sopenharmony_ci   :exc:`NotImplementedError` will be raised).
12347db96d56Sopenharmony_ci
12357db96d56Sopenharmony_ci   The *optimization* parameter is used to specify the optimization level of the
12367db96d56Sopenharmony_ci   bytecode file. An empty string represents no optimization, so
12377db96d56Sopenharmony_ci   ``/foo/bar/baz.py`` with an *optimization* of ``''`` will result in a
12387db96d56Sopenharmony_ci   bytecode path of ``/foo/bar/__pycache__/baz.cpython-32.pyc``. ``None`` causes
12397db96d56Sopenharmony_ci   the interpreter's optimization level to be used. Any other value's string
12407db96d56Sopenharmony_ci   representation is used, so ``/foo/bar/baz.py`` with an *optimization* of
12417db96d56Sopenharmony_ci   ``2`` will lead to the bytecode path of
12427db96d56Sopenharmony_ci   ``/foo/bar/__pycache__/baz.cpython-32.opt-2.pyc``. The string representation
12437db96d56Sopenharmony_ci   of *optimization* can only be alphanumeric, else :exc:`ValueError` is raised.
12447db96d56Sopenharmony_ci
12457db96d56Sopenharmony_ci   The *debug_override* parameter is deprecated and can be used to override
12467db96d56Sopenharmony_ci   the system's value for ``__debug__``. A ``True`` value is the equivalent of
12477db96d56Sopenharmony_ci   setting *optimization* to the empty string. A ``False`` value is the same as
12487db96d56Sopenharmony_ci   setting *optimization* to ``1``. If both *debug_override* an *optimization*
12497db96d56Sopenharmony_ci   are not ``None`` then :exc:`TypeError` is raised.
12507db96d56Sopenharmony_ci
12517db96d56Sopenharmony_ci   .. versionadded:: 3.4
12527db96d56Sopenharmony_ci
12537db96d56Sopenharmony_ci   .. versionchanged:: 3.5
12547db96d56Sopenharmony_ci      The *optimization* parameter was added and the *debug_override* parameter
12557db96d56Sopenharmony_ci      was deprecated.
12567db96d56Sopenharmony_ci
12577db96d56Sopenharmony_ci   .. versionchanged:: 3.6
12587db96d56Sopenharmony_ci      Accepts a :term:`path-like object`.
12597db96d56Sopenharmony_ci
12607db96d56Sopenharmony_ci
12617db96d56Sopenharmony_ci.. function:: source_from_cache(path)
12627db96d56Sopenharmony_ci
12637db96d56Sopenharmony_ci   Given the *path* to a :pep:`3147` file name, return the associated source code
12647db96d56Sopenharmony_ci   file path.  For example, if *path* is
12657db96d56Sopenharmony_ci   ``/foo/bar/__pycache__/baz.cpython-32.pyc`` the returned path would be
12667db96d56Sopenharmony_ci   ``/foo/bar/baz.py``.  *path* need not exist, however if it does not conform
12677db96d56Sopenharmony_ci   to :pep:`3147` or :pep:`488` format, a :exc:`ValueError` is raised. If
12687db96d56Sopenharmony_ci   :attr:`sys.implementation.cache_tag` is not defined,
12697db96d56Sopenharmony_ci   :exc:`NotImplementedError` is raised.
12707db96d56Sopenharmony_ci
12717db96d56Sopenharmony_ci   .. versionadded:: 3.4
12727db96d56Sopenharmony_ci
12737db96d56Sopenharmony_ci   .. versionchanged:: 3.6
12747db96d56Sopenharmony_ci      Accepts a :term:`path-like object`.
12757db96d56Sopenharmony_ci
12767db96d56Sopenharmony_ci.. function:: decode_source(source_bytes)
12777db96d56Sopenharmony_ci
12787db96d56Sopenharmony_ci   Decode the given bytes representing source code and return it as a string
12797db96d56Sopenharmony_ci   with universal newlines (as required by
12807db96d56Sopenharmony_ci   :meth:`importlib.abc.InspectLoader.get_source`).
12817db96d56Sopenharmony_ci
12827db96d56Sopenharmony_ci   .. versionadded:: 3.4
12837db96d56Sopenharmony_ci
12847db96d56Sopenharmony_ci.. function:: resolve_name(name, package)
12857db96d56Sopenharmony_ci
12867db96d56Sopenharmony_ci   Resolve a relative module name to an absolute one.
12877db96d56Sopenharmony_ci
12887db96d56Sopenharmony_ci   If  **name** has no leading dots, then **name** is simply returned. This
12897db96d56Sopenharmony_ci   allows for usage such as
12907db96d56Sopenharmony_ci   ``importlib.util.resolve_name('sys', __spec__.parent)`` without doing a
12917db96d56Sopenharmony_ci   check to see if the **package** argument is needed.
12927db96d56Sopenharmony_ci
12937db96d56Sopenharmony_ci   :exc:`ImportError` is raised if **name** is a relative module name but
12947db96d56Sopenharmony_ci   **package** is a false value (e.g. ``None`` or the empty string).
12957db96d56Sopenharmony_ci   :exc:`ImportError` is also raised if a relative name would escape its
12967db96d56Sopenharmony_ci   containing package (e.g. requesting ``..bacon`` from within the ``spam``
12977db96d56Sopenharmony_ci   package).
12987db96d56Sopenharmony_ci
12997db96d56Sopenharmony_ci   .. versionadded:: 3.3
13007db96d56Sopenharmony_ci
13017db96d56Sopenharmony_ci   .. versionchanged:: 3.9
13027db96d56Sopenharmony_ci      To improve consistency with import statements, raise
13037db96d56Sopenharmony_ci      :exc:`ImportError` instead of :exc:`ValueError` for invalid relative
13047db96d56Sopenharmony_ci      import attempts.
13057db96d56Sopenharmony_ci
13067db96d56Sopenharmony_ci.. function:: find_spec(name, package=None)
13077db96d56Sopenharmony_ci
13087db96d56Sopenharmony_ci   Find the :term:`spec <module spec>` for a module, optionally relative to
13097db96d56Sopenharmony_ci   the specified **package** name. If the module is in :attr:`sys.modules`,
13107db96d56Sopenharmony_ci   then ``sys.modules[name].__spec__`` is returned (unless the spec would be
13117db96d56Sopenharmony_ci   ``None`` or is not set, in which case :exc:`ValueError` is raised).
13127db96d56Sopenharmony_ci   Otherwise a search using :attr:`sys.meta_path` is done. ``None`` is
13137db96d56Sopenharmony_ci   returned if no spec is found.
13147db96d56Sopenharmony_ci
13157db96d56Sopenharmony_ci   If **name** is for a submodule (contains a dot), the parent module is
13167db96d56Sopenharmony_ci   automatically imported.
13177db96d56Sopenharmony_ci
13187db96d56Sopenharmony_ci   **name** and **package** work the same as for :func:`import_module`.
13197db96d56Sopenharmony_ci
13207db96d56Sopenharmony_ci   .. versionadded:: 3.4
13217db96d56Sopenharmony_ci
13227db96d56Sopenharmony_ci   .. versionchanged:: 3.7
13237db96d56Sopenharmony_ci      Raises :exc:`ModuleNotFoundError` instead of :exc:`AttributeError` if
13247db96d56Sopenharmony_ci      **package** is in fact not a package (i.e. lacks a :attr:`__path__`
13257db96d56Sopenharmony_ci      attribute).
13267db96d56Sopenharmony_ci
13277db96d56Sopenharmony_ci.. function:: module_from_spec(spec)
13287db96d56Sopenharmony_ci
13297db96d56Sopenharmony_ci   Create a new module based on **spec** and
13307db96d56Sopenharmony_ci   :meth:`spec.loader.create_module <importlib.abc.Loader.create_module>`.
13317db96d56Sopenharmony_ci
13327db96d56Sopenharmony_ci   If :meth:`spec.loader.create_module <importlib.abc.Loader.create_module>`
13337db96d56Sopenharmony_ci   does not return ``None``, then any pre-existing attributes will not be reset.
13347db96d56Sopenharmony_ci   Also, no :exc:`AttributeError` will be raised if triggered while accessing
13357db96d56Sopenharmony_ci   **spec** or setting an attribute on the module.
13367db96d56Sopenharmony_ci
13377db96d56Sopenharmony_ci   This function is preferred over using :class:`types.ModuleType` to create a
13387db96d56Sopenharmony_ci   new module as **spec** is used to set as many import-controlled attributes on
13397db96d56Sopenharmony_ci   the module as possible.
13407db96d56Sopenharmony_ci
13417db96d56Sopenharmony_ci   .. versionadded:: 3.5
13427db96d56Sopenharmony_ci
13437db96d56Sopenharmony_ci.. decorator:: module_for_loader
13447db96d56Sopenharmony_ci
13457db96d56Sopenharmony_ci    A :term:`decorator` for :meth:`importlib.abc.Loader.load_module`
13467db96d56Sopenharmony_ci    to handle selecting the proper
13477db96d56Sopenharmony_ci    module object to load with. The decorated method is expected to have a call
13487db96d56Sopenharmony_ci    signature taking two positional arguments
13497db96d56Sopenharmony_ci    (e.g. ``load_module(self, module)``) for which the second argument
13507db96d56Sopenharmony_ci    will be the module **object** to be used by the loader.
13517db96d56Sopenharmony_ci    Note that the decorator will not work on static methods because of the
13527db96d56Sopenharmony_ci    assumption of two arguments.
13537db96d56Sopenharmony_ci
13547db96d56Sopenharmony_ci    The decorated method will take in the **name** of the module to be loaded
13557db96d56Sopenharmony_ci    as expected for a :term:`loader`. If the module is not found in
13567db96d56Sopenharmony_ci    :data:`sys.modules` then a new one is constructed. Regardless of where the
13577db96d56Sopenharmony_ci    module came from, :attr:`__loader__` set to **self** and :attr:`__package__`
13587db96d56Sopenharmony_ci    is set based on what :meth:`importlib.abc.InspectLoader.is_package` returns
13597db96d56Sopenharmony_ci    (if available). These attributes are set unconditionally to support
13607db96d56Sopenharmony_ci    reloading.
13617db96d56Sopenharmony_ci
13627db96d56Sopenharmony_ci    If an exception is raised by the decorated method and a module was added to
13637db96d56Sopenharmony_ci    :data:`sys.modules`, then the module will be removed to prevent a partially
13647db96d56Sopenharmony_ci    initialized module from being in left in :data:`sys.modules`. If the module
13657db96d56Sopenharmony_ci    was already in :data:`sys.modules` then it is left alone.
13667db96d56Sopenharmony_ci
13677db96d56Sopenharmony_ci    .. versionchanged:: 3.3
13687db96d56Sopenharmony_ci       :attr:`__loader__` and :attr:`__package__` are automatically set
13697db96d56Sopenharmony_ci       (when possible).
13707db96d56Sopenharmony_ci
13717db96d56Sopenharmony_ci    .. versionchanged:: 3.4
13727db96d56Sopenharmony_ci       Set :attr:`__name__`, :attr:`__loader__` :attr:`__package__`
13737db96d56Sopenharmony_ci       unconditionally to support reloading.
13747db96d56Sopenharmony_ci
13757db96d56Sopenharmony_ci    .. deprecated:: 3.4
13767db96d56Sopenharmony_ci       The import machinery now directly performs all the functionality
13777db96d56Sopenharmony_ci       provided by this function.
13787db96d56Sopenharmony_ci
13797db96d56Sopenharmony_ci.. decorator:: set_loader
13807db96d56Sopenharmony_ci
13817db96d56Sopenharmony_ci   A :term:`decorator` for :meth:`importlib.abc.Loader.load_module`
13827db96d56Sopenharmony_ci   to set the :attr:`__loader__`
13837db96d56Sopenharmony_ci   attribute on the returned module. If the attribute is already set the
13847db96d56Sopenharmony_ci   decorator does nothing. It is assumed that the first positional argument to
13857db96d56Sopenharmony_ci   the wrapped method (i.e. ``self``) is what :attr:`__loader__` should be set
13867db96d56Sopenharmony_ci   to.
13877db96d56Sopenharmony_ci
13887db96d56Sopenharmony_ci   .. versionchanged:: 3.4
13897db96d56Sopenharmony_ci      Set ``__loader__`` if set to ``None``, as if the attribute does not
13907db96d56Sopenharmony_ci      exist.
13917db96d56Sopenharmony_ci
13927db96d56Sopenharmony_ci   .. deprecated:: 3.4
13937db96d56Sopenharmony_ci      The import machinery takes care of this automatically.
13947db96d56Sopenharmony_ci
13957db96d56Sopenharmony_ci.. decorator:: set_package
13967db96d56Sopenharmony_ci
13977db96d56Sopenharmony_ci   A :term:`decorator` for :meth:`importlib.abc.Loader.load_module` to set the
13987db96d56Sopenharmony_ci   :attr:`__package__` attribute on the returned module. If :attr:`__package__`
13997db96d56Sopenharmony_ci   is set and has a value other than ``None`` it will not be changed.
14007db96d56Sopenharmony_ci
14017db96d56Sopenharmony_ci   .. deprecated:: 3.4
14027db96d56Sopenharmony_ci      The import machinery takes care of this automatically.
14037db96d56Sopenharmony_ci
14047db96d56Sopenharmony_ci.. function:: spec_from_loader(name, loader, *, origin=None, is_package=None)
14057db96d56Sopenharmony_ci
14067db96d56Sopenharmony_ci   A factory function for creating a :class:`~importlib.machinery.ModuleSpec`
14077db96d56Sopenharmony_ci   instance based on a loader.  The parameters have the same meaning as they do
14087db96d56Sopenharmony_ci   for ModuleSpec.  The function uses available :term:`loader` APIs, such as
14097db96d56Sopenharmony_ci   :meth:`InspectLoader.is_package`, to fill in any missing
14107db96d56Sopenharmony_ci   information on the spec.
14117db96d56Sopenharmony_ci
14127db96d56Sopenharmony_ci   .. versionadded:: 3.4
14137db96d56Sopenharmony_ci
14147db96d56Sopenharmony_ci.. function:: spec_from_file_location(name, location, *, loader=None, submodule_search_locations=None)
14157db96d56Sopenharmony_ci
14167db96d56Sopenharmony_ci   A factory function for creating a :class:`~importlib.machinery.ModuleSpec`
14177db96d56Sopenharmony_ci   instance based on the path to a file.  Missing information will be filled in
14187db96d56Sopenharmony_ci   on the spec by making use of loader APIs and by the implication that the
14197db96d56Sopenharmony_ci   module will be file-based.
14207db96d56Sopenharmony_ci
14217db96d56Sopenharmony_ci   .. versionadded:: 3.4
14227db96d56Sopenharmony_ci
14237db96d56Sopenharmony_ci   .. versionchanged:: 3.6
14247db96d56Sopenharmony_ci      Accepts a :term:`path-like object`.
14257db96d56Sopenharmony_ci
14267db96d56Sopenharmony_ci.. function:: source_hash(source_bytes)
14277db96d56Sopenharmony_ci
14287db96d56Sopenharmony_ci   Return the hash of *source_bytes* as bytes. A hash-based ``.pyc`` file embeds
14297db96d56Sopenharmony_ci   the :func:`source_hash` of the corresponding source file's contents in its
14307db96d56Sopenharmony_ci   header.
14317db96d56Sopenharmony_ci
14327db96d56Sopenharmony_ci   .. versionadded:: 3.7
14337db96d56Sopenharmony_ci
14347db96d56Sopenharmony_ci.. class:: LazyLoader(loader)
14357db96d56Sopenharmony_ci
14367db96d56Sopenharmony_ci   A class which postpones the execution of the loader of a module until the
14377db96d56Sopenharmony_ci   module has an attribute accessed.
14387db96d56Sopenharmony_ci
14397db96d56Sopenharmony_ci   This class **only** works with loaders that define
14407db96d56Sopenharmony_ci   :meth:`~importlib.abc.Loader.exec_module` as control over what module type
14417db96d56Sopenharmony_ci   is used for the module is required. For those same reasons, the loader's
14427db96d56Sopenharmony_ci   :meth:`~importlib.abc.Loader.create_module` method must return ``None`` or a
14437db96d56Sopenharmony_ci   type for which its ``__class__`` attribute can be mutated along with not
14447db96d56Sopenharmony_ci   using :term:`slots <__slots__>`. Finally, modules which substitute the object
14457db96d56Sopenharmony_ci   placed into :attr:`sys.modules` will not work as there is no way to properly
14467db96d56Sopenharmony_ci   replace the module references throughout the interpreter safely;
14477db96d56Sopenharmony_ci   :exc:`ValueError` is raised if such a substitution is detected.
14487db96d56Sopenharmony_ci
14497db96d56Sopenharmony_ci   .. note::
14507db96d56Sopenharmony_ci      For projects where startup time is critical, this class allows for
14517db96d56Sopenharmony_ci      potentially minimizing the cost of loading a module if it is never used.
14527db96d56Sopenharmony_ci      For projects where startup time is not essential then use of this class is
14537db96d56Sopenharmony_ci      **heavily** discouraged due to error messages created during loading being
14547db96d56Sopenharmony_ci      postponed and thus occurring out of context.
14557db96d56Sopenharmony_ci
14567db96d56Sopenharmony_ci   .. versionadded:: 3.5
14577db96d56Sopenharmony_ci
14587db96d56Sopenharmony_ci   .. versionchanged:: 3.6
14597db96d56Sopenharmony_ci      Began calling :meth:`~importlib.abc.Loader.create_module`, removing the
14607db96d56Sopenharmony_ci      compatibility warning for :class:`importlib.machinery.BuiltinImporter` and
14617db96d56Sopenharmony_ci      :class:`importlib.machinery.ExtensionFileLoader`.
14627db96d56Sopenharmony_ci
14637db96d56Sopenharmony_ci   .. classmethod:: factory(loader)
14647db96d56Sopenharmony_ci
14657db96d56Sopenharmony_ci      A class method which returns a callable that creates a lazy loader. This
14667db96d56Sopenharmony_ci      is meant to be used in situations where the loader is passed by class
14677db96d56Sopenharmony_ci      instead of by instance.
14687db96d56Sopenharmony_ci      ::
14697db96d56Sopenharmony_ci
14707db96d56Sopenharmony_ci        suffixes = importlib.machinery.SOURCE_SUFFIXES
14717db96d56Sopenharmony_ci        loader = importlib.machinery.SourceFileLoader
14727db96d56Sopenharmony_ci        lazy_loader = importlib.util.LazyLoader.factory(loader)
14737db96d56Sopenharmony_ci        finder = importlib.machinery.FileFinder(path, (lazy_loader, suffixes))
14747db96d56Sopenharmony_ci
14757db96d56Sopenharmony_ci.. _importlib-examples:
14767db96d56Sopenharmony_ci
14777db96d56Sopenharmony_ciExamples
14787db96d56Sopenharmony_ci--------
14797db96d56Sopenharmony_ci
14807db96d56Sopenharmony_ciImporting programmatically
14817db96d56Sopenharmony_ci''''''''''''''''''''''''''
14827db96d56Sopenharmony_ci
14837db96d56Sopenharmony_ciTo programmatically import a module, use :func:`importlib.import_module`.
14847db96d56Sopenharmony_ci::
14857db96d56Sopenharmony_ci
14867db96d56Sopenharmony_ci  import importlib
14877db96d56Sopenharmony_ci
14887db96d56Sopenharmony_ci  itertools = importlib.import_module('itertools')
14897db96d56Sopenharmony_ci
14907db96d56Sopenharmony_ci
14917db96d56Sopenharmony_ciChecking if a module can be imported
14927db96d56Sopenharmony_ci''''''''''''''''''''''''''''''''''''
14937db96d56Sopenharmony_ci
14947db96d56Sopenharmony_ciIf you need to find out if a module can be imported without actually doing the
14957db96d56Sopenharmony_ciimport, then you should use :func:`importlib.util.find_spec`.
14967db96d56Sopenharmony_ci
14977db96d56Sopenharmony_ciNote that if ``name`` is a submodule (contains a dot),
14987db96d56Sopenharmony_ci:func:`importlib.util.find_spec` will import the parent module.
14997db96d56Sopenharmony_ci::
15007db96d56Sopenharmony_ci
15017db96d56Sopenharmony_ci  import importlib.util
15027db96d56Sopenharmony_ci  import sys
15037db96d56Sopenharmony_ci
15047db96d56Sopenharmony_ci  # For illustrative purposes.
15057db96d56Sopenharmony_ci  name = 'itertools'
15067db96d56Sopenharmony_ci
15077db96d56Sopenharmony_ci  if name in sys.modules:
15087db96d56Sopenharmony_ci      print(f"{name!r} already in sys.modules")
15097db96d56Sopenharmony_ci  elif (spec := importlib.util.find_spec(name)) is not None:
15107db96d56Sopenharmony_ci      # If you chose to perform the actual import ...
15117db96d56Sopenharmony_ci      module = importlib.util.module_from_spec(spec)
15127db96d56Sopenharmony_ci      sys.modules[name] = module
15137db96d56Sopenharmony_ci      spec.loader.exec_module(module)
15147db96d56Sopenharmony_ci      print(f"{name!r} has been imported")
15157db96d56Sopenharmony_ci  else:
15167db96d56Sopenharmony_ci      print(f"can't find the {name!r} module")
15177db96d56Sopenharmony_ci
15187db96d56Sopenharmony_ci
15197db96d56Sopenharmony_ciImporting a source file directly
15207db96d56Sopenharmony_ci''''''''''''''''''''''''''''''''
15217db96d56Sopenharmony_ci
15227db96d56Sopenharmony_ciTo import a Python source file directly, use the following recipe::
15237db96d56Sopenharmony_ci
15247db96d56Sopenharmony_ci  import importlib.util
15257db96d56Sopenharmony_ci  import sys
15267db96d56Sopenharmony_ci
15277db96d56Sopenharmony_ci  # For illustrative purposes.
15287db96d56Sopenharmony_ci  import tokenize
15297db96d56Sopenharmony_ci  file_path = tokenize.__file__
15307db96d56Sopenharmony_ci  module_name = tokenize.__name__
15317db96d56Sopenharmony_ci
15327db96d56Sopenharmony_ci  spec = importlib.util.spec_from_file_location(module_name, file_path)
15337db96d56Sopenharmony_ci  module = importlib.util.module_from_spec(spec)
15347db96d56Sopenharmony_ci  sys.modules[module_name] = module
15357db96d56Sopenharmony_ci  spec.loader.exec_module(module)
15367db96d56Sopenharmony_ci
15377db96d56Sopenharmony_ci
15387db96d56Sopenharmony_ciImplementing lazy imports
15397db96d56Sopenharmony_ci'''''''''''''''''''''''''
15407db96d56Sopenharmony_ci
15417db96d56Sopenharmony_ciThe example below shows how to implement lazy imports::
15427db96d56Sopenharmony_ci
15437db96d56Sopenharmony_ci    >>> import importlib.util
15447db96d56Sopenharmony_ci    >>> import sys
15457db96d56Sopenharmony_ci    >>> def lazy_import(name):
15467db96d56Sopenharmony_ci    ...     spec = importlib.util.find_spec(name)
15477db96d56Sopenharmony_ci    ...     loader = importlib.util.LazyLoader(spec.loader)
15487db96d56Sopenharmony_ci    ...     spec.loader = loader
15497db96d56Sopenharmony_ci    ...     module = importlib.util.module_from_spec(spec)
15507db96d56Sopenharmony_ci    ...     sys.modules[name] = module
15517db96d56Sopenharmony_ci    ...     loader.exec_module(module)
15527db96d56Sopenharmony_ci    ...     return module
15537db96d56Sopenharmony_ci    ...
15547db96d56Sopenharmony_ci    >>> lazy_typing = lazy_import("typing")
15557db96d56Sopenharmony_ci    >>> #lazy_typing is a real module object,
15567db96d56Sopenharmony_ci    >>> #but it is not loaded in memory yet.
15577db96d56Sopenharmony_ci    >>> lazy_typing.TYPE_CHECKING
15587db96d56Sopenharmony_ci    False
15597db96d56Sopenharmony_ci
15607db96d56Sopenharmony_ci
15617db96d56Sopenharmony_ci
15627db96d56Sopenharmony_ciSetting up an importer
15637db96d56Sopenharmony_ci''''''''''''''''''''''
15647db96d56Sopenharmony_ci
15657db96d56Sopenharmony_ciFor deep customizations of import, you typically want to implement an
15667db96d56Sopenharmony_ci:term:`importer`. This means managing both the :term:`finder` and :term:`loader`
15677db96d56Sopenharmony_ciside of things. For finders there are two flavours to choose from depending on
15687db96d56Sopenharmony_ciyour needs: a :term:`meta path finder` or a :term:`path entry finder`. The
15697db96d56Sopenharmony_ciformer is what you would put on :attr:`sys.meta_path` while the latter is what
15707db96d56Sopenharmony_ciyou create using a :term:`path entry hook` on :attr:`sys.path_hooks` which works
15717db96d56Sopenharmony_ciwith :attr:`sys.path` entries to potentially create a finder. This example will
15727db96d56Sopenharmony_cishow you how to register your own importers so that import will use them (for
15737db96d56Sopenharmony_cicreating an importer for yourself, read the documentation for the appropriate
15747db96d56Sopenharmony_ciclasses defined within this package)::
15757db96d56Sopenharmony_ci
15767db96d56Sopenharmony_ci  import importlib.machinery
15777db96d56Sopenharmony_ci  import sys
15787db96d56Sopenharmony_ci
15797db96d56Sopenharmony_ci  # For illustrative purposes only.
15807db96d56Sopenharmony_ci  SpamMetaPathFinder = importlib.machinery.PathFinder
15817db96d56Sopenharmony_ci  SpamPathEntryFinder = importlib.machinery.FileFinder
15827db96d56Sopenharmony_ci  loader_details = (importlib.machinery.SourceFileLoader,
15837db96d56Sopenharmony_ci                    importlib.machinery.SOURCE_SUFFIXES)
15847db96d56Sopenharmony_ci
15857db96d56Sopenharmony_ci  # Setting up a meta path finder.
15867db96d56Sopenharmony_ci  # Make sure to put the finder in the proper location in the list in terms of
15877db96d56Sopenharmony_ci  # priority.
15887db96d56Sopenharmony_ci  sys.meta_path.append(SpamMetaPathFinder)
15897db96d56Sopenharmony_ci
15907db96d56Sopenharmony_ci  # Setting up a path entry finder.
15917db96d56Sopenharmony_ci  # Make sure to put the path hook in the proper location in the list in terms
15927db96d56Sopenharmony_ci  # of priority.
15937db96d56Sopenharmony_ci  sys.path_hooks.append(SpamPathEntryFinder.path_hook(loader_details))
15947db96d56Sopenharmony_ci
15957db96d56Sopenharmony_ci
15967db96d56Sopenharmony_ciApproximating :func:`importlib.import_module`
15977db96d56Sopenharmony_ci'''''''''''''''''''''''''''''''''''''''''''''
15987db96d56Sopenharmony_ci
15997db96d56Sopenharmony_ciImport itself is implemented in Python code, making it possible to
16007db96d56Sopenharmony_ciexpose most of the import machinery through importlib. The following
16017db96d56Sopenharmony_cihelps illustrate the various APIs that importlib exposes by providing an
16027db96d56Sopenharmony_ciapproximate implementation of
16037db96d56Sopenharmony_ci:func:`importlib.import_module`::
16047db96d56Sopenharmony_ci
16057db96d56Sopenharmony_ci  import importlib.util
16067db96d56Sopenharmony_ci  import sys
16077db96d56Sopenharmony_ci
16087db96d56Sopenharmony_ci  def import_module(name, package=None):
16097db96d56Sopenharmony_ci      """An approximate implementation of import."""
16107db96d56Sopenharmony_ci      absolute_name = importlib.util.resolve_name(name, package)
16117db96d56Sopenharmony_ci      try:
16127db96d56Sopenharmony_ci          return sys.modules[absolute_name]
16137db96d56Sopenharmony_ci      except KeyError:
16147db96d56Sopenharmony_ci          pass
16157db96d56Sopenharmony_ci
16167db96d56Sopenharmony_ci      path = None
16177db96d56Sopenharmony_ci      if '.' in absolute_name:
16187db96d56Sopenharmony_ci          parent_name, _, child_name = absolute_name.rpartition('.')
16197db96d56Sopenharmony_ci          parent_module = import_module(parent_name)
16207db96d56Sopenharmony_ci          path = parent_module.__spec__.submodule_search_locations
16217db96d56Sopenharmony_ci      for finder in sys.meta_path:
16227db96d56Sopenharmony_ci          spec = finder.find_spec(absolute_name, path)
16237db96d56Sopenharmony_ci          if spec is not None:
16247db96d56Sopenharmony_ci              break
16257db96d56Sopenharmony_ci      else:
16267db96d56Sopenharmony_ci          msg = f'No module named {absolute_name!r}'
16277db96d56Sopenharmony_ci          raise ModuleNotFoundError(msg, name=absolute_name)
16287db96d56Sopenharmony_ci      module = importlib.util.module_from_spec(spec)
16297db96d56Sopenharmony_ci      sys.modules[absolute_name] = module
16307db96d56Sopenharmony_ci      spec.loader.exec_module(module)
16317db96d56Sopenharmony_ci      if path is not None:
16327db96d56Sopenharmony_ci          setattr(parent_module, child_name, module)
16337db96d56Sopenharmony_ci      return module
1634