blob: 43fad3c181461f76b92860d9936a7037d3d482ad [file] [log] [blame]
\section{Standard Module \sectcode{site}}
\label{module-site}
\stmodindex{site}
\strong{This module is automatically imported during initialization.}
In earlier versions of Python (up to and including 1.5a3), scripts or
modules that needed to use site-specific modules would place
\code{import site} somewhere near the top of their code. This is no
longer necessary.
This will append site-specific paths to to the 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 (on Mac or Windows) or it uses
first \file{lib/python\var{version}/site-packages} and then
\file{lib/site-python} (on Unix). For each of the distinct head-tail
combinations, it sees if it refers to an existing directory, and if
so, adds to \code{sys.path}, and also inspected for path 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}; 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.
\index{package}
\indexiii{path}{configuration}{file}
\kwindex{sys.prefix}
\kwindex{sys.exec_prefix}
\kwindex{prefix}
\kwindex{exec_prefix}
For example, suppose \code{sys.prefix} and \code{sys.exec_prefix} are
set to \file{/usr/local}. The Python 1.5 library is then installed in
\file{/usr/local/lib/python1.5}. Suppose this has a subdirectory
\file{/usr/local/python1.5/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:
\bcode\begin{verbatim}
# foo package configuration
foo
bar
bletch
\end{verbatim}\ecode
and \file{bar.pth} contains:
\bcode\begin{verbatim}
# bar package configuration
bar
\end{verbatim}\ecode
Then the following directories are added to sys.path, in this order:
\bcode\begin{verbatim}
/usr/local/python1.5/site-packages/bar
/usr/local/python1.5/site-packages/foo
\end{verbatim}\ecode
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 \code{sitecustomize}, which can perform arbitrary site-specific
customizations. If this import fails with an \code{ImportError}
exception, it is silently ignored.
\stmodindex{sitecustomize}
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 \code{sitecustomize} is still attempted.