mirror of
https://github.com/python/cpython.git
synced 2025-11-01 02:38:53 +00:00
In the install and library docs, I changed the text to refer to packaging instead of distutils. I also checked that the documented paths correctly reflect what’s really defined in sysconfig; the main difference with paths defined in distutils.install is that include directories don’t end with the distribution name anymore (i.e. distutils uses include/python3.3/spam, sysconfig include/python3.3), I have no idea why.
This commit is contained in:
Éric Araujo
commit
7dc76fdeb1
7 changed files with 408 additions and 159 deletions
|
|
@ -2,22 +2,24 @@
|
|||
================================================
|
||||
|
||||
.. module:: site
|
||||
:synopsis: A standard way to reference site-specific modules.
|
||||
:synopsis: Module responsible for site-specific configuration.
|
||||
|
||||
**Source code:** :source:`Lib/site.py`
|
||||
|
||||
--------------
|
||||
|
||||
.. highlightlang:: none
|
||||
|
||||
**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.
|
||||
Importing this module will append site-specific paths to the module search path
|
||||
and add a few builtins, unless :option:`-S` was used. In that case, this module
|
||||
can be safely imported with no automatic modifications to the module search path
|
||||
or additions to the builtins. To explicitly trigger the usual site-specific
|
||||
additions, call the :func:`site.main` function.
|
||||
|
||||
.. versionchanged:: 3.3
|
||||
Importing the module used to trigger paths manipulation even when using
|
||||
|
|
@ -36,11 +38,11 @@ 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`
|
||||
A path configuration file is a file whose name has the form :file:`{name}.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
|
||||
are never added to ``sys.path``, and 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.
|
||||
|
||||
|
|
@ -50,8 +52,7 @@ with ``import`` (followed by space or tab) are executed.
|
|||
|
||||
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
|
||||
:file:`/usr/local/lib/python{X.Y}`. 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
|
||||
|
|
@ -84,42 +85,59 @@ not mentioned in either path configuration file.
|
|||
|
||||
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.
|
||||
It is typically created by a system administrator in the site-packages
|
||||
directory. If this import fails with an :exc:`ImportError` exception, it is
|
||||
silently ignored.
|
||||
|
||||
.. index:: module: sitecustomize
|
||||
.. index:: module: usercustomize
|
||||
|
||||
After this, an attempt is made to import a module named :mod:`usercustomize`,
|
||||
which can perform arbitrary user-specific customizations, if
|
||||
:data:`ENABLE_USER_SITE` is true. This file is intended to be created in the
|
||||
user site-packages directory (see below), which is part of ``sys.path`` unless
|
||||
disabled by :option:`-s`. An :exc:`ImportError` will be silently ignored.
|
||||
|
||||
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.
|
||||
:mod:`sitecustomize` and :mod:`usercustomize` is still attempted.
|
||||
|
||||
|
||||
.. data:: PREFIXES
|
||||
|
||||
A list of prefixes for site package directories
|
||||
A list of prefixes for site-packages 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.
|
||||
Flag showing the status of the user site-packages directory. ``True`` means
|
||||
that it is enabled and was added to ``sys.path``. ``False`` means that it
|
||||
was disabled by user request (with :option:`-s` or
|
||||
:envvar:`PYTHONNOUSERSITE`). ``None`` means it was disabled for security
|
||||
reasons (mismatch between user or group id and effective id) or by an
|
||||
administrator.
|
||||
|
||||
|
||||
.. data:: USER_SITE
|
||||
|
||||
Path to the user site directory for the current Python version or None
|
||||
Path to the user site-packages for the running Python. Can be ``None`` if
|
||||
:func:`getusersitepackages` hasn't been called yet. Default value is
|
||||
:file:`~/.local/lib/python{X.Y}/site-packages` for UNIX and non-framework Mac
|
||||
OS X builds, :file:`~/Library/Python/{X.Y}/lib/python/site-packages` for Mac
|
||||
framework builds, and :file:`{%APPDATA%}\\Python\\Python{XY}\\site-packages`
|
||||
on Windows. This directory is a site directory, which means that
|
||||
:file:`.pth` files in it will be processed.
|
||||
|
||||
|
||||
.. data:: USER_BASE
|
||||
|
||||
Path to the base directory for user site directories
|
||||
|
||||
|
||||
.. envvar:: PYTHONNOUSERSITE
|
||||
|
||||
|
||||
.. envvar:: PYTHONUSERBASE
|
||||
Path to the base directory for the user site-packages. Can be ``None`` if
|
||||
:func:`getuserbase` hasn't been called yet. Default value is
|
||||
:file:`~/.local` for UNIX and Mac OS X non-framework builds,
|
||||
:file:`~/Library/Python/{X.Y}` for Mac framework builds, and
|
||||
:file:`{%APPDATA%}\\Python` for Windows. This value is used by Packaging to
|
||||
compute the installation directories for scripts, data files, Python modules,
|
||||
etc. for the :ref:`user installation scheme <packaging-alt-install-user>`.
|
||||
See also :envvar:`PYTHONUSERBASE`.
|
||||
|
||||
|
||||
.. function:: main()
|
||||
|
|
@ -135,34 +153,67 @@ empty, and the path manipulations are skipped; however the import of
|
|||
|
||||
.. function:: addsitedir(sitedir, known_paths=None)
|
||||
|
||||
Adds a directory to sys.path and processes its pth files.
|
||||
Add a directory to sys.path and process its :file:`.pth` files. Typically
|
||||
used in :mod:`sitecustomize` or :mod:`usercustomize` (see above).
|
||||
|
||||
|
||||
.. function:: getsitepackages()
|
||||
|
||||
Returns a list containing all global site-packages directories
|
||||
(and possibly site-python).
|
||||
Return 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.
|
||||
Return the path of the user base directory, :data:`USER_BASE`. If it is not
|
||||
initialized yet, this function will also set it, respecting
|
||||
:envvar:`PYTHONUSERBASE`.
|
||||
|
||||
.. 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.
|
||||
Return the path of the user-specific site-packages directory,
|
||||
:data:`USER_SITE`. If it is not initialized yet, this function will also set
|
||||
it, respecting :envvar:`PYTHONNOUSERSITE` and :data:`USER_BASE`.
|
||||
|
||||
.. versionadded:: 3.2
|
||||
|
||||
.. XXX Update documentation
|
||||
.. XXX document python -m site --user-base --user-site
|
||||
|
||||
The :mod:`site` module also provides a way to get the user directories from the
|
||||
command line:
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
$ python3 -m site --user-site
|
||||
/home/user/.local/lib/python3.3/site-packages
|
||||
|
||||
.. program:: site
|
||||
|
||||
If it is called without arguments, it will print the contents of
|
||||
:data:`sys.path` on the standard output, followed by the value of
|
||||
:data:`USER_BASE` and whether the directory exists, then the same thing for
|
||||
:data:`USER_SITE`, and finally the value of :data:`ENABLE_USER_SITE`.
|
||||
|
||||
.. cmdoption:: --user-base
|
||||
|
||||
Print the path to the user base directory.
|
||||
|
||||
.. cmdoption:: --user-site
|
||||
|
||||
Print the path to the user site-packages directory.
|
||||
|
||||
If both options are given, user base and user site will be printed (always in
|
||||
this order), separated by :data:`os.pathsep`.
|
||||
|
||||
If any option is given, the script will exit with one of these values: ``O`` if
|
||||
the user site-packages directory is enabled, ``1`` if it was disabled by the
|
||||
user, ``2`` if it is disabled for security reasons or by an administrator, and a
|
||||
value greater than 2 if there is an error.
|
||||
|
||||
.. seealso::
|
||||
|
||||
:pep:`370` -- Per user site-packages directory
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue