| \section{\module{user} --- |
| A standard way to reference user-specific modules.} |
| \declaremodule{standard}{user} |
| |
| \modulesynopsis{A standard way to reference user-specific modules.} |
| |
| \indexii{.pythonrc.py}{file} |
| \indexiii{user}{configuration}{file} |
| |
| As a policy, Python doesn't run user-specified code on startup of |
| Python programs. (Only interactive sessions execute the script |
| specified in the \envvar{PYTHONSTARTUP} environment variable if it |
| exists). |
| |
| However, some programs or sites may find it convenient to allow users |
| to have a standard customization file, which gets run when a program |
| requests it. This module implements such a mechanism. A program |
| that wishes to use the mechanism must execute the statement |
| |
| \begin{verbatim} |
| import user |
| \end{verbatim} |
| |
| The \module{user} module looks for a file \file{.pythonrc.py} in the user's |
| home directory and if it can be opened, exececutes it (using |
| \function{execfile()}\bifuncindex{execfile}) in its own (i.e. the |
| module \module{user}'s) global namespace. Errors during this phase |
| are not caught; that's up to the program that imports the |
| \module{user} module, if it wishes. The home directory is assumed to |
| be named by the \envvar{HOME} environment variable; if this is not set, |
| the current directory is used. |
| |
| The user's \file{.pythonrc.py} could conceivably test for |
| \code{sys.version} if it wishes to do different things depending on |
| the Python version. |
| |
| A warning to users: be very conservative in what you place in your |
| \file{.pythonrc.py} file. Since you don't know which programs will |
| use it, changing the behavior of standard modules or functions is |
| generally not a good idea. |
| |
| A suggestion for programmers who wish to use this mechanism: a simple |
| way to let users specify options for your package is to have them |
| define variables in their \file{.pythonrc.py} file that you test in |
| your module. For example, a module \module{spam} that has a verbosity |
| level can look for a variable \code{user.spam_verbose}, as follows: |
| |
| \begin{verbatim} |
| import user |
| try: |
| verbose = user.spam_verbose # user's verbosity preference |
| except AttributeError: |
| verbose = 0 # default verbosity |
| \end{verbatim} |
| |
| Programs with extensive customization needs are better off reading a |
| program-specific customization file. |
| |
| Programs with security or privacy concerns should \emph{not} import |
| this module; a user can easily break into a program by placing |
| arbitrary code in the \file{.pythonrc.py} file. |
| |
| Modules for general use should \emph{not} import this module; it may |
| interfere with the operation of the importing program. |
| |
| \begin{seealso} |
| \seemodule{site}{site-wide customization mechanism} |
| \refstmodindex{site} |
| \end{seealso} |