cpython/Doc/lib/libsite.tex

\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.}

In earlier versions of Python (up to and including 1.5a3), scripts or
modules that needed to use site-specific modules would place
\samp{import site} somewhere near the top of their code.  This is no
longer necessary.

This 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 (on Macintosh or Windows) or
it uses first \file{lib/python\shortversion/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 inspects the 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}; 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} are executed.
\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/python1.5/site-packages/bar
/usr/local/lib/python1.5/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.