Doc/library/site.rst

   1 :mod:`site` --- Site-specific configuration hook
   2 ================================================
   3
   4 .. module:: site
   5    :synopsis: Module responsible for site-specific configuration.
   6
   7 **Source code:** :source:`Lib/site.py`
   8
   9 --------------
  10
  11 .. highlightlang:: none
  12
  13 **This module is automatically imported during initialization.** The automatic
  14 import can be suppressed using the interpreter's :option:`-S` option.
  15
  16 .. index:: triple: module; search; path
  17
  18 Importing this module will append site-specific paths to the module search path
  19 and add a few builtins.
  20
  21 .. index::
  22    pair: site-python; directory
  23    pair: site-packages; directory
  24
  25 It starts by constructing up to four directories from a head and a tail part.
  26 For the head part, it uses ``sys.prefix`` and ``sys.exec_prefix``; empty heads
  27 are skipped.  For the tail part, it uses the empty string and then
  28 :file:`lib/site-packages` (on Windows) or
  29 :file:`lib/python|version|/site-packages` and then :file:`lib/site-python` (on
  30 Unix and Macintosh).  For each of the distinct head-tail combinations, it sees
  31 if it refers to an existing directory, and if so, adds it to ``sys.path`` and
  32 also inspects the newly added path for configuration files.
  33
  34 A path configuration file is a file whose name has the form :file:`{name}.pth`
  35 and exists in one of the four directories mentioned above; its contents are
  36 additional items (one per line) to be added to ``sys.path``.  Non-existing items
  37 are never added to ``sys.path``, and no check is made that the item refers to a
  38 directory rather than a file.  No item is added to ``sys.path`` more than
  39 once.  Blank lines and lines beginning with ``#`` are skipped.  Lines starting
  40 with ``import`` (followed by space or tab) are executed.
  41
  42 .. versionchanged:: 2.6
  43    A space or tab is now required after the import keyword.
  44
  45 .. index::
  46    single: package
  47    triple: path; configuration; file
  48
  49 For example, suppose ``sys.prefix`` and ``sys.exec_prefix`` are set to
  50 :file:`/usr/local`.  The Python X.Y library is then installed in
  51 :file:`/usr/local/lib/python{X.Y}`.  Suppose this has
  52 a subdirectory :file:`/usr/local/lib/python{X.Y}/site-packages` with three
  53 subsubdirectories, :file:`foo`, :file:`bar` and :file:`spam`, and two path
  54 configuration files, :file:`foo.pth` and :file:`bar.pth`.  Assume
  55 :file:`foo.pth` contains the following::
  56
  57    # foo package configuration
  58
  59    foo
  60    bar
  61    bletch
  62
  63 and :file:`bar.pth` contains::
  64
  65    # bar package configuration
  66
  67    bar
  68
  69 Then the following version-specific directories are added to
  70 ``sys.path``, in this order::
  71
  72    /usr/local/lib/pythonX.Y/site-packages/bar
  73    /usr/local/lib/pythonX.Y/site-packages/foo
  74
  75 Note that :file:`bletch` is omitted because it doesn't exist; the :file:`bar`
  76 directory precedes the :file:`foo` directory because :file:`bar.pth` comes
  77 alphabetically before :file:`foo.pth`; and :file:`spam` is omitted because it is
  78 not mentioned in either path configuration file.
  79
  80 .. index:: module: sitecustomize
  81
  82 After these path manipulations, an attempt is made to import a module named
  83 :mod:`sitecustomize`, which can perform arbitrary site-specific customizations.
  84 It is typically created by a system administrator in the site-packages
  85 directory.  If this import fails with an :exc:`ImportError` exception, it is
  86 silently ignored.
  87
  88 .. index:: module: usercustomize
  89
  90 After this, an attempt is made to import a module named :mod:`usercustomize`,
  91 which can perform arbitrary user-specific customizations, if
  92 :data:`ENABLE_USER_SITE` is true.  This file is intended to be created in the
  93 user site-packages directory (see below), which is part of ``sys.path`` unless
  94 disabled by :option:`-s`.  An :exc:`ImportError` will be silently ignored.
  95
  96 Note that for some non-Unix systems, ``sys.prefix`` and ``sys.exec_prefix`` are
  97 empty, and the path manipulations are skipped; however the import of
  98 :mod:`sitecustomize` and :mod:`usercustomize` is still attempted.
  99
 100
 101 .. data:: PREFIXES
 102
 103    A list of prefixes for site-packages directories.
 104
 105    .. versionadded:: 2.6
 106
 107
 108 .. data:: ENABLE_USER_SITE
 109
 110    Flag showing the status of the user site-packages directory.  ``True`` means
 111    that it is enabled and was added to ``sys.path``.  ``False`` means that it
 112    was disabled by user request (with :option:`-s` or
 113    :envvar:`PYTHONNOUSERSITE`).  ``None`` means it was disabled for security
 114    reasons (mismatch between user or group id and effective id) or by an
 115    administrator.
 116
 117    .. versionadded:: 2.6
 118
 119
 120 .. data:: USER_SITE
 121
 122    Path to the user site-packages for the running Python.  Can be ``None`` if
 123    :func:`getusersitepackages` hasn't been called yet.  Default value is
 124    :file:`~/.local/lib/python{X.Y}/site-packages` for UNIX and non-framework Mac
 125    OS X builds, :file:`~/Library/Python/{X.Y}/lib/python/site-packages` for Mac
 126    framework builds, and :file:`{%APPDATA%}\\Python\\Python{XY}\\site-packages`
 127    on Windows.  This directory is a site directory, which means that
 128    :file:`.pth` files in it will be processed.
 129
 130    .. versionadded:: 2.6
 131
 132
 133 .. data:: USER_BASE
 134
 135    Path to the base directory for the user site-packages.  Can be ``None`` if
 136    :func:`getuserbase` hasn't been called yet.  Default value is
 137    :file:`~/.local` for UNIX and Mac OS X non-framework builds,
 138    :file:`~/Library/Python/{X.Y}` for Mac framework builds, and
 139    :file:`{%APPDATA%}\\Python` for Windows.  This value is used by Distutils to
 140    compute the installation directories for scripts, data files, Python modules,
 141    etc. for the :ref:`user installation scheme <inst-alt-install-user>`.  See
 142    also :envvar:`PYTHONUSERBASE`.
 143
 144    .. versionadded:: 2.6
 145
 146
 147 .. function:: addsitedir(sitedir, known_paths=None)
 148
 149    Add a directory to sys.path and process its :file:`.pth` files.  Typically
 150    used in :mod:`sitecustomize` or :mod:`usercustomize` (see above).
 151
 152
 153 .. function:: getsitepackages()
 154
 155    Return a list containing all global site-packages directories (and possibly
 156    site-python).
 157
 158    .. versionadded:: 2.7
 159
 160
 161 .. function:: getuserbase()
 162
 163    Return the path of the user base directory, :data:`USER_BASE`.  If it is not
 164    initialized yet, this function will also set it, respecting
 165    :envvar:`PYTHONUSERBASE`.
 166
 167    .. versionadded:: 2.7
 168
 169
 170 .. function:: getusersitepackages()
 171
 172    Return the path of the user-specific site-packages directory,
 173    :data:`USER_SITE`.  If it is not initialized yet, this function will also set
 174    it, respecting :envvar:`PYTHONNOUSERSITE` and :data:`USER_BASE`.
 175
 176    .. versionadded:: 2.7
 177
 178
 179 The :mod:`site` module also provides a way to get the user directories from the
 180 command line:
 181
 182 .. code-block:: sh
 183
 184    $ python3 -m site --user-site
 185    /home/user/.local/lib/python3.3/site-packages
 186
 187 .. program:: site
 188
 189 If it is called without arguments, it will print the contents of
 190 :data:`sys.path` on the standard output, followed by the value of
 191 :data:`USER_BASE` and whether the directory exists, then the same thing for
 192 :data:`USER_SITE`, and finally the value of :data:`ENABLE_USER_SITE`.
 193
 194 .. cmdoption:: --user-base
 195
 196    Print the path to the user base directory.
 197
 198 .. cmdoption:: --user-site
 199
 200    Print the path to the user site-packages directory.
 201
 202 If both options are given, user base and user site will be printed (always in
 203 this order), separated by :data:`os.pathsep`.
 204
 205 If any option is given, the script will exit with one of these values: ``O`` if
 206 the user site-packages directory is enabled, ``1`` if it was disabled by the
 207 user, ``2`` if it is disabled for security reasons or by an administrator, and a
 208 value greater than 2 if there is an error.
 209
 210 .. seealso::
 211
 212    :pep:`370` -- Per user site-packages directory