/Doc/library/site.rst

  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
 10import can be suppressed using the interpreter's :option:`-S` option.
 11
 12.. index:: triple: module; search; path
 13
 14Importing 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
 20It starts by constructing up to four directories from a head and a tail part.
 21For the head part, it uses ``sys.prefix`` and ``sys.exec_prefix``; empty heads
 22are 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
 25Unix and Macintosh).  For each of the distinct head-tail combinations, it sees
 26if it refers to an existing directory, and if so, adds it to ``sys.path`` and
 27also inspects the newly added path for configuration files.
 28
 29A path configuration file is a file whose name has the form :file:`package.pth`
 30and exists in one of the four directories mentioned above; its contents are
 31additional items (one per line) to be added to ``sys.path``.  Non-existing items
 32are never added to ``sys.path``, but no check is made that the item refers to a
 33directory (rather than a file).  No item is added to ``sys.path`` more than
 34once.  Blank lines and lines beginning with ``#`` are skipped.  Lines starting
 35with ``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
 44For 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
 48a subdirectory :file:`/usr/local/lib/python{X.Y}/site-packages` with three
 49subsubdirectories, :file:`foo`, :file:`bar` and :file:`spam`, and two path
 50configuration 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
 59and :file:`bar.pth` contains::
 60
 61   # bar package configuration
 62
 63   bar
 64
 65Then 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
 71Note that :file:`bletch` is omitted because it doesn't exist; the :file:`bar`
 72directory precedes the :file:`foo` directory because :file:`bar.pth` comes
 73alphabetically before :file:`foo.pth`; and :file:`spam` is omitted because it is
 74not mentioned in either path configuration file.
 75
 76.. index:: module: sitecustomize
 77
 78After these path manipulations, an attempt is made to import a module named
 79:mod:`sitecustomize`, which can perform arbitrary site-specific customizations.
 80If this import fails with an :exc:`ImportError` exception, it is silently
 81ignored.
 82
 83.. index:: module: sitecustomize
 84
 85Note that for some non-Unix systems, ``sys.prefix`` and ``sys.exec_prefix`` are
 86empty, 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