Fred Drake | 295da24 | 1998-08-10 19:42:37 +0000 | [diff] [blame] | 1 | \section{\module{user} --- |
Fred Drake | bbac432 | 1999-02-20 00:14:17 +0000 | [diff] [blame] | 2 | User-specific configuration hook} |
Fred Drake | b91e934 | 1998-07-23 17:59:49 +0000 | [diff] [blame] | 3 | |
Fred Drake | bbac432 | 1999-02-20 00:14:17 +0000 | [diff] [blame] | 4 | \declaremodule{standard}{user} |
Fred Drake | b91e934 | 1998-07-23 17:59:49 +0000 | [diff] [blame] | 5 | \modulesynopsis{A standard way to reference user-specific modules.} |
| 6 | |
Fred Drake | bbac432 | 1999-02-20 00:14:17 +0000 | [diff] [blame] | 7 | |
Fred Drake | 18f9f53 | 1998-01-13 18:45:34 +0000 | [diff] [blame] | 8 | \indexii{.pythonrc.py}{file} |
| 9 | \indexiii{user}{configuration}{file} |
Guido van Rossum | 36764b8 | 1997-08-30 20:02:25 +0000 | [diff] [blame] | 10 | |
| 11 | As a policy, Python doesn't run user-specified code on startup of |
| 12 | Python programs. (Only interactive sessions execute the script |
Fred Drake | 7be8fcb | 1998-03-12 06:47:48 +0000 | [diff] [blame] | 13 | specified in the \envvar{PYTHONSTARTUP} environment variable if it |
| 14 | exists). |
Guido van Rossum | 36764b8 | 1997-08-30 20:02:25 +0000 | [diff] [blame] | 15 | |
| 16 | However, some programs or sites may find it convenient to allow users |
| 17 | to have a standard customization file, which gets run when a program |
| 18 | requests it. This module implements such a mechanism. A program |
| 19 | that wishes to use the mechanism must execute the statement |
| 20 | |
Fred Drake | 8d0ff31 | 1998-01-09 22:27:55 +0000 | [diff] [blame] | 21 | \begin{verbatim} |
Guido van Rossum | 36764b8 | 1997-08-30 20:02:25 +0000 | [diff] [blame] | 22 | import user |
Fred Drake | 8d0ff31 | 1998-01-09 22:27:55 +0000 | [diff] [blame] | 23 | \end{verbatim} |
Guido van Rossum | 36764b8 | 1997-08-30 20:02:25 +0000 | [diff] [blame] | 24 | |
Fred Drake | 8fab8cf | 1998-03-08 07:14:20 +0000 | [diff] [blame] | 25 | The \module{user} module looks for a file \file{.pythonrc.py} in the user's |
Thomas Wouters | f831663 | 2000-07-16 19:01:10 +0000 | [diff] [blame] | 26 | home directory and if it can be opened, executes it (using |
Fred Drake | 907e76b | 2001-07-06 20:30:11 +0000 | [diff] [blame] | 27 | \function{execfile()}\bifuncindex{execfile}) in its own (the |
Fred Drake | 8fab8cf | 1998-03-08 07:14:20 +0000 | [diff] [blame] | 28 | module \module{user}'s) global namespace. Errors during this phase |
| 29 | are not caught; that's up to the program that imports the |
| 30 | \module{user} module, if it wishes. The home directory is assumed to |
Fred Drake | 7be8fcb | 1998-03-12 06:47:48 +0000 | [diff] [blame] | 31 | be named by the \envvar{HOME} environment variable; if this is not set, |
Fred Drake | 8fab8cf | 1998-03-08 07:14:20 +0000 | [diff] [blame] | 32 | the current directory is used. |
Guido van Rossum | 36764b8 | 1997-08-30 20:02:25 +0000 | [diff] [blame] | 33 | |
| 34 | The user's \file{.pythonrc.py} could conceivably test for |
| 35 | \code{sys.version} if it wishes to do different things depending on |
| 36 | the Python version. |
| 37 | |
| 38 | A warning to users: be very conservative in what you place in your |
| 39 | \file{.pythonrc.py} file. Since you don't know which programs will |
| 40 | use it, changing the behavior of standard modules or functions is |
| 41 | generally not a good idea. |
| 42 | |
| 43 | A suggestion for programmers who wish to use this mechanism: a simple |
| 44 | 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] | 45 | define variables in their \file{.pythonrc.py} file that you test in |
Fred Drake | 8fab8cf | 1998-03-08 07:14:20 +0000 | [diff] [blame] | 46 | your module. For example, a module \module{spam} that has a verbosity |
Guido van Rossum | 36764b8 | 1997-08-30 20:02:25 +0000 | [diff] [blame] | 47 | level can look for a variable \code{user.spam_verbose}, as follows: |
| 48 | |
Fred Drake | 1947991 | 1998-02-13 06:58:54 +0000 | [diff] [blame] | 49 | \begin{verbatim} |
Guido van Rossum | 36764b8 | 1997-08-30 20:02:25 +0000 | [diff] [blame] | 50 | import user |
Fred Drake | ea49de3 | 2003-12-30 23:01:19 +0000 | [diff] [blame] | 51 | |
| 52 | verbose = bool(getattr(user, "spam_verbose", 0)) |
Fred Drake | 1947991 | 1998-02-13 06:58:54 +0000 | [diff] [blame] | 53 | \end{verbatim} |
Guido van Rossum | 36764b8 | 1997-08-30 20:02:25 +0000 | [diff] [blame] | 54 | |
Fred Drake | ea49de3 | 2003-12-30 23:01:19 +0000 | [diff] [blame] | 55 | (The three-argument form of \function{getattr()} is used in case |
| 56 | the user has not defined \code{spam_verbose} in their |
| 57 | \file{.pythonrc.py} file.) |
| 58 | |
Guido van Rossum | 36764b8 | 1997-08-30 20:02:25 +0000 | [diff] [blame] | 59 | Programs with extensive customization needs are better off reading a |
| 60 | program-specific customization file. |
| 61 | |
| 62 | Programs with security or privacy concerns should \emph{not} import |
Fred Drake | d8a41e6 | 1999-02-19 17:54:10 +0000 | [diff] [blame] | 63 | this module; a user can easily break into a program by placing |
Guido van Rossum | 36764b8 | 1997-08-30 20:02:25 +0000 | [diff] [blame] | 64 | arbitrary code in the \file{.pythonrc.py} file. |
| 65 | |
| 66 | Modules for general use should \emph{not} import this module; it may |
| 67 | interfere with the operation of the importing program. |
| 68 | |
Fred Drake | 18f9f53 | 1998-01-13 18:45:34 +0000 | [diff] [blame] | 69 | \begin{seealso} |
Fred Drake | ba0a989 | 2000-10-18 17:43:06 +0000 | [diff] [blame] | 70 | \seemodule{site}{Site-wide customization mechanism.} |
Fred Drake | 18f9f53 | 1998-01-13 18:45:34 +0000 | [diff] [blame] | 71 | \end{seealso} |