Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libpkgutil.tex @ 28646:193b8aec00ce legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Changes from Jonathan Riehl to allow his pgen extension (PEP 269) to work. This includes some more code that used to be part of pgen in the main parser; I'm okay with that. I'll see if the Windows build needs work next.
author Guido van Rossum <guido@python.org>
date Thu, 17 Apr 2003 14:55:42 +0000
parents 7fd1bf20a0c0
children 2290853ab40a
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 \begin{notice}[warning]
7fd1bf20a0c0 Added docs for (draft) pkgutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
10 This is an experimental module. It may be withdrawn or completely
7fd1bf20a0c0 Added docs for (draft) pkgutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
11 changed up to an including the release of Python 2.3 beta 1.
7fd1bf20a0c0 Added docs for (draft) pkgutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
12 \end{notice}
7fd1bf20a0c0 Added docs for (draft) pkgutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
13
7fd1bf20a0c0 Added docs for (draft) pkgutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
14 This module provides a single function:
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{funcdesc}{extend_path}{path, name}
7fd1bf20a0c0 Added docs for (draft) pkgutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
17 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
18 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
19 \file{__init__.py}:
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 \begin{verbatim}
7fd1bf20a0c0 Added docs for (draft) pkgutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
22 from pkgutil import extend_path
7fd1bf20a0c0 Added docs for (draft) pkgutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
23 __path__ = extend_path(__path__, __name__)
7fd1bf20a0c0 Added docs for (draft) pkgutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
24 \end{verbatim}
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 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
27 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
28 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
29 logical package as multiple directories.
7fd1bf20a0c0 Added docs for (draft) pkgutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
30
7fd1bf20a0c0 Added docs for (draft) pkgutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
31 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
32 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
33 \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
34 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
35 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
36 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
37 \file{*.pkg} file are added to the path, regardless of whether they
7fd1bf20a0c0 Added docs for (draft) pkgutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
38 exist the filesystem. (This is a feature.)
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 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
41 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
42 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
43 to the copy at the end.
7fd1bf20a0c0 Added docs for (draft) pkgutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
44
7fd1bf20a0c0 Added docs for (draft) pkgutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
45 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
46 \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
47 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
48 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
49 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
50 \end{funcdesc}