Lines Matching +full:file +full:- +full:entry +full:- +full:cache
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
72 You can think of packages as the directories on a file system and modules as
74 packages and modules need not originate from the file system. For the
76 directories and files. Like file system directories, packages are organized
93 ----------------
102 ``__init__.py`` file. When a regular package is imported, this
103 ``__init__.py`` file is implicitly executed, and the objects it defines are
104 bound to names in the package's namespace. The ``__init__.py`` file can
108 For example, the following file system layout defines a top level ``parent``
127 ------------------
135 may reside in different locations on the file system. Portions may also be
138 objects on the file system; they may be virtual modules that have no concrete
147 With namespace packages, there is no ``parent/__init__.py`` file. In fact,
151 namespace package for the top-level ``parent`` package whenever it or one of
172 The module cache
173 ----------------
179 mapping serves as a cache of all modules that have been previously imported,
193 but it will invalidate the cache entry for the named module, causing
199 invalidate its cache entry in :data:`sys.modules`, and then re-import the
205 .. _finders-and-loaders:
208 -------------------
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
227 name file system paths or zip files. It can also be extended to search
234 return a :dfn:`module spec`, an encapsulation of the module's import-related
247 ------------
262 import processing has occurred, other than :data:`sys.modules` cache look up.
264 modules, or even built-in modules. Meta hooks are registered by adding new
274 -------------
299 top-level modules, the second argument is ``None``, but for submodules or
321 knows how to import built-in modules, one that knows how to import frozen
350 # The import-related module attributes get set here:
385 * If loading fails, the failing module -- and only the failing module --
387 :data:`sys.modules` cache, and any module that was successfully loaded
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
481 ----------
484 ``import`` or ``import-from`` statements, or built-in ``__import__()``) a
514 -----------
519 this import-related information on a per-module basis.
533 .. _import-mod-attrs:
535 Import-related module attributes
536 --------------------------------
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
597 :ref:`below <package-path-rules>`.
599 Non-package modules should not have a ``__path__`` attribute.
605 the pathname of the file from which the module was loaded (if
606 loaded from a file), or the pathname of the shared library file
615 the code (e.g. byte-compiled file). The file does not need to exist
617 compiled file would exist (see :pep:`3147`).
624 from a file, that atypical scenario may be appropriate.
626 .. _package-path-rules:
629 ---------------
644 A package's ``__init__.py`` file may set or alter the package's ``__path__``
652 ------------
696 .. _pyc-invalidation:
699 ----------------------------
701 Before Python loads cached bytecode from a ``.pyc`` file, it checks whether the
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
704 writing it. At runtime, the import system then validates the cache file by
705 checking the stored metadata in the cache file against the source's
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,
711 Python validates the cache file by hashing the source file and comparing the
712 resulting hash with the hash in the cache file. If a checked hash-based cache
713 file is found to be invalid, Python regenerates it and writes a new checked
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.
733 which contains a list of :term:`path entries <path entry>`. Each path
734 entry names a location to search for modules.
738 path entry finder that knows how to handle that particular kind of path.
740 The default set of path entry finders implement all the semantics for finding
741 modules on the file system, handling special file types such as Python source
744 module in the standard library, the default path entry finders also handle
745 loading all of these file types (other than shared libraries) from zipfiles.
747 Path entries need not be limited to file system locations. They can refer to
755 callable) would return a :term:`path entry finder` supporting the protocol
761 :term:`path entry finder`. These two types of finders are very similar,
767 By contrast, path entry finders are in a sense an implementation detail
769 removed from :data:`sys.meta_path`, none of the path entry finder semantics
773 Path entry finders
774 ------------------
784 :term:`path entry`. Most path entries name locations in the file system,
799 environment variable and various other installation- and
800 implementation-specific defaults. Entries in :data:`sys.path` can name
801 directories on the file system, zip files, and potentially other "locations"
811 list of string paths to traverse - typically a package's ``__path__``
815 The path based finder iterates over every entry in the search path, and
816 for each of these, looks for an appropriate :term:`path entry finder`
818 path entry. Because this can be an expensive operation (e.g. there may be
820 a cache mapping path entries to path entry finders. This cache is maintained
821 in :data:`sys.path_importer_cache` (despite the name, this cache actually
823 In this way, the expensive search for a particular :term:`path entry`
824 location's :term:`path entry finder` need only be done once. User code is
825 free to remove cache entries from :data:`sys.path_importer_cache` forcing
826 the path based finder to perform the path entry search again [#fnpic]_.
828 If the path entry is not present in the cache, the path based finder iterates
829 over every callable in :data:`sys.path_hooks`. Each of the :term:`path entry
830 hooks <path entry hook>` in this list is called with a single argument, the
831 path entry to be searched. This callable may either return a :term:`path
832 entry finder` that can handle the path entry, or it may raise
834 signal that the hook cannot find a :term:`path entry finder`
835 for that :term:`path entry`. The
838 is up to the hook (e.g. it may be a file system encoding, UTF-8, or something
842 If :data:`sys.path_hooks` iteration ends with no :term:`path entry finder`
846 this path entry) and return ``None``, indicating that this
849 If a :term:`path entry finder` *is* returned by one of the :term:`path entry
854 The current working directory -- denoted by an empty string -- is handled
863 Path entry finder protocol
864 --------------------------
867 contribute portions to namespace packages, path entry finders must implement
876 :term:`portion`, the path entry finder sets "submodule_search_locations" to
885 Older path entry finders may implement one of these two deprecated methods
888 implemented on the path entry finder, the legacy methods are ignored.
892 returns a 2-tuple where the first item is the loader and the second item
896 protocol, many path entry finders also support the same,
898 However path entry finder ``find_module()`` methods are never called
902 The ``find_module()`` method on path entry finders is deprecated,
903 as it does not allow the path entry finder to contribute portions to
905 exist on a path entry finder, the import system will always call
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
999 directory, zipfile or other :data:`sys.path` entry.
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
1011 *even if* the file could technically be imported directly as a module
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