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