summaryrefslogtreecommitdiffstats
path: root/Doc/library
diff options
context:
space:
mode:
Diffstat (limited to 'Doc/library')
-rw-r--r--Doc/library/site.rst124
1 files changed, 88 insertions, 36 deletions
diff --git a/Doc/library/site.rst b/Doc/library/site.rst
index b77f3cf..db96add 100644
--- a/Doc/library/site.rst
+++ b/Doc/library/site.rst
@@ -2,18 +2,21 @@
================================================
.. 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.
+Importing this module will append site-specific paths to the module search path
+and add a few builtins.
.. index::
pair: site-python; directory
@@ -28,11 +31,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.
@@ -42,8 +45,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
@@ -76,74 +78,124 @@ 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
+ 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 Distutils to
+ compute the installation directories for scripts, data files, Python modules,
+ etc. for the :ref:`user installation scheme <inst-alt-install-user>`. See
+ also :envvar:`PYTHONUSERBASE`.
-.. envvar:: PYTHONNOUSERSITE
+.. function:: addsitedir(sitedir, known_paths=None)
+ Add a directory to sys.path and process its :file:`.pth` files. Typically
+ used in :mod:`sitecustomize` or :mod:`usercustomize` (see above).
-.. envvar:: PYTHONUSERBASE
+.. function:: getsitepackages()
-.. function:: addsitedir(sitedir, known_paths=None)
+ Return a list containing all global site-packages directories (and possibly
+ site-python).
- Adds a directory to sys.path and processes its pth files.
+ .. versionadded:: 3.2
-.. function:: getsitepackages()
- Returns a list containing all global site-packages directories
- (and possibly site-python).
+.. function:: getuserbase()
+
+ 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:: getuserbase()
- Returns the "user base" directory path.
+.. function:: getusersitepackages()
- 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-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
-.. function:: getusersitepackages()
- Returns the user-specific site-packages directory path.
+The :mod:`site` module also provides a way to get the user directories from the
+command line:
- If the global variable ``USER_SITE`` is not initialized yet, this
- function will also set it.
+.. code-block:: sh
- .. versionadded:: 3.2
+ $ 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.
-.. XXX Update documentation
-.. XXX document python -m site --user-base --user-site
+.. seealso::
+ :pep:`370` -- Per user site-packages directory