ꦫꦣꦺꦤ꧀ꦄꦤ꧀ꦠꦱꦺꦤ

PATH: usr / share / doc / python3-docs / html / _sources / library

:mod:`pkgutil` --- Package extension utility
============================================

.. module:: pkgutil
   :synopsis: Utilities for the import system.

**Source code:** :source:`Lib/pkgutil.py`

--------------

This module provides utilities for the import system, in particular package
support.

.. class:: ModuleInfo(module_finder, name, ispkg)

A namedtuple that holds a brief summary of a module's info.

.. versionadded:: 3.6

.. function:: extend_path(path, name)

Extend the search path for the modules which comprise a package.  Intended
   use is to place the following code in a package's :file:`__init__.py`::

from pkgutil import extend_path
      __path__ = extend_path(__path__, __name__)

This will add to the package's ``__path__`` all subdirectories of directories
   on ``sys.path`` named after the package.  This is useful if one wants to
   distribute different parts of a single logical package as multiple
   directories.

It also looks for :file:`\*.pkg` files beginning where ``*`` matches the
   *name* argument.  This feature is similar to :file:`\*.pth` files (see the
   :mod:`site` module for more information), except that it doesn't special-case
   lines starting with ``import``.  A :file:`\*.pkg` file is trusted at face
   value: apart from checking for duplicates, all entries found in a
   :file:`\*.pkg` file are added to the path, regardless of whether they exist
   on the filesystem.  (This is a feature.)

If the input path is not a list (as is the case for frozen packages) it is
   returned unchanged.  The input path is not modified; an extended copy is
   returned.  Items are only appended to the copy at the end.

It is assumed that :data:`sys.path` is a sequence.  Items of :data:`sys.path`
   that are not strings referring to existing directories are ignored. Unicode
   items on :data:`sys.path` that cause errors when used as filenames may cause
   this function to raise an exception (in line with :func:`os.path.isdir`
   behavior).

.. class:: ImpImporter(dirname=None)

:pep:`302` Finder that wraps Python's "classic" import algorithm.

If *dirname* is a string, a :pep:`302` finder is created that searches that
   directory.  If *dirname* is ``None``, a :pep:`302` finder is created that
   searches the current :data:`sys.path`, plus any modules that are frozen or
   built-in.

Note that :class:`ImpImporter` does not currently support being used by
   placement on :data:`sys.meta_path`.

.. deprecated:: 3.3
      This emulation is no longer needed, as the standard import mechanism
      is now fully PEP 302 compliant and available in :mod:`importlib`.

.. class:: ImpLoader(fullname, file, filename, etc)

:term:`Loader` that wraps Python's "classic" import algorithm.

.. deprecated:: 3.3
      This emulation is no longer needed, as the standard import mechanism
      is now fully PEP 302 compliant and available in :mod:`importlib`.

.. function:: find_loader(fullname)

Retrieve a module :term:`loader` for the given *fullname*.

This is a backwards compatibility wrapper around
   :func:`importlib.util.find_spec` that converts most failures to
   :exc:`ImportError` and only returns the loader rather than the full
   :class:`ModuleSpec`.

.. versionchanged:: 3.3
      Updated to be based directly on :mod:`importlib` rather than relying
      on the package internal PEP 302 import emulation.

.. versionchanged:: 3.4
      Updated to be based on :pep:`451`

.. function:: get_importer(path_item)

Retrieve a :term:`finder` for the given *path_item*.

The returned finder is cached in :data:`sys.path_importer_cache` if it was
   newly created by a path hook.

The cache (or part of it) can be cleared manually if a rescan of
   :data:`sys.path_hooks` is necessary.

.. versionchanged:: 3.3
      Updated to be based directly on :mod:`importlib` rather than relying
      on the package internal PEP 302 import emulation.

.. function:: get_loader(module_or_name)

Get a :term:`loader` object for *module_or_name*.

If the module or package is accessible via the normal import mechanism, a
   wrapper around the relevant part of that machinery is returned.  Returns
   ``None`` if the module cannot be found or imported.  If the named module is
   not already imported, its containing package (if any) is imported, in order
   to establish the package ``__path__``.

.. versionchanged:: 3.3
      Updated to be based directly on :mod:`importlib` rather than relying
      on the package internal PEP 302 import emulation.

