/Doc/library/site.rst

http://unladen-swallow.googlecode.com/ · ReStructuredText · 136 lines · 85 code · 51 blank · 0 comment · 0 complexity · ed618439ce93ba8f09b1327b4159515c MD5 · raw file

  1. :mod:`site` --- Site-specific configuration hook
  2. ================================================
  3. .. module:: site
  4. :synopsis: A standard way to reference site-specific modules.
  5. **This module is automatically imported during initialization.** The automatic
  6. import can be suppressed using the interpreter's :option:`-S` option.
  7. .. index:: triple: module; search; path
  8. Importing this module will append site-specific paths to the module search path.
  9. .. index::
  10. pair: site-python; directory
  11. pair: site-packages; directory
  12. It starts by constructing up to four directories from a head and a tail part.
  13. For the head part, it uses ``sys.prefix`` and ``sys.exec_prefix``; empty heads
  14. are skipped. For the tail part, it uses the empty string and then
  15. :file:`lib/site-packages` (on Windows) or
  16. :file:`lib/python|version|/site-packages` and then :file:`lib/site-python` (on
  17. Unix and Macintosh). For each of the distinct head-tail combinations, it sees
  18. if it refers to an existing directory, and if so, adds it to ``sys.path`` and
  19. also inspects the newly added path for configuration files.
  20. A path configuration file is a file whose name has the form :file:`package.pth`
  21. and exists in one of the four directories mentioned above; its contents are
  22. additional items (one per line) to be added to ``sys.path``. Non-existing items
  23. are never added to ``sys.path``, but no check is made that the item refers to a
  24. directory (rather than a file). No item is added to ``sys.path`` more than
  25. once. Blank lines and lines beginning with ``#`` are skipped. Lines starting
  26. with ``import`` (followed by space or tab) are executed.
  27. .. versionchanged:: 2.6
  28. A space or tab is now required after the import keyword.
  29. .. index::
  30. single: package
  31. triple: path; configuration; file
  32. For example, suppose ``sys.prefix`` and ``sys.exec_prefix`` are set to
  33. :file:`/usr/local`. The Python X.Y library is then installed in
  34. :file:`/usr/local/lib/python{X.Y}` (where only the first three characters of
  35. ``sys.version`` are used to form the installation path name). Suppose this has
  36. a subdirectory :file:`/usr/local/lib/python{X.Y}/site-packages` with three
  37. subsubdirectories, :file:`foo`, :file:`bar` and :file:`spam`, and two path
  38. configuration files, :file:`foo.pth` and :file:`bar.pth`. Assume
  39. :file:`foo.pth` contains the following::
  40. # foo package configuration
  41. foo
  42. bar
  43. bletch
  44. and :file:`bar.pth` contains::
  45. # bar package configuration
  46. bar
  47. Then the following version-specific directories are added to
  48. ``sys.path``, in this order::
  49. /usr/local/lib/pythonX.Y/site-packages/bar
  50. /usr/local/lib/pythonX.Y/site-packages/foo
  51. Note that :file:`bletch` is omitted because it doesn't exist; the :file:`bar`
  52. directory precedes the :file:`foo` directory because :file:`bar.pth` comes
  53. alphabetically before :file:`foo.pth`; and :file:`spam` is omitted because it is
  54. not mentioned in either path configuration file.
  55. .. index:: module: sitecustomize
  56. After these path manipulations, an attempt is made to import a module named
  57. :mod:`sitecustomize`, which can perform arbitrary site-specific customizations.
  58. If this import fails with an :exc:`ImportError` exception, it is silently
  59. ignored.
  60. .. index:: module: sitecustomize
  61. Note that for some non-Unix systems, ``sys.prefix`` and ``sys.exec_prefix`` are
  62. empty, and the path manipulations are skipped; however the import of
  63. :mod:`sitecustomize` is still attempted.
  64. .. data:: PREFIXES
  65. A list of prefixes for site package directories
  66. .. versionadded:: 2.6
  67. .. data:: ENABLE_USER_SITE
  68. Flag showing the status of the user site directory. True means the
  69. user site directory is enabled and added to sys.path. When the flag
  70. is None the user site directory is disabled for security reasons.
  71. .. versionadded:: 2.6
  72. .. data:: USER_SITE
  73. Path to the user site directory for the current Python version or None
  74. .. versionadded:: 2.6
  75. .. data:: USER_BASE
  76. Path to the base directory for user site directories
  77. .. versionadded:: 2.6
  78. .. envvar:: PYTHONNOUSERSITE
  79. .. versionadded:: 2.6
  80. .. envvar:: PYTHONUSERBASE
  81. .. versionadded:: 2.6
  82. .. function:: addsitedir(sitedir, known_paths=None)
  83. Adds a directory to sys.path and processes its pth files.
  84. .. XXX Update documentation
  85. .. XXX document python -m site --user-base --user-site