ref: 1fe3143e4c43ce2c74e0cfdd70b1bd556bbb9e1b
dir: /sys/src/cmd/python/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.} The automatic import can be suppressed using the interpreter's \programopt{-S} option. Importing this module 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 and then \file{lib/site-packages} (on Windows) or \file{lib/python\shortversion/site-packages} and then \file{lib/site-python} (on \UNIX{} and Macintosh). For each of the distinct head-tail combinations, it sees if it refers to an existing directory, and if so, adds it to \code{sys.path} and also inspects the newly added 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} and exists in one of the four directories mentioned above; 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/python2.3/site-packages/bar /usr/local/lib/python2.3/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.