Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 37 | .. index:: |
| 38 | single: package |
| 39 | triple: path; configuration; file |
| 40 | |
| 41 | For example, suppose ``sys.prefix`` and ``sys.exec_prefix`` are set to |
| 42 | :file:`/usr/local`. The Python X.Y library is then installed in |
| 43 | :file:`/usr/local/lib/python{X.Y}` (where only the first three characters of |
| 44 | ``sys.version`` are used to form the installation path name). Suppose this has |
| 45 | a subdirectory :file:`/usr/local/lib/python{X.Y}/site-packages` with three |
| 46 | subsubdirectories, :file:`foo`, :file:`bar` and :file:`spam`, and two path |
| 47 | configuration files, :file:`foo.pth` and :file:`bar.pth`. Assume |
| 48 | :file:`foo.pth` contains the following:: |
| 49 | |
| 50 | # foo package configuration |
| 51 | |
| 52 | foo |
| 53 | bar |
| 54 | bletch |
| 55 | |
| 56 | and :file:`bar.pth` contains:: |
| 57 | |
| 58 | # bar package configuration |
| 59 | |
| 60 | bar |
| 61 | |
Benjamin Peterson | e9bbc8b | 2008-09-28 02:06:32 +0000 | [diff] [blame] | 62 | Then the following version-specific directories are added to |
| 63 | ``sys.path``, in this order:: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 64 | |
Benjamin Peterson | e9bbc8b | 2008-09-28 02:06:32 +0000 | [diff] [blame] | 65 | /usr/local/lib/pythonX.Y/site-packages/bar |
| 66 | /usr/local/lib/pythonX.Y/site-packages/foo |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 67 | |
| 68 | Note that :file:`bletch` is omitted because it doesn't exist; the :file:`bar` |
| 69 | directory precedes the :file:`foo` directory because :file:`bar.pth` comes |
| 70 | alphabetically before :file:`foo.pth`; and :file:`spam` is omitted because it is |
| 71 | not mentioned in either path configuration file. |
| 72 | |
| 73 | .. index:: module: sitecustomize |
| 74 | |
| 75 | After these path manipulations, an attempt is made to import a module named |
| 76 | :mod:`sitecustomize`, which can perform arbitrary site-specific customizations. |
| 77 | If this import fails with an :exc:`ImportError` exception, it is silently |
| 78 | ignored. |
| 79 | |
| 80 | .. index:: module: sitecustomize |
| 81 | |
| 82 | Note that for some non-Unix systems, ``sys.prefix`` and ``sys.exec_prefix`` are |
| 83 | empty, and the path manipulations are skipped; however the import of |
| 84 | :mod:`sitecustomize` is still attempted. |
| 85 | |
Christian Heimes | 8dc226f | 2008-05-06 23:45:46 +0000 | [diff] [blame] | 86 | |
| 87 | .. data:: PREFIXES |
| 88 | |
| 89 | A list of prefixes for site package directories |
| 90 | |
Christian Heimes | 8dc226f | 2008-05-06 23:45:46 +0000 | [diff] [blame] | 91 | |
| 92 | .. data:: ENABLE_USER_SITE |
| 93 | |
| 94 | Flag showing the status of the user site directory. True means the |
| 95 | user site directory is enabled and added to sys.path. When the flag |
| 96 | is None the user site directory is disabled for security reasons. |
| 97 | |
Christian Heimes | 8dc226f | 2008-05-06 23:45:46 +0000 | [diff] [blame] | 98 | |
| 99 | .. data:: USER_SITE |
| 100 | |
| 101 | Path to the user site directory for the current Python version or None |
| 102 | |
Christian Heimes | 8dc226f | 2008-05-06 23:45:46 +0000 | [diff] [blame] | 103 | |
| 104 | .. data:: USER_BASE |
| 105 | |
| 106 | Path to the base directory for user site directories |
| 107 | |
Christian Heimes | 8dc226f | 2008-05-06 23:45:46 +0000 | [diff] [blame] | 108 | |
| 109 | .. envvar:: PYTHONNOUSERSITE |
| 110 | |
Christian Heimes | 8dc226f | 2008-05-06 23:45:46 +0000 | [diff] [blame] | 111 | |
| 112 | .. envvar:: PYTHONUSERBASE |
| 113 | |
Christian Heimes | 8dc226f | 2008-05-06 23:45:46 +0000 | [diff] [blame] | 114 | |
| 115 | .. function:: addsitedir(sitedir, known_paths=None) |
| 116 | |
| 117 | Adds a directory to sys.path and processes its pth files. |
| 118 | |
| 119 | |
| 120 | XXX Update documentation |
| 121 | XXX document python -m site --user-base --user-site |