Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libsys.tex @ 39940:dfd809dcf680 2.5

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Bug #1446043: correctly raise a LookupError if an encoding name given to encodings.search_function() contains a dot. (backport from rev. 52075)
author Georg Brandl <georg@python.org>
date Sat, 30 Sep 2006 11:22:35 +0000
parents 388b7d90bb89
children 8d5018d7508a
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{sys} ---
10703
e4e800a78d8d Make internal module references hyperlinks wherever it makes sense.
Fred Drake <fdrake@acm.org>
parents: 10465
diff changeset
2 System-specific parameters and functions}
e4e800a78d8d Make internal module references hyperlinks wherever it makes sense.
Fred Drake <fdrake@acm.org>
parents: 10465
diff changeset
3
8716
760dcf197048 Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents: 8480
diff changeset
4 \declaremodule{builtin}{sys}
8918
acfffe14628e New section header style.
Fred Drake <fdrake@acm.org>
parents: 8716
diff changeset
5 \modulesynopsis{Access system-specific parameters and functions.}
8716
760dcf197048 Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents: 8480
diff changeset
6
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
7 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
8 interpreter and to functions that interact strongly with the interpreter.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
9 It is always available.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
10
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
11
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
12 \begin{datadesc}{argv}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
13 The list of command line arguments passed to a Python script.
18694
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
14 \code{argv[0]} is the script name (it is operating system dependent
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
15 whether this is a full pathname or not). If the command was
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
16 executed using the \programopt{-c} command line option to the
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
17 interpreter, \code{argv[0]} is set to the string \code{'-c'}. If no
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
18 script name was passed to the Python interpreter, \code{argv} has
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
19 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
13977
eb9a36163a9e Guido pointed out that all names in the sys module have no underscore,
Fred Drake <fdrake@acm.org>
parents: 13969
diff changeset
22 \begin{datadesc}{byteorder}
13969
55e3988205b3 Document the byte_order value in the sys module.
Fred Drake <fdrake@acm.org>
parents: 13222
diff changeset
23 An indicator of the native byte order. This will have the value
39088
Fredrik Lundh <fredrik@pythonware.com>
parents: 39056
diff changeset
24 \code{'big'} on big-endian (most-significant byte first) platforms,
13969
55e3988205b3 Document the byte_order value in the sys module.
Fred Drake <fdrake@acm.org>
parents: 13222
diff changeset
25 and \code{'little'} on little-endian (least-significant byte first)
55e3988205b3 Document the byte_order value in the sys module.
Fred Drake <fdrake@acm.org>
parents: 13222
diff changeset
26 platforms.
55e3988205b3 Document the byte_order value in the sys module.
Fred Drake <fdrake@acm.org>
parents: 13222
diff changeset
27 \versionadded{2.0}
55e3988205b3 Document the byte_order value in the sys module.
Fred Drake <fdrake@acm.org>
parents: 13222
diff changeset
28 \end{datadesc}
55e3988205b3 Document the byte_order value in the sys module.
Fred Drake <fdrake@acm.org>
parents: 13222
diff changeset
29
36207
825a041813fb Drop sys.build_number. Add sys.subversion.
Martin v. Löwis <martin@v.loewis.de>
parents: 36071
diff changeset
30 \begin{datadesc}{subversion}
825a041813fb Drop sys.build_number. Add sys.subversion.
Martin v. Löwis <martin@v.loewis.de>
parents: 36071
diff changeset
31 A triple (repo, branch, version) representing the Subversion
825a041813fb Drop sys.build_number. Add sys.subversion.
Martin v. Löwis <martin@v.loewis.de>
parents: 36071
diff changeset
32 information of the Python interpreter.
825a041813fb Drop sys.build_number. Add sys.subversion.
Martin v. Löwis <martin@v.loewis.de>
parents: 36071
diff changeset
33 \var{repo} is the name of the repository, \code{'CPython'}.
36217
77b4aaad6903 Correct typo
Georg Brandl <georg@python.org>
parents: 36207
diff changeset
34 \var{branch} is a string of one of the forms \code{'trunk'},
36207
825a041813fb Drop sys.build_number. Add sys.subversion.
Martin v. Löwis <martin@v.loewis.de>
parents: 36071
diff changeset
35 \code{'branches/name'} or \code{'tags/name'}.
825a041813fb Drop sys.build_number. Add sys.subversion.
Martin v. Löwis <martin@v.loewis.de>
parents: 36071
diff changeset
36 \var{version} is the output of \code{svnversion}, if the
825a041813fb Drop sys.build_number. Add sys.subversion.
Martin v. Löwis <martin@v.loewis.de>
parents: 36071
diff changeset
37 interpreter was built from a Subversion checkout; it contains
825a041813fb Drop sys.build_number. Add sys.subversion.
Martin v. Löwis <martin@v.loewis.de>
parents: 36071
diff changeset
38 the revision number (range) and possibly a trailing 'M' if
825a041813fb Drop sys.build_number. Add sys.subversion.
Martin v. Löwis <martin@v.loewis.de>
parents: 36071
diff changeset
39 there were local modifications. If the tree was exported
825a041813fb Drop sys.build_number. Add sys.subversion.
Martin v. Löwis <martin@v.loewis.de>
parents: 36071
diff changeset
40 (or svnversion was not available), it is the revision of
825a041813fb Drop sys.build_number. Add sys.subversion.
Martin v. Löwis <martin@v.loewis.de>
parents: 36071
diff changeset
41 \code{Include/patchlevel.h} if the branch is a tag. Otherwise,
825a041813fb Drop sys.build_number. Add sys.subversion.
Martin v. Löwis <martin@v.loewis.de>
parents: 36071
diff changeset
42 it is \code{None}.
36071
45f7b7383a4e Add versionadded info
Neal Norwitz <nnorwitz@gmail.com>
parents: 36070
diff changeset
43 \versionadded{2.5}
39056
b6fd499e4343 After approval from Anthony, merge the tim-current_frames
Tim Peters <tim.peters@gmail.com>
parents: 38095
diff changeset
44 \end{datadesc}
36070
9697eeeaf246 Expose Subversion revision number (calculated via "svnversion .") to Python.
Barry Warsaw <barry@python.org>
parents: 33966
diff changeset
45
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
46 \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
47 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
48 into this Python interpreter. (This information is not available in
7602
7f4a503ce58b Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
49 any other way --- \code{modules.keys()} only lists the imported
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
50 modules.)
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
51 \end{datadesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
52
8480
d93ae374fb99 Document several variables that were previously undocumented,
Guido van Rossum <guido@python.org>
parents: 7877
diff changeset
53 \begin{datadesc}{copyright}
18694
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
54 A string containing the copyright pertaining to the Python
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
55 interpreter.
8480
d93ae374fb99 Document several variables that were previously undocumented,
Guido van Rossum <guido@python.org>
parents: 7877
diff changeset
56 \end{datadesc}
d93ae374fb99 Document several variables that were previously undocumented,
Guido van Rossum <guido@python.org>
parents: 7877
diff changeset
57
39056
b6fd499e4343 After approval from Anthony, merge the tim-current_frames
Tim Peters <tim.peters@gmail.com>
parents: 38095
diff changeset
58 \begin{funcdesc}{_current_frames}{}
b6fd499e4343 After approval from Anthony, merge the tim-current_frames
Tim Peters <tim.peters@gmail.com>
parents: 38095
diff changeset
59 Return a dictionary mapping each thread's identifier to the topmost stack
b6fd499e4343 After approval from Anthony, merge the tim-current_frames
Tim Peters <tim.peters@gmail.com>
parents: 38095
diff changeset
60 frame currently active in that thread at the time the function is called.
b6fd499e4343 After approval from Anthony, merge the tim-current_frames
Tim Peters <tim.peters@gmail.com>
parents: 38095
diff changeset
61 Note that functions in the \refmodule{traceback} module can build the
b6fd499e4343 After approval from Anthony, merge the tim-current_frames
Tim Peters <tim.peters@gmail.com>
parents: 38095
diff changeset
62 call stack given such a frame.
b6fd499e4343 After approval from Anthony, merge the tim-current_frames
Tim Peters <tim.peters@gmail.com>
parents: 38095
diff changeset
63
b6fd499e4343 After approval from Anthony, merge the tim-current_frames
Tim Peters <tim.peters@gmail.com>
parents: 38095
diff changeset
64 This is most useful for debugging deadlock: this function does not
b6fd499e4343 After approval from Anthony, merge the tim-current_frames
Tim Peters <tim.peters@gmail.com>
parents: 38095
diff changeset
65 require the deadlocked threads' cooperation, and such threads' call stacks
b6fd499e4343 After approval from Anthony, merge the tim-current_frames
Tim Peters <tim.peters@gmail.com>
parents: 38095
diff changeset
66 are frozen for as long as they remain deadlocked. The frame returned
b6fd499e4343 After approval from Anthony, merge the tim-current_frames
Tim Peters <tim.peters@gmail.com>
parents: 38095
diff changeset
67 for a non-deadlocked thread may bear no relationship to that thread's
b6fd499e4343 After approval from Anthony, merge the tim-current_frames
Tim Peters <tim.peters@gmail.com>
parents: 38095
diff changeset
68 current activity by the time calling code examines the frame.
b6fd499e4343 After approval from Anthony, merge the tim-current_frames
Tim Peters <tim.peters@gmail.com>
parents: 38095
diff changeset
69
b6fd499e4343 After approval from Anthony, merge the tim-current_frames
Tim Peters <tim.peters@gmail.com>
parents: 38095
diff changeset
70 This function should be used for internal and specialized purposes
b6fd499e4343 After approval from Anthony, merge the tim-current_frames
Tim Peters <tim.peters@gmail.com>
parents: 38095
diff changeset
71 only.
b6fd499e4343 After approval from Anthony, merge the tim-current_frames
Tim Peters <tim.peters@gmail.com>
parents: 38095
diff changeset
72 \versionadded{2.5}
b6fd499e4343 After approval from Anthony, merge the tim-current_frames
Tim Peters <tim.peters@gmail.com>
parents: 38095
diff changeset
73 \end{funcdesc}
b6fd499e4343 After approval from Anthony, merge the tim-current_frames
Tim Peters <tim.peters@gmail.com>
parents: 38095
diff changeset
74
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11457
diff changeset
75 \begin{datadesc}{dllhandle}
18694
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
76 Integer specifying the handle of the Python DLL.
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
77 Availability: Windows.
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11457
diff changeset
78 \end{datadesc}
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11457
diff changeset
79
15811
1a00d21910c8 Implementation of PEP-0217.
Moshe Zadka <moshez@math.huji.ac.il>
parents: 15487
diff changeset
80 \begin{funcdesc}{displayhook}{\var{value}}
18694
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
81 If \var{value} is not \code{None}, this function prints it to
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
82 \code{sys.stdout}, and saves it in \code{__builtin__._}.
15811
1a00d21910c8 Implementation of PEP-0217.
Moshe Zadka <moshez@math.huji.ac.il>
parents: 15487
diff changeset
83
18694
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
84 \code{sys.displayhook} is called on the result of evaluating an
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
85 expression entered in an interactive Python session. The display of
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
86 these values can be customized by assigning another one-argument
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
87 function to \code{sys.displayhook}.
15811
1a00d21910c8 Implementation of PEP-0217.
Moshe Zadka <moshez@math.huji.ac.il>
parents: 15487
diff changeset
88 \end{funcdesc}
1a00d21910c8 Implementation of PEP-0217.
Moshe Zadka <moshez@math.huji.ac.il>
parents: 15487
diff changeset
89
17164
b44e77a12978 Add sys.excepthook.
Ka-Ping Yee <ping@zesty.ca>
parents: 15811
diff changeset
90 \begin{funcdesc}{excepthook}{\var{type}, \var{value}, \var{traceback}}
18694
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
91 This function prints out a given traceback and exception to
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
92 \code{sys.stderr}.
17164
b44e77a12978 Add sys.excepthook.
Ka-Ping Yee <ping@zesty.ca>
parents: 15811
diff changeset
93
18694
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
94 When an exception is raised and uncaught, the interpreter calls
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
95 \code{sys.excepthook} with three arguments, the exception class,
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
96 exception instance, and a traceback object. In an interactive
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
97 session this happens just before control is returned to the prompt;
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
98 in a Python program this happens just before the program exits. The
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
99 handling of such top-level exceptions can be customized by assigning
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
100 another three-argument function to \code{sys.excepthook}.
17164
b44e77a12978 Add sys.excepthook.
Ka-Ping Yee <ping@zesty.ca>
parents: 15811
diff changeset
101 \end{funcdesc}
b44e77a12978 Add sys.excepthook.
Ka-Ping Yee <ping@zesty.ca>
parents: 15811
diff changeset
102
b44e77a12978 Add sys.excepthook.
Ka-Ping Yee <ping@zesty.ca>
parents: 15811
diff changeset
103 \begin{datadesc}{__displayhook__}
b44e77a12978 Add sys.excepthook.
Ka-Ping Yee <ping@zesty.ca>
parents: 15811
diff changeset
104 \dataline{__excepthook__}
18694
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
105 These objects contain the original values of \code{displayhook} and
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
106 \code{excepthook} at the start of the program. They are saved so
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
107 that \code{displayhook} and \code{excepthook} can be restored in
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
108 case they happen to get replaced with broken objects.
17164
b44e77a12978 Add sys.excepthook.
Ka-Ping Yee <ping@zesty.ca>
parents: 15811
diff changeset
109 \end{datadesc}
b44e77a12978 Add sys.excepthook.
Ka-Ping Yee <ping@zesty.ca>
parents: 15811
diff changeset
110
6492
222dd4d06581 Documented exc_info(); also updated exc_type and last_type docs.
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
111 \begin{funcdesc}{exc_info}{}
18694
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
112 This function returns a tuple of three values that give information
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
113 about the exception that is currently being handled. The
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
114 information returned is specific both to the current thread and to
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
115 the current stack frame. If the current stack frame is not handling
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
116 an exception, the information is taken from the calling stack frame,
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
117 or its caller, and so on until a stack frame is found that is
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
118 handling an exception. Here, ``handling an exception'' is defined
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
119 as ``executing or having executed an except clause.'' For any stack
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
120 frame, only information about the most recently handled exception is
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
121 accessible.
6492
222dd4d06581 Documented exc_info(); also updated exc_type and last_type docs.
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
122
18694
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
123 If no exception is being handled anywhere on the stack, a tuple
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
124 containing three \code{None} values is returned. Otherwise, the
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
125 values returned are \code{(\var{type}, \var{value},
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
126 \var{traceback})}. Their meaning is: \var{type} gets the exception
29302
08a1cbdd0367 SF bug #719367, string exceptions are deprecated
Neal Norwitz <nnorwitz@gmail.com>
parents: 28174
diff changeset
127 type of the exception being handled (a class object);
18694
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
128 \var{value} gets the exception parameter (its \dfn{associated value}
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
129 or the second argument to \keyword{raise}, which is always a class
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
130 instance if the exception type is a class object); \var{traceback}
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
131 gets a traceback object (see the Reference Manual) which
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
132 encapsulates the call stack at the point where the exception
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
133 originally occurred. \obindex{traceback}
6492
222dd4d06581 Documented exc_info(); also updated exc_type and last_type docs.
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
134
28119
869695cba2cd - New function sys.exc_clear() clears the current exception. This is
Guido van Rossum <guido@python.org>
parents: 25666
diff changeset
135 If \function{exc_clear()} is called, this function will return three
869695cba2cd - New function sys.exc_clear() clears the current exception. This is
Guido van Rossum <guido@python.org>
parents: 25666
diff changeset
136 \code{None} values until either another exception is raised in the
869695cba2cd - New function sys.exc_clear() clears the current exception. This is
Guido van Rossum <guido@python.org>
parents: 25666
diff changeset
137 current thread or the execution stack returns to a frame where
869695cba2cd - New function sys.exc_clear() clears the current exception. This is
Guido van Rossum <guido@python.org>
parents: 25666
diff changeset
138 another exception is being handled.
869695cba2cd - New function sys.exc_clear() clears the current exception. This is
Guido van Rossum <guido@python.org>
parents: 25666
diff changeset
139
20580
376ee174ecd0 Use the \note and \warning macros where appropriate.
Fred Drake <fdrake@acm.org>
parents: 20455
diff changeset
140 \warning{Assigning the \var{traceback} return value to a
18694
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
141 local variable in a function that is handling an exception will
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
142 cause a circular reference. This will prevent anything referenced
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
143 by a local variable in the same function or by the traceback from
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
144 being garbage collected. Since most functions don't need access to
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
145 the traceback, the best solution is to use something like
21641
b72da0780e7a Do not mask the name of a built-in function in example code.
Fred Drake <fdrake@acm.org>
parents: 21062
diff changeset
146 \code{exctype, value = sys.exc_info()[:2]} to extract only the
18694
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
147 exception type and value. If you do need the traceback, make sure
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
148 to delete it after use (best done with a \keyword{try}
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
149 ... \keyword{finally} statement) or to call \function{exc_info()} in
20624
7c381dd0779c Doc and NEWS changes due to Jeremy adding traceback objects to gc.
Tim Peters <tim.peters@gmail.com>
parents: 20580
diff changeset
150 a function that does not itself handle an exception.} \note{Beginning
7c381dd0779c Doc and NEWS changes due to Jeremy adding traceback objects to gc.
Tim Peters <tim.peters@gmail.com>
parents: 20580
diff changeset
151 with Python 2.2, such cycles are automatically reclaimed when garbage
7c381dd0779c Doc and NEWS changes due to Jeremy adding traceback objects to gc.
Tim Peters <tim.peters@gmail.com>
parents: 20580
diff changeset
152 collection is enabled and they become unreachable, but it remains more
7c381dd0779c Doc and NEWS changes due to Jeremy adding traceback objects to gc.
Tim Peters <tim.peters@gmail.com>
parents: 20580
diff changeset
153 efficient to avoid creating cycles.}
6492
222dd4d06581 Documented exc_info(); also updated exc_type and last_type docs.
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
154 \end{funcdesc}
222dd4d06581 Documented exc_info(); also updated exc_type and last_type docs.
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
155
28119
869695cba2cd - New function sys.exc_clear() clears the current exception. This is
Guido van Rossum <guido@python.org>
parents: 25666
diff changeset
156 \begin{funcdesc}{exc_clear}{}
869695cba2cd - New function sys.exc_clear() clears the current exception. This is
Guido van Rossum <guido@python.org>
parents: 25666
diff changeset
157 This function clears all information relating to the current or last
33457
016d7016c6c6 Patch #1026384: fix two common typo's:
Johannes Gijsbers <jlg@dds.nl>
parents: 33167
diff changeset
158 exception that occurred in the current thread. After calling this
28119
869695cba2cd - New function sys.exc_clear() clears the current exception. This is
Guido van Rossum <guido@python.org>
parents: 25666
diff changeset
159 function, \function{exc_info()} will return three \code{None} values until
869695cba2cd - New function sys.exc_clear() clears the current exception. This is
Guido van Rossum <guido@python.org>
parents: 25666
diff changeset
160 another exception is raised in the current thread or the execution stack
869695cba2cd - New function sys.exc_clear() clears the current exception. This is
Guido van Rossum <guido@python.org>
parents: 25666
diff changeset
161 returns to a frame where another exception is being handled.
39056
b6fd499e4343 After approval from Anthony, merge the tim-current_frames
Tim Peters <tim.peters@gmail.com>
parents: 38095
diff changeset
162
28119
869695cba2cd - New function sys.exc_clear() clears the current exception. This is
Guido van Rossum <guido@python.org>
parents: 25666
diff changeset
163 This function is only needed in only a few obscure situations. These
869695cba2cd - New function sys.exc_clear() clears the current exception. This is
Guido van Rossum <guido@python.org>
parents: 25666
diff changeset
164 include logging and error handling systems that report information on the
869695cba2cd - New function sys.exc_clear() clears the current exception. This is
Guido van Rossum <guido@python.org>
parents: 25666
diff changeset
165 last or current exception. This function can also be used to try to free
869695cba2cd - New function sys.exc_clear() clears the current exception. This is
Guido van Rossum <guido@python.org>
parents: 25666
diff changeset
166 resources and trigger object finalization, though no guarantee is made as
869695cba2cd - New function sys.exc_clear() clears the current exception. This is
Guido van Rossum <guido@python.org>
parents: 25666
diff changeset
167 to what objects will be freed, if any.
869695cba2cd - New function sys.exc_clear() clears the current exception. This is
Guido van Rossum <guido@python.org>
parents: 25666
diff changeset
168 \versionadded{2.3}
869695cba2cd - New function sys.exc_clear() clears the current exception. This is
Guido van Rossum <guido@python.org>
parents: 25666
diff changeset
169 \end{funcdesc}
869695cba2cd - New function sys.exc_clear() clears the current exception. This is
Guido van Rossum <guido@python.org>
parents: 25666
diff changeset
170
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
171 \begin{datadesc}{exc_type}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
172 \dataline{exc_value}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
173 \dataline{exc_traceback}
7602
7f4a503ce58b Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
174 \deprecated {1.5}
7f4a503ce58b Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
175 {Use \function{exc_info()} instead.}
18694
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
176 Since they are global variables, they are not specific to the
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
177 current thread, so their use is not safe in a multi-threaded
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
178 program. When no exception is being handled, \code{exc_type} is set
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
179 to \code{None} and the other two are undefined.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
180 \end{datadesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
181
5684
a0831de2358c Additional info about sys.path, sys.version, sys.prefix, sys.exec_prefix.
Guido van Rossum <guido@python.org>
parents: 4908
diff changeset
182 \begin{datadesc}{exec_prefix}
18694
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
183 A string giving the site-specific directory prefix where the
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
184 platform-dependent Python files are installed; by default, this is
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
185 also \code{'/usr/local'}. This can be set at build time with the
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
186 \longprogramopt{exec-prefix} argument to the \program{configure}
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
187 script. Specifically, all configuration files (e.g. the
18835
2dea40e40d9d Patch #411138: Rename config.h to pyconfig.h. Closes bug #231774.
Martin v. Löwis <martin@v.loewis.de>
parents: 18716
diff changeset
188 \file{pyconfig.h} header file) are installed in the directory
18694
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
189 \code{exec_prefix + '/lib/python\var{version}/config'}, and shared
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
190 library modules are installed in \code{exec_prefix +
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
191 '/lib/python\var{version}/lib-dynload'}, where \var{version} is
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
192 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
193 \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
194
8480
d93ae374fb99 Document several variables that were previously undocumented,
Guido van Rossum <guido@python.org>
parents: 7877
diff changeset
195 \begin{datadesc}{executable}
18694
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
196 A string giving the name of the executable binary for the Python
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
197 interpreter, on systems where this makes sense.
8480
d93ae374fb99 Document several variables that were previously undocumented,
Guido van Rossum <guido@python.org>
parents: 7877
diff changeset
198 \end{datadesc}
d93ae374fb99 Document several variables that were previously undocumented,
Guido van Rossum <guido@python.org>
parents: 7877
diff changeset
199
9511
bbe92932a005 Rewrote the section on sys.exit(), documenting other argument types
Guido van Rossum <guido@python.org>
parents: 8918
diff changeset
200 \begin{funcdesc}{exit}{\optional{arg}}
18694
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
201 Exit from Python. This is implemented by raising the
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
202 \exception{SystemExit} exception, so cleanup actions specified by
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
203 finally clauses of \keyword{try} statements are honored, and it is
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
204 possible to intercept the exit attempt at an outer level. The
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
205 optional argument \var{arg} can be an integer giving the exit status
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
206 (defaulting to zero), or another type of object. If it is an
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
207 integer, zero is considered ``successful termination'' and any
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
208 nonzero value is considered ``abnormal termination'' by shells and
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
209 the like. Most systems require it to be in the range 0-127, and
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
210 produce undefined results otherwise. Some systems have a convention
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
211 for assigning specific meanings to specific exit codes, but these
21062
bc02c3b09626 Clean up some markup cruft. A number of the macros that take no
Fred Drake <fdrake@acm.org>
parents: 20624
diff changeset
212 are generally underdeveloped; \UNIX{} programs generally use 2 for
18694
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
213 command line syntax errors and 1 for all other kind of errors. If
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
214 another type of object is passed, \code{None} is equivalent to
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
215 passing zero, and any other object is printed to \code{sys.stderr}
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
216 and results in an exit code of 1. In particular,
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
217 \code{sys.exit("some error message")} is a quick way to exit a
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
218 program when an error occurs.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
219 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
220
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
221 \begin{datadesc}{exitfunc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
222 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
223 the user (or by a program) to specify a clean-up action at program
18694
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
224 exit. When set, it should be a parameterless function. This
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
225 function will be called when the interpreter exits. Only one
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
226 function may be installed in this way; to allow multiple functions
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
227 which will be called at termination, use the \refmodule{atexit}
20580
376ee174ecd0 Use the \note and \warning macros where appropriate.
Fred Drake <fdrake@acm.org>
parents: 20455
diff changeset
228 module. \note{The exit function is not called when the program is
18694
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
229 killed by a signal, when a Python fatal internal error is detected,
20580
376ee174ecd0 Use the \note and \warning macros where appropriate.
Fred Drake <fdrake@acm.org>
parents: 20455
diff changeset
230 or when \code{os._exit()} is called.}
33167
96bf402488c7 Deprecate sys.exitfunc in favor of the atexit module.
Raymond Hettinger <python@rcn.com>
parents: 32969
diff changeset
231 \deprecated{2.4}{Use \refmodule{atexit} instead.}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
232 \end{datadesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
233
29765
e9e5832d706f New function sys.getcheckinterval(), to complement setcheckinterval().
Tim Peters <tim.peters@gmail.com>
parents: 29750
diff changeset
234 \begin{funcdesc}{getcheckinterval}{}
e9e5832d706f New function sys.getcheckinterval(), to complement setcheckinterval().
Tim Peters <tim.peters@gmail.com>
parents: 29750
diff changeset
235 Return the interpreter's ``check interval'';
e9e5832d706f New function sys.getcheckinterval(), to complement setcheckinterval().
Tim Peters <tim.peters@gmail.com>
parents: 29750
diff changeset
236 see \function{setcheckinterval()}.
29766
7a478d13f27d add versionadded for getcheckinterval
Neal Norwitz <nnorwitz@gmail.com>
parents: 29765
diff changeset
237 \versionadded{2.3}
29765
e9e5832d706f New function sys.getcheckinterval(), to complement setcheckinterval().
Tim Peters <tim.peters@gmail.com>
parents: 29750
diff changeset
238 \end{funcdesc}
e9e5832d706f New function sys.getcheckinterval(), to complement setcheckinterval().
Tim Peters <tim.peters@gmail.com>
parents: 29750
diff changeset
239
15331
788b523d4827 Additions from Marc-Andre Lemburg <mal@lemburg.com>, documenting
Fred Drake <fdrake@acm.org>
parents: 14311
diff changeset
240 \begin{funcdesc}{getdefaultencoding}{}
788b523d4827 Additions from Marc-Andre Lemburg <mal@lemburg.com>, documenting
Fred Drake <fdrake@acm.org>
parents: 14311
diff changeset
241 Return the name of the current default string encoding used by the
788b523d4827 Additions from Marc-Andre Lemburg <mal@lemburg.com>, documenting
Fred Drake <fdrake@acm.org>
parents: 14311
diff changeset
242 Unicode implementation.
788b523d4827 Additions from Marc-Andre Lemburg <mal@lemburg.com>, documenting
Fred Drake <fdrake@acm.org>
parents: 14311
diff changeset
243 \versionadded{2.0}
788b523d4827 Additions from Marc-Andre Lemburg <mal@lemburg.com>, documenting
Fred Drake <fdrake@acm.org>
parents: 14311
diff changeset
244 \end{funcdesc}
788b523d4827 Additions from Marc-Andre Lemburg <mal@lemburg.com>, documenting
Fred Drake <fdrake@acm.org>
parents: 14311
diff changeset
245
18689
064de84385ca Patch #412229: Add functions sys.getdlopenflags and sys.setdlopenflags.
Martin v. Löwis <martin@v.loewis.de>
parents: 17176
diff changeset
246 \begin{funcdesc}{getdlopenflags}{}
18691
07917f143488 Made a few minor style & markup changes to the new {get,set}dlopenflags()
Fred Drake <fdrake@acm.org>
parents: 18689
diff changeset
247 Return the current value of the flags that are used for
07917f143488 Made a few minor style & markup changes to the new {get,set}dlopenflags()
Fred Drake <fdrake@acm.org>
parents: 18689
diff changeset
248 \cfunction{dlopen()} calls. The flag constants are defined in the
07917f143488 Made a few minor style & markup changes to the new {get,set}dlopenflags()
Fred Drake <fdrake@acm.org>
parents: 18689
diff changeset
249 \refmodule{dl} and \module{DLFCN} modules.
07917f143488 Made a few minor style & markup changes to the new {get,set}dlopenflags()
Fred Drake <fdrake@acm.org>
parents: 18689
diff changeset
250 Availability: \UNIX.
07917f143488 Made a few minor style & markup changes to the new {get,set}dlopenflags()
Fred Drake <fdrake@acm.org>
parents: 18689
diff changeset
251 \versionadded{2.2}
18689
064de84385ca Patch #412229: Add functions sys.getdlopenflags and sys.setdlopenflags.
Martin v. Löwis <martin@v.loewis.de>
parents: 17176
diff changeset
252 \end{funcdesc}
064de84385ca Patch #412229: Add functions sys.getdlopenflags and sys.setdlopenflags.
Martin v. Löwis <martin@v.loewis.de>
parents: 17176
diff changeset
253
28174
3f90d21debe9 Always initialize Py_FileSystemDefaultEncoding on Unix in Py_Initialize,
Martin v. Löwis <martin@v.loewis.de>
parents: 28119
diff changeset
254 \begin{funcdesc}{getfilesystemencoding}{}
3f90d21debe9 Always initialize Py_FileSystemDefaultEncoding on Unix in Py_Initialize,
Martin v. Löwis <martin@v.loewis.de>
parents: 28119
diff changeset
255 Return the name of the encoding used to convert Unicode filenames
3f90d21debe9 Always initialize Py_FileSystemDefaultEncoding on Unix in Py_Initialize,
Martin v. Löwis <martin@v.loewis.de>
parents: 28119
diff changeset
256 into system file names, or \code{None} if the system default encoding
3f90d21debe9 Always initialize Py_FileSystemDefaultEncoding on Unix in Py_Initialize,
Martin v. Löwis <martin@v.loewis.de>
parents: 28119
diff changeset
257 is used. The result value depends on the operating system:
3f90d21debe9 Always initialize Py_FileSystemDefaultEncoding on Unix in Py_Initialize,
Martin v. Löwis <martin@v.loewis.de>
parents: 28119
diff changeset
258 \begin{itemize}
3f90d21debe9 Always initialize Py_FileSystemDefaultEncoding on Unix in Py_Initialize,
Martin v. Löwis <martin@v.loewis.de>
parents: 28119
diff changeset
259 \item On Windows 9x, the encoding is ``mbcs''.
3f90d21debe9 Always initialize Py_FileSystemDefaultEncoding on Unix in Py_Initialize,
Martin v. Löwis <martin@v.loewis.de>
parents: 28119
diff changeset
260 \item On Mac OS X, the encoding is ``utf-8''.
39296
388b7d90bb89 lots of markup nits, most commonly Unix/unix --> \UNIX
Fred Drake <fdrake@acm.org>
parents: 39088
diff changeset
261 \item On \UNIX, the encoding is the user's preference
388b7d90bb89 lots of markup nits, most commonly Unix/unix --> \UNIX
Fred Drake <fdrake@acm.org>
parents: 39088
diff changeset
262 according to the result of nl_langinfo(CODESET), or \constant{None}
388b7d90bb89 lots of markup nits, most commonly Unix/unix --> \UNIX
Fred Drake <fdrake@acm.org>
parents: 39088
diff changeset
263 if the \code{nl_langinfo(CODESET)} failed.
28174
3f90d21debe9 Always initialize Py_FileSystemDefaultEncoding on Unix in Py_Initialize,
Martin v. Löwis <martin@v.loewis.de>
parents: 28119
diff changeset
264 \item On Windows NT+, file names are Unicode natively, so no conversion
39296
388b7d90bb89 lots of markup nits, most commonly Unix/unix --> \UNIX
Fred Drake <fdrake@acm.org>
parents: 39088
diff changeset
265 is performed. \function{getfilesystemencoding()} still returns
388b7d90bb89 lots of markup nits, most commonly Unix/unix --> \UNIX
Fred Drake <fdrake@acm.org>
parents: 39088
diff changeset
266 \code{'mbcs'}, as this is the encoding that applications should use
388b7d90bb89 lots of markup nits, most commonly Unix/unix --> \UNIX
Fred Drake <fdrake@acm.org>
parents: 39088
diff changeset
267 when they explicitly want to convert Unicode strings to byte strings
388b7d90bb89 lots of markup nits, most commonly Unix/unix --> \UNIX
Fred Drake <fdrake@acm.org>
parents: 39088
diff changeset
268 that are equivalent when used as file names.
28174
3f90d21debe9 Always initialize Py_FileSystemDefaultEncoding on Unix in Py_Initialize,
Martin v. Löwis <martin@v.loewis.de>
parents: 28119
diff changeset
269 \end{itemize}
3f90d21debe9 Always initialize Py_FileSystemDefaultEncoding on Unix in Py_Initialize,
Martin v. Löwis <martin@v.loewis.de>
parents: 28119
diff changeset
270 \versionadded{2.3}
3f90d21debe9 Always initialize Py_FileSystemDefaultEncoding on Unix in Py_Initialize,
Martin v. Löwis <martin@v.loewis.de>
parents: 28119
diff changeset
271 \end{funcdesc}
3f90d21debe9 Always initialize Py_FileSystemDefaultEncoding on Unix in Py_Initialize,
Martin v. Löwis <martin@v.loewis.de>
parents: 28119
diff changeset
272
7216
16ecf1554a83 Document getrefcount().
Guido van Rossum <guido@python.org>
parents: 7079
diff changeset
273 \begin{funcdesc}{getrefcount}{object}
18694
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
274 Return the reference count of the \var{object}. The count returned
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
275 is generally one higher than you might expect, because it includes
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
276 the (temporary) reference as an argument to
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
277 \function{getrefcount()}.
7216
16ecf1554a83 Document getrefcount().
Guido van Rossum <guido@python.org>
parents: 7079
diff changeset
278 \end{funcdesc}
16ecf1554a83 Document getrefcount().
Guido van Rossum <guido@python.org>
parents: 7079
diff changeset
279
14308
b8b3f76ffd51 add user-modifiable recursion_limit
Jeremy Hylton <jeremy@alum.mit.edu>
parents: 13977
diff changeset
280 \begin{funcdesc}{getrecursionlimit}{}
18694
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
281 Return the current value of the recursion limit, the maximum depth
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
282 of the Python interpreter stack. This limit prevents infinite
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
283 recursion from causing an overflow of the C stack and crashing
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
284 Python. It can be set by \function{setrecursionlimit()}.
14308
b8b3f76ffd51 add user-modifiable recursion_limit
Jeremy Hylton <jeremy@alum.mit.edu>
parents: 13977
diff changeset
285 \end{funcdesc}
b8b3f76ffd51 add user-modifiable recursion_limit
Jeremy Hylton <jeremy@alum.mit.edu>
parents: 13977
diff changeset
286
15487
f0ca4c67957b _getframe(): New sys module function for getting at the stack frame.
Barry Warsaw <barry@python.org>
parents: 15331
diff changeset
287 \begin{funcdesc}{_getframe}{\optional{depth}}
18694
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
288 Return a frame object from the call stack. If optional integer
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
289 \var{depth} is given, return the frame object that many calls below
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
290 the top of the stack. If that is deeper than the call stack,
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
291 \exception{ValueError} is raised. The default for \var{depth} is
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
292 zero, returning the frame at the top of the call stack.
15487
f0ca4c67957b _getframe(): New sys module function for getting at the stack frame.
Barry Warsaw <barry@python.org>
parents: 15331
diff changeset
293
18694
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
294 This function should be used for internal and specialized purposes
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
295 only.
15487
f0ca4c67957b _getframe(): New sys module function for getting at the stack frame.
Barry Warsaw <barry@python.org>
parents: 15331
diff changeset
296 \end{funcdesc}
f0ca4c67957b _getframe(): New sys module function for getting at the stack frame.
Barry Warsaw <barry@python.org>
parents: 15331
diff changeset
297
25666
4a825b902310 Add os.path.supports_unicode_filenames for all platforms,
Mark Hammond <mhammond@skippinet.com.au>
parents: 25099
diff changeset
298 \begin{funcdesc}{getwindowsversion}{}
39056
b6fd499e4343 After approval from Anthony, merge the tim-current_frames
Tim Peters <tim.peters@gmail.com>
parents: 38095
diff changeset
299 Return a tuple containing five components, describing the Windows
b6fd499e4343 After approval from Anthony, merge the tim-current_frames
Tim Peters <tim.peters@gmail.com>
parents: 38095
diff changeset
300 version currently running. The elements are \var{major}, \var{minor},
25666
4a825b902310 Add os.path.supports_unicode_filenames for all platforms,
Mark Hammond <mhammond@skippinet.com.au>
parents: 25099
diff changeset
301 \var{build}, \var{platform}, and \var{text}. \var{text} contains
4a825b902310 Add os.path.supports_unicode_filenames for all platforms,
Mark Hammond <mhammond@skippinet.com.au>
parents: 25099
diff changeset
302 a string while all other values are integers.
4a825b902310 Add os.path.supports_unicode_filenames for all platforms,
Mark Hammond <mhammond@skippinet.com.au>
parents: 25099
diff changeset
303
4a825b902310 Add os.path.supports_unicode_filenames for all platforms,
Mark Hammond <mhammond@skippinet.com.au>
parents: 25099
diff changeset
304 \var{platform} may be one of the following values:
33966
06ee53a76f01 - remove use of a "list" environment (replace with a table)
Fred Drake <fdrake@acm.org>
parents: 33457
diff changeset
305
06ee53a76f01 - remove use of a "list" environment (replace with a table)
Fred Drake <fdrake@acm.org>
parents: 33457
diff changeset
306 \begin{tableii}{l|l}{constant}{Constant}{Platform}
36617
a9d6b1aec096 Bug #1323369: document possible values of sys.getwindowsversion()
Georg Brandl <georg@python.org>
parents: 36217
diff changeset
307 \lineii{0 (VER_PLATFORM_WIN32s)} {Win32s on Windows 3.1}
a9d6b1aec096 Bug #1323369: document possible values of sys.getwindowsversion()
Georg Brandl <georg@python.org>
parents: 36217
diff changeset
308 \lineii{1 (VER_PLATFORM_WIN32_WINDOWS)}{Windows 95/98/ME}
a9d6b1aec096 Bug #1323369: document possible values of sys.getwindowsversion()
Georg Brandl <georg@python.org>
parents: 36217
diff changeset
309 \lineii{2 (VER_PLATFORM_WIN32_NT)} {Windows NT/2000/XP}
a9d6b1aec096 Bug #1323369: document possible values of sys.getwindowsversion()
Georg Brandl <georg@python.org>
parents: 36217
diff changeset
310 \lineii{3 (VER_PLATFORM_WIN32_CE)} {Windows CE}
33966
06ee53a76f01 - remove use of a "list" environment (replace with a table)
Fred Drake <fdrake@acm.org>
parents: 33457
diff changeset
311 \end{tableii}
06ee53a76f01 - remove use of a "list" environment (replace with a table)
Fred Drake <fdrake@acm.org>
parents: 33457
diff changeset
312
06ee53a76f01 - remove use of a "list" environment (replace with a table)
Fred Drake <fdrake@acm.org>
parents: 33457
diff changeset
313 This function wraps the Win32 \cfunction{GetVersionEx()} function;
06ee53a76f01 - remove use of a "list" environment (replace with a table)
Fred Drake <fdrake@acm.org>
parents: 33457
diff changeset
314 see the Microsoft documentation for more information about these
25666
4a825b902310 Add os.path.supports_unicode_filenames for all platforms,
Mark Hammond <mhammond@skippinet.com.au>
parents: 25099
diff changeset
315 fields.
4a825b902310 Add os.path.supports_unicode_filenames for all platforms,
Mark Hammond <mhammond@skippinet.com.au>
parents: 25099
diff changeset
316
4a825b902310 Add os.path.supports_unicode_filenames for all platforms,
Mark Hammond <mhammond@skippinet.com.au>
parents: 25099
diff changeset
317 Availability: Windows.
4a825b902310 Add os.path.supports_unicode_filenames for all platforms,
Mark Hammond <mhammond@skippinet.com.au>
parents: 25099
diff changeset
318 \versionadded{2.3}
4a825b902310 Add os.path.supports_unicode_filenames for all platforms,
Mark Hammond <mhammond@skippinet.com.au>
parents: 25099
diff changeset
319 \end{funcdesc}
4a825b902310 Add os.path.supports_unicode_filenames for all platforms,
Mark Hammond <mhammond@skippinet.com.au>
parents: 25099
diff changeset
320
12395
3bb398996291 Document hexversion (incompletely explained) and version_info (easily
Fred Drake <fdrake@acm.org>
parents: 12380
diff changeset
321 \begin{datadesc}{hexversion}
18694
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
322 The version number encoded as a single integer. This is guaranteed
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
323 to increase with each version, including proper support for
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
324 non-production releases. For example, to test that the Python
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
325 interpreter is at least version 1.5.2, use:
12395
3bb398996291 Document hexversion (incompletely explained) and version_info (easily
Fred Drake <fdrake@acm.org>
parents: 12380
diff changeset
326
3bb398996291 Document hexversion (incompletely explained) and version_info (easily
Fred Drake <fdrake@acm.org>
parents: 12380
diff changeset
327 \begin{verbatim}
3bb398996291 Document hexversion (incompletely explained) and version_info (easily
Fred Drake <fdrake@acm.org>
parents: 12380
diff changeset
328 if sys.hexversion >= 0x010502F0:
3bb398996291 Document hexversion (incompletely explained) and version_info (easily
Fred Drake <fdrake@acm.org>
parents: 12380
diff changeset
329 # use some advanced feature
3bb398996291 Document hexversion (incompletely explained) and version_info (easily
Fred Drake <fdrake@acm.org>
parents: 12380
diff changeset
330 ...
3bb398996291 Document hexversion (incompletely explained) and version_info (easily
Fred Drake <fdrake@acm.org>
parents: 12380
diff changeset
331 else:
3bb398996291 Document hexversion (incompletely explained) and version_info (easily
Fred Drake <fdrake@acm.org>
parents: 12380
diff changeset
332 # use an alternative implementation or warn the user
3bb398996291 Document hexversion (incompletely explained) and version_info (easily
Fred Drake <fdrake@acm.org>
parents: 12380
diff changeset
333 ...
3bb398996291 Document hexversion (incompletely explained) and version_info (easily
Fred Drake <fdrake@acm.org>
parents: 12380
diff changeset
334 \end{verbatim}
3bb398996291 Document hexversion (incompletely explained) and version_info (easily
Fred Drake <fdrake@acm.org>
parents: 12380
diff changeset
335
18694
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
336 This is called \samp{hexversion} since it only really looks
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
337 meaningful when viewed as the result of passing it to the built-in
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
338 \function{hex()} function. The \code{version_info} value may be
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
339 used for a more human-friendly encoding of the same information.
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
340 \versionadded{1.5.2}
12395
3bb398996291 Document hexversion (incompletely explained) and version_info (easily
Fred Drake <fdrake@acm.org>
parents: 12380
diff changeset
341 \end{datadesc}
3bb398996291 Document hexversion (incompletely explained) and version_info (easily
Fred Drake <fdrake@acm.org>
parents: 12380
diff changeset
342
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
343 \begin{datadesc}{last_type}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
344 \dataline{last_value}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
345 \dataline{last_traceback}
18694
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
346 These three variables are not always defined; they are set when an
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
347 exception is not handled and the interpreter prints an error message
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
348 and a stack traceback. Their intended use is to allow an
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
349 interactive user to import a debugger module and engage in
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
350 post-mortem debugging without having to re-execute the command that
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
351 caused the error. (Typical use is \samp{import pdb; pdb.pm()} to
33966
06ee53a76f01 - remove use of a "list" environment (replace with a table)
Fred Drake <fdrake@acm.org>
parents: 33457
diff changeset
352 enter the post-mortem debugger; see chapter~\ref{debugger}, ``The
18694
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
353 Python Debugger,'' for more information.)
6492
222dd4d06581 Documented exc_info(); also updated exc_type and last_type docs.
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
354
18694
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
355 The meaning of the variables is the same as that of the return
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
356 values from \function{exc_info()} above. (Since there is only one
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
357 interactive thread, thread-safety is not a concern for these
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
358 variables, unlike for \code{exc_type} etc.)
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
359 \end{datadesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
360
8480
d93ae374fb99 Document several variables that were previously undocumented,
Guido van Rossum <guido@python.org>
parents: 7877
diff changeset
361 \begin{datadesc}{maxint}
18694
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
362 The largest positive integer supported by Python's regular integer
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
363 type. This is at least 2**31-1. The largest negative integer is
19688
31a66c0c7d30 Added documentation for sys.maxunicode and sys.warnoptions.
Fred Drake <fdrake@acm.org>
parents: 18835
diff changeset
364 \code{-maxint-1} --- the asymmetry results from the use of 2's
18694
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
365 complement binary arithmetic.
8480
d93ae374fb99 Document several variables that were previously undocumented,
Guido van Rossum <guido@python.org>
parents: 7877
diff changeset
366 \end{datadesc}
d93ae374fb99 Document several variables that were previously undocumented,
Guido van Rossum <guido@python.org>
parents: 7877
diff changeset
367
19688
31a66c0c7d30 Added documentation for sys.maxunicode and sys.warnoptions.
Fred Drake <fdrake@acm.org>
parents: 18835
diff changeset
368 \begin{datadesc}{maxunicode}
31a66c0c7d30 Added documentation for sys.maxunicode and sys.warnoptions.
Fred Drake <fdrake@acm.org>
parents: 18835
diff changeset
369 An integer giving the largest supported code point for a Unicode
31a66c0c7d30 Added documentation for sys.maxunicode and sys.warnoptions.
Fred Drake <fdrake@acm.org>
parents: 18835
diff changeset
370 character. The value of this depends on the configuration option
31a66c0c7d30 Added documentation for sys.maxunicode and sys.warnoptions.
Fred Drake <fdrake@acm.org>
parents: 18835
diff changeset
371 that specifies whether Unicode characters are stored as UCS-2 or
31a66c0c7d30 Added documentation for sys.maxunicode and sys.warnoptions.
Fred Drake <fdrake@acm.org>
parents: 18835
diff changeset
372 UCS-4.
31a66c0c7d30 Added documentation for sys.maxunicode and sys.warnoptions.
Fred Drake <fdrake@acm.org>
parents: 18835
diff changeset
373 \end{datadesc}
31a66c0c7d30 Added documentation for sys.maxunicode and sys.warnoptions.
Fred Drake <fdrake@acm.org>
parents: 18835
diff changeset
374
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
375 \begin{datadesc}{modules}
7602
7f4a503ce58b Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
376 This is a dictionary that maps module names to modules which have
7f4a503ce58b Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
377 already been loaded. This can be manipulated to force reloading of
7f4a503ce58b Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
378 modules and other tricks. Note that removing a module from this
7f4a503ce58b Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
379 dictionary is \emph{not} the same as calling
7f4a503ce58b Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
380 \function{reload()}\bifuncindex{reload} on the corresponding module
7f4a503ce58b Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
381 object.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
382 \end{datadesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
383
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
384 \begin{datadesc}{path}
7079
322dca5ee145 Added "module search path" to the index.
Fred Drake <fdrake@acm.org>
parents: 6862
diff changeset
385 \indexiii{module}{search}{path}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
386 A list of strings that specifies the search path for modules.
24238
3895b78d3ee0 Clarify that the description of sys.path[0] is only valid upon program
Guido van Rossum <guido@python.org>
parents: 22609
diff changeset
387 Initialized from the environment variable \envvar{PYTHONPATH}, plus an
18694
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
388 installation-dependent default.
5684
a0831de2358c Additional info about sys.path, sys.version, sys.prefix, sys.exec_prefix.
Guido van Rossum <guido@python.org>
parents: 4908
diff changeset
389
24238
3895b78d3ee0 Clarify that the description of sys.path[0] is only valid upon program
Guido van Rossum <guido@python.org>
parents: 22609
diff changeset
390 As initialized upon program startup,
3895b78d3ee0 Clarify that the description of sys.path[0] is only valid upon program
Guido van Rossum <guido@python.org>
parents: 22609
diff changeset
391 the first item of this list, \code{path[0]}, is the directory
18694
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
392 containing the script that was used to invoke the Python
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
393 interpreter. If the script directory is not available (e.g. if the
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
394 interpreter is invoked interactively or if the script is read from
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
395 standard input), \code{path[0]} is the empty string, which directs
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
396 Python to search modules in the current directory first. Notice
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
397 that the script directory is inserted \emph{before} the entries
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
398 inserted as a result of \envvar{PYTHONPATH}.
24238
3895b78d3ee0 Clarify that the description of sys.path[0] is only valid upon program
Guido van Rossum <guido@python.org>
parents: 22609
diff changeset
399
3895b78d3ee0 Clarify that the description of sys.path[0] is only valid upon program
Guido van Rossum <guido@python.org>
parents: 22609
diff changeset
400 A program is free to modify this list for its own purposes.
29913
52760751c61e Note that Unicode strings are now supported in sys.path.
Fred Drake <fdrake@acm.org>
parents: 29766
diff changeset
401
31727
c4d9a96be2dd Removed extra period from \versionchanged entry; macro adds period
Brett Cannon <bcannon@gmail.com>
parents: 29913
diff changeset
402 \versionchanged[Unicode strings are no longer ignored]{2.3}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
403 \end{datadesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
404
2817
8b8fb24d4837 correct typo; document sys.platform
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
405 \begin{datadesc}{platform}
18694
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
406 This string contains a platform identifier, e.g. \code{'sunos5'} or
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
407 \code{'linux1'}. This can be used to append platform-specific
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
408 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
409 \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
410
a0831de2358c Additional info about sys.path, sys.version, sys.prefix, sys.exec_prefix.
Guido van Rossum <guido@python.org>
parents: 4908
diff changeset
411 \begin{datadesc}{prefix}
18694
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
412 A string giving the site-specific directory prefix where the
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
413 platform independent Python files are installed; by default, this is
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
414 the string \code{'/usr/local'}. This can be set at build time with
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
415 the \longprogramopt{prefix} argument to the \program{configure}
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
416 script. The main collection of Python library modules is installed
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
417 in the directory \code{prefix + '/lib/python\var{version}'} while
18835
2dea40e40d9d Patch #411138: Rename config.h to pyconfig.h. Closes bug #231774.
Martin v. Löwis <martin@v.loewis.de>
parents: 18716
diff changeset
418 the platform independent header files (all except \file{pyconfig.h})
18694
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
419 are stored in \code{prefix + '/include/python\var{version}'}, where
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
420 \var{version} is equal to \code{version[:3]}.
2817
8b8fb24d4837 correct typo; document sys.platform
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
421 \end{datadesc}
8b8fb24d4837 correct typo; document sys.platform
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
422
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
423 \begin{datadesc}{ps1}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
424 \dataline{ps2}
7824
b85a675b6503 New index entries.
Fred Drake <fdrake@acm.org>
parents: 7759
diff changeset
425 \index{interpreter prompts}
b85a675b6503 New index entries.
Fred Drake <fdrake@acm.org>
parents: 7759
diff changeset
426 \index{prompts, interpreter}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
427 Strings specifying the primary and secondary prompt of the
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
428 interpreter. These are only defined if the interpreter is in
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
429 interactive mode. Their initial values in this case are
38095
eb03562df4a7 fix up whitespace in prompt strings
Fred Drake <fdrake@acm.org>
parents: 38091
diff changeset
430 \code{'>>>~'} and \code{'...~'}. If a non-string object is
18694
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
431 assigned to either variable, its \function{str()} is re-evaluated
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
432 each time the interpreter prepares to read a new interactive
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
433 command; this can be used to implement a dynamic prompt.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
434 \end{datadesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
435
2109
07080a296070 sys.setcheckinterval(x) instead of sys.check_interval = x
Guido van Rossum <guido@python.org>
parents: 1936
diff changeset
436 \begin{funcdesc}{setcheckinterval}{interval}
18694
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
437 Set the interpreter's ``check interval''. This integer value
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
438 determines how often the interpreter checks for periodic things such
29750
b86446f0350f Correct documentation of check interval - it's 100 by default, not 10 any
Skip Montanaro <skip@pobox.com>
parents: 29302
diff changeset
439 as thread switches and signal handlers. The default is \code{100},
b86446f0350f Correct documentation of check interval - it's 100 by default, not 10 any
Skip Montanaro <skip@pobox.com>
parents: 29302
diff changeset
440 meaning the check is performed every 100 Python virtual instructions.
18694
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
441 Setting it to a larger value may increase performance for programs
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
442 using threads. Setting it to a value \code{<=} 0 checks every
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
443 virtual instruction, maximizing responsiveness as well as overhead.
2138
23f040317828 cosmetics/typos
Guido van Rossum <guido@python.org>
parents: 2109
diff changeset
444 \end{funcdesc}
2109
07080a296070 sys.setcheckinterval(x) instead of sys.check_interval = x
Guido van Rossum <guido@python.org>
parents: 1936
diff changeset
445
15331
788b523d4827 Additions from Marc-Andre Lemburg <mal@lemburg.com>, documenting
Fred Drake <fdrake@acm.org>
parents: 14311
diff changeset
446 \begin{funcdesc}{setdefaultencoding}{name}
788b523d4827 Additions from Marc-Andre Lemburg <mal@lemburg.com>, documenting
Fred Drake <fdrake@acm.org>
parents: 14311
diff changeset
447 Set the current default string encoding used by the Unicode
788b523d4827 Additions from Marc-Andre Lemburg <mal@lemburg.com>, documenting
Fred Drake <fdrake@acm.org>
parents: 14311
diff changeset
448 implementation. If \var{name} does not match any available
788b523d4827 Additions from Marc-Andre Lemburg <mal@lemburg.com>, documenting
Fred Drake <fdrake@acm.org>
parents: 14311
diff changeset
449 encoding, \exception{LookupError} is raised. This function is only
788b523d4827 Additions from Marc-Andre Lemburg <mal@lemburg.com>, documenting
Fred Drake <fdrake@acm.org>
parents: 14311
diff changeset
450 intended to be used by the \refmodule{site} module implementation
788b523d4827 Additions from Marc-Andre Lemburg <mal@lemburg.com>, documenting
Fred Drake <fdrake@acm.org>
parents: 14311
diff changeset
451 and, where needed, by \module{sitecustomize}. Once used by the
788b523d4827 Additions from Marc-Andre Lemburg <mal@lemburg.com>, documenting
Fred Drake <fdrake@acm.org>
parents: 14311
diff changeset
452 \refmodule{site} module, it is removed from the \module{sys}
788b523d4827 Additions from Marc-Andre Lemburg <mal@lemburg.com>, documenting
Fred Drake <fdrake@acm.org>
parents: 14311
diff changeset
453 module's namespace.
788b523d4827 Additions from Marc-Andre Lemburg <mal@lemburg.com>, documenting
Fred Drake <fdrake@acm.org>
parents: 14311
diff changeset
454 % Note that \refmodule{site} is not imported if
788b523d4827 Additions from Marc-Andre Lemburg <mal@lemburg.com>, documenting
Fred Drake <fdrake@acm.org>
parents: 14311
diff changeset
455 % the \programopt{-S} option is passed to the interpreter, in which
788b523d4827 Additions from Marc-Andre Lemburg <mal@lemburg.com>, documenting
Fred Drake <fdrake@acm.org>
parents: 14311
diff changeset
456 % case this function will remain available.
788b523d4827 Additions from Marc-Andre Lemburg <mal@lemburg.com>, documenting
Fred Drake <fdrake@acm.org>
parents: 14311
diff changeset
457 \versionadded{2.0}
788b523d4827 Additions from Marc-Andre Lemburg <mal@lemburg.com>, documenting
Fred Drake <fdrake@acm.org>
parents: 14311
diff changeset
458 \end{funcdesc}
788b523d4827 Additions from Marc-Andre Lemburg <mal@lemburg.com>, documenting
Fred Drake <fdrake@acm.org>
parents: 14311
diff changeset
459
18716
4ca9aced5503 Fix a few typos
Andrew M. Kuchling <amk@amk.ca>
parents: 18694
diff changeset
460 \begin{funcdesc}{setdlopenflags}{n}
18691
07917f143488 Made a few minor style & markup changes to the new {get,set}dlopenflags()
Fred Drake <fdrake@acm.org>
parents: 18689
diff changeset
461 Set the flags used by the interpreter for \cfunction{dlopen()}
07917f143488 Made a few minor style & markup changes to the new {get,set}dlopenflags()
Fred Drake <fdrake@acm.org>
parents: 18689
diff changeset
462 calls, such as when the interpreter loads extension modules. Among
07917f143488 Made a few minor style & markup changes to the new {get,set}dlopenflags()
Fred Drake <fdrake@acm.org>
parents: 18689
diff changeset
463 other things, this will enable a lazy resolving of symbols when
18716
4ca9aced5503 Fix a few typos
Andrew M. Kuchling <amk@amk.ca>
parents: 18694
diff changeset
464 importing a module, if called as \code{sys.setdlopenflags(0)}. To
4ca9aced5503 Fix a few typos
Andrew M. Kuchling <amk@amk.ca>
parents: 18694
diff changeset
465 share symbols across extension modules, call as
18694
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
466 \code{sys.setdlopenflags(dl.RTLD_NOW | dl.RTLD_GLOBAL)}. Symbolic
18691
07917f143488 Made a few minor style & markup changes to the new {get,set}dlopenflags()
Fred Drake <fdrake@acm.org>
parents: 18689
diff changeset
467 names for the flag modules can be either found in the \refmodule{dl}
07917f143488 Made a few minor style & markup changes to the new {get,set}dlopenflags()
Fred Drake <fdrake@acm.org>
parents: 18689
diff changeset
468 module, or in the \module{DLFCN} module. If \module{DLFCN} is not
18694
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
469 available, it can be generated from \file{/usr/include/dlfcn.h}
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
470 using the \program{h2py} script.
18691
07917f143488 Made a few minor style & markup changes to the new {get,set}dlopenflags()
Fred Drake <fdrake@acm.org>
parents: 18689
diff changeset
471 Availability: \UNIX.
07917f143488 Made a few minor style & markup changes to the new {get,set}dlopenflags()
Fred Drake <fdrake@acm.org>
parents: 18689
diff changeset
472 \versionadded{2.2}
18689
064de84385ca Patch #412229: Add functions sys.getdlopenflags and sys.setdlopenflags.
Martin v. Löwis <martin@v.loewis.de>
parents: 17176
diff changeset
473 \end{funcdesc}
064de84385ca Patch #412229: Add functions sys.getdlopenflags and sys.setdlopenflags.
Martin v. Löwis <martin@v.loewis.de>
parents: 17176
diff changeset
474
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
475 \begin{funcdesc}{setprofile}{profilefunc}
18694
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
476 Set the system's profile function,\index{profile function} which
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
477 allows you to implement a Python source code profiler in
33966
06ee53a76f01 - remove use of a "list" environment (replace with a table)
Fred Drake <fdrake@acm.org>
parents: 33457
diff changeset
478 Python.\index{profiler} See chapter~\ref{profile} for more
18694
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
479 information on the Python profiler. The system's profile function
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
480 is called similarly to the system's trace function (see
18694
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
481 \function{settrace()}), but it isn't called for each executed line
20455
ec9596687292 Added information about setprofile() and settrace() hooks being thread-
Fred Drake <fdrake@acm.org>
parents: 19688
diff changeset
482 of code (only on call and return, but the return event is reported
ec9596687292 Added information about setprofile() and settrace() hooks being thread-
Fred Drake <fdrake@acm.org>
parents: 19688
diff changeset
483 even when an exception has been set). The function is
ec9596687292 Added information about setprofile() and settrace() hooks being thread-
Fred Drake <fdrake@acm.org>
parents: 19688
diff changeset
484 thread-specific, but there is no way for the profiler to know about
ec9596687292 Added information about setprofile() and settrace() hooks being thread-
Fred Drake <fdrake@acm.org>
parents: 19688
diff changeset
485 context switches between threads, so it does not make sense to use
ec9596687292 Added information about setprofile() and settrace() hooks being thread-
Fred Drake <fdrake@acm.org>
parents: 19688
diff changeset
486 this in the presence of multiple threads.
18694
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
487 Also, its return value is not used, so it can simply return
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
488 \code{None}.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
489 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
490
14308
b8b3f76ffd51 add user-modifiable recursion_limit
Jeremy Hylton <jeremy@alum.mit.edu>
parents: 13977
diff changeset
491 \begin{funcdesc}{setrecursionlimit}{limit}
18694
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
492 Set the maximum depth of the Python interpreter stack to
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
493 \var{limit}. This limit prevents infinite recursion from causing an
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
494 overflow of the C stack and crashing Python.
14308
b8b3f76ffd51 add user-modifiable recursion_limit
Jeremy Hylton <jeremy@alum.mit.edu>
parents: 13977
diff changeset
495
18694
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
496 The highest possible limit is platform-dependent. A user may need
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
497 to set the limit higher when she has a program that requires deep
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
498 recursion and a platform that supports a higher limit. This should
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
499 be done with care, because a too-high limit can lead to a crash.
14311
97651f28b004 Fix markup error and minor consistency nit.
Fred Drake <fdrake@acm.org>
parents: 14308
diff changeset
500 \end{funcdesc}
14308
b8b3f76ffd51 add user-modifiable recursion_limit
Jeremy Hylton <jeremy@alum.mit.edu>
parents: 13977
diff changeset
501
8480
d93ae374fb99 Document several variables that were previously undocumented,
Guido van Rossum <guido@python.org>
parents: 7877
diff changeset
502 \begin{funcdesc}{settrace}{tracefunc}
18694
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
503 Set the system's trace function,\index{trace function} which allows
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
504 you to implement a Python source code debugger in Python. See
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
505 section \ref{debugger-hooks}, ``How It Works,'' in the chapter on
20455
ec9596687292 Added information about setprofile() and settrace() hooks being thread-
Fred Drake <fdrake@acm.org>
parents: 19688
diff changeset
506 the Python debugger.\index{debugger} The function is
ec9596687292 Added information about setprofile() and settrace() hooks being thread-
Fred Drake <fdrake@acm.org>
parents: 19688
diff changeset
507 thread-specific; for a debugger to support multiple threads, it must
ec9596687292 Added information about setprofile() and settrace() hooks being thread-
Fred Drake <fdrake@acm.org>
parents: 19688
diff changeset
508 be registered using \function{settrace()} for each thread being
32969
e6d009276c54 Warn that settrace() is implementation rather than language
Phillip J. Eby <pje@telecommunity.com>
parents: 32358
diff changeset
509 debugged. \note{The \function{settrace()} function is intended only
e6d009276c54 Warn that settrace() is implementation rather than language
Phillip J. Eby <pje@telecommunity.com>
parents: 32358
diff changeset
510 for implementing debuggers, profilers, coverage tools and the like.
39056
b6fd499e4343 After approval from Anthony, merge the tim-current_frames
Tim Peters <tim.peters@gmail.com>
parents: 38095
diff changeset
511 Its behavior is part of the implementation platform, rather than
32969
e6d009276c54 Warn that settrace() is implementation rather than language
Phillip J. Eby <pje@telecommunity.com>
parents: 32358
diff changeset
512 part of the language definition, and thus may not be available in
e6d009276c54 Warn that settrace() is implementation rather than language
Phillip J. Eby <pje@telecommunity.com>
parents: 32358
diff changeset
513 all Python implementations.}
8480
d93ae374fb99 Document several variables that were previously undocumented,
Guido van Rossum <guido@python.org>
parents: 7877
diff changeset
514 \end{funcdesc}
d93ae374fb99 Document several variables that were previously undocumented,
Guido van Rossum <guido@python.org>
parents: 7877
diff changeset
515
32301
41c59d80bbc5 Patch #510695: Add TSC profiling for the VM.
Martin v. Löwis <martin@v.loewis.de>
parents: 31727
diff changeset
516 \begin{funcdesc}{settscdump}{on_flag}
41c59d80bbc5 Patch #510695: Add TSC profiling for the VM.
Martin v. Löwis <martin@v.loewis.de>
parents: 31727
diff changeset
517 Activate dumping of VM measurements using the Pentium timestamp
41c59d80bbc5 Patch #510695: Add TSC profiling for the VM.
Martin v. Löwis <martin@v.loewis.de>
parents: 31727
diff changeset
518 counter, if \var{on_flag} is true. Deactivate these dumps if
41c59d80bbc5 Patch #510695: Add TSC profiling for the VM.
Martin v. Löwis <martin@v.loewis.de>
parents: 31727
diff changeset
519 \var{on_flag} is off. The function is available only if Python
32303
a0d8b1456819 - markup fix
Fred Drake <fdrake@acm.org>
parents: 32301
diff changeset
520 was compiled with \longprogramopt{with-tsc}. To understand the
a0d8b1456819 - markup fix
Fred Drake <fdrake@acm.org>
parents: 32301
diff changeset
521 output of this dump, read \file{Python/ceval.c} in the Python
a0d8b1456819 - markup fix
Fred Drake <fdrake@acm.org>
parents: 32301
diff changeset
522 sources.
32301
41c59d80bbc5 Patch #510695: Add TSC profiling for the VM.
Martin v. Löwis <martin@v.loewis.de>
parents: 31727
diff changeset
523 \versionadded{2.4}
41c59d80bbc5 Patch #510695: Add TSC profiling for the VM.
Martin v. Löwis <martin@v.loewis.de>
parents: 31727
diff changeset
524 \end{funcdesc}
41c59d80bbc5 Patch #510695: Add TSC profiling for the VM.
Martin v. Löwis <martin@v.loewis.de>
parents: 31727
diff changeset
525
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
526 \begin{datadesc}{stdin}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
527 \dataline{stdout}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
528 \dataline{stderr}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
529 File objects corresponding to the interpreter's standard input,
18694
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
530 output and error streams. \code{stdin} is used for all interpreter
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
531 input except for scripts but including calls to
7602
7f4a503ce58b Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
532 \function{input()}\bifuncindex{input} and
18694
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
533 \function{raw_input()}\bifuncindex{raw_input}. \code{stdout} is
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
534 used for the output of \keyword{print} and expression statements and
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
535 for the prompts of \function{input()} and \function{raw_input()}.
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
536 The interpreter's own prompts and (almost all of) its error messages
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
537 go to \code{stderr}. \code{stdout} and \code{stderr} needn't be
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
538 built-in file objects: any object is acceptable as long as it has a
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
539 \method{write()} method that takes a string argument. (Changing
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
540 these objects doesn't affect the standard I/O streams of processes
7602
7f4a503ce58b Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
541 executed by \function{os.popen()}, \function{os.system()} or the
18694
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
542 \function{exec*()} family of functions in the \refmodule{os}
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
543 module.)
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
544 \end{datadesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
545
8480
d93ae374fb99 Document several variables that were previously undocumented,
Guido van Rossum <guido@python.org>
parents: 7877
diff changeset
546 \begin{datadesc}{__stdin__}
d93ae374fb99 Document several variables that were previously undocumented,
Guido van Rossum <guido@python.org>
parents: 7877
diff changeset
547 \dataline{__stdout__}
d93ae374fb99 Document several variables that were previously undocumented,
Guido van Rossum <guido@python.org>
parents: 7877
diff changeset
548 \dataline{__stderr__}
18694
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
549 These objects contain the original values of \code{stdin},
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
550 \code{stderr} and \code{stdout} at the start of the program. They
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
551 are used during finalization, and could be useful to restore the
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
552 actual files to known working file objects in case they have been
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
553 overwritten with a broken object.
8480
d93ae374fb99 Document several variables that were previously undocumented,
Guido van Rossum <guido@python.org>
parents: 7877
diff changeset
554 \end{datadesc}
d93ae374fb99 Document several variables that were previously undocumented,
Guido van Rossum <guido@python.org>
parents: 7877
diff changeset
555
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
556 \begin{datadesc}{tracebacklimit}
18694
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
557 When this variable is set to an integer value, it determines the
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
558 maximum number of levels of traceback information printed when an
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
559 unhandled exception occurs. The default is \code{1000}. When set
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
560 to \code{0} or less, all traceback information is suppressed and
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
561 only the exception type and value are printed.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
562 \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
563
a0831de2358c Additional info about sys.path, sys.version, sys.prefix, sys.exec_prefix.
Guido van Rossum <guido@python.org>
parents: 4908
diff changeset
564 \begin{datadesc}{version}
18694
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
565 A string containing the version number of the Python interpreter
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
566 plus additional information on the build number and compiler used.
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
567 It has a value of the form \code{'\var{version}
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
568 (\#\var{build_number}, \var{build_date}, \var{build_time})
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
569 [\var{compiler}]'}. The first three characters are used to identify
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
570 the version in the installation directories (where appropriate on
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
571 each platform). An example:
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11457
diff changeset
572
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11457
diff changeset
573 \begin{verbatim}
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11457
diff changeset
574 >>> import sys
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11457
diff changeset
575 >>> sys.version
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11457
diff changeset
576 '1.5.2 (#0 Apr 13 1999, 10:51:12) [MSC 32 bit (Intel)]'
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11457
diff changeset
577 \end{verbatim}
5684
a0831de2358c Additional info about sys.path, sys.version, sys.prefix, sys.exec_prefix.
Guido van Rossum <guido@python.org>
parents: 4908
diff changeset
578 \end{datadesc}
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11457
diff changeset
579
25099
a69a12484d69 expose PYTHON_API_VERSION macro as sys.api_version. Closes patch # 601456.
Skip Montanaro <skip@pobox.com>
parents: 24238
diff changeset
580 \begin{datadesc}{api_version}
a69a12484d69 expose PYTHON_API_VERSION macro as sys.api_version. Closes patch # 601456.
Skip Montanaro <skip@pobox.com>
parents: 24238
diff changeset
581 The C API version for this interpreter. Programmers may find this useful
a69a12484d69 expose PYTHON_API_VERSION macro as sys.api_version. Closes patch # 601456.
Skip Montanaro <skip@pobox.com>
parents: 24238
diff changeset
582 when debugging version conflicts between Python and extension
a69a12484d69 expose PYTHON_API_VERSION macro as sys.api_version. Closes patch # 601456.
Skip Montanaro <skip@pobox.com>
parents: 24238
diff changeset
583 modules. \versionadded{2.3}
a69a12484d69 expose PYTHON_API_VERSION macro as sys.api_version. Closes patch # 601456.
Skip Montanaro <skip@pobox.com>
parents: 24238
diff changeset
584 \end{datadesc}
a69a12484d69 expose PYTHON_API_VERSION macro as sys.api_version. Closes patch # 601456.
Skip Montanaro <skip@pobox.com>
parents: 24238
diff changeset
585
12395
3bb398996291 Document hexversion (incompletely explained) and version_info (easily
Fred Drake <fdrake@acm.org>
parents: 12380
diff changeset
586 \begin{datadesc}{version_info}
18694
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
587 A tuple containing the five components of the version number:
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
588 \var{major}, \var{minor}, \var{micro}, \var{releaselevel}, and
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
589 \var{serial}. All values except \var{releaselevel} are integers;
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
590 the release level is \code{'alpha'}, \code{'beta'},
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
591 \code{'candidate'}, or \code{'final'}. The \code{version_info}
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
592 value corresponding to the Python version 2.0 is \code{(2, 0, 0,
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
593 'final', 0)}.
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
594 \versionadded{2.0}
12395
3bb398996291 Document hexversion (incompletely explained) and version_info (easily
Fred Drake <fdrake@acm.org>
parents: 12380
diff changeset
595 \end{datadesc}
3bb398996291 Document hexversion (incompletely explained) and version_info (easily
Fred Drake <fdrake@acm.org>
parents: 12380
diff changeset
596
19688
31a66c0c7d30 Added documentation for sys.maxunicode and sys.warnoptions.
Fred Drake <fdrake@acm.org>
parents: 18835
diff changeset
597 \begin{datadesc}{warnoptions}
31a66c0c7d30 Added documentation for sys.maxunicode and sys.warnoptions.
Fred Drake <fdrake@acm.org>
parents: 18835
diff changeset
598 This is an implementation detail of the warnings framework; do not
31a66c0c7d30 Added documentation for sys.maxunicode and sys.warnoptions.
Fred Drake <fdrake@acm.org>
parents: 18835
diff changeset
599 modify this value. Refer to the \refmodule{warnings} module for
31a66c0c7d30 Added documentation for sys.maxunicode and sys.warnoptions.
Fred Drake <fdrake@acm.org>
parents: 18835
diff changeset
600 more information on the warnings framework.
31a66c0c7d30 Added documentation for sys.maxunicode and sys.warnoptions.
Fred Drake <fdrake@acm.org>
parents: 18835
diff changeset
601 \end{datadesc}
31a66c0c7d30 Added documentation for sys.maxunicode and sys.warnoptions.
Fred Drake <fdrake@acm.org>
parents: 18835
diff changeset
602
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11457
diff changeset
603 \begin{datadesc}{winver}
18694
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
604 The version number used to form registry keys on Windows platforms.
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
605 This is stored as string resource 1000 in the Python DLL. The value
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
606 is normally the first three characters of \constant{version}. It is
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
607 provided in the \module{sys} module for informational purposes;
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
608 modifying this value has no effect on the registry keys used by
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
609 Python.
9218fa652391 "Make small changes, but carry a big diff."
Fred Drake <fdrake@acm.org>
parents: 18691
diff changeset
610 Availability: Windows.
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11457
diff changeset
611 \end{datadesc}
22609
4c7bb0b4d354 add seealso referring to site module doc where people can learn how to
Skip Montanaro <skip@pobox.com>
parents: 21641
diff changeset
612
4c7bb0b4d354 add seealso referring to site module doc where people can learn how to
Skip Montanaro <skip@pobox.com>
parents: 21641
diff changeset
613
4c7bb0b4d354 add seealso referring to site module doc where people can learn how to
Skip Montanaro <skip@pobox.com>
parents: 21641
diff changeset
614 \begin{seealso}
4c7bb0b4d354 add seealso referring to site module doc where people can learn how to
Skip Montanaro <skip@pobox.com>
parents: 21641
diff changeset
615 \seemodule{site}
4c7bb0b4d354 add seealso referring to site module doc where people can learn how to
Skip Montanaro <skip@pobox.com>
parents: 21641
diff changeset
616 {This describes how to use .pth files to extend \code{sys.path}.}
4c7bb0b4d354 add seealso referring to site module doc where people can learn how to
Skip Montanaro <skip@pobox.com>
parents: 21641
diff changeset
617 \end{seealso}