Guido van Rossum | 36764b8 | 1997-08-30 20:02:25 +0000 | [diff] [blame] | 1 | \section{Standard Module \sectcode{user}} |
| 2 | \label{module-user} |
| 3 | \stmodindex{user} |
Fred Drake | 18f9f53 | 1998-01-13 18:45:34 +0000 | [diff] [blame] | 4 | \indexii{.pythonrc.py}{file} |
| 5 | \indexiii{user}{configuration}{file} |
Guido van Rossum | 36764b8 | 1997-08-30 20:02:25 +0000 | [diff] [blame] | 6 | |
| 7 | As a policy, Python doesn't run user-specified code on startup of |
| 8 | Python programs. (Only interactive sessions execute the script |
Guido van Rossum | 8291bb3 | 1997-12-09 19:46:45 +0000 | [diff] [blame] | 9 | specified in the \code{PYTHONSTARTUP} environment variable if it exists). |
Guido van Rossum | 36764b8 | 1997-08-30 20:02:25 +0000 | [diff] [blame] | 10 | |
| 11 | However, some programs or sites may find it convenient to allow users |
| 12 | to have a standard customization file, which gets run when a program |
| 13 | requests it. This module implements such a mechanism. A program |
| 14 | that wishes to use the mechanism must execute the statement |
| 15 | |
Fred Drake | 8d0ff31 | 1998-01-09 22:27:55 +0000 | [diff] [blame] | 16 | \begin{verbatim} |
Guido van Rossum | 36764b8 | 1997-08-30 20:02:25 +0000 | [diff] [blame] | 17 | import user |
Fred Drake | 8d0ff31 | 1998-01-09 22:27:55 +0000 | [diff] [blame] | 18 | \end{verbatim} |
Guido van Rossum | 36764b8 | 1997-08-30 20:02:25 +0000 | [diff] [blame] | 19 | |
Fred Drake | 5493205 | 1997-12-16 14:41:36 +0000 | [diff] [blame] | 20 | The \code{user} module looks for a file \file{.pythonrc.py} in the user's |
Guido van Rossum | 36764b8 | 1997-08-30 20:02:25 +0000 | [diff] [blame] | 21 | home directory and if it can be opened, exececutes it (using |
| 22 | \code{execfile()}) in its own (i.e. the module \code{user}'s) global |
| 23 | namespace. Errors during this phase are not caught; that's up to the |
Fred Drake | 5493205 | 1997-12-16 14:41:36 +0000 | [diff] [blame] | 24 | program that imports the \code{user} module, if it wishes. The home |
Guido van Rossum | 36764b8 | 1997-08-30 20:02:25 +0000 | [diff] [blame] | 25 | directory is assumed to be named by the \code{HOME} environment |
| 26 | variable; if this is not set, the current directory is used. |
| 27 | |
| 28 | The user's \file{.pythonrc.py} could conceivably test for |
| 29 | \code{sys.version} if it wishes to do different things depending on |
| 30 | the Python version. |
| 31 | |
| 32 | A warning to users: be very conservative in what you place in your |
| 33 | \file{.pythonrc.py} file. Since you don't know which programs will |
| 34 | use it, changing the behavior of standard modules or functions is |
| 35 | generally not a good idea. |
| 36 | |
| 37 | A suggestion for programmers who wish to use this mechanism: a simple |
| 38 | way to let users specify options for your package is to have them |
Fred Drake | 9d2f7d4 | 1997-12-16 14:43:37 +0000 | [diff] [blame] | 39 | define variables in their \file{.pythonrc.py} file that you test in |
Guido van Rossum | 36764b8 | 1997-08-30 20:02:25 +0000 | [diff] [blame] | 40 | your module. For example, a module \code{spam} that has a verbosity |
| 41 | level can look for a variable \code{user.spam_verbose}, as follows: |
| 42 | |
Fred Drake | 1947991 | 1998-02-13 06:58:54 +0000 | [diff] [blame^] | 43 | \begin{verbatim} |
Guido van Rossum | 36764b8 | 1997-08-30 20:02:25 +0000 | [diff] [blame] | 44 | import user |
| 45 | try: |
| 46 | verbose = user.spam_verbose # user's verbosity preference |
| 47 | except AttributeError: |
| 48 | verbose = 0 # default verbosity |
Fred Drake | 1947991 | 1998-02-13 06:58:54 +0000 | [diff] [blame^] | 49 | \end{verbatim} |
Guido van Rossum | 36764b8 | 1997-08-30 20:02:25 +0000 | [diff] [blame] | 50 | |
| 51 | Programs with extensive customization needs are better off reading a |
| 52 | program-specific customization file. |
| 53 | |
| 54 | Programs with security or privacy concerns should \emph{not} import |
| 55 | this module; a user can easily break into a a program by placing |
| 56 | arbitrary code in the \file{.pythonrc.py} file. |
| 57 | |
| 58 | Modules for general use should \emph{not} import this module; it may |
| 59 | interfere with the operation of the importing program. |
| 60 | |
Fred Drake | 18f9f53 | 1998-01-13 18:45:34 +0000 | [diff] [blame] | 61 | \begin{seealso} |
| 62 | \seemodule{site}{site-wide customization mechanism} |
Fred Drake | 5493205 | 1997-12-16 14:41:36 +0000 | [diff] [blame] | 63 | \refstmodindex{site} |
Fred Drake | 18f9f53 | 1998-01-13 18:45:34 +0000 | [diff] [blame] | 64 | \end{seealso} |