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