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 version-specific directories are added to
  66 ``sys.path``, in this order::
  67
  68    /usr/local/lib/pythonX.Y/site-packages/bar
  69    /usr/local/lib/pythonX.Y/site-packages/foo
  70
  71 Note that :file:`bletch` is omitted because it doesn't exist; the :file:`bar`
  72 directory precedes the :file:`foo` directory because :file:`bar.pth` comes
  73 alphabetically before :file:`foo.pth`; and :file:`spam` is omitted because it is
  74 not mentioned in either path configuration file.
  75
  76 .. index:: module: sitecustomize
  77
  78 After these path manipulations, an attempt is made to import a module named
  79 :mod:`sitecustomize`, which can perform arbitrary site-specific customizations.
  80 If this import fails with an :exc:`ImportError` exception, it is silently
  81 ignored.
  82
  83 .. index:: module: sitecustomize
  84
  85 Note that for some non-Unix systems, ``sys.prefix`` and ``sys.exec_prefix`` are
  86 empty, and the path manipulations are skipped; however the import of
  87 :mod:`sitecustomize` is still attempted.
  88
  89
  90 .. data:: PREFIXES
  91
  92    A list of prefixes for site package directories
  93
  94    .. versionadded:: 2.6
  95
  96
  97 .. data:: ENABLE_USER_SITE
  98
  99    Flag showing the status of the user site directory. True means the
 100    user site directory is enabled and added to sys.path. When the flag
 101    is None the user site directory is disabled for security reasons.
 102
 103    .. versionadded:: 2.6
 104
 105
 106 .. data:: USER_SITE
 107
 108    Path to the user site directory for the current Python version or None
 109
 110    .. versionadded:: 2.6
 111
 112
 113 .. data:: USER_BASE
 114
 115    Path to the base directory for user site directories
 116
 117    .. versionadded:: 2.6
 118
 119
 120 .. envvar:: PYTHONNOUSERSITE
 121
 122    .. versionadded:: 2.6
 123
 124
 125 .. envvar:: PYTHONUSERBASE
 126
 127    .. versionadded:: 2.6
 128
 129
 130 .. function:: addsitedir(sitedir, known_paths=None)
 131
 132    Adds a directory to sys.path and processes its pth files.
 133
 134 .. function:: getsitepackages()
 135
 136    Returns a list containing all global site-packages directories
 137    (and possibly site-python).
 138
 139    .. versionadded:: 2.7
 140
 141 .. function:: getuserbase()
 142
 143    Returns the `user base` directory path.
 144
 145    The `user base` directory can be used to store data. If the global
 146    variable ``USER_BASE`` is not initialized yet, this function will also set
 147    it.
 148
 149    .. versionadded:: 2.7
 150
 151 .. function:: getusersitepackages()
 152
 153    Returns the user-specific site-packages directory path.
 154
 155    If the global variable ``USER_SITE`` is not initialized yet, this
 156    function will also set it.
 157
 158    .. versionadded:: 2.7
 159
 160 .. XXX Update documentation
 161 .. XXX document python -m site --user-base --user-site
 162