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.. highlight:: 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, unless :option:`-S` was used. In that case, this module 20can be safely imported with no automatic modifications to the module search path 21or additions to the builtins. To explicitly trigger the usual site-specific 22additions, call the :func:`site.main` function. 23 24.. versionchanged:: 3.3 25 Importing the module used to trigger paths manipulation even when using 26 :option:`-S`. 27 28.. index:: 29 pair: site-packages; directory 30 31It starts by constructing up to four directories from a head and a tail part. 32For the head part, it uses ``sys.prefix`` and ``sys.exec_prefix``; empty heads 33are skipped. For the tail part, it uses the empty string and then 34:file:`lib/site-packages` (on Windows) or 35:file:`lib/python{X.Y}/site-packages` (on Unix and Macintosh). For each 36of the distinct head-tail combinations, it sees if it refers to an existing 37directory, and if so, adds it to ``sys.path`` and also inspects the newly 38added path for configuration files. 39 40.. versionchanged:: 3.5 41 Support for the "site-python" directory has been removed. 42 43If a file named "pyvenv.cfg" exists one directory above sys.executable, 44sys.prefix and sys.exec_prefix are set to that directory and 45it is also checked for site-packages (sys.base_prefix and 46sys.base_exec_prefix will always be the "real" prefixes of the Python 47installation). If "pyvenv.cfg" (a bootstrap configuration file) contains 48the key "include-system-site-packages" set to anything other than "true" 49(case-insensitive), the system-level prefixes will not be 50searched for site-packages; otherwise they will. 51 52.. index:: 53 single: # (hash); comment 54 statement: import 55 56A path configuration file is a file whose name has the form :file:`{name}.pth` 57and exists in one of the four directories mentioned above; its contents are 58additional items (one per line) to be added to ``sys.path``. Non-existing items 59are never added to ``sys.path``, and no check is made that the item refers to a 60directory rather than a file. No item is added to ``sys.path`` more than 61once. Blank lines and lines beginning with ``#`` are skipped. Lines starting 62with ``import`` (followed by space or tab) are executed. 63 64.. note:: 65 66 An executable line in a :file:`.pth` file is run at every Python startup, 67 regardless of whether a particular module is actually going to be used. 68 Its impact should thus be kept to a minimum. 69 The primary intended purpose of executable lines is to make the 70 corresponding module(s) importable 71 (load 3rd-party import hooks, adjust :envvar:`PATH` etc). 72 Any other initialization is supposed to be done upon a module's 73 actual import, if and when it happens. 74 Limiting a code chunk to a single line is a deliberate measure 75 to discourage putting anything more complex here. 76 77.. index:: 78 single: package 79 triple: path; configuration; file 80 81For example, suppose ``sys.prefix`` and ``sys.exec_prefix`` are set to 82:file:`/usr/local`. The Python X.Y library is then installed in 83:file:`/usr/local/lib/python{X.Y}`. Suppose this has 84a subdirectory :file:`/usr/local/lib/python{X.Y}/site-packages` with three 85subsubdirectories, :file:`foo`, :file:`bar` and :file:`spam`, and two path 86configuration files, :file:`foo.pth` and :file:`bar.pth`. Assume 87:file:`foo.pth` contains the following:: 88 89 # foo package configuration 90 91 foo 92 bar 93 bletch 94 95and :file:`bar.pth` contains:: 96 97 # bar package configuration 98 99 bar 100 101Then the following version-specific directories are added to 102``sys.path``, in this order:: 103 104 /usr/local/lib/pythonX.Y/site-packages/bar 105 /usr/local/lib/pythonX.Y/site-packages/foo 106 107Note that :file:`bletch` is omitted because it doesn't exist; the :file:`bar` 108directory precedes the :file:`foo` directory because :file:`bar.pth` comes 109alphabetically before :file:`foo.pth`; and :file:`spam` is omitted because it is 110not mentioned in either path configuration file. 111 112.. index:: module: sitecustomize 113 114After these path manipulations, an attempt is made to import a module named 115:mod:`sitecustomize`, which can perform arbitrary site-specific customizations. 116It is typically created by a system administrator in the site-packages 117directory. If this import fails with an :exc:`ImportError` or its subclass 118exception, and the exception's :attr:`name` attribute equals to ``'sitecustomize'``, 119it is silently ignored. If Python is started without output streams available, as 120with :file:`pythonw.exe` on Windows (which is used by default to start IDLE), 121attempted output from :mod:`sitecustomize` is ignored. Any other exception 122causes a silent and perhaps mysterious failure of the process. 123 124.. index:: module: usercustomize 125 126After this, an attempt is made to import a module named :mod:`usercustomize`, 127which can perform arbitrary user-specific customizations, if 128:data:`ENABLE_USER_SITE` is true. This file is intended to be created in the 129user site-packages directory (see below), which is part of ``sys.path`` unless 130disabled by :option:`-s`. If this import fails with an :exc:`ImportError` or 131its subclass exception, and the exception's :attr:`name` attribute equals to 132``'usercustomize'``, it is silently ignored. 133 134Note that for some non-Unix systems, ``sys.prefix`` and ``sys.exec_prefix`` are 135empty, and the path manipulations are skipped; however the import of 136:mod:`sitecustomize` and :mod:`usercustomize` is still attempted. 137 138 139.. _rlcompleter-config: 140 141Readline configuration 142---------------------- 143 144On systems that support :mod:`readline`, this module will also import and 145configure the :mod:`rlcompleter` module, if Python is started in 146:ref:`interactive mode <tut-interactive>` and without the :option:`-S` option. 147The default behavior is enable tab-completion and to use 148:file:`~/.python_history` as the history save file. To disable it, delete (or 149override) the :data:`sys.__interactivehook__` attribute in your 150:mod:`sitecustomize` or :mod:`usercustomize` module or your 151:envvar:`PYTHONSTARTUP` file. 152 153.. versionchanged:: 3.4 154 Activation of rlcompleter and history was made automatic. 155 156 157Module contents 158--------------- 159 160.. data:: PREFIXES 161 162 A list of prefixes for site-packages directories. 163 164 165.. data:: ENABLE_USER_SITE 166 167 Flag showing the status of the user site-packages directory. ``True`` means 168 that it is enabled and was added to ``sys.path``. ``False`` means that it 169 was disabled by user request (with :option:`-s` or 170 :envvar:`PYTHONNOUSERSITE`). ``None`` means it was disabled for security 171 reasons (mismatch between user or group id and effective id) or by an 172 administrator. 173 174 175.. data:: USER_SITE 176 177 Path to the user site-packages for the running Python. Can be ``None`` if 178 :func:`getusersitepackages` hasn't been called yet. Default value is 179 :file:`~/.local/lib/python{X.Y}/site-packages` for UNIX and non-framework Mac 180 OS X builds, :file:`~/Library/Python/{X.Y}/lib/python/site-packages` for Mac 181 framework builds, and :file:`{%APPDATA%}\\Python\\Python{XY}\\site-packages` 182 on Windows. This directory is a site directory, which means that 183 :file:`.pth` files in it will be processed. 184 185 186.. data:: USER_BASE 187 188 Path to the base directory for the user site-packages. Can be ``None`` if 189 :func:`getuserbase` hasn't been called yet. Default value is 190 :file:`~/.local` for UNIX and Mac OS X non-framework builds, 191 :file:`~/Library/Python/{X.Y}` for Mac framework builds, and 192 :file:`{%APPDATA%}\\Python` for Windows. This value is used by Distutils to 193 compute the installation directories for scripts, data files, Python modules, 194 etc. for the :ref:`user installation scheme <inst-alt-install-user>`. 195 See also :envvar:`PYTHONUSERBASE`. 196 197 198.. function:: main() 199 200 Adds all the standard site-specific directories to the module search 201 path. This function is called automatically when this module is imported, 202 unless the Python interpreter was started with the :option:`-S` flag. 203 204 .. versionchanged:: 3.3 205 This function used to be called unconditionally. 206 207 208.. function:: addsitedir(sitedir, known_paths=None) 209 210 Add a directory to sys.path and process its :file:`.pth` files. Typically 211 used in :mod:`sitecustomize` or :mod:`usercustomize` (see above). 212 213 214.. function:: getsitepackages() 215 216 Return a list containing all global site-packages directories. 217 218 .. versionadded:: 3.2 219 220 221.. function:: getuserbase() 222 223 Return the path of the user base directory, :data:`USER_BASE`. If it is not 224 initialized yet, this function will also set it, respecting 225 :envvar:`PYTHONUSERBASE`. 226 227 .. versionadded:: 3.2 228 229 230.. function:: getusersitepackages() 231 232 Return the path of the user-specific site-packages directory, 233 :data:`USER_SITE`. If it is not initialized yet, this function will also set 234 it, respecting :data:`USER_BASE`. To determine if the user-specific 235 site-packages was added to ``sys.path`` :data:`ENABLE_USER_SITE` should be 236 used. 237 238 .. versionadded:: 3.2 239 240 241.. _site-commandline: 242 243Command Line Interface 244---------------------- 245 246.. program:: site 247 248The :mod:`site` module also provides a way to get the user directories from the 249command line: 250 251.. code-block:: shell-session 252 253 $ python3 -m site --user-site 254 /home/user/.local/lib/python3.3/site-packages 255 256If it is called without arguments, it will print the contents of 257:data:`sys.path` on the standard output, followed by the value of 258:data:`USER_BASE` and whether the directory exists, then the same thing for 259:data:`USER_SITE`, and finally the value of :data:`ENABLE_USER_SITE`. 260 261.. cmdoption:: --user-base 262 263 Print the path to the user base directory. 264 265.. cmdoption:: --user-site 266 267 Print the path to the user site-packages directory. 268 269If both options are given, user base and user site will be printed (always in 270this order), separated by :data:`os.pathsep`. 271 272If any option is given, the script will exit with one of these values: ``0`` if 273the user site-packages directory is enabled, ``1`` if it was disabled by the 274user, ``2`` if it is disabled for security reasons or by an administrator, and a 275value greater than 2 if there is an error. 276 277.. seealso:: 278 279 :pep:`370` -- Per user site-packages directory 280