| \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}/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{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/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/packages/bar |
| /usr/local/python1.5/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. |