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