diff --git a/Doc/library/site.rst b/Doc/library/site.rst --- 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 di 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 ta 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,118 @@ not mentioned in either path configurati 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}`. + + .. TODO document values for other platforms .. 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`. This value is used by Distutils to compute the + installation directories for scripts, data files, Python modules, etc. See + also :envvar:`PYTHONUSERBASE`. .. 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. + .. 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 diff --git a/Doc/tutorial/interactive.rst b/Doc/tutorial/interactive.rst --- a/Doc/tutorial/interactive.rst +++ b/Doc/tutorial/interactive.rst @@ -156,17 +156,18 @@ symbol table. A command to check (or ev quotes, etc., would also be useful. One alternative enhanced interactive interpreter that has been around for quite -some time is `IPython`_, which features tab completion, object exploration and +some time is IPython_, which features tab completion, object exploration and advanced history management. It can also be thoroughly customized and embedded into other applications. Another similar enhanced interactive environment is -`bpython`_. +bpython_. .. rubric:: Footnotes .. [#] Python will execute the contents of a file identified by the :envvar:`PYTHONSTARTUP` environment variable when you start an interactive - interpreter. + interpreter. To customize Python even for non-interactive mode, see + :ref:`tut-customize`. .. _GNU Readline: http://tiswww.case.edu/php/chet/readline/rltop.html diff --git a/Doc/tutorial/interpreter.rst b/Doc/tutorial/interpreter.rst --- a/Doc/tutorial/interpreter.rst +++ b/Doc/tutorial/interpreter.rst @@ -236,6 +236,29 @@ in the script:: exec(open(filename).read()) +.. _tut-customize: + +The Customization Modules +------------------------- + +Python provides two hooks to let you customize it: :mod:`sitecustomize` and +:mod:`usercustomize`. To see how it works, you need first to find the location +of your user site-packages directory. Start Python and run this code: + + >>> import site + >>> site.getusersitepackages() + '/home/user/.local/lib/python3.2/site-packages' + +Now you can create a file named :file:`usercustomize.py` in that directory and +put anything you want in it. It will affect every invocation of Python, unless +it is started with the :option:`-s` option to disable the automatic import. + +:mod:`sitecustomize` works in the same way, but is typically created by an +administrator of the computer in the global site-packages directory, and is +imported before :mod:`usercustomize`. See the documentation of the :mod:`site` +module for more details. + + .. rubric:: Footnotes .. [#] On Unix, the Python 3.x interpreter is by default not installed with the @@ -243,4 +266,3 @@ in the script:: simultaneously installed Python 2.x executable. .. [#] A problem with the GNU Readline package may prevent this. - diff --git a/Doc/using/cmdline.rst b/Doc/using/cmdline.rst --- a/Doc/using/cmdline.rst +++ b/Doc/using/cmdline.rst @@ -229,7 +229,8 @@ Miscellaneous options .. cmdoption:: -s - Don't add user site directory to sys.path + Don't add the :data:`user site-packages directory ` to + :data:`sys.path`. .. seealso:: @@ -468,7 +469,8 @@ These environment variables influence Py .. envvar:: PYTHONNOUSERSITE - If this is set, Python won't add the user site directory to sys.path + If this is set, Python won't add the :data:`user site-packages directory + ` to :data:`sys.path`. .. seealso:: @@ -477,7 +479,9 @@ These environment variables influence Py .. envvar:: PYTHONUSERBASE - Sets the base directory for the user site directory + Defines the :data:`user base directory `, which is used to + compute the path of the :data:`user site-packages directory ` + and Distutils installation paths for ``setup.py install --user``. .. seealso::