.. versionchanged:: 3.4
      Updated to be based on :pep:`451`

.. function:: iter_importers(fullname='')

Yield :term:`finder` objects for the given module name.

If fullname contains a '.', the finders will be for the package
   containing fullname, otherwise they will be all registered top level
   finders (i.e. those on both sys.meta_path and sys.path_hooks).

If the named module is in a package, that package is imported as a side
   effect of invoking this function.

If no module name is specified, all top level finders are produced.

.. versionchanged:: 3.3
      Updated to be based directly on :mod:`importlib` rather than relying
      on the package internal PEP 302 import emulation.

.. function:: iter_modules(path=None, prefix='')

Yields :class:`ModuleInfo` for all submodules on *path*, or, if
   *path* is ``None``, all top-level modules on ``sys.path``.

*path* should be either ``None`` or a list of paths to look for modules in.

*prefix* is a string to output on the front of every module name on output.

.. note::

Only works for a :term:`finder` which defines an ``iter_modules()``
      method. This interface is non-standard, so the module also provides
      implementations for :class:`importlib.machinery.FileFinder` and
      :class:`zipimport.zipimporter`.

.. versionchanged:: 3.3
      Updated to be based directly on :mod:`importlib` rather than relying
      on the package internal PEP 302 import emulation.

.. function:: walk_packages(path=None, prefix='', onerror=None)

Yields :class:`ModuleInfo` for all modules recursively on
   *path*, or, if *path* is ``None``, all accessible modules.

*path* should be either ``None`` or a list of paths to look for modules in.

*prefix* is a string to output on the front of every module name on output.

Note that this function must import all *packages* (*not* all modules!) on
   the given *path*, in order to access the ``__path__`` attribute to find
   submodules.

*onerror* is a function which gets called with one argument (the name of the
   package which was being imported) if any exception occurs while trying to
   import a package.  If no *onerror* function is supplied, :exc:`ImportError`\s
   are caught and ignored, while all other exceptions are propagated,
   terminating the search.

Examples::

# list all modules python can access
      walk_packages()

# list all submodules of ctypes
      walk_packages(ctypes.__path__, ctypes.__name__ + '.')

.. note::

.. versionchanged:: 3.3
      Updated to be based directly on :mod:`importlib` rather than relying
      on the package internal PEP 302 import emulation.

.. function:: get_data(package, resource)

Get a resource from a package.

This is a wrapper for the :term:`loader`
   :meth:`get_data <importlib.abc.ResourceLoader.get_data>` API.  The
   *package* argument should be the name of a package, in standard module format
   (``foo.bar``).  The *resource* argument should be in the form of a relative
   filename, using ``/`` as the path separator.  The parent directory name
   ``..`` is not allowed, and nor is a rooted name (starting with a ``/``).

The function returns a binary string that is the contents of the specified
   resource.

For packages located in the filesystem, which have already been imported,
   this is the rough equivalent of::

d = os.path.dirname(sys.modules[package].__file__)
      data = open(os.path.join(d, resource), 'rb').read()

If the package cannot be located or loaded, or it uses a :term:`loader`
   which does not support :meth:`get_data <importlib.abc.ResourceLoader.get_data>`,
   then ``None`` is returned.  In particular, the :term:`loader` for
   :term:`namespace packages <namespace package>` does not support
   :meth:`get_data <importlib.abc.ResourceLoader.get_data>`.

