1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
|
\section{\module{site} ---
Site-specific configuration hook}
\declaremodule{standard}{site}
\modulesynopsis{A standard way to reference site-specific modules.}
\strong{This module is automatically imported during initialization.}
The automatic import can be suppressed using the interpreter's
\programopt{-S} option.
Importing this module will append site-specific paths to the module
search path.
\indexiii{module}{search}{path}
It starts by constructing up to four directories from a head and a
tail part. For the head part, it uses \code{sys.prefix} and
\code{sys.exec_prefix}; empty heads are skipped. For
the tail part, it uses the empty string and then
\file{lib/site-packages} (on Windows) or
\file{lib/python\shortversion/site-packages} and then
\file{lib/site-python} (on \UNIX{} and Macintosh). For each of the
distinct head-tail combinations, it sees if it refers to an existing
directory, and if so, adds it to \code{sys.path} and also inspects
the newly added path for configuration files.
\indexii{site-python}{directory}
\indexii{site-packages}{directory}
A path configuration file is a file whose name has the form
\file{\var{package}.pth} and exists in one of the four directories
mentioned above; its contents are additional items (one per line) to
be added to \code{sys.path}. Non-existing items are never added to
\code{sys.path}, but no check is made that the item refers to a
directory (rather than a file). No item is added to \code{sys.path}
more than once. Blank lines and lines beginning with \code{\#} are
skipped. Lines starting with \code{import} (followed by space or tab)
are executed.
\versionchanged[A space or tab is now required after the import
keyword]{2.6}
\index{package}
\indexiii{path}{configuration}{file}
For example, suppose \code{sys.prefix} and \code{sys.exec_prefix} are
set to \file{/usr/local}. The Python \version\ library is then
installed in \file{/usr/local/lib/python\shortversion} (where only the
first three characters of \code{sys.version} are used to form the
installation path name). Suppose this has a subdirectory
\file{/usr/local/lib/python\shortversion/site-packages} with three
subsubdirectories, \file{foo}, \file{bar} and \file{spam}, and two
path configuration files, \file{foo.pth} and \file{bar.pth}. Assume
\file{foo.pth} contains the following:
\begin{verbatim}
# foo package configuration
foo
bar
bletch
\end{verbatim}
and \file{bar.pth} contains:
\begin{verbatim}
# bar package configuration
bar
\end{verbatim}
Then the following directories are added to \code{sys.path}, in this
order:
\begin{verbatim}
/usr/local/lib/python2.3/site-packages/bar
/usr/local/lib/python2.3/site-packages/foo
\end{verbatim}
Note that \file{bletch} is omitted because it doesn't exist; the
\file{bar} directory precedes the \file{foo} directory because
\file{bar.pth} comes alphabetically before \file{foo.pth}; and
\file{spam} is omitted because it is not mentioned in either path
configuration file.
After these path manipulations, an attempt is made to import a module
named \module{sitecustomize}\refmodindex{sitecustomize}, which can
perform arbitrary site-specific customizations. If this import fails
with an \exception{ImportError} exception, it is silently ignored.
Note that for some non-\UNIX{} systems, \code{sys.prefix} and
\code{sys.exec_prefix} are empty, and the path manipulations are
skipped; however the import of
\module{sitecustomize}\refmodindex{sitecustomize} is still attempted.
|
