1:mod:`pkgutil` --- Package extension utility
2============================================
3
4.. module:: pkgutil
5   :synopsis: Utilities for the import system.
6
7**Source code:** :source:`Lib/pkgutil.py`
8
9--------------
10
11This module provides utilities for the import system, in particular package
12support.
13
14.. class:: ModuleInfo(module_finder, name, ispkg)
15
16    A namedtuple that holds a brief summary of a module's info.
17
18    .. versionadded:: 3.6
19
20.. function:: extend_path(path, name)
21
22   Extend the search path for the modules which comprise a package.  Intended
23   use is to place the following code in a package's :file:`__init__.py`::
24
25      from pkgutil import extend_path
26      __path__ = extend_path(__path__, __name__)
27
28   This will add to the package's ``__path__`` all subdirectories of directories
29   on ``sys.path`` named after the package.  This is useful if one wants to
30   distribute different parts of a single logical package as multiple
31   directories.
32
33   It also looks for :file:`\*.pkg` files beginning where ``*`` matches the
34   *name* argument.  This feature is similar to :file:`\*.pth` files (see the
35   :mod:`site` module for more information), except that it doesn't special-case
36   lines starting with ``import``.  A :file:`\*.pkg` file is trusted at face
37   value: apart from checking for duplicates, all entries found in a
38   :file:`\*.pkg` file are added to the path, regardless of whether they exist
39   on the filesystem.  (This is a feature.)
40
41   If the input path is not a list (as is the case for frozen packages) it is
42   returned unchanged.  The input path is not modified; an extended copy is
43   returned.  Items are only appended to the copy at the end.
44
45   It is assumed that :data:`sys.path` is a sequence.  Items of :data:`sys.path`
46   that are not strings referring to existing directories are ignored. Unicode
47   items on :data:`sys.path` that cause errors when used as filenames may cause
48   this function to raise an exception (in line with :func:`os.path.isdir`
49   behavior).
50
51
52.. class:: ImpImporter(dirname=None)
53
54   :pep:`302` Finder that wraps Python's "classic" import algorithm.
55
56   If *dirname* is a string, a :pep:`302` finder is created that searches that
57   directory.  If *dirname* is ``None``, a :pep:`302` finder is created that
58   searches the current :data:`sys.path`, plus any modules that are frozen or
59   built-in.
60
61   Note that :class:`ImpImporter` does not currently support being used by
62   placement on :data:`sys.meta_path`.
63
64   .. deprecated:: 3.3
65      This emulation is no longer needed, as the standard import mechanism
66      is now fully :pep:`302` compliant and available in :mod:`importlib`.
67
68
69.. class:: ImpLoader(fullname, file, filename, etc)
70
71   :term:`Loader <loader>` that wraps Python's "classic" import algorithm.
72
73   .. deprecated:: 3.3
74      This emulation is no longer needed, as the standard import mechanism
75      is now fully :pep:`302` compliant and available in :mod:`importlib`.
76
77
78.. function:: find_loader(fullname)
79
80   Retrieve a module :term:`loader` for the given *fullname*.
81
82   This is a backwards compatibility wrapper around
83   :func:`importlib.util.find_spec` that converts most failures to
84   :exc:`ImportError` and only returns the loader rather than the full
85   :class:`ModuleSpec`.
86
87   .. versionchanged:: 3.3
88      Updated to be based directly on :mod:`importlib` rather than relying
89      on the package internal :pep:`302` import emulation.
90
91   .. versionchanged:: 3.4
92      Updated to be based on :pep:`451`
93
94.. function:: get_importer(path_item)
95
96   Retrieve a :term:`finder` for the given *path_item*.
97
98   The returned finder is cached in :data:`sys.path_importer_cache` if it was
99   newly created by a path hook.
100
101   The cache (or part of it) can be cleared manually if a rescan of
102   :data:`sys.path_hooks` is necessary.
103
104   .. versionchanged:: 3.3
105      Updated to be based directly on :mod:`importlib` rather than relying
106      on the package internal :pep:`302` import emulation.
107
108
109.. function:: get_loader(module_or_name)
110
111   Get a :term:`loader` object for *module_or_name*.
112
113   If the module or package is accessible via the normal import mechanism, a
114   wrapper around the relevant part of that machinery is returned.  Returns
115   ``None`` if the module cannot be found or imported.  If the named module is
116   not already imported, its containing package (if any) is imported, in order
117   to establish the package ``__path__``.
118
119   .. versionchanged:: 3.3
120      Updated to be based directly on :mod:`importlib` rather than relying
121      on the package internal :pep:`302` import emulation.
122
123   .. versionchanged:: 3.4
124      Updated to be based on :pep:`451`
125
126
127.. function:: iter_importers(fullname='')
128
129   Yield :term:`finder` objects for the given module name.
130
131   If fullname contains a '.', the finders will be for the package
132   containing fullname, otherwise they will be all registered top level
133   finders (i.e. those on both sys.meta_path and sys.path_hooks).
134
135   If the named module is in a package, that package is imported as a side
136   effect of invoking this function.
137
138   If no module name is specified, all top level finders are produced.
139
140   .. versionchanged:: 3.3
141      Updated to be based directly on :mod:`importlib` rather than relying
142      on the package internal :pep:`302` import emulation.
143
144
145.. function:: iter_modules(path=None, prefix='')
146
147   Yields :class:`ModuleInfo` for all submodules on *path*, or, if
148   *path* is ``None``, all top-level modules on ``sys.path``.
149
150   *path* should be either ``None`` or a list of paths to look for modules in.
151
152   *prefix* is a string to output on the front of every module name on output.
153
154   .. note::
155
156      Only works for a :term:`finder` which defines an ``iter_modules()``
157      method. This interface is non-standard, so the module also provides
158      implementations for :class:`importlib.machinery.FileFinder` and
159      :class:`zipimport.zipimporter`.
160
161   .. versionchanged:: 3.3
162      Updated to be based directly on :mod:`importlib` rather than relying
163      on the package internal :pep:`302` import emulation.
164
165
166.. function:: walk_packages(path=None, prefix='', onerror=None)
167
168   Yields :class:`ModuleInfo` for all modules recursively on
169   *path*, or, if *path* is ``None``, all accessible modules.
170
171   *path* should be either ``None`` or a list of paths to look for modules in.
172
173   *prefix* is a string to output on the front of every module name on output.
174
175   Note that this function must import all *packages* (*not* all modules!) on
176   the given *path*, in order to access the ``__path__`` attribute to find
177   submodules.
178
179   *onerror* is a function which gets called with one argument (the name of the
180   package which was being imported) if any exception occurs while trying to
181   import a package.  If no *onerror* function is supplied, :exc:`ImportError`\s
182   are caught and ignored, while all other exceptions are propagated,
183   terminating the search.
184
185   Examples::
186
187      # list all modules python can access
188      walk_packages()
189
190      # list all submodules of ctypes
191      walk_packages(ctypes.__path__, ctypes.__name__ + '.')
192
193   .. note::
194
195      Only works for a :term:`finder` which defines an ``iter_modules()``
196      method. This interface is non-standard, so the module also provides
197      implementations for :class:`importlib.machinery.FileFinder` and
198      :class:`zipimport.zipimporter`.
199
200   .. versionchanged:: 3.3
201      Updated to be based directly on :mod:`importlib` rather than relying
202      on the package internal :pep:`302` import emulation.
203
204
205.. function:: get_data(package, resource)
206
207   Get a resource from a package.
208
209   This is a wrapper for the :term:`loader`
210   :meth:`get_data <importlib.abc.ResourceLoader.get_data>` API.  The
211   *package* argument should be the name of a package, in standard module format
212   (``foo.bar``).  The *resource* argument should be in the form of a relative
213   filename, using ``/`` as the path separator.  The parent directory name
214   ``..`` is not allowed, and nor is a rooted name (starting with a ``/``).
215
216   The function returns a binary string that is the contents of the specified
217   resource.
218
219   For packages located in the filesystem, which have already been imported,
220   this is the rough equivalent of::
221
222      d = os.path.dirname(sys.modules[package].__file__)
223      data = open(os.path.join(d, resource), 'rb').read()
224
225   If the package cannot be located or loaded, or it uses a :term:`loader`
226   which does not support :meth:`get_data <importlib.abc.ResourceLoader.get_data>`,
227   then ``None`` is returned.  In particular, the :term:`loader` for
228   :term:`namespace packages <namespace package>` does not support
229   :meth:`get_data <importlib.abc.ResourceLoader.get_data>`.
230