Doc/lib/libsite.tex

   1 \section{\module{site} ---
   2          Site-specific configuration hook}
   3
   4 \declaremodule{standard}{site}
   5 \modulesynopsis{A standard way to reference site-specific modules.}
   6
   7
   8 \strong{This module is automatically imported during initialization.}
   9
  10 In earlier versions of Python (up to and including 1.5a3), scripts or
  11 modules that needed to use site-specific modules would place
  12 \samp{import site} somewhere near the top of their code.  This is no
  13 longer necessary.
  14
  15 This will append site-specific paths to the module search path.
  16 \indexiii{module}{search}{path}
  17
  18 It starts by constructing up to four directories from a head and a
  19 tail part.  For the head part, it uses \code{sys.prefix} and
  20 \code{sys.exec_prefix}; empty heads are skipped.  For
  21 the tail part, it uses the empty string (on Macintosh or Windows) or
  22 it uses first \file{lib/python\shortversion/site-packages} and then
  23 \file{lib/site-python} (on \UNIX{}).  For each of the distinct
  24 head-tail combinations, it sees if it refers to an existing directory,
  25 and if so, adds to \code{sys.path}, and also inspects the path for
  26 configuration files.
  27 \indexii{site-python}{directory}
  28 \indexii{site-packages}{directory}
  29
  30 A path configuration file is a file whose name has the form
  31 \file{\var{package}.pth}; its contents are additional items (one
  32 per line) to be added to \code{sys.path}.  Non-existing items are
  33 never added to \code{sys.path}, but no check is made that the item
  34 refers to a directory (rather than a file).  No item is added to
  35 \code{sys.path} more than once.  Blank lines and lines beginning with
  36 \code{\#} are skipped.  Lines starting with \code{import} are executed.
  37 \index{package}
  38 \indexiii{path}{configuration}{file}
  39
  40 For example, suppose \code{sys.prefix} and \code{sys.exec_prefix} are
  41 set to \file{/usr/local}.  The Python \version\ library is then
  42 installed in \file{/usr/local/lib/python\shortversion} (where only the
  43 first three characters of \code{sys.version} are used to form the
  44 installation path name).  Suppose this has a subdirectory
  45 \file{/usr/local/lib/python\shortversion/site-packages} with three
  46 subsubdirectories, \file{foo}, \file{bar} and \file{spam}, and two
  47 path configuration files, \file{foo.pth} and \file{bar.pth}.  Assume
  48 \file{foo.pth} contains the following:
  49
  50 \begin{verbatim}
  51 # foo package configuration
  52
  53 foo
  54 bar
  55 bletch
  56 \end{verbatim}
  57
  58 and \file{bar.pth} contains:
  59
  60 \begin{verbatim}
  61 # bar package configuration
  62
  63 bar
  64 \end{verbatim}
  65
  66 Then the following directories are added to \code{sys.path}, in this
  67 order:
  68
  69 \begin{verbatim}
  70 /usr/local/lib/python1.5/site-packages/bar
  71 /usr/local/lib/python1.5/site-packages/foo
  72 \end{verbatim}
  73
  74 Note that \file{bletch} is omitted because it doesn't exist; the
  75 \file{bar} directory precedes the \file{foo} directory because
  76 \file{bar.pth} comes alphabetically before \file{foo.pth}; and
  77 \file{spam} is omitted because it is not mentioned in either path
  78 configuration file.
  79
  80 After these path manipulations, an attempt is made to import a module
  81 named \module{sitecustomize}\refmodindex{sitecustomize}, which can
  82 perform arbitrary site-specific customizations.  If this import fails
  83 with an \exception{ImportError} exception, it is silently ignored.
  84
  85 Note that for some non-\UNIX{} systems, \code{sys.prefix} and
  86 \code{sys.exec_prefix} are empty, and the path manipulations are
  87 skipped; however the import of
  88 \module{sitecustomize}\refmodindex{sitecustomize} is still attempted.