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 |
| 36 | :file:`lib/python|version|/site-packages` and then :file:`lib/site-python` (on |
| 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 | |
Éric Araujo | de4f05b | 2011-08-06 01:51:07 +0200 | [diff] [blame] | 41 | 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] | 42 | and exists in one of the four directories mentioned above; its contents are |
| 43 | 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] | 44 | are never added to ``sys.path``, and no check is made that the item refers to a |
| 45 | 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] | 46 | once. Blank lines and lines beginning with ``#`` are skipped. Lines starting |
| 47 | with ``import`` (followed by space or tab) are executed. |
| 48 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 49 | .. index:: |
| 50 | single: package |
| 51 | triple: path; configuration; file |
| 52 | |
| 53 | For example, suppose ``sys.prefix`` and ``sys.exec_prefix`` are set to |
| 54 | :file:`/usr/local`. The Python X.Y library is then installed in |
Éric Araujo | de4f05b | 2011-08-06 01:51:07 +0200 | [diff] [blame] | 55 | :file:`/usr/local/lib/python{X.Y}`. Suppose this has |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 56 | a subdirectory :file:`/usr/local/lib/python{X.Y}/site-packages` with three |
| 57 | subsubdirectories, :file:`foo`, :file:`bar` and :file:`spam`, and two path |
| 58 | configuration files, :file:`foo.pth` and :file:`bar.pth`. Assume |
| 59 | :file:`foo.pth` contains the following:: |
| 60 | |
| 61 | # foo package configuration |
| 62 | |
| 63 | foo |
| 64 | bar |
| 65 | bletch |
| 66 | |
| 67 | and :file:`bar.pth` contains:: |
| 68 | |
| 69 | # bar package configuration |
| 70 | |
| 71 | bar |
| 72 | |
Benjamin Peterson | e9bbc8b | 2008-09-28 02:06:32 +0000 | [diff] [blame] | 73 | Then the following version-specific directories are added to |
| 74 | ``sys.path``, in this order:: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 75 | |
Benjamin Peterson | e9bbc8b | 2008-09-28 02:06:32 +0000 | [diff] [blame] | 76 | /usr/local/lib/pythonX.Y/site-packages/bar |
| 77 | /usr/local/lib/pythonX.Y/site-packages/foo |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 78 | |
| 79 | Note that :file:`bletch` is omitted because it doesn't exist; the :file:`bar` |
| 80 | directory precedes the :file:`foo` directory because :file:`bar.pth` comes |
| 81 | alphabetically before :file:`foo.pth`; and :file:`spam` is omitted because it is |
| 82 | not mentioned in either path configuration file. |
| 83 | |
| 84 | .. index:: module: sitecustomize |
| 85 | |
| 86 | After these path manipulations, an attempt is made to import a module named |
| 87 | :mod:`sitecustomize`, which can perform arbitrary site-specific customizations. |
Éric Araujo | de4f05b | 2011-08-06 01:51:07 +0200 | [diff] [blame] | 88 | It is typically created by a system administrator in the site-packages |
| 89 | directory. If this import fails with an :exc:`ImportError` exception, it is |
| 90 | silently ignored. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 91 | |
Éric Araujo | de4f05b | 2011-08-06 01:51:07 +0200 | [diff] [blame] | 92 | .. index:: module: usercustomize |
| 93 | |
| 94 | After this, an attempt is made to import a module named :mod:`usercustomize`, |
| 95 | which can perform arbitrary user-specific customizations, if |
| 96 | :data:`ENABLE_USER_SITE` is true. This file is intended to be created in the |
| 97 | user site-packages directory (see below), which is part of ``sys.path`` unless |
| 98 | disabled by :option:`-s`. An :exc:`ImportError` will be silently ignored. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 99 | |
| 100 | Note that for some non-Unix systems, ``sys.prefix`` and ``sys.exec_prefix`` are |
| 101 | empty, and the path manipulations are skipped; however the import of |
Éric Araujo | de4f05b | 2011-08-06 01:51:07 +0200 | [diff] [blame] | 102 | :mod:`sitecustomize` and :mod:`usercustomize` is still attempted. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 103 | |
Christian Heimes | 8dc226f | 2008-05-06 23:45:46 +0000 | [diff] [blame] | 104 | |
| 105 | .. data:: PREFIXES |
| 106 | |
Éric Araujo | de4f05b | 2011-08-06 01:51:07 +0200 | [diff] [blame] | 107 | A list of prefixes for site-packages directories. |
Christian Heimes | 8dc226f | 2008-05-06 23:45:46 +0000 | [diff] [blame] | 108 | |
Christian Heimes | 8dc226f | 2008-05-06 23:45:46 +0000 | [diff] [blame] | 109 | |
| 110 | .. data:: ENABLE_USER_SITE |
| 111 | |
Éric Araujo | de4f05b | 2011-08-06 01:51:07 +0200 | [diff] [blame] | 112 | Flag showing the status of the user site-packages directory. ``True`` means |
| 113 | that it is enabled and was added to ``sys.path``. ``False`` means that it |
| 114 | was disabled by user request (with :option:`-s` or |
| 115 | :envvar:`PYTHONNOUSERSITE`). ``None`` means it was disabled for security |
| 116 | reasons (mismatch between user or group id and effective id) or by an |
| 117 | administrator. |
Christian Heimes | 8dc226f | 2008-05-06 23:45:46 +0000 | [diff] [blame] | 118 | |
Christian Heimes | 8dc226f | 2008-05-06 23:45:46 +0000 | [diff] [blame] | 119 | |
| 120 | .. data:: USER_SITE |
| 121 | |
Éric Araujo | de4f05b | 2011-08-06 01:51:07 +0200 | [diff] [blame] | 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. |
Christian Heimes | 8dc226f | 2008-05-06 23:45:46 +0000 | [diff] [blame] | 129 | |
Christian Heimes | 8dc226f | 2008-05-06 23:45:46 +0000 | [diff] [blame] | 130 | |
| 131 | .. data:: USER_BASE |
| 132 | |
Éric Araujo | de4f05b | 2011-08-06 01:51:07 +0200 | [diff] [blame] | 133 | Path to the base directory for the user site-packages. Can be ``None`` if |
| 134 | :func:`getuserbase` hasn't been called yet. Default value is |
| 135 | :file:`~/.local` for UNIX and Mac OS X non-framework builds, |
| 136 | :file:`~/Library/Python/{X.Y}` for Mac framework builds, and |
Éric Araujo | 7dc76fd | 2011-08-06 16:58:15 +0200 | [diff] [blame] | 137 | :file:`{%APPDATA%}\\Python` for Windows. This value is used by Packaging to |
Éric Araujo | de4f05b | 2011-08-06 01:51:07 +0200 | [diff] [blame] | 138 | compute the installation directories for scripts, data files, Python modules, |
Éric Araujo | 7dc76fd | 2011-08-06 16:58:15 +0200 | [diff] [blame] | 139 | etc. for the :ref:`user installation scheme <packaging-alt-install-user>`. |
| 140 | See also :envvar:`PYTHONUSERBASE`. |
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 | |
Éric Araujo | c09fca6 | 2011-03-23 02:06:24 +0100 | [diff] [blame] | 143 | .. function:: main() |
| 144 | |
| 145 | Adds all the standard site-specific directories to the module search |
| 146 | path. This function is called automatically when this module is imported, |
| 147 | unless the :program:`python` interpreter was started with the :option:`-S` |
| 148 | flag. |
| 149 | |
Éric Araujo | 17b60f0 | 2011-05-06 18:50:08 +0200 | [diff] [blame] | 150 | .. versionchanged:: 3.3 |
| 151 | This function used to be called unconditionnally. |
| 152 | |
| 153 | |
Christian Heimes | 8dc226f | 2008-05-06 23:45:46 +0000 | [diff] [blame] | 154 | .. function:: addsitedir(sitedir, known_paths=None) |
| 155 | |
Éric Araujo | 6ef038e | 2011-08-06 16:30:42 +0200 | [diff] [blame] | 156 | Add a directory to sys.path and process its :file:`.pth` files. Typically |
| 157 | used in :mod:`sitecustomize` or :mod:`usercustomize` (see above). |
Éric Araujo | de4f05b | 2011-08-06 01:51:07 +0200 | [diff] [blame] | 158 | |
Christian Heimes | 8dc226f | 2008-05-06 23:45:46 +0000 | [diff] [blame] | 159 | |
Tarek Ziadé | 4a608c0 | 2009-08-20 21:28:05 +0000 | [diff] [blame] | 160 | .. function:: getsitepackages() |
| 161 | |
Éric Araujo | de4f05b | 2011-08-06 01:51:07 +0200 | [diff] [blame] | 162 | Return a list containing all global site-packages directories (and possibly |
| 163 | site-python). |
Tarek Ziadé | 4a608c0 | 2009-08-20 21:28:05 +0000 | [diff] [blame] | 164 | |
Mark Dickinson | 574b1d6 | 2009-10-01 20:20:09 +0000 | [diff] [blame] | 165 | .. versionadded:: 3.2 |
Tarek Ziadé | 4a608c0 | 2009-08-20 21:28:05 +0000 | [diff] [blame] | 166 | |
Éric Araujo | de4f05b | 2011-08-06 01:51:07 +0200 | [diff] [blame] | 167 | |
Tarek Ziadé | 4a608c0 | 2009-08-20 21:28:05 +0000 | [diff] [blame] | 168 | .. function:: getuserbase() |
| 169 | |
Éric Araujo | de4f05b | 2011-08-06 01:51:07 +0200 | [diff] [blame] | 170 | Return the path of the user base directory, :data:`USER_BASE`. If it is not |
| 171 | initialized yet, this function will also set it, respecting |
| 172 | :envvar:`PYTHONUSERBASE`. |
Tarek Ziadé | 4a608c0 | 2009-08-20 21:28:05 +0000 | [diff] [blame] | 173 | |
Mark Dickinson | 574b1d6 | 2009-10-01 20:20:09 +0000 | [diff] [blame] | 174 | .. versionadded:: 3.2 |
Tarek Ziadé | 4a608c0 | 2009-08-20 21:28:05 +0000 | [diff] [blame] | 175 | |
Éric Araujo | de4f05b | 2011-08-06 01:51:07 +0200 | [diff] [blame] | 176 | |
Tarek Ziadé | 4a608c0 | 2009-08-20 21:28:05 +0000 | [diff] [blame] | 177 | .. function:: getusersitepackages() |
| 178 | |
Éric Araujo | de4f05b | 2011-08-06 01:51:07 +0200 | [diff] [blame] | 179 | Return the path of the user-specific site-packages directory, |
| 180 | :data:`USER_SITE`. If it is not initialized yet, this function will also set |
| 181 | it, respecting :envvar:`PYTHONNOUSERSITE` and :data:`USER_BASE`. |
Tarek Ziadé | 4a608c0 | 2009-08-20 21:28:05 +0000 | [diff] [blame] | 182 | |
Mark Dickinson | 574b1d6 | 2009-10-01 20:20:09 +0000 | [diff] [blame] | 183 | .. versionadded:: 3.2 |
Christian Heimes | 8dc226f | 2008-05-06 23:45:46 +0000 | [diff] [blame] | 184 | |
Tarek Ziadé | 4a608c0 | 2009-08-20 21:28:05 +0000 | [diff] [blame] | 185 | |
Éric Araujo | de4f05b | 2011-08-06 01:51:07 +0200 | [diff] [blame] | 186 | The :mod:`site` module also provides a way to get the user directories from the |
| 187 | command line: |
| 188 | |
| 189 | .. code-block:: sh |
| 190 | |
| 191 | $ python3 -m site --user-site |
| 192 | /home/user/.local/lib/python3.3/site-packages |
| 193 | |
| 194 | .. program:: site |
| 195 | |
| 196 | If it is called without arguments, it will print the contents of |
| 197 | :data:`sys.path` on the standard output, followed by the value of |
| 198 | :data:`USER_BASE` and whether the directory exists, then the same thing for |
| 199 | :data:`USER_SITE`, and finally the value of :data:`ENABLE_USER_SITE`. |
| 200 | |
| 201 | .. cmdoption:: --user-base |
| 202 | |
| 203 | Print the path to the user base directory. |
| 204 | |
| 205 | .. cmdoption:: --user-site |
| 206 | |
| 207 | Print the path to the user site-packages directory. |
| 208 | |
| 209 | If both options are given, user base and user site will be printed (always in |
| 210 | this order), separated by :data:`os.pathsep`. |
| 211 | |
| 212 | If any option is given, the script will exit with one of these values: ``O`` if |
| 213 | the user site-packages directory is enabled, ``1`` if it was disabled by the |
| 214 | user, ``2`` if it is disabled for security reasons or by an administrator, and a |
| 215 | value greater than 2 if there is an error. |
| 216 | |
| 217 | .. seealso:: |
| 218 | |
| 219 | :pep:`370` -- Per user site-packages directory |