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