diff options
Diffstat (limited to 'Doc/library/importlib.rst')
| -rw-r--r-- | Doc/library/importlib.rst | 52 |
1 files changed, 45 insertions, 7 deletions
diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst index c9f742ad03..e5cc27f974 100644 --- a/Doc/library/importlib.rst +++ b/Doc/library/importlib.rst @@ -86,6 +86,17 @@ Functions that was imported (e.g. ``pkg.mod``), while :func:`__import__` returns the top-level package or module (e.g. ``pkg``). +.. function:: invalidate_caches() + + Invalidate the internal caches of the finders stored at + :data:`sys.path_importer_cache`. If a finder implements + :meth:`abc.Finder.invalidate_caches()` then it will be called to perform the + invalidation. This function may be needed if some modules are installed + while your program is running and you expect the program to notice the + changes. + + .. versionadded:: 3.3 + :mod:`importlib.abc` -- Abstract base classes related to import --------------------------------------------------------------- @@ -111,6 +122,12 @@ are also provided to help in implementing the core ABCs. be the value of :attr:`__path__` from the parent package. If a loader cannot be found, ``None`` is returned. + .. method:: invalidate_caches() + + An optional method which, when called, should invalidate any internal + cache used by the finder. Used by :func:`invalidate_caches()` when + invalidating the caches of all cached finders. + .. class:: Loader @@ -239,11 +256,30 @@ are also provided to help in implementing the core ABCs. optimization to speed up loading by removing the parsing step of Python's compiler, and so no bytecode-specific API is exposed. + .. method:: path_stats(self, path) + + Optional abstract method which returns a :class:`dict` containing + metadata about the specifed path. Supported dictionary keys are: + + - ``'mtime'`` (mandatory): an integer or floating-point number + representing the modification time of the source code; + - ``'size'`` (optional): the size in bytes of the source code. + + Any other keys in the dictionary are ignored, to allow for future + extensions. + + .. versionadded:: 3.3 + .. method:: path_mtime(self, path) Optional abstract method which returns the modification time for the specified path. + .. deprecated:: 3.3 + This method is deprecated in favour of :meth:`path_stats`. You don't + have to implement it, but it is still available for compatibility + purposes. + .. method:: set_data(self, path, data) Optional abstract method which writes the specified bytes to a file @@ -441,7 +477,9 @@ find and load modules. This class does not perfectly mirror the semantics of :keyword:`import` in terms of :data:`sys.path`. No implicit path hooks are assumed for - simplification of the class and its semantics. + simplification of the class and its semantics. This implies that when + ``None`` is found in :data:`sys.path_importer_cache` that it is simply + ignored instead of implying a default finder. Only class methods are defined by this class to alleviate the need for instantiation. @@ -451,7 +489,7 @@ find and load modules. Class method that attempts to find a :term:`loader` for the module specified by *fullname* on :data:`sys.path` or, if defined, on *path*. For each path entry that is searched, - :data:`sys.path_importer_cache` is checked. If an non-false object is + :data:`sys.path_importer_cache` is checked. If a non-false object is found then it is used as the :term:`finder` to look for the module being searched for. If no entry is found in :data:`sys.path_importer_cache`, then :data:`sys.path_hooks` is @@ -464,7 +502,7 @@ find and load modules. --------------------------------------------------- .. module:: importlib.util - :synopsis: Importers and path hooks + :synopsis: Utility code for importers This module contains the various objects that help in the construction of an :term:`importer`. @@ -500,7 +538,7 @@ an :term:`importer`. to set the :attr:`__loader__` attribute on loaded modules. If the attribute is already set the decorator does nothing. It is assumed that the first positional argument to the - wrapped method is what :attr:`__loader__` should be set to. + wrapped method (i.e. ``self``) is what :attr:`__loader__` should be set to. .. decorator:: set_package @@ -511,8 +549,8 @@ an :term:`importer`. set on and not the module found in :data:`sys.modules`. Reliance on this decorator is discouraged when it is possible to set - :attr:`__package__` before the execution of the code is possible. By - setting it before the code for the module is executed it allows the - attribute to be used at the global level of the module during + :attr:`__package__` before importing. By + setting it beforehand the code for the module is executed with the + attribute set and thus can be used by global level code during initialization. |