mirror of
https://github.com/python/cpython.git
synced 2024-11-26 03:14:27 +08:00
ba0a989988
letter and end with proper punctuation. "Documenting Python" will be updated accordingly so that this will be editorial policy for the Python documentation.
70 lines
2.6 KiB
TeX
70 lines
2.6 KiB
TeX
\section{\module{user} ---
|
|
User-specific configuration hook}
|
|
|
|
\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, executes 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.}
|
|
\end{seealso}
|