1 

     2 :mod:`site` --- Site-specific configuration hook

     3 ================================================

     4 

     5 .. module:: site

     6    :synopsis: A standard way to reference site-specific modules.

     7 

     8 

     9 **This module is automatically imported during initialization.** The automatic

    10 import can be suppressed using the interpreter's :option:`-S` option.

    11 

    12 .. index:: triple: module; search; path

    13 

    14 Importing this module will append site-specific paths to the module search path.

    15 

    16 .. index::

    17    pair: site-python; directory

    18    pair: site-packages; directory

    19 

    20 It starts by constructing up to four directories from a head and a tail part.

    21 For the head part, it uses ``sys.prefix`` and ``sys.exec_prefix``; empty heads

    22 are skipped.  For the tail part, it uses the empty string and then

    23 :file:`lib/site-packages` (on Windows) or

    24 :file:`lib/python|version|/site-packages` and then :file:`lib/site-python` (on

    25 Unix and Macintosh).  For each of the distinct head-tail combinations, it sees

    26 if it refers to an existing directory, and if so, adds it to ``sys.path`` and

    27 also inspects the newly added path for configuration files.

    28 

    29 A path configuration file is a file whose name has the form :file:`package.pth`

    30 and exists in one of the four directories mentioned above; its contents are

    31 additional items (one per line) to be added to ``sys.path``.  Non-existing items

    32 are never added to ``sys.path``, but no check is made that the item refers to a

    33 directory (rather than a file).  No item is added to ``sys.path`` more than

    34 once.  Blank lines and lines beginning with ``#`` are skipped.  Lines starting

    35 with ``import`` (followed by space or tab) are executed.

    36 

    37 .. versionchanged:: 2.6

    38    A space or tab is now required after the import keyword.

    39 

    40 .. index::

    41    single: package

    42    triple: path; configuration; file

    43 

    44 For example, suppose ``sys.prefix`` and ``sys.exec_prefix`` are set to

    45 :file:`/usr/local`.  The Python X.Y library is then installed in

    46 :file:`/usr/local/lib/python{X.Y}` (where only the first three characters of

    47 ``sys.version`` are used to form the installation path name).  Suppose this has

    48 a subdirectory :file:`/usr/local/lib/python{X.Y}/site-packages` with three

    49 subsubdirectories, :file:`foo`, :file:`bar` and :file:`spam`, and two path

    50 configuration files, :file:`foo.pth` and :file:`bar.pth`.  Assume

    51 :file:`foo.pth` contains the following::

    52 

    53    # foo package configuration

    54 

    55    foo

    56    bar

    57    bletch

    58 

    59 and :file:`bar.pth` contains::

    60 

    61    # bar package configuration

    62 

    63    bar

    64 

    65 Then the following version-specific directories are added to

    66 ``sys.path``, in this order::

    67 

    68    /usr/local/lib/pythonX.Y/site-packages/bar

    69    /usr/local/lib/pythonX.Y/site-packages/foo

    70 

    71 Note that :file:`bletch` is omitted because it doesn't exist; the :file:`bar`

    72 directory precedes the :file:`foo` directory because :file:`bar.pth` comes

    73 alphabetically before :file:`foo.pth`; and :file:`spam` is omitted because it is

    74 not mentioned in either path configuration file.

    75 

    76 .. index:: module: sitecustomize

    77 

    78 After these path manipulations, an attempt is made to import a module named

    79 :mod:`sitecustomize`, which can perform arbitrary site-specific customizations.

    80 If this import fails with an :exc:`ImportError` exception, it is silently

    81 ignored.

    82 

    83 .. index:: module: sitecustomize

    84 

    85 Note that for some non-Unix systems, ``sys.prefix`` and ``sys.exec_prefix`` are

    86 empty, and the path manipulations are skipped; however the import of

    87 :mod:`sitecustomize` is still attempted.

    88 

    89 

    90 .. data:: PREFIXES

    91 

    92    A list of prefixes for site package directories

    93 

    94    .. versionadded:: 2.6

    95 

    96 

    97 .. data:: ENABLE_USER_SITE

    98 

    99    Flag showing the status of the user site directory. True means the

   100    user site directory is enabled and added to sys.path. When the flag

   101    is None the user site directory is disabled for security reasons.

   102 

   103    .. versionadded:: 2.6

   104 

   105 

   106 .. data:: USER_SITE

   107 

   108    Path to the user site directory for the current Python version or None

   109 

   110    .. versionadded:: 2.6

   111 

   112 

   113 .. data:: USER_BASE

   114 

   115    Path to the base directory for user site directories

   116 

   117    .. versionadded:: 2.6

   118 

   119 

   120 .. envvar:: PYTHONNOUSERSITE

   121 

   122    .. versionadded:: 2.6

   123 

   124 

   125 .. envvar:: PYTHONUSERBASE

   126 

   127    .. versionadded:: 2.6

   128 

   129 

   130 .. function:: addsitedir(sitedir, known_paths=None)

   131 

   132    Adds a directory to sys.path and processes its pth files.

   133 

   134 

   135 XXX Update documentation

   136 XXX document python -m site --user-base --user-site