Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libsys.tex @ 8831:00a6bb65ff29 legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Getting rid of this ancient stuff.
author Guido van Rossum <guido@python.org>
date Wed, 05 Aug 1998 21:10:09 +0000
parents 760dcf197048
children acfffe14628e
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
7877
8e5223680a9d Remove all uses of \sectcode; we can now use logical markup everywhere.
Fred Drake <fdrake@acm.org>
parents: 7868
diff changeset
1 \section{Built-in Module \module{sys}}
8716
760dcf197048 Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents: 8480
diff changeset
2 \declaremodule{builtin}{sys}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
3
8716
760dcf197048 Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents: 8480
diff changeset
4 \modulesynopsis{Access system specific parameters and functions.}
760dcf197048 Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents: 8480
diff changeset
5
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
6 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
7 interpreter and to functions that interact strongly with the interpreter.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
8 It is always available.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
9
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
10
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
11 \begin{datadesc}{argv}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
12 The list of command line arguments passed to a Python script.
7602
7f4a503ce58b Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
13 \code{argv[0]} is the script name (it is operating system
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
14 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
15 If the command was executed using the \samp{-c} command line option
7602
7f4a503ce58b Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
16 to the interpreter, \code{argv[0]} is set to the string
8716
760dcf197048 Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents: 8480
diff changeset
17 \code{'-c'}.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
18 If no script name was passed to the Python interpreter,
7602
7f4a503ce58b Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
19 \code{argv} has zero length.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
20 \end{datadesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
21
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
22 \begin{datadesc}{builtin_module_names}
4908
cfa1282902da Document that sys.builtin_module_names is now a tuple.
Guido van Rossum <guido@python.org>
parents: 2817
diff changeset
23 A tuple of strings giving the names of all modules that are compiled
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
24 into this Python interpreter. (This information is not available in
7602
7f4a503ce58b Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
25 any other way --- \code{modules.keys()} only lists the imported
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
26 modules.)
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
27 \end{datadesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
28
8480
d93ae374fb99 Document several variables that were previously undocumented,
Guido van Rossum <guido@python.org>
parents: 7877
diff changeset
29 \begin{datadesc}{copyright}
d93ae374fb99 Document several variables that were previously undocumented,
Guido van Rossum <guido@python.org>
parents: 7877
diff changeset
30 A string containing the copyright pertaining to the Python interpreter.
d93ae374fb99 Document several variables that were previously undocumented,
Guido van Rossum <guido@python.org>
parents: 7877
diff changeset
31 \end{datadesc}
d93ae374fb99 Document several variables that were previously undocumented,
Guido van Rossum <guido@python.org>
parents: 7877
diff changeset
32
6492
222dd4d06581 Documented exc_info(); also updated exc_type and last_type docs.
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
33 \begin{funcdesc}{exc_info}{}
222dd4d06581 Documented exc_info(); also updated exc_type and last_type docs.
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
34 This function returns a tuple of three values that give information
222dd4d06581 Documented exc_info(); also updated exc_type and last_type docs.
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
35 about the exception that is currently being handled. The information
222dd4d06581 Documented exc_info(); also updated exc_type and last_type docs.
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
36 returned is specific both to the current thread and to the current
222dd4d06581 Documented exc_info(); also updated exc_type and last_type docs.
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
37 stack frame. If the current stack frame is not handling an exception,
222dd4d06581 Documented exc_info(); also updated exc_type and last_type docs.
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
38 the information is taken from the calling stack frame, or its caller,
222dd4d06581 Documented exc_info(); also updated exc_type and last_type docs.
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
39 and so on until a stack frame is found that is handling an exception.
222dd4d06581 Documented exc_info(); also updated exc_type and last_type docs.
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
40 Here, ``handling an exception'' is defined as ``executing or having
7602
7f4a503ce58b Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
41 executed an except clause.'' For any stack frame, only
6492
222dd4d06581 Documented exc_info(); also updated exc_type and last_type docs.
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
42 information about the most recently handled exception is accessible.
222dd4d06581 Documented exc_info(); also updated exc_type and last_type docs.
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
43
222dd4d06581 Documented exc_info(); also updated exc_type and last_type docs.
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
44 If no exception is being handled anywhere on the stack, a tuple
222dd4d06581 Documented exc_info(); also updated exc_type and last_type docs.
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
45 containing three \code{None} values is returned. Otherwise, the
222dd4d06581 Documented exc_info(); also updated exc_type and last_type docs.
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
46 values returned are
222dd4d06581 Documented exc_info(); also updated exc_type and last_type docs.
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
47 \code{(\var{type}, \var{value}, \var{traceback})}.
222dd4d06581 Documented exc_info(); also updated exc_type and last_type docs.
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
48 Their meaning is: \var{type} gets the exception type of the exception
222dd4d06581 Documented exc_info(); also updated exc_type and last_type docs.
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
49 being handled (a string or class object); \var{value} gets the
222dd4d06581 Documented exc_info(); also updated exc_type and last_type docs.
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
50 exception parameter (its \dfn{associated value} or the second argument
7602
7f4a503ce58b Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
51 to \keyword{raise}, which is always a class instance if the exception
6492
222dd4d06581 Documented exc_info(); also updated exc_type and last_type docs.
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
52 type is a class object); \var{traceback} gets a traceback object (see
222dd4d06581 Documented exc_info(); also updated exc_type and last_type docs.
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
53 the Reference Manual) which encapsulates the call stack at the point
222dd4d06581 Documented exc_info(); also updated exc_type and last_type docs.
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
54 where the exception originally occurred.
222dd4d06581 Documented exc_info(); also updated exc_type and last_type docs.
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
55 \obindex{traceback}
222dd4d06581 Documented exc_info(); also updated exc_type and last_type docs.
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
56
222dd4d06581 Documented exc_info(); also updated exc_type and last_type docs.
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
57 \strong{Warning:} assigning the \var{traceback} return value to a
222dd4d06581 Documented exc_info(); also updated exc_type and last_type docs.
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
58 local variable in a function that is handling an exception will cause
222dd4d06581 Documented exc_info(); also updated exc_type and last_type docs.
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
59 a circular reference. This will prevent anything referenced by a local
222dd4d06581 Documented exc_info(); also updated exc_type and last_type docs.
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
60 variable in the same function or by the traceback from being garbage
222dd4d06581 Documented exc_info(); also updated exc_type and last_type docs.
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
61 collected. Since most functions don't need access to the traceback,
222dd4d06581 Documented exc_info(); also updated exc_type and last_type docs.
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
62 the best solution is to use something like
222dd4d06581 Documented exc_info(); also updated exc_type and last_type docs.
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
63 \code{type, value = sys.exc_info()[:2]}
222dd4d06581 Documented exc_info(); also updated exc_type and last_type docs.
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
64 to extract only the exception type and value. If you do need the
222dd4d06581 Documented exc_info(); also updated exc_type and last_type docs.
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
65 traceback, make sure to delete it after use (best done with a
7602
7f4a503ce58b Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
66 \keyword{try} ... \keyword{finally} statement) or to call
7f4a503ce58b Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
67 \function{exc_info()} in a function that does not itself handle an
7f4a503ce58b Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
68 exception.
6492
222dd4d06581 Documented exc_info(); also updated exc_type and last_type docs.
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
69 \end{funcdesc}
222dd4d06581 Documented exc_info(); also updated exc_type and last_type docs.
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
70
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
71 \begin{datadesc}{exc_type}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
72 \dataline{exc_value}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
73 \dataline{exc_traceback}
7602
7f4a503ce58b Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
74 \deprecated {1.5}
7f4a503ce58b Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
75 {Use \function{exc_info()} instead.}
7f4a503ce58b Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
76 Since they are global variables, they are not specific to the current
6492
222dd4d06581 Documented exc_info(); also updated exc_type and last_type docs.
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
77 thread, so their use is not safe in a multi-threaded program. When no
7602
7f4a503ce58b Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
78 exception is being handled, \code{exc_type} is set to \code{None} and
7f4a503ce58b Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
79 the other two are undefined.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
80 \end{datadesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
81
5684
a0831de2358c Additional info about sys.path, sys.version, sys.prefix, sys.exec_prefix.
Guido van Rossum <guido@python.org>
parents: 4908
diff changeset
82 \begin{datadesc}{exec_prefix}
a0831de2358c Additional info about sys.path, sys.version, sys.prefix, sys.exec_prefix.
Guido van Rossum <guido@python.org>
parents: 4908
diff changeset
83 A string giving the site-specific
a0831de2358c Additional info about sys.path, sys.version, sys.prefix, sys.exec_prefix.
Guido van Rossum <guido@python.org>
parents: 4908
diff changeset
84 directory prefix where the platform-dependent Python files are
8716
760dcf197048 Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents: 8480
diff changeset
85 installed; by default, this is also \code{'/usr/local'}. This can be
7759
a5e2bebe179a Make sure both hyphens of a long-option show up in the HTML output.
Fred Drake <fdrake@acm.org>
parents: 7602
diff changeset
86 set at build time with the \code{-}\code{-exec-prefix} argument to the
7602
7f4a503ce58b Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
87 \program{configure} script. Specifically, all configuration files
7f4a503ce58b Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
88 (e.g. the \file{config.h} header file) are installed in the directory
8716
760dcf197048 Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents: 8480
diff changeset
89 \code{exec_prefix + '/lib/python\var{version}/config'}, and shared library
5684
a0831de2358c Additional info about sys.path, sys.version, sys.prefix, sys.exec_prefix.
Guido van Rossum <guido@python.org>
parents: 4908
diff changeset
90 modules are installed in
8716
760dcf197048 Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents: 8480
diff changeset
91 \code{exec_prefix + '/lib/python\var{version}/lib-dynload'},
7602
7f4a503ce58b Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
92 where \var{version} is equal to \code{version[:3]}.
5684
a0831de2358c Additional info about sys.path, sys.version, sys.prefix, sys.exec_prefix.
Guido van Rossum <guido@python.org>
parents: 4908
diff changeset
93 \end{datadesc}
a0831de2358c Additional info about sys.path, sys.version, sys.prefix, sys.exec_prefix.
Guido van Rossum <guido@python.org>
parents: 4908
diff changeset
94
8480
d93ae374fb99 Document several variables that were previously undocumented,
Guido van Rossum <guido@python.org>
parents: 7877
diff changeset
95 \begin{datadesc}{executable}
d93ae374fb99 Document several variables that were previously undocumented,
Guido van Rossum <guido@python.org>
parents: 7877
diff changeset
96 A string giving the name of the executable binary for the Python
d93ae374fb99 Document several variables that were previously undocumented,
Guido van Rossum <guido@python.org>
parents: 7877
diff changeset
97 interpreter, on systems where this makes sense.
d93ae374fb99 Document several variables that were previously undocumented,
Guido van Rossum <guido@python.org>
parents: 7877
diff changeset
98 \end{datadesc}
d93ae374fb99 Document several variables that were previously undocumented,
Guido van Rossum <guido@python.org>
parents: 7877
diff changeset
99
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
100 \begin{funcdesc}{exit}{n}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
101 Exit from Python with numeric exit status \var{n}. This is
7602
7f4a503ce58b Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
102 implemented by raising the \exception{SystemExit} exception, so cleanup
7f4a503ce58b Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
103 actions specified by finally clauses of \keyword{try} statements
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
104 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
105 level.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
106 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
107
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
108 \begin{datadesc}{exitfunc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
109 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
110 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
111 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
112 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
113 fatal error occurs: in that case the interpreter's internal state
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
114 cannot be trusted).
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
115 \end{datadesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
116
7216
16ecf1554a83 Document getrefcount().
Guido van Rossum <guido@python.org>
parents: 7079
diff changeset
117 \begin{funcdesc}{getrefcount}{object}
16ecf1554a83 Document getrefcount().
Guido van Rossum <guido@python.org>
parents: 7079
diff changeset
118 Return the reference count of the \var{object}. The count returned is
16ecf1554a83 Document getrefcount().
Guido van Rossum <guido@python.org>
parents: 7079
diff changeset
119 generally one higher than you might expect, because it includes the
8716
760dcf197048 Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents: 8480
diff changeset
120 (temporary) reference as an argument to \function{getrefcount()}.
7216
16ecf1554a83 Document getrefcount().
Guido van Rossum <guido@python.org>
parents: 7079
diff changeset
121 \end{funcdesc}
16ecf1554a83 Document getrefcount().
Guido van Rossum <guido@python.org>
parents: 7079
diff changeset
122
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
123 \begin{datadesc}{last_type}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
124 \dataline{last_value}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
125 \dataline{last_traceback}
6492
222dd4d06581 Documented exc_info(); also updated exc_type and last_type docs.
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
126 These three variables are not always defined; they are set when an
222dd4d06581 Documented exc_info(); also updated exc_type and last_type docs.
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
127 exception is not handled and the interpreter prints an error message
222dd4d06581 Documented exc_info(); also updated exc_type and last_type docs.
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
128 and a stack traceback. Their intended use is to allow an interactive
222dd4d06581 Documented exc_info(); also updated exc_type and last_type docs.
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
129 user to import a debugger module and engage in post-mortem debugging
222dd4d06581 Documented exc_info(); also updated exc_type and last_type docs.
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
130 without having to re-execute the command that caused the error.
7602
7f4a503ce58b Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
131 (Typical use is \samp{import pdb; pdb.pm()} to enter the post-mortem
6492
222dd4d06581 Documented exc_info(); also updated exc_type and last_type docs.
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
132 debugger; see the chapter ``The Python Debugger'' for more
222dd4d06581 Documented exc_info(); also updated exc_type and last_type docs.
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
133 information.)
6862
c5bfb1de61a5 Fixed index references to modules.
Fred Drake <fdrake@acm.org>
parents: 6662
diff changeset
134 \refstmodindex{pdb}
6492
222dd4d06581 Documented exc_info(); also updated exc_type and last_type docs.
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
135
222dd4d06581 Documented exc_info(); also updated exc_type and last_type docs.
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
136 The meaning of the variables is the same
7602
7f4a503ce58b Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
137 as that of the return values from \function{exc_info()} above.
6492
222dd4d06581 Documented exc_info(); also updated exc_type and last_type docs.
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
138 (Since there is only one interactive thread, thread-safety is not a
7602
7f4a503ce58b Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
139 concern for these variables, unlike for \code{exc_type} etc.)
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
140 \end{datadesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
141
8480
d93ae374fb99 Document several variables that were previously undocumented,
Guido van Rossum <guido@python.org>
parents: 7877
diff changeset
142 \begin{datadesc}{maxint}
d93ae374fb99 Document several variables that were previously undocumented,
Guido van Rossum <guido@python.org>
parents: 7877
diff changeset
143 The largest positive integer supported by Python's regular integer
d93ae374fb99 Document several variables that were previously undocumented,
Guido van Rossum <guido@python.org>
parents: 7877
diff changeset
144 type. This is at least 2**31-1. The largest negative integer is
d93ae374fb99 Document several variables that were previously undocumented,
Guido van Rossum <guido@python.org>
parents: 7877
diff changeset
145 \code{-maxint-1} -- the asymmetry results from the use of 2's
d93ae374fb99 Document several variables that were previously undocumented,
Guido van Rossum <guido@python.org>
parents: 7877
diff changeset
146 complement binary arithmetic.
d93ae374fb99 Document several variables that were previously undocumented,
Guido van Rossum <guido@python.org>
parents: 7877
diff changeset
147 \end{datadesc}
d93ae374fb99 Document several variables that were previously undocumented,
Guido van Rossum <guido@python.org>
parents: 7877
diff changeset
148
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
149 \begin{datadesc}{modules}
7602
7f4a503ce58b Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
150 This is a dictionary that maps module names to modules which have
7f4a503ce58b Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
151 already been loaded. This can be manipulated to force reloading of
7f4a503ce58b Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
152 modules and other tricks. Note that removing a module from this
7f4a503ce58b Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
153 dictionary is \emph{not} the same as calling
7f4a503ce58b Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
154 \function{reload()}\bifuncindex{reload} on the corresponding module
7f4a503ce58b Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
155 object.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
156 \end{datadesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
157
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
158 \begin{datadesc}{path}
7079
322dca5ee145 Added "module search path" to the index.
Fred Drake <fdrake@acm.org>
parents: 6862
diff changeset
159 \indexiii{module}{search}{path}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
160 A list of strings that specifies the search path for modules.
8716
760dcf197048 Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents: 8480
diff changeset
161 Initialized from the environment variable \envvar{PYTHONPATH}, or an
5684
a0831de2358c Additional info about sys.path, sys.version, sys.prefix, sys.exec_prefix.
Guido van Rossum <guido@python.org>
parents: 4908
diff changeset
162 installation-dependent default.
a0831de2358c Additional info about sys.path, sys.version, sys.prefix, sys.exec_prefix.
Guido van Rossum <guido@python.org>
parents: 4908
diff changeset
163
7602
7f4a503ce58b Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
164 The first item of this list, \code{path[0]}, is the
5684
a0831de2358c Additional info about sys.path, sys.version, sys.prefix, sys.exec_prefix.
Guido van Rossum <guido@python.org>
parents: 4908
diff changeset
165 directory containing the script that was used to invoke the Python
a0831de2358c Additional info about sys.path, sys.version, sys.prefix, sys.exec_prefix.
Guido van Rossum <guido@python.org>
parents: 4908
diff changeset
166 interpreter. If the script directory is not available (e.g. if the
a0831de2358c Additional info about sys.path, sys.version, sys.prefix, sys.exec_prefix.
Guido van Rossum <guido@python.org>
parents: 4908
diff changeset
167 interpreter is invoked interactively or if the script is read from
7602
7f4a503ce58b Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
168 standard input), \code{path[0]} is the empty string, which directs
5684
a0831de2358c Additional info about sys.path, sys.version, sys.prefix, sys.exec_prefix.
Guido van Rossum <guido@python.org>
parents: 4908
diff changeset
169 Python to search modules in the current directory first. Notice that
6862
c5bfb1de61a5 Fixed index references to modules.
Fred Drake <fdrake@acm.org>
parents: 6662
diff changeset
170 the script directory is inserted \emph{before} the entries inserted as
8716
760dcf197048 Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents: 8480
diff changeset
171 a result of \envvar{PYTHONPATH}.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
172 \end{datadesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
173
2817
8b8fb24d4837 correct typo; document sys.platform
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
174 \begin{datadesc}{platform}
7602
7f4a503ce58b Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
175 This string contains a platform identifier, e.g. \code{'sunos5'} or
7f4a503ce58b Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
176 \code{'linux1'}. This can be used to append platform-specific
7f4a503ce58b Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
177 components to \code{path}, for instance.
5684
a0831de2358c Additional info about sys.path, sys.version, sys.prefix, sys.exec_prefix.
Guido van Rossum <guido@python.org>
parents: 4908
diff changeset
178 \end{datadesc}
a0831de2358c Additional info about sys.path, sys.version, sys.prefix, sys.exec_prefix.
Guido van Rossum <guido@python.org>
parents: 4908
diff changeset
179
a0831de2358c Additional info about sys.path, sys.version, sys.prefix, sys.exec_prefix.
Guido van Rossum <guido@python.org>
parents: 4908
diff changeset
180 \begin{datadesc}{prefix}
a0831de2358c Additional info about sys.path, sys.version, sys.prefix, sys.exec_prefix.
Guido van Rossum <guido@python.org>
parents: 4908
diff changeset
181 A string giving the site-specific directory prefix where the platform
a0831de2358c Additional info about sys.path, sys.version, sys.prefix, sys.exec_prefix.
Guido van Rossum <guido@python.org>
parents: 4908
diff changeset
182 independent Python files are installed; by default, this is the string
8716
760dcf197048 Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents: 8480
diff changeset
183 \code{'/usr/local'}. This can be set at build time with the
7759
a5e2bebe179a Make sure both hyphens of a long-option show up in the HTML output.
Fred Drake <fdrake@acm.org>
parents: 7602
diff changeset
184 \code{-}\code{-prefix} argument to the \program{configure} script. The main
5684
a0831de2358c Additional info about sys.path, sys.version, sys.prefix, sys.exec_prefix.
Guido van Rossum <guido@python.org>
parents: 4908
diff changeset
185 collection of Python library modules is installed in the directory
8716
760dcf197048 Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents: 8480
diff changeset
186 \code{prefix + '/lib/python\var{version}'} while the platform
7602
7f4a503ce58b Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
187 independent header files (all except \file{config.h}) are stored in
8716
760dcf197048 Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents: 8480
diff changeset
188 \code{prefix + '/include/python\var{version}'},
7602
7f4a503ce58b Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
189 where \var{version} is equal to \code{version[:3]}.
5684
a0831de2358c Additional info about sys.path, sys.version, sys.prefix, sys.exec_prefix.
Guido van Rossum <guido@python.org>
parents: 4908
diff changeset
190
2817
8b8fb24d4837 correct typo; document sys.platform
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
191 \end{datadesc}
8b8fb24d4837 correct typo; document sys.platform
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
192
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
193 \begin{datadesc}{ps1}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
194 \dataline{ps2}
7824
b85a675b6503 New index entries.
Fred Drake <fdrake@acm.org>
parents: 7759
diff changeset
195 \index{interpreter prompts}
b85a675b6503 New index entries.
Fred Drake <fdrake@acm.org>
parents: 7759
diff changeset
196 \index{prompts, interpreter}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
197 Strings specifying the primary and secondary prompt of the
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
198 interpreter. These are only defined if the interpreter is in
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
199 interactive mode. Their initial values in this case are
6662
fbfcf38d2b39 Documented brand new behavior of sys.ps1 and sys.ps2 (str() is applied
Guido van Rossum <guido@python.org>
parents: 6647
diff changeset
200 \code{'>>> '} and \code{'... '}. If a non-string object is assigned
7602
7f4a503ce58b Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
201 to either variable, its \function{str()} is re-evaluated each time
7f4a503ce58b Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
202 the interpreter prepares to read a new interactive command; this can
7f4a503ce58b Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
203 be used to implement a dynamic prompt.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
204 \end{datadesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
205
2109
07080a296070 sys.setcheckinterval(x) instead of sys.check_interval = x
Guido van Rossum <guido@python.org>
parents: 1936
diff changeset
206 \begin{funcdesc}{setcheckinterval}{interval}
07080a296070 sys.setcheckinterval(x) instead of sys.check_interval = x
Guido van Rossum <guido@python.org>
parents: 1936
diff changeset
207 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
208 determines how often the interpreter checks for periodic things such
7602
7f4a503ce58b Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
209 as thread switches and signal handlers. The default is \code{10}, meaning
2109
07080a296070 sys.setcheckinterval(x) instead of sys.check_interval = x
Guido van Rossum <guido@python.org>
parents: 1936
diff changeset
210 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
211 it to a larger value may increase performance for programs using
6647
a7ea74a27993 Get rid of math mode in some places.
Guido van Rossum <guido@python.org>
parents: 6492
diff changeset
212 threads. Setting it to a value \code{<=} 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
213 maximizing responsiveness as well as overhead.
2138
23f040317828 cosmetics/typos
Guido van Rossum <guido@python.org>
parents: 2109
diff changeset
214 \end{funcdesc}
2109
07080a296070 sys.setcheckinterval(x) instead of sys.check_interval = x
Guido van Rossum <guido@python.org>
parents: 1936
diff changeset
215
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
216 \begin{funcdesc}{setprofile}{profilefunc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
217 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
218 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
219 Python Profiler. The system's profile function
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
220 is called similarly to the system's trace function (see
7602
7f4a503ce58b Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
221 \function{settrace()}), but it isn't called for each executed line of
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
222 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
223 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
224 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
225 \index{profile function}
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
226 \index{profiler}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
227
8480
d93ae374fb99 Document several variables that were previously undocumented,
Guido van Rossum <guido@python.org>
parents: 7877
diff changeset
228 \begin{funcdesc}{settrace}{tracefunc}
d93ae374fb99 Document several variables that were previously undocumented,
Guido van Rossum <guido@python.org>
parents: 7877
diff changeset
229 Set the system's trace function, which allows you to implement a
d93ae374fb99 Document several variables that were previously undocumented,
Guido van Rossum <guido@python.org>
parents: 7877
diff changeset
230 Python source code debugger in Python. See section ``How It Works''
d93ae374fb99 Document several variables that were previously undocumented,
Guido van Rossum <guido@python.org>
parents: 7877
diff changeset
231 in the chapter on the Python Debugger.
d93ae374fb99 Document several variables that were previously undocumented,
Guido van Rossum <guido@python.org>
parents: 7877
diff changeset
232 \end{funcdesc}
d93ae374fb99 Document several variables that were previously undocumented,
Guido van Rossum <guido@python.org>
parents: 7877
diff changeset
233 \index{trace function}
d93ae374fb99 Document several variables that were previously undocumented,
Guido van Rossum <guido@python.org>
parents: 7877
diff changeset
234 \index{debugger}
d93ae374fb99 Document several variables that were previously undocumented,
Guido van Rossum <guido@python.org>
parents: 7877
diff changeset
235
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
236 \begin{datadesc}{stdin}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
237 \dataline{stdout}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
238 \dataline{stderr}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
239 File objects corresponding to the interpreter's standard input,
7602
7f4a503ce58b Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
240 output and error streams. \code{stdin} is used for all
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
241 interpreter input except for scripts but including calls to
7602
7f4a503ce58b Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
242 \function{input()}\bifuncindex{input} and
7f4a503ce58b Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
243 \function{raw_input()}\bifuncindex{raw_input}. \code{stdout} is used
7f4a503ce58b Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
244 for the output of \keyword{print} and expression statements and for the
7f4a503ce58b Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
245 prompts of \function{input()} and \function{raw_input()}. The interpreter's
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
246 own prompts and (almost all of) its error messages go to
7602
7f4a503ce58b Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
247 \code{stderr}. \code{stdout} and \code{stderr} needn't
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
248 be built-in file objects: any object is acceptable as long as it has
7602
7f4a503ce58b Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
249 a \method{write()} method that takes a string argument. (Changing these
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
250 objects doesn't affect the standard I/O streams of processes
7602
7f4a503ce58b Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
251 executed by \function{os.popen()}, \function{os.system()} or the
7f4a503ce58b Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
252 \function{exec*()} family of functions in the \module{os} module.)
6862
c5bfb1de61a5 Fixed index references to modules.
Fred Drake <fdrake@acm.org>
parents: 6662
diff changeset
253 \refstmodindex{os}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
254 \end{datadesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
255
8480
d93ae374fb99 Document several variables that were previously undocumented,
Guido van Rossum <guido@python.org>
parents: 7877
diff changeset
256 \begin{datadesc}{__stdin__}
d93ae374fb99 Document several variables that were previously undocumented,
Guido van Rossum <guido@python.org>
parents: 7877
diff changeset
257 \dataline{__stdout__}
d93ae374fb99 Document several variables that were previously undocumented,
Guido van Rossum <guido@python.org>
parents: 7877
diff changeset
258 \dataline{__stderr__}
d93ae374fb99 Document several variables that were previously undocumented,
Guido van Rossum <guido@python.org>
parents: 7877
diff changeset
259 These objects contain the original values of \code{stdin},
d93ae374fb99 Document several variables that were previously undocumented,
Guido van Rossum <guido@python.org>
parents: 7877
diff changeset
260 \code{stderr} and \code{stdout} at the start of the program. They are
d93ae374fb99 Document several variables that were previously undocumented,
Guido van Rossum <guido@python.org>
parents: 7877
diff changeset
261 used during finalization, and could be useful to restore the actual
d93ae374fb99 Document several variables that were previously undocumented,
Guido van Rossum <guido@python.org>
parents: 7877
diff changeset
262 files to known working file objects in case they have been overwritten
d93ae374fb99 Document several variables that were previously undocumented,
Guido van Rossum <guido@python.org>
parents: 7877
diff changeset
263 with a broken object.
d93ae374fb99 Document several variables that were previously undocumented,
Guido van Rossum <guido@python.org>
parents: 7877
diff changeset
264 \end{datadesc}
d93ae374fb99 Document several variables that were previously undocumented,
Guido van Rossum <guido@python.org>
parents: 7877
diff changeset
265
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
266 \begin{datadesc}{tracebacklimit}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
267 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
268 maximum number of levels of traceback information printed when an
7602
7f4a503ce58b Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
269 unhandled exception occurs. The default is \code{1000}. When set to
7f4a503ce58b Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
270 0 or less, all traceback information is suppressed and only the
7f4a503ce58b Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
271 exception type and value are printed.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
272 \end{datadesc}
5684
a0831de2358c Additional info about sys.path, sys.version, sys.prefix, sys.exec_prefix.
Guido van Rossum <guido@python.org>
parents: 4908
diff changeset
273
a0831de2358c Additional info about sys.path, sys.version, sys.prefix, sys.exec_prefix.
Guido van Rossum <guido@python.org>
parents: 4908
diff changeset
274 \begin{datadesc}{version}
8480
d93ae374fb99 Document several variables that were previously undocumented,
Guido van Rossum <guido@python.org>
parents: 7877
diff changeset
275 A string containing the version number of the Python interpreter.
5684
a0831de2358c Additional info about sys.path, sys.version, sys.prefix, sys.exec_prefix.
Guido van Rossum <guido@python.org>
parents: 4908
diff changeset
276 \end{datadesc}