mirror of https://github.com/python/cpython
161 lines
5.2 KiB
ReStructuredText
161 lines
5.2 KiB
ReStructuredText
:mod:`site` --- Site-specific configuration hook
|
|
================================================
|
|
|
|
.. module:: site
|
|
:synopsis: A standard way to reference site-specific modules.
|
|
|
|
**Source code:** :source:`Lib/site.py`
|
|
|
|
--------------
|
|
|
|
**This module is automatically imported during initialization.** The automatic
|
|
import can be suppressed using the interpreter's :option:`-S` option.
|
|
|
|
.. index:: triple: module; search; path
|
|
|
|
Importing this module will append site-specific paths to the module search
|
|
path, unless :option:`-S` was used. In that case, this module can be safely
|
|
imported with no automatic modifications to the module search path. To
|
|
explicitly trigger the usual site-specific additions, call the
|
|
:func:`site.main` function.
|
|
|
|
.. index::
|
|
pair: site-python; directory
|
|
pair: site-packages; directory
|
|
|
|
It starts by constructing up to four directories from a head and a tail part.
|
|
For the head part, it uses ``sys.prefix`` and ``sys.exec_prefix``; empty heads
|
|
are skipped. For the tail part, it uses the empty string and then
|
|
:file:`lib/site-packages` (on Windows) or
|
|
:file:`lib/python|version|/site-packages` and then :file:`lib/site-python` (on
|
|
Unix and Macintosh). For each of the distinct head-tail combinations, it sees
|
|
if it refers to an existing directory, and if so, adds it to ``sys.path`` and
|
|
also inspects the newly added path for configuration files.
|
|
|
|
A path configuration file is a file whose name has the form :file:`package.pth`
|
|
and exists in one of the four directories mentioned above; its contents are
|
|
additional items (one per line) to be added to ``sys.path``. Non-existing items
|
|
are never added to ``sys.path``, but no check is made that the item refers to a
|
|
directory (rather than a file). No item is added to ``sys.path`` more than
|
|
once. Blank lines and lines beginning with ``#`` are skipped. Lines starting
|
|
with ``import`` (followed by space or tab) are executed.
|
|
|
|
.. index::
|
|
single: package
|
|
triple: path; configuration; file
|
|
|
|
For example, suppose ``sys.prefix`` and ``sys.exec_prefix`` are set to
|
|
:file:`/usr/local`. The Python X.Y library is then installed in
|
|
:file:`/usr/local/lib/python{X.Y}` (where only the first three characters of
|
|
``sys.version`` are used to form the installation path name). Suppose this has
|
|
a subdirectory :file:`/usr/local/lib/python{X.Y}/site-packages` with three
|
|
subsubdirectories, :file:`foo`, :file:`bar` and :file:`spam`, and two path
|
|
configuration files, :file:`foo.pth` and :file:`bar.pth`. Assume
|
|
:file:`foo.pth` contains the following::
|
|
|
|
# foo package configuration
|
|
|
|
foo
|
|
bar
|
|
bletch
|
|
|
|
and :file:`bar.pth` contains::
|
|
|
|
# bar package configuration
|
|
|
|
bar
|
|
|
|
Then the following version-specific directories are added to
|
|
``sys.path``, in this order::
|
|
|
|
/usr/local/lib/pythonX.Y/site-packages/bar
|
|
/usr/local/lib/pythonX.Y/site-packages/foo
|
|
|
|
Note that :file:`bletch` is omitted because it doesn't exist; the :file:`bar`
|
|
directory precedes the :file:`foo` directory because :file:`bar.pth` comes
|
|
alphabetically before :file:`foo.pth`; and :file:`spam` is omitted because it is
|
|
not mentioned in either path configuration file.
|
|
|
|
.. index:: module: sitecustomize
|
|
|
|
After these path manipulations, an attempt is made to import a module named
|
|
:mod:`sitecustomize`, which can perform arbitrary site-specific customizations.
|
|
If this import fails with an :exc:`ImportError` exception, it is silently
|
|
ignored.
|
|
|
|
.. index:: module: sitecustomize
|
|
|
|
Note that for some non-Unix systems, ``sys.prefix`` and ``sys.exec_prefix`` are
|
|
empty, and the path manipulations are skipped; however the import of
|
|
:mod:`sitecustomize` is still attempted.
|
|
|
|
|
|
.. data:: PREFIXES
|
|
|
|
A list of prefixes for site package directories
|
|
|
|
|
|
.. data:: ENABLE_USER_SITE
|
|
|
|
Flag showing the status of the user site directory. True means the
|
|
user site directory is enabled and added to sys.path. When the flag
|
|
is None the user site directory is disabled for security reasons.
|
|
|
|
|
|
.. data:: USER_SITE
|
|
|
|
Path to the user site directory for the current Python version or None
|
|
|
|
|
|
.. data:: USER_BASE
|
|
|
|
Path to the base directory for user site directories
|
|
|
|
|
|
.. envvar:: PYTHONNOUSERSITE
|
|
|
|
|
|
.. envvar:: PYTHONUSERBASE
|
|
|
|
|
|
.. function:: main()
|
|
|
|
Adds all the standard site-specific directories to the module search
|
|
path. This function is called automatically when this module is imported,
|
|
unless the :program:`python` interpreter was started with the :option:`-S`
|
|
flag.
|
|
|
|
.. function:: addsitedir(sitedir, known_paths=None)
|
|
|
|
Adds a directory to sys.path and processes its pth files.
|
|
|
|
.. function:: getsitepackages()
|
|
|
|
Returns a list containing all global site-packages directories
|
|
(and possibly site-python).
|
|
|
|
.. versionadded:: 3.2
|
|
|
|
.. function:: getuserbase()
|
|
|
|
Returns the "user base" directory path.
|
|
|
|
The "user base" directory can be used to store data. If the global
|
|
variable ``USER_BASE`` is not initialized yet, this function will also set
|
|
it.
|
|
|
|
.. versionadded:: 3.2
|
|
|
|
.. function:: getusersitepackages()
|
|
|
|
Returns the user-specific site-packages directory path.
|
|
|
|
If the global variable ``USER_SITE`` is not initialized yet, this
|
|
function will also set it.
|
|
|
|
.. versionadded:: 3.2
|
|
|
|
.. XXX Update documentation
|
|
.. XXX document python -m site --user-base --user-site
|
|
|