Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1 | :mod:`site` --- Site-specific configuration hook |
| 2 | ================================================ |
| 3 | |
| 4 | .. module:: site |
Éric Araujo | de4f05b | 2011-08-06 01:51:07 +0200 | [diff] [blame] | 5 | :synopsis: Module responsible for site-specific configuration. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 6 | |
Raymond Hettinger | 469271d | 2011-01-27 20:38:46 +0000 | [diff] [blame] | 7 | **Source code:** :source:`Lib/site.py` |
| 8 | |
| 9 | -------------- |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 10 | |
Éric Araujo | de4f05b | 2011-08-06 01:51:07 +0200 | [diff] [blame] | 11 | .. highlightlang:: none |
| 12 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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 | |
Éric Araujo | de4f05b | 2011-08-06 01:51:07 +0200 | [diff] [blame] | 18 | Importing this module will append site-specific paths to the module search path |
Éric Araujo | 7dc76fd | 2011-08-06 16:58:15 +0200 | [diff] [blame] | 19 | and add a few builtins, unless :option:`-S` was used. In that case, this module |
| 20 | can be safely imported with no automatic modifications to the module search path |
| 21 | or additions to the builtins. To explicitly trigger the usual site-specific |
| 22 | additions, call the :func:`site.main` function. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 23 | |
Éric Araujo | b173451 | 2011-04-24 03:15:32 +0200 | [diff] [blame] | 24 | .. versionchanged:: 3.3 |
| 25 | Importing the module used to trigger paths manipulation even when using |
| 26 | :option:`-S`. |
| 27 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 28 | .. index:: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 29 | pair: site-packages; directory |
| 30 | |
| 31 | It starts by constructing up to four directories from a head and a tail part. |
| 32 | For the head part, it uses ``sys.prefix`` and ``sys.exec_prefix``; empty heads |
| 33 | are skipped. For the tail part, it uses the empty string and then |
| 34 | :file:`lib/site-packages` (on Windows) or |
Antoine Pitrou | 9e82b17 | 2014-06-12 19:41:30 -0400 | [diff] [blame] | 35 | :file:`lib/python{X.Y}/site-packages` (on Unix and Macintosh). For each |
| 36 | of the distinct head-tail combinations, it sees if it refers to an existing |
| 37 | directory, and if so, adds it to ``sys.path`` and also inspects the newly |
| 38 | added path for configuration files. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 39 | |
Antoine Pitrou | 9e82b17 | 2014-06-12 19:41:30 -0400 | [diff] [blame] | 40 | .. versionchanged:: 3.5 |
| 41 | Support for the "site-python" directory has been removed. |
Antoine Pitrou | 3b2f0f0 | 2013-10-25 21:39:26 +0200 | [diff] [blame] | 42 | |
Vinay Sajip | abd344c | 2012-07-03 16:33:57 +0100 | [diff] [blame] | 43 | If a file named "pyvenv.cfg" exists one directory above sys.executable, |
| 44 | sys.prefix and sys.exec_prefix are set to that directory and |
Antoine Pitrou | 9e82b17 | 2014-06-12 19:41:30 -0400 | [diff] [blame] | 45 | it is also checked for site-packages (sys.base_prefix and |
Vinay Sajip | abd344c | 2012-07-03 16:33:57 +0100 | [diff] [blame] | 46 | sys.base_exec_prefix will always be the "real" prefixes of the Python |
| 47 | installation). If "pyvenv.cfg" (a bootstrap configuration file) contains |
| 48 | the key "include-system-site-packages" set to anything other than "false" |
| 49 | (case-insensitive), the system-level prefixes will still also be |
| 50 | searched for site-packages; otherwise they won't. |
| 51 | |
Éric Araujo | de4f05b | 2011-08-06 01:51:07 +0200 | [diff] [blame] | 52 | A path configuration file is a file whose name has the form :file:`{name}.pth` |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 53 | and exists in one of the four directories mentioned above; its contents are |
| 54 | additional items (one per line) to be added to ``sys.path``. Non-existing items |
Éric Araujo | de4f05b | 2011-08-06 01:51:07 +0200 | [diff] [blame] | 55 | are never added to ``sys.path``, and no check is made that the item refers to a |
| 56 | directory rather than a file. No item is added to ``sys.path`` more than |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 57 | once. Blank lines and lines beginning with ``#`` are skipped. Lines starting |
| 58 | with ``import`` (followed by space or tab) are executed. |
| 59 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 60 | .. index:: |
| 61 | single: package |
| 62 | triple: path; configuration; file |
| 63 | |
| 64 | For example, suppose ``sys.prefix`` and ``sys.exec_prefix`` are set to |
| 65 | :file:`/usr/local`. The Python X.Y library is then installed in |
Éric Araujo | de4f05b | 2011-08-06 01:51:07 +0200 | [diff] [blame] | 66 | :file:`/usr/local/lib/python{X.Y}`. Suppose this has |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 67 | a subdirectory :file:`/usr/local/lib/python{X.Y}/site-packages` with three |
| 68 | subsubdirectories, :file:`foo`, :file:`bar` and :file:`spam`, and two path |
| 69 | configuration files, :file:`foo.pth` and :file:`bar.pth`. Assume |
| 70 | :file:`foo.pth` contains the following:: |
| 71 | |
| 72 | # foo package configuration |
| 73 | |
| 74 | foo |
| 75 | bar |
| 76 | bletch |
| 77 | |
| 78 | and :file:`bar.pth` contains:: |
| 79 | |
| 80 | # bar package configuration |
| 81 | |
| 82 | bar |
| 83 | |
Benjamin Peterson | e9bbc8b | 2008-09-28 02:06:32 +0000 | [diff] [blame] | 84 | Then the following version-specific directories are added to |
| 85 | ``sys.path``, in this order:: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 86 | |
Benjamin Peterson | e9bbc8b | 2008-09-28 02:06:32 +0000 | [diff] [blame] | 87 | /usr/local/lib/pythonX.Y/site-packages/bar |
| 88 | /usr/local/lib/pythonX.Y/site-packages/foo |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 89 | |
| 90 | Note that :file:`bletch` is omitted because it doesn't exist; the :file:`bar` |
| 91 | directory precedes the :file:`foo` directory because :file:`bar.pth` comes |
| 92 | alphabetically before :file:`foo.pth`; and :file:`spam` is omitted because it is |
| 93 | not mentioned in either path configuration file. |
| 94 | |
| 95 | .. index:: module: sitecustomize |
| 96 | |
| 97 | After these path manipulations, an attempt is made to import a module named |
| 98 | :mod:`sitecustomize`, which can perform arbitrary site-specific customizations. |
Éric Araujo | de4f05b | 2011-08-06 01:51:07 +0200 | [diff] [blame] | 99 | It is typically created by a system administrator in the site-packages |
| 100 | directory. If this import fails with an :exc:`ImportError` exception, it is |
Terry Jan Reedy | 43e7cd3 | 2014-04-29 00:31:53 -0400 | [diff] [blame] | 101 | silently ignored. If Python is started without output streams available, as |
| 102 | with :file:`pythonw.exe` on Windows (which is used by default to start IDLE), |
| 103 | attempted output from :mod:`sitecustomize` is ignored. Any exception other |
| 104 | than :exc:`ImportError` causes a silent and perhaps mysterious failure of the |
| 105 | process. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 106 | |
Éric Araujo | de4f05b | 2011-08-06 01:51:07 +0200 | [diff] [blame] | 107 | .. index:: module: usercustomize |
| 108 | |
| 109 | After this, an attempt is made to import a module named :mod:`usercustomize`, |
| 110 | which can perform arbitrary user-specific customizations, if |
| 111 | :data:`ENABLE_USER_SITE` is true. This file is intended to be created in the |
| 112 | user site-packages directory (see below), which is part of ``sys.path`` unless |
| 113 | disabled by :option:`-s`. An :exc:`ImportError` will be silently ignored. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 114 | |
| 115 | Note that for some non-Unix systems, ``sys.prefix`` and ``sys.exec_prefix`` are |
| 116 | empty, and the path manipulations are skipped; however the import of |
Éric Araujo | de4f05b | 2011-08-06 01:51:07 +0200 | [diff] [blame] | 117 | :mod:`sitecustomize` and :mod:`usercustomize` is still attempted. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 118 | |
Christian Heimes | 8dc226f | 2008-05-06 23:45:46 +0000 | [diff] [blame] | 119 | |
Antoine Pitrou | 1a6cb30 | 2013-05-04 20:08:35 +0200 | [diff] [blame] | 120 | .. _rlcompleter-config: |
| 121 | |
| 122 | Readline configuration |
| 123 | ---------------------- |
| 124 | |
| 125 | On systems that support :mod:`readline`, this module will also import and |
| 126 | configure the :mod:`rlcompleter` module, if Python is started in |
| 127 | :ref:`interactive mode <tut-interactive>` and without the :option:`-S` option. |
| 128 | The default behavior is enable tab-completion and to use |
R David Murray | 4e40cec | 2014-03-09 12:03:30 -0400 | [diff] [blame] | 129 | :file:`~/.python_history` as the history save file. To disable it, delete (or |
| 130 | override) the :data:`sys.__interactivehook__` attribute in your |
| 131 | :mod:`sitecustomize` or :mod:`usercustomize` module or your |
| 132 | :envvar:`PYTHONSTARTUP` file. |
| 133 | |
| 134 | .. versionchanged:: 3.4 |
| 135 | Activation of rlcompleter and history was made automatic. |
Antoine Pitrou | 1a6cb30 | 2013-05-04 20:08:35 +0200 | [diff] [blame] | 136 | |
| 137 | |
| 138 | Module contents |
| 139 | --------------- |
| 140 | |
Christian Heimes | 8dc226f | 2008-05-06 23:45:46 +0000 | [diff] [blame] | 141 | .. data:: PREFIXES |
| 142 | |
Éric Araujo | de4f05b | 2011-08-06 01:51:07 +0200 | [diff] [blame] | 143 | A list of prefixes for site-packages directories. |
Christian Heimes | 8dc226f | 2008-05-06 23:45:46 +0000 | [diff] [blame] | 144 | |
Christian Heimes | 8dc226f | 2008-05-06 23:45:46 +0000 | [diff] [blame] | 145 | |
| 146 | .. data:: ENABLE_USER_SITE |
| 147 | |
Éric Araujo | de4f05b | 2011-08-06 01:51:07 +0200 | [diff] [blame] | 148 | Flag showing the status of the user site-packages directory. ``True`` means |
| 149 | that it is enabled and was added to ``sys.path``. ``False`` means that it |
| 150 | was disabled by user request (with :option:`-s` or |
| 151 | :envvar:`PYTHONNOUSERSITE`). ``None`` means it was disabled for security |
| 152 | reasons (mismatch between user or group id and effective id) or by an |
| 153 | administrator. |
Christian Heimes | 8dc226f | 2008-05-06 23:45:46 +0000 | [diff] [blame] | 154 | |
Christian Heimes | 8dc226f | 2008-05-06 23:45:46 +0000 | [diff] [blame] | 155 | |
| 156 | .. data:: USER_SITE |
| 157 | |
Éric Araujo | de4f05b | 2011-08-06 01:51:07 +0200 | [diff] [blame] | 158 | Path to the user site-packages for the running Python. Can be ``None`` if |
| 159 | :func:`getusersitepackages` hasn't been called yet. Default value is |
| 160 | :file:`~/.local/lib/python{X.Y}/site-packages` for UNIX and non-framework Mac |
| 161 | OS X builds, :file:`~/Library/Python/{X.Y}/lib/python/site-packages` for Mac |
| 162 | framework builds, and :file:`{%APPDATA%}\\Python\\Python{XY}\\site-packages` |
| 163 | on Windows. This directory is a site directory, which means that |
| 164 | :file:`.pth` files in it will be processed. |
Christian Heimes | 8dc226f | 2008-05-06 23:45:46 +0000 | [diff] [blame] | 165 | |
Christian Heimes | 8dc226f | 2008-05-06 23:45:46 +0000 | [diff] [blame] | 166 | |
| 167 | .. data:: USER_BASE |
| 168 | |
Éric Araujo | de4f05b | 2011-08-06 01:51:07 +0200 | [diff] [blame] | 169 | Path to the base directory for the user site-packages. Can be ``None`` if |
| 170 | :func:`getuserbase` hasn't been called yet. Default value is |
| 171 | :file:`~/.local` for UNIX and Mac OS X non-framework builds, |
| 172 | :file:`~/Library/Python/{X.Y}` for Mac framework builds, and |
Éric Araujo | 859aad6 | 2012-06-24 00:07:41 -0400 | [diff] [blame] | 173 | :file:`{%APPDATA%}\\Python` for Windows. This value is used by Distutils to |
Éric Araujo | de4f05b | 2011-08-06 01:51:07 +0200 | [diff] [blame] | 174 | compute the installation directories for scripts, data files, Python modules, |
Éric Araujo | 859aad6 | 2012-06-24 00:07:41 -0400 | [diff] [blame] | 175 | etc. for the :ref:`user installation scheme <inst-alt-install-user>`. |
Éric Araujo | 7dc76fd | 2011-08-06 16:58:15 +0200 | [diff] [blame] | 176 | See also :envvar:`PYTHONUSERBASE`. |
Christian Heimes | 8dc226f | 2008-05-06 23:45:46 +0000 | [diff] [blame] | 177 | |
Christian Heimes | 8dc226f | 2008-05-06 23:45:46 +0000 | [diff] [blame] | 178 | |
Éric Araujo | c09fca6 | 2011-03-23 02:06:24 +0100 | [diff] [blame] | 179 | .. function:: main() |
| 180 | |
| 181 | Adds all the standard site-specific directories to the module search |
| 182 | path. This function is called automatically when this module is imported, |
Antoine Pitrou | 1a6cb30 | 2013-05-04 20:08:35 +0200 | [diff] [blame] | 183 | unless the Python interpreter was started with the :option:`-S` flag. |
Éric Araujo | c09fca6 | 2011-03-23 02:06:24 +0100 | [diff] [blame] | 184 | |
Éric Araujo | 17b60f0 | 2011-05-06 18:50:08 +0200 | [diff] [blame] | 185 | .. versionchanged:: 3.3 |
Donald Stufft | 8b852f1 | 2014-05-20 12:58:38 -0400 | [diff] [blame] | 186 | This function used to be called unconditionally. |
Éric Araujo | 17b60f0 | 2011-05-06 18:50:08 +0200 | [diff] [blame] | 187 | |
| 188 | |
Christian Heimes | 8dc226f | 2008-05-06 23:45:46 +0000 | [diff] [blame] | 189 | .. function:: addsitedir(sitedir, known_paths=None) |
| 190 | |
Éric Araujo | 6ef038e | 2011-08-06 16:30:42 +0200 | [diff] [blame] | 191 | Add a directory to sys.path and process its :file:`.pth` files. Typically |
| 192 | used in :mod:`sitecustomize` or :mod:`usercustomize` (see above). |
Éric Araujo | de4f05b | 2011-08-06 01:51:07 +0200 | [diff] [blame] | 193 | |
Christian Heimes | 8dc226f | 2008-05-06 23:45:46 +0000 | [diff] [blame] | 194 | |
Tarek Ziadé | 4a608c0 | 2009-08-20 21:28:05 +0000 | [diff] [blame] | 195 | .. function:: getsitepackages() |
| 196 | |
Antoine Pitrou | 9e82b17 | 2014-06-12 19:41:30 -0400 | [diff] [blame] | 197 | Return a list containing all global site-packages directories. |
Tarek Ziadé | 4a608c0 | 2009-08-20 21:28:05 +0000 | [diff] [blame] | 198 | |
Mark Dickinson | 574b1d6 | 2009-10-01 20:20:09 +0000 | [diff] [blame] | 199 | .. versionadded:: 3.2 |
Tarek Ziadé | 4a608c0 | 2009-08-20 21:28:05 +0000 | [diff] [blame] | 200 | |
Éric Araujo | de4f05b | 2011-08-06 01:51:07 +0200 | [diff] [blame] | 201 | |
Tarek Ziadé | 4a608c0 | 2009-08-20 21:28:05 +0000 | [diff] [blame] | 202 | .. function:: getuserbase() |
| 203 | |
Éric Araujo | de4f05b | 2011-08-06 01:51:07 +0200 | [diff] [blame] | 204 | Return the path of the user base directory, :data:`USER_BASE`. If it is not |
| 205 | initialized yet, this function will also set it, respecting |
| 206 | :envvar:`PYTHONUSERBASE`. |
Tarek Ziadé | 4a608c0 | 2009-08-20 21:28:05 +0000 | [diff] [blame] | 207 | |
Mark Dickinson | 574b1d6 | 2009-10-01 20:20:09 +0000 | [diff] [blame] | 208 | .. versionadded:: 3.2 |
Tarek Ziadé | 4a608c0 | 2009-08-20 21:28:05 +0000 | [diff] [blame] | 209 | |
Éric Araujo | de4f05b | 2011-08-06 01:51:07 +0200 | [diff] [blame] | 210 | |
Tarek Ziadé | 4a608c0 | 2009-08-20 21:28:05 +0000 | [diff] [blame] | 211 | .. function:: getusersitepackages() |
| 212 | |
Éric Araujo | de4f05b | 2011-08-06 01:51:07 +0200 | [diff] [blame] | 213 | Return the path of the user-specific site-packages directory, |
| 214 | :data:`USER_SITE`. If it is not initialized yet, this function will also set |
| 215 | it, respecting :envvar:`PYTHONNOUSERSITE` and :data:`USER_BASE`. |
Tarek Ziadé | 4a608c0 | 2009-08-20 21:28:05 +0000 | [diff] [blame] | 216 | |
Mark Dickinson | 574b1d6 | 2009-10-01 20:20:09 +0000 | [diff] [blame] | 217 | .. versionadded:: 3.2 |
Christian Heimes | 8dc226f | 2008-05-06 23:45:46 +0000 | [diff] [blame] | 218 | |
Tarek Ziadé | 4a608c0 | 2009-08-20 21:28:05 +0000 | [diff] [blame] | 219 | |
Éric Araujo | de4f05b | 2011-08-06 01:51:07 +0200 | [diff] [blame] | 220 | The :mod:`site` module also provides a way to get the user directories from the |
| 221 | command line: |
| 222 | |
| 223 | .. code-block:: sh |
| 224 | |
| 225 | $ python3 -m site --user-site |
| 226 | /home/user/.local/lib/python3.3/site-packages |
| 227 | |
| 228 | .. program:: site |
| 229 | |
| 230 | If it is called without arguments, it will print the contents of |
| 231 | :data:`sys.path` on the standard output, followed by the value of |
| 232 | :data:`USER_BASE` and whether the directory exists, then the same thing for |
| 233 | :data:`USER_SITE`, and finally the value of :data:`ENABLE_USER_SITE`. |
| 234 | |
| 235 | .. cmdoption:: --user-base |
| 236 | |
| 237 | Print the path to the user base directory. |
| 238 | |
| 239 | .. cmdoption:: --user-site |
| 240 | |
| 241 | Print the path to the user site-packages directory. |
| 242 | |
| 243 | If both options are given, user base and user site will be printed (always in |
| 244 | this order), separated by :data:`os.pathsep`. |
| 245 | |
| 246 | If any option is given, the script will exit with one of these values: ``O`` if |
| 247 | the user site-packages directory is enabled, ``1`` if it was disabled by the |
| 248 | user, ``2`` if it is disabled for security reasons or by an administrator, and a |
| 249 | value greater than 2 if there is an error. |
| 250 | |
| 251 | .. seealso:: |
| 252 | |
| 253 | :pep:`370` -- Per user site-packages directory |