1998-08-10 16:42:37 -03:00
|
|
|
\section{\module{site} ---
|
1999-02-19 20:14:17 -04:00
|
|
|
Site-specific configuration hook}
|
1998-07-23 14:59:49 -03:00
|
|
|
|
1999-02-19 20:14:17 -04:00
|
|
|
\declaremodule{standard}{site}
|
1998-07-23 14:59:49 -03:00
|
|
|
\modulesynopsis{A standard way to reference site-specific modules.}
|
|
|
|
|
1997-04-03 18:41:49 -04:00
|
|
|
|
1997-08-30 17:03:28 -03:00
|
|
|
\strong{This module is automatically imported during initialization.}
|
2003-12-30 18:51:32 -04:00
|
|
|
The automatic import can be suppressed using the interpreter's
|
|
|
|
\programopt{-S} option.
|
1997-08-30 17:03:28 -03:00
|
|
|
|
2003-12-30 18:51:32 -04:00
|
|
|
Importing this module will append site-specific paths to the module
|
|
|
|
search path.
|
1998-01-13 14:34:40 -04:00
|
|
|
\indexiii{module}{search}{path}
|
1997-09-03 19:05:54 -03:00
|
|
|
|
|
|
|
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
|
2005-02-13 18:50:04 -04:00
|
|
|
the tail part, it uses the empty string (on Windows) or
|
2005-08-24 04:31:33 -03:00
|
|
|
\file{lib/python\shortversion/site-packages} (on \UNIX{} and Macintosh)
|
|
|
|
and then \file{lib/site-python}. For each of the distinct
|
1998-01-13 14:34:40 -04:00
|
|
|
head-tail combinations, it sees if it refers to an existing directory,
|
2002-12-29 23:08:27 -04:00
|
|
|
and if so, adds it to \code{sys.path} and also inspects the newly added
|
|
|
|
path for configuration files.
|
1997-09-03 19:05:54 -03:00
|
|
|
\indexii{site-python}{directory}
|
1997-09-07 23:02:37 -03:00
|
|
|
\indexii{site-packages}{directory}
|
1997-09-03 19:05:54 -03:00
|
|
|
|
|
|
|
A path configuration file is a file whose name has the form
|
2004-03-20 17:41:28 -04:00
|
|
|
\file{\var{package}.pth} and exists in one of the four directories
|
|
|
|
mentioned above; its contents are additional items (one
|
1997-09-03 19:05:54 -03:00
|
|
|
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
|
1997-08-30 17:03:28 -03:00
|
|
|
\code{sys.path} more than once. Blank lines and lines beginning with
|
2001-01-11 18:07:25 -04:00
|
|
|
\code{\#} are skipped. Lines starting with \code{import} are executed.
|
1997-08-30 17:03:28 -03:00
|
|
|
\index{package}
|
1997-09-03 19:05:54 -03:00
|
|
|
\indexiii{path}{configuration}{file}
|
1997-08-30 17:03:28 -03:00
|
|
|
|
|
|
|
For example, suppose \code{sys.prefix} and \code{sys.exec_prefix} are
|
1998-02-16 16:58:58 -04:00
|
|
|
set to \file{/usr/local}. The Python \version\ library is then
|
2000-09-14 17:24:17 -03:00
|
|
|
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
|
1998-02-16 16:58:58 -04:00
|
|
|
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:
|
1997-08-30 17:03:28 -03:00
|
|
|
|
1998-02-13 02:58:54 -04:00
|
|
|
\begin{verbatim}
|
1997-08-30 17:03:28 -03:00
|
|
|
# foo package configuration
|
|
|
|
|
|
|
|
foo
|
|
|
|
bar
|
|
|
|
bletch
|
1998-02-13 02:58:54 -04:00
|
|
|
\end{verbatim}
|
1997-08-30 17:03:28 -03:00
|
|
|
|
|
|
|
and \file{bar.pth} contains:
|
|
|
|
|
1998-02-13 02:58:54 -04:00
|
|
|
\begin{verbatim}
|
1997-08-30 17:03:28 -03:00
|
|
|
# bar package configuration
|
|
|
|
|
|
|
|
bar
|
1998-02-13 02:58:54 -04:00
|
|
|
\end{verbatim}
|
1997-08-30 17:03:28 -03:00
|
|
|
|
1998-01-13 14:34:40 -04:00
|
|
|
Then the following directories are added to \code{sys.path}, in this
|
|
|
|
order:
|
1997-08-30 17:03:28 -03:00
|
|
|
|
1998-02-13 02:58:54 -04:00
|
|
|
\begin{verbatim}
|
2002-02-18 22:58:54 -04:00
|
|
|
/usr/local/lib/python2.3/site-packages/bar
|
|
|
|
/usr/local/lib/python2.3/site-packages/foo
|
1998-02-13 02:58:54 -04:00
|
|
|
\end{verbatim}
|
1997-08-30 17:03:28 -03:00
|
|
|
|
|
|
|
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.
|
1997-04-03 18:41:49 -04:00
|
|
|
|
|
|
|
After these path manipulations, an attempt is made to import a module
|
1998-03-08 03:09:19 -04:00
|
|
|
named \module{sitecustomize}\refmodindex{sitecustomize}, which can
|
1998-01-13 14:34:40 -04:00
|
|
|
perform arbitrary site-specific customizations. If this import fails
|
1998-03-08 03:09:19 -04:00
|
|
|
with an \exception{ImportError} exception, it is silently ignored.
|
1997-04-03 18:41:49 -04:00
|
|
|
|
1998-01-13 14:34:40 -04:00
|
|
|
Note that for some non-\UNIX{} systems, \code{sys.prefix} and
|
1997-04-03 18:41:49 -04:00
|
|
|
\code{sys.exec_prefix} are empty, and the path manipulations are
|
1998-01-13 14:34:40 -04:00
|
|
|
skipped; however the import of
|
1998-03-08 03:09:19 -04:00
|
|
|
\module{sitecustomize}\refmodindex{sitecustomize} is still attempted.
|