[+] ..
[-] crypt.rst.txt [edit]
[-] logging.handlers.rst.txt [edit]
[-] __main__.rst.txt [edit]
[-] pty.rst.txt [edit]
[-] email.rst.txt [edit]
[-] traceback.rst.txt [edit]
[-] fileinput.rst.txt [edit]
[-] xml.sax.reader.rst.txt [edit]
[-] curses.rst.txt [edit]
[-] copy.rst.txt [edit]
[-] aifc.rst.txt [edit]
[-] xmlrpc.client.rst.txt [edit]
[-] pydoc.rst.txt [edit]
[-] asyncio-eventloops.rst.txt [edit]
[-] uuid.rst.txt [edit]
[-] functional.rst.txt [edit]
[-] posix.rst.txt [edit]
[-] hashlib.rst.txt [edit]
[-] cmd.rst.txt [edit]
[-] nntplib.rst.txt [edit]
[-] python.rst.txt [edit]
[-] types.rst.txt [edit]
[-] exceptions.rst.txt [edit]
[-] tracemalloc.rst.txt [edit]
[-] othergui.rst.txt [edit]
[-] xml.dom.pulldom.rst.txt [edit]
[-] inspect.rst.txt [edit]
[-] asyncio-stream.rst.txt [edit]
[-] i18n.rst.txt [edit]
[-] concurrent.rst.txt [edit]
[-] imghdr.rst.txt [edit]
[-] spwd.rst.txt [edit]
[-] os.path.rst.txt [edit]
[-] email.message.rst.txt [edit]
[-] random.rst.txt [edit]
[-] fileformats.rst.txt [edit]
[-] faulthandler.rst.txt [edit]
[-] parser.rst.txt [edit]
[-] stat.rst.txt [edit]
[-] code.rst.txt [edit]
[-] email.headerregistry.rst.txt [edit]
[-] timeit.rst.txt [edit]
[-] optparse.rst.txt [edit]
[-] smtplib.rst.txt [edit]
[-] filesys.rst.txt [edit]
[-] email.mime.rst.txt [edit]
[-] itertools.rst.txt [edit]
[-] sys.rst.txt [edit]
[-] bdb.rst.txt [edit]
[-] stringprep.rst.txt [edit]
[-] asyncio-subprocess.rst.txt [edit]
[-] decimal.rst.txt [edit]
[-] unicodedata.rst.txt [edit]
[-] intro.rst.txt [edit]
[-] constants.rst.txt [edit]
[-] xmlrpc.rst.txt [edit]
[-] grp.rst.txt [edit]
[-] pickle.rst.txt [edit]
[-] mmap.rst.txt [edit]
[-] debug.rst.txt [edit]
[-] unittest.mock-examples.rst.txt [edit]
[-] undoc.rst.txt [edit]
[-] functools.rst.txt [edit]
[-] ssl.rst.txt [edit]
[-] locale.rst.txt [edit]
[-] secrets.rst.txt [edit]
[-] pprint.rst.txt [edit]
[-] email.header.rst.txt [edit]
[-] email.contentmanager.rst.txt [edit]
[-] _thread.rst.txt [edit]
[-] errno.rst.txt [edit]
[-] sunau.rst.txt [edit]
[-] syslog.rst.txt [edit]
[-] tkinter.ttk.rst.txt [edit]
[-] distribution.rst.txt [edit]
[-] pdb.rst.txt [edit]
[-] distutils.rst.txt [edit]
[-] dummy_threading.rst.txt [edit]
[-] text.rst.txt [edit]
[-] socketserver.rst.txt [edit]
[-] _dummy_thread.rst.txt [edit]
[-] persistence.rst.txt [edit]
[-] asyncio-eventloop.rst.txt [edit]
[-] collections.abc.rst.txt [edit]
[-] fnmatch.rst.txt [edit]
[-] quopri.rst.txt [edit]
[-] http.server.rst.txt [edit]
[-] keyword.rst.txt [edit]
[-] xml.dom.rst.txt [edit]
[-] cgi.rst.txt [edit]
[-] heapq.rst.txt [edit]
[-] email.iterators.rst.txt [edit]
[-] io.rst.txt [edit]
[-] curses.panel.rst.txt [edit]
[-] winreg.rst.txt [edit]
[-] urllib.parse.rst.txt [edit]
[-] unix.rst.txt [edit]
[-] getpass.rst.txt [edit]
[-] sched.rst.txt [edit]
[-] socket.rst.txt [edit]
[-] pipes.rst.txt [edit]
[-] email.compat32-message.rst.txt [edit]
[-] asyncio-sync.rst.txt [edit]
[-] modulefinder.rst.txt [edit]
[-] html.entities.rst.txt [edit]
[-] ctypes.rst.txt [edit]
[-] pyexpat.rst.txt [edit]
[-] pyclbr.rst.txt [edit]
[-] html.rst.txt [edit]
[-] test.rst.txt [edit]
[-] markup.rst.txt [edit]
[-] doctest.rst.txt [edit]
[-] csv.rst.txt [edit]
[-] colorsys.rst.txt [edit]
[-] xml.sax.rst.txt [edit]
[-] zlib.rst.txt [edit]
[-] subprocess.rst.txt [edit]
[-] base64.rst.txt [edit]
[-] platform.rst.txt [edit]
[-] binascii.rst.txt [edit]
[-] http.rst.txt [edit]
[-] nis.rst.txt [edit]
[-] statistics.rst.txt [edit]
[-] sqlite3.rst.txt [edit]
[-] json.rst.txt [edit]
[-] gzip.rst.txt [edit]
[-] netdata.rst.txt [edit]
[-] pkgutil.rst.txt [edit]
[-] linecache.rst.txt [edit]
[-] cgitb.rst.txt [edit]
[-] archiving.rst.txt [edit]
[-] argparse.rst.txt [edit]
[-] wsgiref.rst.txt [edit]
[-] tokenize.rst.txt [edit]
[-] mm.rst.txt [edit]
[-] telnetlib.rst.txt [edit]
[-] ossaudiodev.rst.txt [edit]
[-] tk.rst.txt [edit]
[-] string.rst.txt [edit]
[-] misc.rst.txt [edit]
[-] marshal.rst.txt [edit]
[-] email.encoders.rst.txt [edit]
[-] array.rst.txt [edit]
[-] queue.rst.txt [edit]
[-] copyreg.rst.txt [edit]
[-] atexit.rst.txt [edit]
[-] signal.rst.txt [edit]
[-] collections.rst.txt [edit]
[-] tkinter.scrolledtext.rst.txt [edit]
[-] tempfile.rst.txt [edit]
[-] codeop.rst.txt [edit]
[-] threading.rst.txt [edit]
[-] enum.rst.txt [edit]
[-] imp.rst.txt [edit]
[-] crypto.rst.txt [edit]
[-] bisect.rst.txt [edit]
[-] dbm.rst.txt [edit]
[-] formatter.rst.txt [edit]
[-] language.rst.txt [edit]
[-] trace.rst.txt [edit]
[-] tkinter.tix.rst.txt [edit]
[-] smtpd.rst.txt [edit]
[-] asyncio-task.rst.txt [edit]
[-] abc.rst.txt [edit]
[-] gettext.rst.txt [edit]
[-] concurrency.rst.txt [edit]
[-] allos.rst.txt [edit]
[-] xml.sax.utils.rst.txt [edit]
[-] tty.rst.txt [edit]
[-] mailcap.rst.txt [edit]
[-] msvcrt.rst.txt [edit]
[-] reprlib.rst.txt [edit]
[-] development.rst.txt [edit]
[-] contextlib.rst.txt [edit]
[-] configparser.rst.txt [edit]
[-] symbol.rst.txt [edit]
[-] shlex.rst.txt [edit]
[-] tabnanny.rst.txt [edit]
[-] asyncio-dev.rst.txt [edit]
[-] py_compile.rst.txt [edit]
[-] uu.rst.txt [edit]
[-] logging.rst.txt [edit]
[-] runpy.rst.txt [edit]
[-] pathlib.rst.txt [edit]
[-] os.rst.txt [edit]
[-] urllib.request.rst.txt [edit]
[-] html.parser.rst.txt [edit]
[-] bz2.rst.txt [edit]
[-] binhex.rst.txt [edit]
[-] time.rst.txt [edit]
[-] zipapp.rst.txt [edit]
[-] fcntl.rst.txt [edit]
[-] tkinter.rst.txt [edit]
[-] glob.rst.txt [edit]
[-] email.policy.rst.txt [edit]
[-] pwd.rst.txt [edit]
[-] numeric.rst.txt [edit]
[-] winsound.rst.txt [edit]
[-] urllib.robotparser.rst.txt [edit]
[-] selectors.rst.txt [edit]
[-] xdrlib.rst.txt [edit]
[-] webbrowser.rst.txt [edit]
[-] zipfile.rst.txt [edit]
[-] ipc.rst.txt [edit]
[-] mailbox.rst.txt [edit]
[-] plistlib.rst.txt [edit]
[-] getopt.rst.txt [edit]
[-] concurrent.futures.rst.txt [edit]
[-] symtable.rst.txt [edit]
[-] rlcompleter.rst.txt [edit]
[-] __future__.rst.txt [edit]
[-] asynchat.rst.txt [edit]
[-] audioop.rst.txt [edit]
[-] compileall.rst.txt [edit]
[-] unittest.mock.rst.txt [edit]
[-] dis.rst.txt [edit]
[-] index.rst.txt [edit]
[-] logging.config.rst.txt [edit]
[-] gc.rst.txt [edit]
[-] shutil.rst.txt [edit]
[-] sndhdr.rst.txt [edit]
[-] ipaddress.rst.txt [edit]
[-] asyncio-queue.rst.txt [edit]
[-] curses.ascii.rst.txt [edit]
[-] builtins.rst.txt [edit]
[-] calendar.rst.txt [edit]
[-] sysconfig.rst.txt [edit]
[-] token.rst.txt [edit]
[-] xml.dom.minidom.rst.txt [edit]
[-] textwrap.rst.txt [edit]
[-] importlib.rst.txt [edit]
[-] fpectl.rst.txt [edit]
[-] mimetypes.rst.txt [edit]
[-] netrc.rst.txt [edit]
[-] fractions.rst.txt [edit]
[-] select.rst.txt [edit]
[-] lzma.rst.txt [edit]
[-] math.rst.txt [edit]
[-] frameworks.rst.txt [edit]
[-] ftplib.rst.txt [edit]
[-] macpath.rst.txt [edit]
[-] numbers.rst.txt [edit]
[-] xml.etree.elementtree.rst.txt [edit]
[-] pickletools.rst.txt [edit]
[-] asyncore.rst.txt [edit]
[-] warnings.rst.txt [edit]
[-] resource.rst.txt [edit]
[-] unittest.rst.txt [edit]
[-] datetime.rst.txt [edit]
[-] asyncio-protocol.rst.txt [edit]
[-] urllib.rst.txt [edit]
[-] superseded.rst.txt [edit]
[-] email.generator.rst.txt [edit]
[-] ensurepip.rst.txt [edit]
[-] ast.rst.txt [edit]
[-] modules.rst.txt [edit]
[-] venv.rst.txt [edit]
[-] internet.rst.txt [edit]
[-] chunk.rst.txt [edit]
[-] asyncio.rst.txt [edit]
[-] turtle.rst.txt [edit]
[-] struct.rst.txt [edit]
[-] profile.rst.txt [edit]
[-] urllib.error.rst.txt [edit]
[-] http.cookiejar.rst.txt [edit]
[-] tarfile.rst.txt [edit]
[-] http.cookies.rst.txt [edit]
[-] multiprocessing.rst.txt [edit]
[-] msilib.rst.txt [edit]
[-] xmlrpc.server.rst.txt [edit]
[-] termios.rst.txt [edit]
[-] 2to3.rst.txt [edit]
[-] windows.rst.txt [edit]
[-] email.examples.rst.txt [edit]
[-] readline.rst.txt [edit]
[-] binary.rst.txt [edit]
[-] shelve.rst.txt [edit]
[-] re.rst.txt [edit]
[-] xml.sax.handler.rst.txt [edit]
[-] hmac.rst.txt [edit]
[-] datatypes.rst.txt [edit]
[-] typing.rst.txt [edit]
[-] custominterp.rst.txt [edit]
[-] email.charset.rst.txt [edit]
[-] email.util.rst.txt [edit]
[-] zipimport.rst.txt [edit]
[-] cmath.rst.txt [edit]
[-] idle.rst.txt [edit]
[-] operator.rst.txt [edit]
[-] site.rst.txt [edit]
[-] email.parser.rst.txt [edit]
[-] functions.rst.txt [edit]
[-] poplib.rst.txt [edit]
[-] filecmp.rst.txt [edit]
[-] codecs.rst.txt [edit]
[-] imaplib.rst.txt [edit]
[-] stdtypes.rst.txt [edit]
[-] difflib.rst.txt [edit]
[-] weakref.rst.txt [edit]
[-] http.client.rst.txt [edit]
[-] email.errors.rst.txt [edit]
[-] xml.rst.txt [edit]
[-] wave.rst.txt [edit]