Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libpkgutil.tex @ 39940:dfd809dcf680 2.5

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Bug #1446043: correctly raise a LookupError if an encoding name given to encodings.search_function() contains a dot. (backport from rev. 52075)
author Georg Brandl <georg@python.org>
date Sat, 30 Sep 2006 11:22:35 +0000
parents 0691d901d89c
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
26757
7fd1bf20a0c0 Added docs for (draft) pkgutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1 \section{\module{pkgutil} ---
7fd1bf20a0c0 Added docs for (draft) pkgutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
2 Package extension utility}
7fd1bf20a0c0 Added docs for (draft) pkgutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
3
7fd1bf20a0c0 Added docs for (draft) pkgutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
4 \declaremodule{standard}{pkgutil}
7fd1bf20a0c0 Added docs for (draft) pkgutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
5 \modulesynopsis{Utilities to support extension of packages.}
7fd1bf20a0c0 Added docs for (draft) pkgutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
6
7fd1bf20a0c0 Added docs for (draft) pkgutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
7 \versionadded{2.3}
7fd1bf20a0c0 Added docs for (draft) pkgutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
8
7fd1bf20a0c0 Added docs for (draft) pkgutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
9 This module provides a single function:
7fd1bf20a0c0 Added docs for (draft) pkgutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
10
7fd1bf20a0c0 Added docs for (draft) pkgutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
11 \begin{funcdesc}{extend_path}{path, name}
7fd1bf20a0c0 Added docs for (draft) pkgutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
12 Extend the search path for the modules which comprise a package.
7fd1bf20a0c0 Added docs for (draft) pkgutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
13 Intended use is to place the following code in a package's
7fd1bf20a0c0 Added docs for (draft) pkgutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
14 \file{__init__.py}:
7fd1bf20a0c0 Added docs for (draft) pkgutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
15
7fd1bf20a0c0 Added docs for (draft) pkgutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
16 \begin{verbatim}
7fd1bf20a0c0 Added docs for (draft) pkgutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
17 from pkgutil import extend_path
7fd1bf20a0c0 Added docs for (draft) pkgutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
18 __path__ = extend_path(__path__, __name__)
7fd1bf20a0c0 Added docs for (draft) pkgutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
19 \end{verbatim}
7fd1bf20a0c0 Added docs for (draft) pkgutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
20
7fd1bf20a0c0 Added docs for (draft) pkgutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
21 This will add to the package's \code{__path__} all subdirectories of
7fd1bf20a0c0 Added docs for (draft) pkgutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
22 directories on \code{sys.path} named after the package. This is
7fd1bf20a0c0 Added docs for (draft) pkgutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
23 useful if one wants to distribute different parts of a single
7fd1bf20a0c0 Added docs for (draft) pkgutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
24 logical package as multiple directories.
7fd1bf20a0c0 Added docs for (draft) pkgutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
25
7fd1bf20a0c0 Added docs for (draft) pkgutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
26 It also looks for \file{*.pkg} files beginning where \code{*}
7fd1bf20a0c0 Added docs for (draft) pkgutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
27 matches the \var{name} argument. This feature is similar to
7fd1bf20a0c0 Added docs for (draft) pkgutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
28 \file{*.pth} files (see the \refmodule{site} module for more
7fd1bf20a0c0 Added docs for (draft) pkgutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
29 information), except that it doesn't special-case lines starting
7fd1bf20a0c0 Added docs for (draft) pkgutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
30 with \code{import}. A \file{*.pkg} file is trusted at face value:
7fd1bf20a0c0 Added docs for (draft) pkgutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
31 apart from checking for duplicates, all entries found in a
7fd1bf20a0c0 Added docs for (draft) pkgutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
32 \file{*.pkg} file are added to the path, regardless of whether they
39272
0691d901d89c Fix typo
Matt Fleming <mattjfleming@googlemail.com>
parents: 31827
diff changeset
33 exist on the filesystem. (This is a feature.)
26757
7fd1bf20a0c0 Added docs for (draft) pkgutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
34
7fd1bf20a0c0 Added docs for (draft) pkgutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
35 If the input path is not a list (as is the case for frozen
7fd1bf20a0c0 Added docs for (draft) pkgutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
36 packages) it is returned unchanged. The input path is not
7fd1bf20a0c0 Added docs for (draft) pkgutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
37 modified; an extended copy is returned. Items are only appended
7fd1bf20a0c0 Added docs for (draft) pkgutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
38 to the copy at the end.
7fd1bf20a0c0 Added docs for (draft) pkgutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
39
7fd1bf20a0c0 Added docs for (draft) pkgutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
40 It is assumed that \code{sys.path} is a sequence. Items of
7fd1bf20a0c0 Added docs for (draft) pkgutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
41 \code{sys.path} that are not (Unicode or 8-bit) strings referring to
7fd1bf20a0c0 Added docs for (draft) pkgutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
42 existing directories are ignored. Unicode items on \code{sys.path}
7fd1bf20a0c0 Added docs for (draft) pkgutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
43 that cause errors when used as filenames may cause this function to
7fd1bf20a0c0 Added docs for (draft) pkgutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
44 raise an exception (in line with \function{os.path.isdir()} behavior).
7fd1bf20a0c0 Added docs for (draft) pkgutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
45 \end{funcdesc}