Debian Codegraph @

Doc/library/site.rst

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