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