Mercurial > cpython-lru_cache-weakref

annotate Doc/libsys.tex @ 4566:6403c94de50d legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Added safeguard against failure in __del__.
author Guido van Rossum <guido@python.org>
date Wed, 27 Nov 1996 19:39:58 +0000
parents 8b8fb24d4837
children cfa1282902da
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
1 \section{Built-in Module \sectcode{sys}}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
2
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
3 \bimodindex{sys}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
4 This module provides access to some variables used or maintained by the
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
5 interpreter and to functions that interact strongly with the interpreter.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
6 It is always available.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
7
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
8 \renewcommand{\indexsubitem}{(in module sys)}
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
9
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
10 \begin{datadesc}{argv}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
11 The list of command line arguments passed to a Python script.
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
12 \code{sys.argv[0]} is the script name (it is operating system
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
13 dependent whether this is a full pathname or not).
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
14 If the command was executed using the \samp{-c} command line option
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
15 to the interpreter, \code{sys.argv[0]} is set to the string
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
16 \code{"-c"}.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
17 If no script name was passed to the Python interpreter,
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
18 \code{sys.argv} has zero length.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
19 \end{datadesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
20
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
21 \begin{datadesc}{builtin_module_names}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
22 A list of strings giving the names of all modules that are compiled
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
23 into this Python interpreter. (This information is not available in
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
24 any other way --- \code{sys.modules.keys()} only lists the imported
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
25 modules.)
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
26 \end{datadesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
27
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
28 \begin{datadesc}{exc_type}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
29 \dataline{exc_value}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
30 \dataline{exc_traceback}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
31 These three variables are not always defined; they are set when an
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
32 exception handler (an \code{except} clause of a \code{try} statement) is
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
33 invoked. Their meaning is: \code{exc_type} gets the exception type of
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
34 the exception being handled; \code{exc_value} gets the exception
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
35 parameter (its \dfn{associated value} or the second argument to
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
36 \code{raise}); \code{exc_traceback} gets a traceback object (see the
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
37 Reference Manual) which
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
38 encapsulates the call stack at the point where the exception
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
39 originally occurred.
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
40 \obindex{traceback}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
41 \end{datadesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
42
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
43 \begin{funcdesc}{exit}{n}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
44 Exit from Python with numeric exit status \var{n}. This is
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
45 implemented by raising the \code{SystemExit} exception, so cleanup
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
46 actions specified by \code{finally} clauses of \code{try} statements
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
47 are honored, and it is possible to catch the exit attempt at an outer
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
48 level.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
49 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
50
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
51 \begin{datadesc}{exitfunc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
52 This value is not actually defined by the module, but can be set by
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
53 the user (or by a program) to specify a clean-up action at program
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
54 exit. When set, it should be a parameterless function. This function
2817
8b8fb24d4837 correct typo; document sys.platform
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
55 will be called when the interpreter exits in any way (except when a
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
56 fatal error occurs: in that case the interpreter's internal state
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
57 cannot be trusted).
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
58 \end{datadesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
59
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
60 \begin{datadesc}{last_type}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
61 \dataline{last_value}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
62 \dataline{last_traceback}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
63 These three variables are not always defined; they are set when an
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
64 exception is not handled and the interpreter prints an error message
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
65 and a stack traceback. Their intended use is to allow an interactive
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
66 user to import a debugger module and engage in post-mortem debugging
1767
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
67 without having to re-execute the command that caused the error (which
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
68 may be hard to reproduce). The meaning of the variables is the same
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
69 as that of \code{exc_type}, \code{exc_value} and \code{exc_tracaback},
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
70 respectively.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
71 \end{datadesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
72
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
73 \begin{datadesc}{modules}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
74 Gives the list of modules that have already been loaded.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
75 This can be manipulated to force reloading of modules and other tricks.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
76 \end{datadesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
77
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
78 \begin{datadesc}{path}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
79 A list of strings that specifies the search path for modules.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
80 Initialized from the environment variable \code{PYTHONPATH}, or an
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
81 installation-dependent default.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
82 \end{datadesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
83
2817
8b8fb24d4837 correct typo; document sys.platform
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
84 \begin{datadesc}{platform}
8b8fb24d4837 correct typo; document sys.platform
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
85 This string contains a platform identifier. This can be used to
8b8fb24d4837 correct typo; document sys.platform
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
86 append platform-specific components to \code{sys.path}, for instance.
8b8fb24d4837 correct typo; document sys.platform
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
87 \end{datadesc}
8b8fb24d4837 correct typo; document sys.platform
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
88
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
89 \begin{datadesc}{ps1}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
90 \dataline{ps2}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
91 Strings specifying the primary and secondary prompt of the
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
92 interpreter. These are only defined if the interpreter is in
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
93 interactive mode. Their initial values in this case are
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
94 \code{'>>> '} and \code{'... '}.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
95 \end{datadesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
96
2109
07080a296070 sys.setcheckinterval(x) instead of sys.check_interval = x
Guido van Rossum <guido@python.org>
parents: 1936
diff changeset
97 \begin{funcdesc}{setcheckinterval}{interval}
07080a296070 sys.setcheckinterval(x) instead of sys.check_interval = x
Guido van Rossum <guido@python.org>
parents: 1936
diff changeset
98 Set the interpreter's ``check interval''. This integer value
07080a296070 sys.setcheckinterval(x) instead of sys.check_interval = x
Guido van Rossum <guido@python.org>
parents: 1936
diff changeset
99 determines how often the interpreter checks for periodic things such
07080a296070 sys.setcheckinterval(x) instead of sys.check_interval = x
Guido van Rossum <guido@python.org>
parents: 1936
diff changeset
100 as thread switches and signal handlers. The default is 10, meaning
07080a296070 sys.setcheckinterval(x) instead of sys.check_interval = x
Guido van Rossum <guido@python.org>
parents: 1936
diff changeset
101 the check is performed every 10 Python virtual instructions. Setting
07080a296070 sys.setcheckinterval(x) instead of sys.check_interval = x
Guido van Rossum <guido@python.org>
parents: 1936
diff changeset
102 it to a larger value may increase performance for programs using
2491
fb8e08ec88dd changes (suggested) by Soren Larsen
Guido van Rossum <guido@python.org>
parents: 2138
diff changeset
103 threads. Setting it to a value $\leq 0$ checks every virtual instruction,
2109
07080a296070 sys.setcheckinterval(x) instead of sys.check_interval = x
Guido van Rossum <guido@python.org>
parents: 1936
diff changeset
104 maximizing responsiveness as well as overhead.
2138
23f040317828 cosmetics/typos
Guido van Rossum <guido@python.org>
parents: 2109
diff changeset
105 \end{funcdesc}
2109
07080a296070 sys.setcheckinterval(x) instead of sys.check_interval = x
Guido van Rossum <guido@python.org>
parents: 1936
diff changeset
106
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
107 \begin{funcdesc}{settrace}{tracefunc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
108 Set the system's trace function, which allows you to implement a
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
109 Python source code debugger in Python. See section ``How It Works''
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
110 in the chapter on the Python Debugger.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
111 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
112 \index{trace function}
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
113 \index{debugger}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
114
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
115 \begin{funcdesc}{setprofile}{profilefunc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
116 Set the system's profile function, which allows you to implement a
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
117 Python source code profiler in Python. See the chapter on the
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
118 Python Profiler. The system's profile function
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
119 is called similarly to the system's trace function (see
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
120 \code{sys.settrace}), but it isn't called for each executed line of
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
121 code (only on call and return and when an exception occurs). Also,
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
122 its return value is not used, so it can just return \code{None}.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
123 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
124 \index{profile function}
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
125 \index{profiler}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
126
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
127 \begin{datadesc}{stdin}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
128 \dataline{stdout}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
129 \dataline{stderr}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
130 File objects corresponding to the interpreter's standard input,
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
131 output and error streams. \code{sys.stdin} is used for all
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
132 interpreter input except for scripts but including calls to
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
133 \code{input()} and \code{raw_input()}. \code{sys.stdout} is used
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
134 for the output of \code{print} and expression statements and for the
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
135 prompts of \code{input()} and \code{raw_input()}. The interpreter's
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
136 own prompts and (almost all of) its error messages go to
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
137 \code{sys.stderr}. \code{sys.stdout} and \code{sys.stderr} needn't
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
138 be built-in file objects: any object is acceptable as long as it has
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
139 a \code{write} method that takes a string argument. (Changing these
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
140 objects doesn't affect the standard I/O streams of processes
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
141 executed by \code{popen()}, \code{system()} or the \code{exec*()}
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
142 family of functions in the \code{os} module.)
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
143 \stmodindex{os}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
144 \end{datadesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
145
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
146 \begin{datadesc}{tracebacklimit}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
147 When this variable is set to an integer value, it determines the
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
148 maximum number of levels of traceback information printed when an
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
149 unhandled exception occurs. The default is 1000. When set to 0 or
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
150 less, all traceback information is suppressed and only the exception
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
151 type and value are printed.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
152 \end{datadesc}