diff options
Diffstat (limited to 'Doc/library/site.rst')
| -rw-r--r-- | Doc/library/site.rst | 122 |
1 files changed, 86 insertions, 36 deletions
diff --git a/Doc/library/site.rst b/Doc/library/site.rst index b77f3cf..adab800 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,122 @@ 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. See also :envvar:`PYTHONUSERBASE`. -.. envvar:: PYTHONNOUSERSITE +.. function:: addsitedir(sitedir, known_paths=None) + Add a directory to sys.path and process its :file:`.pth` files. -.. 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 |