Guido van Rossum | 571391b | 1997-04-03 22:41:49 +0000 | [diff] [blame] | 1 | \section{Standard Module \sectcode{site}} |
Guido van Rossum | e47da0a | 1997-07-17 16:34:52 +0000 | [diff] [blame] | 2 | \label{module-site} |
Guido van Rossum | 571391b | 1997-04-03 22:41:49 +0000 | [diff] [blame] | 3 | \stmodindex{site} |
| 4 | |
Guido van Rossum | 28cad96 | 1997-08-30 20:03:28 +0000 | [diff] [blame] | 5 | \strong{This module is automatically imported during initialization.} |
Guido van Rossum | 571391b | 1997-04-03 22:41:49 +0000 | [diff] [blame] | 6 | |
Guido van Rossum | 28cad96 | 1997-08-30 20:03:28 +0000 | [diff] [blame] | 7 | In earlier versions of Python (up to and including 1.5a3), scripts or |
| 8 | modules that needed to use site-specific modules would place |
| 9 | \code{import site} somewhere near the top of their code. This is no |
| 10 | longer necessary. |
Guido van Rossum | 571391b | 1997-04-03 22:41:49 +0000 | [diff] [blame] | 11 | |
Guido van Rossum | f01dff7 | 1997-09-03 22:05:54 +0000 | [diff] [blame^] | 12 | This will append site-specific paths to to the module search path. |
| 13 | |
| 14 | It starts by constructing up to four directories from a head and a |
| 15 | tail part. For the head part, it uses \code{sys.prefix} and |
| 16 | \code{sys.exec_prefix}; empty heads are skipped. For |
| 17 | the tail part, it uses the empty string (on Mac or Windows) or it uses |
| 18 | first \file{lib/python\var{version}/packages} and then |
| 19 | \file{lib/site-python} (on Unix). For each of the distinct head-tail |
| 20 | combinations, it sees if it refers to an existing directory, and if |
| 21 | so, adds to \code{sys.path}, and also inspected for path configuration |
| 22 | files. |
| 23 | \indexii{site-python}{directory} |
| 24 | \indexii{packages}{directory} |
| 25 | |
| 26 | A path configuration file is a file whose name has the form |
| 27 | \file{\var{package}.pth}; its contents are additional items (one |
| 28 | per line) to be added to \code{sys.path}. Non-existing items are |
| 29 | never added to \code{sys.path}, but no check is made that the item |
| 30 | refers to a directory (rather than a file). No item is added to |
Guido van Rossum | 28cad96 | 1997-08-30 20:03:28 +0000 | [diff] [blame] | 31 | \code{sys.path} more than once. Blank lines and lines beginning with |
| 32 | \code{\#} are skipped. |
| 33 | \index{package} |
Guido van Rossum | f01dff7 | 1997-09-03 22:05:54 +0000 | [diff] [blame^] | 34 | \indexiii{path}{configuration}{file} |
Guido van Rossum | 28cad96 | 1997-08-30 20:03:28 +0000 | [diff] [blame] | 35 | \kwindex{sys.prefix} |
| 36 | \kwindex{sys.exec_prefix} |
| 37 | \kwindex{prefix} |
| 38 | \kwindex{exec_prefix} |
| 39 | |
| 40 | For example, suppose \code{sys.prefix} and \code{sys.exec_prefix} are |
| 41 | set to \file{/usr/local}. The Python 1.5 library is then installed in |
| 42 | \file{/usr/local/lib/python1.5}. Suppose this has a subdirectory |
| 43 | \file{/usr/local/python1.5/packages} with three subsubdirectories, |
| 44 | \file{foo}, \file{bar} and \file{spam}, and two path configuration |
| 45 | files, \file{foo.pth} and \file{bar.pth}. Assume \file{foo.pth} |
| 46 | contains the following: |
| 47 | |
| 48 | \bcode\begin{verbatim} |
| 49 | # foo package configuration |
| 50 | |
| 51 | foo |
| 52 | bar |
| 53 | bletch |
| 54 | \end{verbatim}\ecode |
| 55 | |
| 56 | and \file{bar.pth} contains: |
| 57 | |
| 58 | \bcode\begin{verbatim} |
| 59 | # bar package configuration |
| 60 | |
| 61 | bar |
| 62 | \end{verbatim}\ecode |
| 63 | |
| 64 | Then the following directories are added to sys.path, in this order: |
| 65 | |
| 66 | \bcode\begin{verbatim} |
| 67 | /usr/local/python1.5/packages/bar |
| 68 | /usr/local/python1.5/packages/foo |
| 69 | \end{verbatim}\ecode |
| 70 | |
| 71 | Note that \file{bletch} is omitted because it doesn't exist; the |
| 72 | \file{bar} directory precedes the \file{foo} directory because |
| 73 | \file{bar.pth} comes alphabetically before \file{foo.pth}; and |
| 74 | \file{spam} is omitted because it is not mentioned in either path |
| 75 | configuration file. |
Guido van Rossum | 571391b | 1997-04-03 22:41:49 +0000 | [diff] [blame] | 76 | |
| 77 | After these path manipulations, an attempt is made to import a module |
| 78 | named \code{sitecustomize}, which can perform arbitrary site-specific |
| 79 | customizations. If this import fails with an \code{ImportError} |
Guido van Rossum | 28cad96 | 1997-08-30 20:03:28 +0000 | [diff] [blame] | 80 | exception, it is silently ignored. |
| 81 | \stmodindex{sitecustomize} |
Guido van Rossum | 571391b | 1997-04-03 22:41:49 +0000 | [diff] [blame] | 82 | |
Guido van Rossum | 28cad96 | 1997-08-30 20:03:28 +0000 | [diff] [blame] | 83 | Note that for some non-Unix systems, \code{sys.prefix} and |
Guido van Rossum | 571391b | 1997-04-03 22:41:49 +0000 | [diff] [blame] | 84 | \code{sys.exec_prefix} are empty, and the path manipulations are |
| 85 | skipped; however the import of \code{sitecustomize} is still attempted. |