Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libuser.tex @ 39042:c02fa187e0f4 legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Part of SF patch #1484695. This removes dead code. The chksum was already verified in .frombuf() on the lines above. If there was a problem an exception is raised, so there was no way this condition could have been true.
author Neal Norwitz <nnorwitz@gmail.com>
date Mon, 10 Jul 2006 00:23:17 +0000
parents fd4cbbeace79
children ac192f89c109
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
8918
acfffe14628e New section header style.
Fred Drake <fdrake@acm.org>
parents: 8716
diff changeset
1 \section{\module{user} ---
10251
d83935d14084 Shorten a few section titles.
Fred Drake <fdrake@acm.org>
parents: 10243
diff changeset
2 User-specific configuration hook}
d83935d14084 Shorten a few section titles.
Fred Drake <fdrake@acm.org>
parents: 10243
diff changeset
3
8716
760dcf197048 Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
4 \declaremodule{standard}{user}
10251
d83935d14084 Shorten a few section titles.
Fred Drake <fdrake@acm.org>
parents: 10243
diff changeset
5 \modulesynopsis{A standard way to reference user-specific modules.}
8716
760dcf197048 Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
6
760dcf197048 Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
7
7080
924f8a0117d5 Removed obsolete \kwindex{} call.
Fred Drake <fdrake@acm.org>
parents: 7052
diff changeset
8 \indexii{.pythonrc.py}{file}
924f8a0117d5 Removed obsolete \kwindex{} call.
Fred Drake <fdrake@acm.org>
parents: 7052
diff changeset
9 \indexiii{user}{configuration}{file}
6207
9c2ee6bbdbb3 Added docs for 'user' customization module. Renamed libuser.tex
Guido van Rossum <guido@python.org>
parents:
diff changeset
10
9c2ee6bbdbb3 Added docs for 'user' customization module. Renamed libuser.tex
Guido van Rossum <guido@python.org>
parents:
diff changeset
11 As a policy, Python doesn't run user-specified code on startup of
9c2ee6bbdbb3 Added docs for 'user' customization module. Renamed libuser.tex
Guido van Rossum <guido@python.org>
parents:
diff changeset
12 Python programs. (Only interactive sessions execute the script
7662
ea2d3217d0c7 Use \envvar{FOO} instead of \code{\$FOO}.
Fred Drake <fdrake@acm.org>
parents: 7610
diff changeset
13 specified in the \envvar{PYTHONSTARTUP} environment variable if it
ea2d3217d0c7 Use \envvar{FOO} instead of \code{\$FOO}.
Fred Drake <fdrake@acm.org>
parents: 7610
diff changeset
14 exists).
6207
9c2ee6bbdbb3 Added docs for 'user' customization module. Renamed libuser.tex
Guido van Rossum <guido@python.org>
parents:
diff changeset
15
9c2ee6bbdbb3 Added docs for 'user' customization module. Renamed libuser.tex
Guido van Rossum <guido@python.org>
parents:
diff changeset
16 However, some programs or sites may find it convenient to allow users
9c2ee6bbdbb3 Added docs for 'user' customization module. Renamed libuser.tex
Guido van Rossum <guido@python.org>
parents:
diff changeset
17 to have a standard customization file, which gets run when a program
9c2ee6bbdbb3 Added docs for 'user' customization module. Renamed libuser.tex
Guido van Rossum <guido@python.org>
parents:
diff changeset
18 requests it. This module implements such a mechanism. A program
9c2ee6bbdbb3 Added docs for 'user' customization module. Renamed libuser.tex
Guido van Rossum <guido@python.org>
parents:
diff changeset
19 that wishes to use the mechanism must execute the statement
9c2ee6bbdbb3 Added docs for 'user' customization module. Renamed libuser.tex
Guido van Rossum <guido@python.org>
parents:
diff changeset
20
7052
502880af4654 Simplify markup.
Fred Drake <fdrake@acm.org>
parents: 6878
diff changeset
21 \begin{verbatim}
6207
9c2ee6bbdbb3 Added docs for 'user' customization module. Renamed libuser.tex
Guido van Rossum <guido@python.org>
parents:
diff changeset
22 import user
7052
502880af4654 Simplify markup.
Fred Drake <fdrake@acm.org>
parents: 6878
diff changeset
23 \end{verbatim}
6207
9c2ee6bbdbb3 Added docs for 'user' customization module. Renamed libuser.tex
Guido van Rossum <guido@python.org>
parents:
diff changeset
24
7610
70bcbcdda74f Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
25 The \module{user} module looks for a file \file{.pythonrc.py} in the user's
13625
fdfd1049f36e Rob W. W. Hooft's spelling fixes for the Library Reference. I hope
Thomas Wouters <thomas@python.org>
parents: 10251
diff changeset
26 home directory and if it can be opened, executes it (using
18416
33b4357aebb8 Fix up a few style nits -- avoid "e.g." and "i.e." -- these make
Fred Drake <fdrake@acm.org>
parents: 15261
diff changeset
27 \function{execfile()}\bifuncindex{execfile}) in its own (the
7610
70bcbcdda74f Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
28 module \module{user}'s) global namespace. Errors during this phase
70bcbcdda74f Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
29 are not caught; that's up to the program that imports the
70bcbcdda74f Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
30 \module{user} module, if it wishes. The home directory is assumed to
7662
ea2d3217d0c7 Use \envvar{FOO} instead of \code{\$FOO}.
Fred Drake <fdrake@acm.org>
parents: 7610
diff changeset
31 be named by the \envvar{HOME} environment variable; if this is not set,
7610
70bcbcdda74f Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
32 the current directory is used.
6207
9c2ee6bbdbb3 Added docs for 'user' customization module. Renamed libuser.tex
Guido van Rossum <guido@python.org>
parents:
diff changeset
33
9c2ee6bbdbb3 Added docs for 'user' customization module. Renamed libuser.tex
Guido van Rossum <guido@python.org>
parents:
diff changeset
34 The user's \file{.pythonrc.py} could conceivably test for
9c2ee6bbdbb3 Added docs for 'user' customization module. Renamed libuser.tex
Guido van Rossum <guido@python.org>
parents:
diff changeset
35 \code{sys.version} if it wishes to do different things depending on
9c2ee6bbdbb3 Added docs for 'user' customization module. Renamed libuser.tex
Guido van Rossum <guido@python.org>
parents:
diff changeset
36 the Python version.
9c2ee6bbdbb3 Added docs for 'user' customization module. Renamed libuser.tex
Guido van Rossum <guido@python.org>
parents:
diff changeset
37
9c2ee6bbdbb3 Added docs for 'user' customization module. Renamed libuser.tex
Guido van Rossum <guido@python.org>
parents:
diff changeset
38 A warning to users: be very conservative in what you place in your
9c2ee6bbdbb3 Added docs for 'user' customization module. Renamed libuser.tex
Guido van Rossum <guido@python.org>
parents:
diff changeset
39 \file{.pythonrc.py} file. Since you don't know which programs will
9c2ee6bbdbb3 Added docs for 'user' customization module. Renamed libuser.tex
Guido van Rossum <guido@python.org>
parents:
diff changeset
40 use it, changing the behavior of standard modules or functions is
9c2ee6bbdbb3 Added docs for 'user' customization module. Renamed libuser.tex
Guido van Rossum <guido@python.org>
parents:
diff changeset
41 generally not a good idea.
9c2ee6bbdbb3 Added docs for 'user' customization module. Renamed libuser.tex
Guido van Rossum <guido@python.org>
parents:
diff changeset
42
9c2ee6bbdbb3 Added docs for 'user' customization module. Renamed libuser.tex
Guido van Rossum <guido@python.org>
parents:
diff changeset
43 A suggestion for programmers who wish to use this mechanism: a simple
9c2ee6bbdbb3 Added docs for 'user' customization module. Renamed libuser.tex
Guido van Rossum <guido@python.org>
parents:
diff changeset
44 way to let users specify options for your package is to have them
6878
e285a15f3a92 Oops, ".pythonrc.py" should *always* be marked with \file{}; one occurrance
Fred Drake <fdrake@acm.org>
parents: 6877
diff changeset
45 define variables in their \file{.pythonrc.py} file that you test in
7610
70bcbcdda74f Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
46 your module. For example, a module \module{spam} that has a verbosity
6207
9c2ee6bbdbb3 Added docs for 'user' customization module. Renamed libuser.tex
Guido van Rossum <guido@python.org>
parents:
diff changeset
47 level can look for a variable \code{user.spam_verbose}, as follows:
9c2ee6bbdbb3 Added docs for 'user' customization module. Renamed libuser.tex
Guido van Rossum <guido@python.org>
parents:
diff changeset
48
7277
bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous
Fred Drake <fdrake@acm.org>
parents: 7080
diff changeset
49 \begin{verbatim}
6207
9c2ee6bbdbb3 Added docs for 'user' customization module. Renamed libuser.tex
Guido van Rossum <guido@python.org>
parents:
diff changeset
50 import user
31288
fd4cbbeace79 minor cleanup of example
Fred Drake <fdrake@acm.org>
parents: 18416
diff changeset
51
fd4cbbeace79 minor cleanup of example
Fred Drake <fdrake@acm.org>
parents: 18416
diff changeset
52 verbose = bool(getattr(user, "spam_verbose", 0))
7277
bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous
Fred Drake <fdrake@acm.org>
parents: 7080
diff changeset
53 \end{verbatim}
6207
9c2ee6bbdbb3 Added docs for 'user' customization module. Renamed libuser.tex
Guido van Rossum <guido@python.org>
parents:
diff changeset
54
31288
fd4cbbeace79 minor cleanup of example
Fred Drake <fdrake@acm.org>
parents: 18416
diff changeset
55 (The three-argument form of \function{getattr()} is used in case
fd4cbbeace79 minor cleanup of example
Fred Drake <fdrake@acm.org>
parents: 18416
diff changeset
56 the user has not defined \code{spam_verbose} in their
fd4cbbeace79 minor cleanup of example
Fred Drake <fdrake@acm.org>
parents: 18416
diff changeset
57 \file{.pythonrc.py} file.)
fd4cbbeace79 minor cleanup of example
Fred Drake <fdrake@acm.org>
parents: 18416
diff changeset
58
6207
9c2ee6bbdbb3 Added docs for 'user' customization module. Renamed libuser.tex
Guido van Rossum <guido@python.org>
parents:
diff changeset
59 Programs with extensive customization needs are better off reading a
9c2ee6bbdbb3 Added docs for 'user' customization module. Renamed libuser.tex
Guido van Rossum <guido@python.org>
parents:
diff changeset
60 program-specific customization file.
9c2ee6bbdbb3 Added docs for 'user' customization module. Renamed libuser.tex
Guido van Rossum <guido@python.org>
parents:
diff changeset
61
9c2ee6bbdbb3 Added docs for 'user' customization module. Renamed libuser.tex
Guido van Rossum <guido@python.org>
parents:
diff changeset
62 Programs with security or privacy concerns should \emph{not} import
10243
575c4ea2542b Fix an amazing number of typos & malformed sentences reported by Detlef
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
63 this module; a user can easily break into a program by placing
6207
9c2ee6bbdbb3 Added docs for 'user' customization module. Renamed libuser.tex
Guido van Rossum <guido@python.org>
parents:
diff changeset
64 arbitrary code in the \file{.pythonrc.py} file.
9c2ee6bbdbb3 Added docs for 'user' customization module. Renamed libuser.tex
Guido van Rossum <guido@python.org>
parents:
diff changeset
65
9c2ee6bbdbb3 Added docs for 'user' customization module. Renamed libuser.tex
Guido van Rossum <guido@python.org>
parents:
diff changeset
66 Modules for general use should \emph{not} import this module; it may
9c2ee6bbdbb3 Added docs for 'user' customization module. Renamed libuser.tex
Guido van Rossum <guido@python.org>
parents:
diff changeset
67 interfere with the operation of the importing program.
9c2ee6bbdbb3 Added docs for 'user' customization module. Renamed libuser.tex
Guido van Rossum <guido@python.org>
parents:
diff changeset
68
7080
924f8a0117d5 Removed obsolete \kwindex{} call.
Fred Drake <fdrake@acm.org>
parents: 7052
diff changeset
69 \begin{seealso}
15261
bc4f89eefb04 Make all the \seemodule explanations consistent: start with a capitalized
Fred Drake <fdrake@acm.org>
parents: 13625
diff changeset
70 \seemodule{site}{Site-wide customization mechanism.}
7080
924f8a0117d5 Removed obsolete \kwindex{} call.
Fred Drake <fdrake@acm.org>
parents: 7052
diff changeset
71 \end{seealso}