Lines Matching full:path
144 that package if the path of their parent package (or :data:`sys.path` for a
167 the dotted path to a submodule, e.g. ``foo.bar.baz``. In this case, Python
225 frozen modules. A third default finder searches an :term:`import path`
226 for modules. The :term:`import path` is a list of locations that may
252 single: path hooks
255 pair: hooks; path
259 hooks* and *import path hooks*.
263 This allows meta hooks to override :data:`sys.path` processing, frozen
267 Import path hooks are called as part of :data:`sys.path` (or
268 ``package.__path__``) processing, at the point where their associated path
269 item is encountered. Import path hooks are registered by adding new callables
273 The meta path
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
295 The :meth:`~importlib.abc.MetaPathFinder.find_spec()` method of meta path
298 The second argument is the path entries to use for the module search. For
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
322 modules, and one that knows how to import modules from an :term:`import path`
323 (i.e. the :term:`path based finder`).
326 The :meth:`~importlib.abc.MetaPathFinder.find_spec` method of meta path
597 :ref:`below <package-path-rules>`.
614 be set, which is the path to any compiled version of
616 to set this attribute; the path can simply point to where the
626 .. _package-path-rules:
634 Within the import machinery, it functions much the same as :data:`sys.path`,
637 :data:`sys.path`.
640 The same rules used for :data:`sys.path` also apply to a package's
724 The Path Based Finder
728 single: path based finder
730 As mentioned previously, Python comes with several default meta path finders.
731 One of these, called the :term:`path based finder`
732 (:class:`~importlib.machinery.PathFinder`), searches an :term:`import path`,
733 which contains a list of :term:`path entries <path entry>`. Each path
736 The path based finder itself doesn't know how to import anything. Instead, it
737 traverses the individual path entries, associating each of them with a
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
744 module in the standard library, the default path entry finders also handle
747 Path entries need not be limited to file system locations. They can refer to
751 The path based finder provides additional hooks and protocols so that you
752 can extend and customize the types of searchable path entries. For example,
753 if you wanted to support path entries as network URLs, you could write a hook
755 callable) would return a :term:`path entry finder` supporting the protocol
760 distinguishing between them by using the terms :term:`meta path finder` and
761 :term:`path entry finder`. These two types of finders are very similar,
764 In particular, meta path finders operate at the beginning of the import
767 By contrast, path entry finders are in a sense an implementation detail
768 of the path based finder, and in fact, if the path based finder were to be
769 removed from :data:`sys.meta_path`, none of the path entry finder semantics
773 Path entry finders
777 single: sys.path
782 The :term:`path based finder` is responsible for finding and loading
784 :term:`path entry`. Most path entries name locations in the file system,
787 As a meta path finder, the :term:`path based finder` implements the
790 customize how modules are found and loaded from the :term:`import path`.
792 Three variables are used by the :term:`path based finder`, :data:`sys.path`,
797 :data:`sys.path` contains a list of strings providing search locations for
800 implementation-specific defaults. Entries in :data:`sys.path` can name
804 :data:`sys.path`; all other data types are ignored.
806 The :term:`path based finder` is a :term:`meta path finder`, so the import
807 machinery begins the :term:`import path` search by calling the path
809 described previously. When the ``path`` argument to
812 attribute for an import within that package. If the ``path`` argument is
813 ``None``, this indicates a top level import and :data:`sys.path` is used.
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
819 ``stat()`` call overheads for this search), the path based finder maintains
820 a cache mapping path entries to path entry finders. This cache is maintained
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
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
833 :exc:`ImportError`. An :exc:`ImportError` is used by the path based finder to
834 signal that the hook cannot find a :term:`path entry finder`
835 for that :term:`path entry`. The
836 exception is ignored and :term:`import path` iteration continues. The hook
842 If :data:`sys.path_hooks` iteration ends with no :term:`path entry finder`
843 being returned, then the path based finder's
846 this path entry) and return ``None``, indicating that this
847 :term:`meta path finder` could not find the module.
849 If a :term:`path entry finder` *is* returned by one of the :term:`path entry
855 slightly differently from other entries on :data:`sys.path`. First, if the
858 directory is looked up fresh for each module lookup. Third, the path used for
863 Path entry finder protocol
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.
896 protocol, many path entry finders also support the same,
897 traditional ``find_module()`` method that meta path finders support.
898 However path entry finder ``find_module()`` methods are never called
899 with a ``path`` argument (they are expected to record the appropriate
900 path information from the initial call to the path hook).
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
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,
999 directory, zipfile or other :data:`sys.path` entry.