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
515 Module spec
516 -----------
520 common to all modules. The purpose of a module's spec is to encapsulate
521 this import-related information on a per-module basis.
523 Using a spec during import allows state to be transferred between import
524 system components, e.g. between the finder that creates the module spec
527 whereas without a module spec the loader had that responsibility.
529 The module's spec is exposed as the ``__spec__`` attribute on a module object.
531 the module spec.
535 .. _import-mod-attrs:
537 Import-related module attributes
538 --------------------------------
541 during loading, based on the module's spec, before the loader executes
546 The ``__name__`` attribute must be set to the fully-qualified name of
554 for introspection, but can be used for additional loader-specific
563 should be set to the empty string for top-level modules, or for
577 The ``__spec__`` attribute must be set to the module spec that was
599 :ref:`below <package-path-rules>`.
601 Non-package modules should not have a ``__path__`` attribute.
612 the code (e.g. byte-compiled file). The file does not need to exist
622 .. _package-path-rules:
625 ---------------
648 ------------
651 attributes set above, and in the module's spec, you can more explicitly
654 If the module has a spec (``__spec__``), the import machinery will try
655 to generate a repr from it. If that fails or there is no spec, the import
663 * If the module has a ``__spec__`` attribute, the information in the spec
677 has been deprecated and the module spec is now used by the import
692 .. _pyc-invalidation:
695 ----------------------------
698 cache is up-to-date with the source ``.py`` file. By default, Python does this
699 by storing the source's last-modified timestamp and size in the cache file when
704 Python also supports "hash-based" cache files, which store a hash of the source
705 file's contents rather than its metadata. There are two variants of hash-based
706 ``.pyc`` files: checked and unchecked. For checked hash-based ``.pyc`` files,
708 resulting hash with the hash in the cache file. If a checked hash-based cache
710 hash-based cache file. For unchecked hash-based ``.pyc`` files, Python simply
711 assumes the cache file is valid if it exists. Hash-based ``.pyc`` files
712 validation behavior may be overridden with the :option:`--check-hash-based-pycs`
716 Added hash-based ``.pyc`` files. Previously, Python only supported
717 timestamp-based invalidation of bytecode caches.
726 As mentioned previously, Python comes with several default meta path finders.
756 distinguishing between them by using the terms :term:`meta path finder` and
760 In particular, meta path finders operate at the beginning of the import
770 ------------------
783 As a meta path finder, the :term:`path based finder` implements the
795 environment variable and various other installation- and
796 implementation-specific defaults. Entries in :data:`sys.path` can name
804 The :term:`path based finder` is a :term:`meta path finder`, so the import
809 list of string paths to traverse - typically a package's ``__path__``
836 is up to the hook (e.g. it may be a file system encoding, UTF-8, or something
845 :term:`meta path finder` could not find the module.
849 to ask the finder for a module spec, which is then used when loading the
852 The current working directory -- denoted by an empty string -- is handled
862 --------------------------
870 module. ``find_spec()`` returns a fully populated spec for the module.
871 This spec will always have "loader" set (with one exception).
873 To indicate to the import machinery that the spec represents a namespace
890 returns a 2-tuple where the first item is the loader and the second item
895 traditional ``find_module()`` method that meta path finders support.
917 entirely with a custom meta path hook.
926 meta path (rather than disabling the standard import system entirely),
929 ``None``. The latter indicates that the meta path search should continue,
973 .. _import-dunder-main:
982 qualify as a built-in module. This is because the manner in which
989 -----------------
994 When Python is started with the :option:`-m` option, ``__spec__`` is set
995 to the module spec of the corresponding module or package. ``__spec__`` is
999 In :ref:`the remaining cases <using-on-interface-options>`
1003 - interactive prompt
1004 - :option:`-c` option
1005 - running from stdin
1006 - running directly from a source or bytecode file
1010 instead. Use the :option:`-m` switch if valid module metadata is desired
1063 :pep:`451` adds the encapsulation of per-module import state in spec
1064 objects. It also off-loads most of the boilerplate responsibilities of
1077 implementation-specific behavior that is not guaranteed to work in other