Lines Matching +full:meta +full:- +full:spec
13 way. Functions such as :func:`importlib.import_module` and built-in
26 found, the module creation operation. While certain side-effects may occur,
45 of :pep:`302`. There is no longer any implicit import machinery - the full
55 recommended, simpler API than built-in :func:`__import__` for invoking the
93 ----------------
127 ------------------
151 namespace package for the top-level ``parent`` package whenever it or one of
173 ----------------
199 invalidate its cache entry in :data:`sys.modules`, and then re-import the
205 .. _finders-and-loaders:
208 -------------------
213 single: module spec
220 interfaces are referred to as :term:`importers <importer>` - they return
224 knows how to locate built-in modules, and the second knows how to locate
234 return a :dfn:`module spec`, an encapsulation of the module's import-related
247 ------------
251 single: meta hooks
254 pair: hooks; meta
258 this are the *import hooks*. There are two types of import hooks: *meta
261 Meta hooks are called at the start of import processing, before any other
263 This allows meta hooks to override :data:`sys.path` processing, frozen
264 modules, or even built-in modules. Meta hooks are registered by adding new
273 The meta path
274 -------------
281 searches :data:`sys.meta_path`, which contains a list of meta path finder
283 the named module. Meta path finders must implement a method called
285 a name, an import path, and (optionally) a target module. The meta path
289 If the meta path finder knows how to handle the named module, it returns a
290 spec object. If it cannot handle the named module, it returns ``None``. If
292 a spec, then a :exc:`ModuleNotFoundError` is raised. Any other exceptions
295 The :meth:`~importlib.abc.MetaPathFinder.find_spec()` method of meta path
299 top-level modules, the second argument is ``None``, but for submodules or
306 The meta path may be traversed multiple times for a single import request.
309 ``mpf.find_spec("foo", None, None)`` on each meta path finder (``mpf``). After
311 meta path a second time, calling
316 Some meta path finders only support top level imports. These importers will
320 Python's default :data:`sys.meta_path` has three meta path finders, one that
321 knows how to import built-in modules, one that knows how to import frozen
326 The :meth:`~importlib.abc.MetaPathFinder.find_spec` method of meta path
340 If and when a module spec is found, the import machinery will use it (and
345 if spec.loader is not None and hasattr(spec.loader, 'create_module'):
347 module = spec.loader.create_module(spec)
349 module = ModuleType(spec.name)
350 # The import-related module attributes get set here:
351 _init_module_attrs(spec, module)
353 if spec.loader is None:
356 if spec.origin is None and spec.submodule_search_locations is not None:
358 sys.modules[spec.name] = module
359 elif not hasattr(spec.loader, 'exec_module'):
360 module = spec.loader.load_module(spec.name)
363 sys.modules[spec.name] = module
365 spec.loader.exec_module(module)
368 del sys.modules[spec.name]
372 return sys.modules[spec.name]
385 * If loading fails, the failing module -- and only the failing module --
388 as a side-effect, must remain in the cache. This contrasts with
392 sets the import-related module attributes ("_init_module_attrs" in
393 the pseudo-code example above), as summarized in a
394 :ref:`later section <import-mod-attrs>`.
409 -------
418 * If the module is a Python module (as opposed to a built-in module or a
428 spec with the loader set to ``self``.
432 It takes one argument, the module spec, and returns the new module object
481 ----------
484 ``import`` or ``import-from`` statements, or built-in ``__import__()``) a
513 Module spec
514 -----------
518 common to all modules. The purpose of a module's spec is to encapsulate
519 this import-related information on a per-module basis.
521 Using a spec during import allows state to be transferred between import
522 system components, e.g. between the finder that creates the module spec
525 whereas without a module spec the loader had that responsibility.
527 The module's spec is exposed as the ``__spec__`` attribute on a module object.
529 the module spec.
533 .. _import-mod-attrs:
535 Import-related module attributes
536 --------------------------------
539 during loading, based on the module's spec, before the loader executes
552 for introspection, but can be used for additional loader-specific
561 should be set to the empty string for top-level modules, or for
575 The ``__spec__`` attribute must be set to the module spec that was
597 :ref:`below <package-path-rules>`.
599 Non-package modules should not have a ``__path__`` attribute.
615 the code (e.g. byte-compiled file). The file does not need to exist
621 loader is what makes use of the module spec provided by the finder
626 .. _package-path-rules:
629 ---------------
652 ------------
655 attributes set above, and in the module's spec, you can more explicitly
658 If the module has a spec (``__spec__``), the import machinery will try
659 to generate a repr from it. If that fails or there is no spec, the import
667 * If the module has a ``__spec__`` attribute, the information in the spec
681 has been deprecated and the module spec is now used by the import
696 .. _pyc-invalidation:
699 ----------------------------
702 cache is up-to-date with the source ``.py`` file. By default, Python does this
703 by storing the source's last-modified timestamp and size in the cache file when
708 Python also supports "hash-based" cache files, which store a hash of the source
709 file's contents rather than its metadata. There are two variants of hash-based
710 ``.pyc`` files: checked and unchecked. For checked hash-based ``.pyc`` files,
712 resulting hash with the hash in the cache file. If a checked hash-based cache
714 hash-based cache file. For unchecked hash-based ``.pyc`` files, Python simply
715 assumes the cache file is valid if it exists. Hash-based ``.pyc`` files
716 validation behavior may be overridden with the :option:`--check-hash-based-pycs`
720 Added hash-based ``.pyc`` files. Previously, Python only supported
721 timestamp-based invalidation of bytecode caches.
730 As mentioned previously, Python comes with several default meta path finders.
760 distinguishing between them by using the terms :term:`meta path finder` and
764 In particular, meta path finders operate at the beginning of the import
774 ------------------
787 As a meta path finder, the :term:`path based finder` implements the
799 environment variable and various other installation- and
800 implementation-specific defaults. Entries in :data:`sys.path` can name
806 The :term:`path based finder` is a :term:`meta path finder`, so the import
811 list of string paths to traverse - typically a package's ``__path__``
838 is up to the hook (e.g. it may be a file system encoding, UTF-8, or something
847 :term:`meta path finder` could not find the module.
851 to ask the finder for a module spec, which is then used when loading the
854 The current working directory -- denoted by an empty string -- is handled
864 --------------------------
872 module. ``find_spec()`` returns a fully populated spec for the module.
873 This spec will always have "loader" set (with one exception).
875 To indicate to the import machinery that the spec represents a namespace
892 returns a 2-tuple where the first item is the loader and the second item
897 traditional ``find_module()`` method that meta path finders support.
919 entirely with a custom meta path hook.
928 meta path (rather than disabling the standard import system entirely),
931 ``None``. The latter indicates that the meta path search should continue,
975 .. _import-dunder-main:
984 qualify as a built-in module. This is because the manner in which
991 -----------------
996 When Python is started with the :option:`-m` option, ``__spec__`` is set
997 to the module spec of the corresponding module or package. ``__spec__`` is
1001 In :ref:`the remaining cases <using-on-interface-options>`
1005 - interactive prompt
1006 - :option:`-c` option
1007 - running from stdin
1008 - running directly from a source or bytecode file
1012 instead. Use the :option:`-m` switch if valid module metadata is desired
1046 :pep:`451` adds the encapsulation of per-module import state in spec
1047 objects. It also off-loads most of the boilerplate responsibilities of
1060 implementation-specific behavior that is not guaranteed to work in other