Doc/library/site.rst

   1
   2 :mod:`site` --- Site-specific configuration hook
   3 ================================================
   4
   5 .. module:: site
   6    :synopsis: A standard way to reference site-specific modules.
   7
   8
   9 **This module is automatically imported during initialization.** The automatic
  10 import can be suppressed using the interpreter's :option:`-S` option.
  11
  12 .. index:: triple: module; search; path
  13
  14 Importing this module will append site-specific paths to the module search path.
  15
  16 .. index::
  17    pair: site-python; directory
  18    pair: site-packages; directory
  19
  20 It starts by constructing up to four directories from a head and a tail part.
  21 For the head part, it uses ``sys.prefix`` and ``sys.exec_prefix``; empty heads
  22 are skipped.  For the tail part, it uses the empty string and then
  23 :file:`lib/site-packages` (on Windows) or
  24 :file:`lib/python|version|/site-packages` and then :file:`lib/site-python` (on
  25 Unix and Macintosh).  For each of the distinct head-tail combinations, it sees
  26 if it refers to an existing directory, and if so, adds it to ``sys.path`` and
  27 also inspects the newly added path for configuration files.
  28
  29 A path configuration file is a file whose name has the form :file:`package.pth`
  30 and exists in one of the four directories mentioned above; its contents are
  31 additional items (one per line) to be added to ``sys.path``.  Non-existing items
  32 are never added to ``sys.path``, but no check is made that the item refers to a
  33 directory (rather than a file).  No item is added to ``sys.path`` more than
  34 once.  Blank lines and lines beginning with ``#`` are skipped.  Lines starting
  35 with ``import`` (followed by space or tab) are executed.
  36
  37 .. versionchanged:: 2.6
  38    A space or tab is now required after the import keyword.
  39
  40 .. index::
  41    single: package
  42    triple: path; configuration; file
  43
  44 For example, suppose ``sys.prefix`` and ``sys.exec_prefix`` are set to
  45 :file:`/usr/local`.  The Python X.Y library is then installed in
  46 :file:`/usr/local/lib/python{X.Y}` (where only the first three characters of
  47 ``sys.version`` are used to form the installation path name).  Suppose this has
  48 a subdirectory :file:`/usr/local/lib/python{X.Y}/site-packages` with three
  49 subsubdirectories, :file:`foo`, :file:`bar` and :file:`spam`, and two path
  50 configuration files, :file:`foo.pth` and :file:`bar.pth`.  Assume
  51 :file:`foo.pth` contains the following::
  52
  53    # foo package configuration
  54
  55    foo
  56    bar
  57    bletch
  58
  59 and :file:`bar.pth` contains::
  60
  61    # bar package configuration
  62
  63    bar
  64
  65 Then the following directories are added to ``sys.path``, in this order::
  66
  67    /usr/local/lib/python2.3/site-packages/bar
  68    /usr/local/lib/python2.3/site-packages/foo
  69
  70 Note that :file:`bletch` is omitted because it doesn't exist; the :file:`bar`
  71 directory precedes the :file:`foo` directory because :file:`bar.pth` comes
  72 alphabetically before :file:`foo.pth`; and :file:`spam` is omitted because it is
  73 not mentioned in either path configuration file.
  74
  75 .. index:: module: sitecustomize
  76
  77 After these path manipulations, an attempt is made to import a module named
  78 :mod:`sitecustomize`, which can perform arbitrary site-specific customizations.
  79 If this import fails with an :exc:`ImportError` exception, it is silently
  80 ignored.
  81
  82 .. index:: module: sitecustomize
  83
  84 Note that for some non-Unix systems, ``sys.prefix`` and ``sys.exec_prefix`` are
  85 empty, and the path manipulations are skipped; however the import of
  86 :mod:`sitecustomize` is still attempted.
  87
  88
  89 .. data:: PREFIXES
  90
  91    A list of prefixes for site package directories
  92
  93    .. versionadded:: 2.6
  94
  95
  96 .. data:: ENABLE_USER_SITE
  97
  98    Flag showing the status of the user site directory. True means the
  99    user site directory is enabled and added to sys.path. When the flag
 100    is None the user site directory is disabled for security reasons.
 101
 102    .. versionadded:: 2.6
 103
 104
 105 .. data:: USER_SITE
 106
 107    Path to the user site directory for the current Python version or None
 108
 109    .. versionadded:: 2.6
 110
 111
 112 .. data:: USER_BASE
 113
 114    Path to the base directory for user site directories
 115
 116    .. versionadded:: 2.6
 117
 118
 119 .. envvar:: PYTHONNOUSERSITE
 120
 121    .. versionadded:: 2.6
 122
 123
 124 .. envvar:: PYTHONUSERBASE
 125
 126    .. versionadded:: 2.6
 127
 128
 129 .. function:: addsitedir(sitedir, known_paths=None)
 130
 131    Adds a directory to sys.path and processes its pth files.
 132
 133
 134 XXX Update documentation
 135 XXX document python -m site --user-base --user-site