Commit | Line | Data |
---|---|---|
920dae64 AT |
1 | <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> |
2 | <html> | |
3 | <head> | |
4 | <link rel="STYLESHEET" href="lib.css" type='text/css' /> | |
5 | <link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" /> | |
6 | <link rel='start' href='../index.html' title='Python Documentation Index' /> | |
7 | <link rel="first" href="lib.html" title='Python Library Reference' /> | |
8 | <link rel='contents' href='contents.html' title="Contents" /> | |
9 | <link rel='index' href='genindex.html' title='Index' /> | |
10 | <link rel='last' href='about.html' title='About this document...' /> | |
11 | <link rel='help' href='about.html' title='About this document...' /> | |
12 | <link rel="next" href="module-gc.html" /> | |
13 | <link rel="prev" href="python.html" /> | |
14 | <link rel="parent" href="python.html" /> | |
15 | <link rel="next" href="module-gc.html" /> | |
16 | <meta name='aesop' content='information' /> | |
17 | <title>3.1 sys -- System-specific parameters and functions</title> | |
18 | </head> | |
19 | <body> | |
20 | <DIV CLASS="navigation"> | |
21 | <div id='top-navigation-panel' xml:id='top-navigation-panel'> | |
22 | <table align="center" width="100%" cellpadding="0" cellspacing="2"> | |
23 | <tr> | |
24 | <td class='online-navigation'><a rel="prev" title="3. Python Runtime Services" | |
25 | href="python.html"><img src='../icons/previous.png' | |
26 | border='0' height='32' alt='Previous Page' width='32' /></A></td> | |
27 | <td class='online-navigation'><a rel="parent" title="3. Python Runtime Services" | |
28 | href="python.html"><img src='../icons/up.png' | |
29 | border='0' height='32' alt='Up One Level' width='32' /></A></td> | |
30 | <td class='online-navigation'><a rel="next" title="3.2 gc " | |
31 | href="module-gc.html"><img src='../icons/next.png' | |
32 | border='0' height='32' alt='Next Page' width='32' /></A></td> | |
33 | <td align="center" width="100%">Python Library Reference</td> | |
34 | <td class='online-navigation'><a rel="contents" title="Table of Contents" | |
35 | href="contents.html"><img src='../icons/contents.png' | |
36 | border='0' height='32' alt='Contents' width='32' /></A></td> | |
37 | <td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png' | |
38 | border='0' height='32' alt='Module Index' width='32' /></a></td> | |
39 | <td class='online-navigation'><a rel="index" title="Index" | |
40 | href="genindex.html"><img src='../icons/index.png' | |
41 | border='0' height='32' alt='Index' width='32' /></A></td> | |
42 | </tr></table> | |
43 | <div class='online-navigation'> | |
44 | <b class="navlabel">Previous:</b> | |
45 | <a class="sectref" rel="prev" href="python.html">3. Python Runtime Services</A> | |
46 | <b class="navlabel">Up:</b> | |
47 | <a class="sectref" rel="parent" href="python.html">3. Python Runtime Services</A> | |
48 | <b class="navlabel">Next:</b> | |
49 | <a class="sectref" rel="next" href="module-gc.html">3.2 gc </A> | |
50 | </div> | |
51 | <hr /></div> | |
52 | </DIV> | |
53 | <!--End of Navigation Panel--> | |
54 | ||
55 | <H1><A NAME="SECTION005100000000000000000"> | |
56 | 3.1 <tt class="module">sys</tt> -- | |
57 | System-specific parameters and functions</A> | |
58 | </H1> | |
59 | ||
60 | <P> | |
61 | <A NAME="module-sys"></A> | |
62 | ||
63 | <P> | |
64 | This module provides access to some variables used or maintained by the | |
65 | interpreter and to functions that interact strongly with the interpreter. | |
66 | It is always available. | |
67 | ||
68 | <P> | |
69 | <dl><dt><b><tt id='l2h-329' xml:id='l2h-329'>argv</tt></b></dt> | |
70 | <dd> | |
71 | The list of command line arguments passed to a Python script. | |
72 | <code>argv[0]</code> is the script name (it is operating system dependent | |
73 | whether this is a full pathname or not). If the command was | |
74 | executed using the <b class="programopt">-c</b> command line option to the | |
75 | interpreter, <code>argv[0]</code> is set to the string <code>'-c'</code>. If no | |
76 | script name was passed to the Python interpreter, <code>argv</code> has | |
77 | zero length. | |
78 | </dd></dl> | |
79 | ||
80 | <P> | |
81 | <dl><dt><b><tt id='l2h-330' xml:id='l2h-330'>byteorder</tt></b></dt> | |
82 | <dd> | |
83 | An indicator of the native byte order. This will have the value | |
84 | <code>'big'</code> on big-endian (most-signigicant byte first) platforms, | |
85 | and <code>'little'</code> on little-endian (least-significant byte first) | |
86 | platforms. | |
87 | ||
88 | <span class="versionnote">New in version 2.0.</span> | |
89 | ||
90 | </dd></dl> | |
91 | ||
92 | <P> | |
93 | <dl><dt><b><tt id='l2h-331' xml:id='l2h-331'>builtin_module_names</tt></b></dt> | |
94 | <dd> | |
95 | A tuple of strings giving the names of all modules that are compiled | |
96 | into this Python interpreter. (This information is not available in | |
97 | any other way -- <code>modules.keys()</code> only lists the imported | |
98 | modules.) | |
99 | </dd></dl> | |
100 | ||
101 | <P> | |
102 | <dl><dt><b><tt id='l2h-332' xml:id='l2h-332'>copyright</tt></b></dt> | |
103 | <dd> | |
104 | A string containing the copyright pertaining to the Python | |
105 | interpreter. | |
106 | </dd></dl> | |
107 | ||
108 | <P> | |
109 | <dl><dt><b><tt id='l2h-333' xml:id='l2h-333'>dllhandle</tt></b></dt> | |
110 | <dd> | |
111 | Integer specifying the handle of the Python DLL. | |
112 | Availability: Windows. | |
113 | </dd></dl> | |
114 | ||
115 | <P> | |
116 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
117 | <td><nobr><b><tt id='l2h-334' xml:id='l2h-334' class="function">displayhook</tt></b>(</nobr></td> | |
118 | <td><var><var>value</var></var>)</td></tr></table></dt> | |
119 | <dd> | |
120 | If <var>value</var> is not <code>None</code>, this function prints it to | |
121 | <code>sys.stdout</code>, and saves it in <code>__builtin__._</code>. | |
122 | ||
123 | <P> | |
124 | <code>sys.displayhook</code> is called on the result of evaluating an | |
125 | expression entered in an interactive Python session. The display of | |
126 | these values can be customized by assigning another one-argument | |
127 | function to <code>sys.displayhook</code>. | |
128 | </dl> | |
129 | ||
130 | <P> | |
131 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
132 | <td><nobr><b><tt id='l2h-335' xml:id='l2h-335' class="function">excepthook</tt></b>(</nobr></td> | |
133 | <td><var><var>type</var>, <var>value</var>, <var>traceback</var></var>)</td></tr></table></dt> | |
134 | <dd> | |
135 | This function prints out a given traceback and exception to | |
136 | <code>sys.stderr</code>. | |
137 | ||
138 | <P> | |
139 | When an exception is raised and uncaught, the interpreter calls | |
140 | <code>sys.excepthook</code> with three arguments, the exception class, | |
141 | exception instance, and a traceback object. In an interactive | |
142 | session this happens just before control is returned to the prompt; | |
143 | in a Python program this happens just before the program exits. The | |
144 | handling of such top-level exceptions can be customized by assigning | |
145 | another three-argument function to <code>sys.excepthook</code>. | |
146 | </dl> | |
147 | ||
148 | <P> | |
149 | <dl><dt><b><tt id='l2h-336' xml:id='l2h-336'>__displayhook__</tt></b></dt> | |
150 | <dd> | |
151 | <dt><b><tt id='l2h-381' xml:id='l2h-381'>__excepthook__</tt></b></dt><dd> | |
152 | These objects contain the original values of <code>displayhook</code> and | |
153 | <code>excepthook</code> at the start of the program. They are saved so | |
154 | that <code>displayhook</code> and <code>excepthook</code> can be restored in | |
155 | case they happen to get replaced with broken objects. | |
156 | </dd></dl> | |
157 | ||
158 | <P> | |
159 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
160 | <td><nobr><b><tt id='l2h-337' xml:id='l2h-337' class="function">exc_info</tt></b>(</nobr></td> | |
161 | <td><var></var>)</td></tr></table></dt> | |
162 | <dd> | |
163 | This function returns a tuple of three values that give information | |
164 | about the exception that is currently being handled. The | |
165 | information returned is specific both to the current thread and to | |
166 | the current stack frame. If the current stack frame is not handling | |
167 | an exception, the information is taken from the calling stack frame, | |
168 | or its caller, and so on until a stack frame is found that is | |
169 | handling an exception. Here, ``handling an exception'' is defined | |
170 | as ``executing or having executed an except clause.'' For any stack | |
171 | frame, only information about the most recently handled exception is | |
172 | accessible. | |
173 | ||
174 | <P> | |
175 | If no exception is being handled anywhere on the stack, a tuple | |
176 | containing three <code>None</code> values is returned. Otherwise, the | |
177 | values returned are <code>(<var>type</var>, <var>value</var>, | |
178 | <var>traceback</var>)</code>. Their meaning is: <var>type</var> gets the exception | |
179 | type of the exception being handled (a class object); | |
180 | <var>value</var> gets the exception parameter (its <i class="dfn">associated value</i> | |
181 | or the second argument to <tt class="keyword">raise</tt>, which is always a class | |
182 | instance if the exception type is a class object); <var>traceback</var> | |
183 | gets a traceback object (see the Reference Manual) which | |
184 | encapsulates the call stack at the point where the exception | |
185 | originally occurred. <a id='l2h-338' xml:id='l2h-338'></a> | |
186 | <P> | |
187 | If <tt class="function">exc_clear()</tt> is called, this function will return three | |
188 | <code>None</code> values until either another exception is raised in the | |
189 | current thread or the execution stack returns to a frame where | |
190 | another exception is being handled. | |
191 | ||
192 | <P> | |
193 | <span class="warning"><b class="label">Warning:</b> | |
194 | Assigning the <var>traceback</var> return value to a | |
195 | local variable in a function that is handling an exception will | |
196 | cause a circular reference. This will prevent anything referenced | |
197 | by a local variable in the same function or by the traceback from | |
198 | being garbage collected. Since most functions don't need access to | |
199 | the traceback, the best solution is to use something like | |
200 | <code>exctype, value = sys.exc_info()[:2]</code> to extract only the | |
201 | exception type and value. If you do need the traceback, make sure | |
202 | to delete it after use (best done with a <tt class="keyword">try</tt> | |
203 | ... <tt class="keyword">finally</tt> statement) or to call <tt class="function">exc_info()</tt> in | |
204 | a function that does not itself handle an exception.</span> <span class="note"><b class="label">Note:</b> | |
205 | Beginning | |
206 | with Python 2.2, such cycles are automatically reclaimed when garbage | |
207 | collection is enabled and they become unreachable, but it remains more | |
208 | efficient to avoid creating cycles.</span> | |
209 | </dl> | |
210 | ||
211 | <P> | |
212 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
213 | <td><nobr><b><tt id='l2h-339' xml:id='l2h-339' class="function">exc_clear</tt></b>(</nobr></td> | |
214 | <td><var></var>)</td></tr></table></dt> | |
215 | <dd> | |
216 | This function clears all information relating to the current or last | |
217 | exception that occurred in the current thread. After calling this | |
218 | function, <tt class="function">exc_info()</tt> will return three <code>None</code> values until | |
219 | another exception is raised in the current thread or the execution stack | |
220 | returns to a frame where another exception is being handled. | |
221 | ||
222 | <P> | |
223 | This function is only needed in only a few obscure situations. These | |
224 | include logging and error handling systems that report information on the | |
225 | last or current exception. This function can also be used to try to free | |
226 | resources and trigger object finalization, though no guarantee is made as | |
227 | to what objects will be freed, if any. | |
228 | ||
229 | <span class="versionnote">New in version 2.3.</span> | |
230 | ||
231 | </dl> | |
232 | ||
233 | <P> | |
234 | <dl><dt><b><tt id='l2h-340' xml:id='l2h-340'>exc_type</tt></b></dt> | |
235 | <dd> | |
236 | <dt><b><tt id='l2h-382' xml:id='l2h-382'>exc_value</tt></b></dt><dd> | |
237 | <dt><b><tt id='l2h-383' xml:id='l2h-383'>exc_traceback</tt></b></dt><dd> | |
238 | <div class="versionnote"><b>Deprecated since release 1.5.</b> | |
239 | Use <tt class="function">exc_info()</tt> instead.</div><p></p> | |
240 | Since they are global variables, they are not specific to the | |
241 | current thread, so their use is not safe in a multi-threaded | |
242 | program. When no exception is being handled, <code>exc_type</code> is set | |
243 | to <code>None</code> and the other two are undefined. | |
244 | </dd></dl> | |
245 | ||
246 | <P> | |
247 | <dl><dt><b><tt id='l2h-341' xml:id='l2h-341'>exec_prefix</tt></b></dt> | |
248 | <dd> | |
249 | A string giving the site-specific directory prefix where the | |
250 | platform-dependent Python files are installed; by default, this is | |
251 | also <code>'/usr/local'</code>. This can be set at build time with the | |
252 | <b class="programopt">--exec-prefix</b> argument to the <b class="program">configure</b> | |
253 | script. Specifically, all configuration files (e.g. the | |
254 | <span class="file">pyconfig.h</span> header file) are installed in the directory | |
255 | <code>exec_prefix + '/lib/python<var>version</var>/config'</code>, and shared | |
256 | library modules are installed in <code>exec_prefix + | |
257 | '/lib/python<var>version</var>/lib-dynload'</code>, where <var>version</var> is | |
258 | equal to <code>version[:3]</code>. | |
259 | </dd></dl> | |
260 | ||
261 | <P> | |
262 | <dl><dt><b><tt id='l2h-342' xml:id='l2h-342'>executable</tt></b></dt> | |
263 | <dd> | |
264 | A string giving the name of the executable binary for the Python | |
265 | interpreter, on systems where this makes sense. | |
266 | </dd></dl> | |
267 | ||
268 | <P> | |
269 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
270 | <td><nobr><b><tt id='l2h-343' xml:id='l2h-343' class="function">exit</tt></b>(</nobr></td> | |
271 | <td><var></var><big>[</big><var>arg</var><big>]</big><var></var>)</td></tr></table></dt> | |
272 | <dd> | |
273 | Exit from Python. This is implemented by raising the | |
274 | <tt class="exception">SystemExit</tt> exception, so cleanup actions specified by | |
275 | finally clauses of <tt class="keyword">try</tt> statements are honored, and it is | |
276 | possible to intercept the exit attempt at an outer level. The | |
277 | optional argument <var>arg</var> can be an integer giving the exit status | |
278 | (defaulting to zero), or another type of object. If it is an | |
279 | integer, zero is considered ``successful termination'' and any | |
280 | nonzero value is considered ``abnormal termination'' by shells and | |
281 | the like. Most systems require it to be in the range 0-127, and | |
282 | produce undefined results otherwise. Some systems have a convention | |
283 | for assigning specific meanings to specific exit codes, but these | |
284 | are generally underdeveloped; <span class="Unix">Unix</span> programs generally use 2 for | |
285 | command line syntax errors and 1 for all other kind of errors. If | |
286 | another type of object is passed, <code>None</code> is equivalent to | |
287 | passing zero, and any other object is printed to <code>sys.stderr</code> | |
288 | and results in an exit code of 1. In particular, | |
289 | <code>sys.exit("some error message")</code> is a quick way to exit a | |
290 | program when an error occurs. | |
291 | </dl> | |
292 | ||
293 | <P> | |
294 | <dl><dt><b><tt id='l2h-344' xml:id='l2h-344'>exitfunc</tt></b></dt> | |
295 | <dd> | |
296 | This value is not actually defined by the module, but can be set by | |
297 | the user (or by a program) to specify a clean-up action at program | |
298 | exit. When set, it should be a parameterless function. This | |
299 | function will be called when the interpreter exits. Only one | |
300 | function may be installed in this way; to allow multiple functions | |
301 | which will be called at termination, use the <tt class="module"><a href="module-atexit.html">atexit</a></tt> | |
302 | module. <span class="note"><b class="label">Note:</b> | |
303 | The exit function is not called when the program is | |
304 | killed by a signal, when a Python fatal internal error is detected, | |
305 | or when <code>os._exit()</code> is called.</span> | |
306 | <div class="versionnote"><b>Deprecated since release 2.4.</b> | |
307 | Use <tt class="module"><a href="module-atexit.html">atexit</a></tt> instead.</div><p></p> | |
308 | </dd></dl> | |
309 | ||
310 | <P> | |
311 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
312 | <td><nobr><b><tt id='l2h-345' xml:id='l2h-345' class="function">getcheckinterval</tt></b>(</nobr></td> | |
313 | <td><var></var>)</td></tr></table></dt> | |
314 | <dd> | |
315 | Return the interpreter's ``check interval''; | |
316 | see <tt class="function">setcheckinterval()</tt>. | |
317 | ||
318 | <span class="versionnote">New in version 2.3.</span> | |
319 | ||
320 | </dl> | |
321 | ||
322 | <P> | |
323 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
324 | <td><nobr><b><tt id='l2h-346' xml:id='l2h-346' class="function">getdefaultencoding</tt></b>(</nobr></td> | |
325 | <td><var></var>)</td></tr></table></dt> | |
326 | <dd> | |
327 | Return the name of the current default string encoding used by the | |
328 | Unicode implementation. | |
329 | ||
330 | <span class="versionnote">New in version 2.0.</span> | |
331 | ||
332 | </dl> | |
333 | ||
334 | <P> | |
335 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
336 | <td><nobr><b><tt id='l2h-347' xml:id='l2h-347' class="function">getdlopenflags</tt></b>(</nobr></td> | |
337 | <td><var></var>)</td></tr></table></dt> | |
338 | <dd> | |
339 | Return the current value of the flags that are used for | |
340 | <tt class="cfunction">dlopen()</tt> calls. The flag constants are defined in the | |
341 | <tt class="module"><a href="module-dl.html">dl</a></tt> and <tt class="module">DLFCN</tt> modules. | |
342 | Availability: <span class="Unix">Unix</span>. | |
343 | ||
344 | <span class="versionnote">New in version 2.2.</span> | |
345 | ||
346 | </dl> | |
347 | ||
348 | <P> | |
349 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
350 | <td><nobr><b><tt id='l2h-348' xml:id='l2h-348' class="function">getfilesystemencoding</tt></b>(</nobr></td> | |
351 | <td><var></var>)</td></tr></table></dt> | |
352 | <dd> | |
353 | Return the name of the encoding used to convert Unicode filenames | |
354 | into system file names, or <code>None</code> if the system default encoding | |
355 | is used. The result value depends on the operating system: | |
356 | ||
357 | <UL> | |
358 | <LI>On Windows 9x, the encoding is ``mbcs''. | |
359 | </LI> | |
360 | <LI>On Mac OS X, the encoding is ``utf-8''. | |
361 | </LI> | |
362 | <LI>On Unix, the encoding is the user's preference | |
363 | according to the result of nl_langinfo(CODESET), or None if | |
364 | the nl_langinfo(CODESET) failed. | |
365 | </LI> | |
366 | <LI>On Windows NT+, file names are Unicode natively, so no conversion | |
367 | is performed. <code>getfilesystemencoding</code> still returns ``mbcs'', | |
368 | as this is the encoding that applications should use when they | |
369 | explicitly want to convert Unicode strings to byte strings that | |
370 | are equivalent when used as file names. | |
371 | </LI> | |
372 | </UL> | |
373 | ||
374 | <span class="versionnote">New in version 2.3.</span> | |
375 | ||
376 | </dl> | |
377 | ||
378 | <P> | |
379 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
380 | <td><nobr><b><tt id='l2h-349' xml:id='l2h-349' class="function">getrefcount</tt></b>(</nobr></td> | |
381 | <td><var>object</var>)</td></tr></table></dt> | |
382 | <dd> | |
383 | Return the reference count of the <var>object</var>. The count returned | |
384 | is generally one higher than you might expect, because it includes | |
385 | the (temporary) reference as an argument to | |
386 | <tt class="function">getrefcount()</tt>. | |
387 | </dl> | |
388 | ||
389 | <P> | |
390 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
391 | <td><nobr><b><tt id='l2h-350' xml:id='l2h-350' class="function">getrecursionlimit</tt></b>(</nobr></td> | |
392 | <td><var></var>)</td></tr></table></dt> | |
393 | <dd> | |
394 | Return the current value of the recursion limit, the maximum depth | |
395 | of the Python interpreter stack. This limit prevents infinite | |
396 | recursion from causing an overflow of the C stack and crashing | |
397 | Python. It can be set by <tt class="function">setrecursionlimit()</tt>. | |
398 | </dl> | |
399 | ||
400 | <P> | |
401 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
402 | <td><nobr><b><tt id='l2h-351' xml:id='l2h-351' class="function">_getframe</tt></b>(</nobr></td> | |
403 | <td><var></var><big>[</big><var>depth</var><big>]</big><var></var>)</td></tr></table></dt> | |
404 | <dd> | |
405 | Return a frame object from the call stack. If optional integer | |
406 | <var>depth</var> is given, return the frame object that many calls below | |
407 | the top of the stack. If that is deeper than the call stack, | |
408 | <tt class="exception">ValueError</tt> is raised. The default for <var>depth</var> is | |
409 | zero, returning the frame at the top of the call stack. | |
410 | ||
411 | <P> | |
412 | This function should be used for internal and specialized purposes | |
413 | only. | |
414 | </dl> | |
415 | ||
416 | <P> | |
417 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
418 | <td><nobr><b><tt id='l2h-352' xml:id='l2h-352' class="function">getwindowsversion</tt></b>(</nobr></td> | |
419 | <td><var></var>)</td></tr></table></dt> | |
420 | <dd> | |
421 | Return a tuple containing five components, describing the Windows | |
422 | version currently running. The elements are <var>major</var>, <var>minor</var>, | |
423 | <var>build</var>, <var>platform</var>, and <var>text</var>. <var>text</var> contains | |
424 | a string while all other values are integers. | |
425 | ||
426 | <P> | |
427 | <var>platform</var> may be one of the following values: | |
428 | ||
429 | <P> | |
430 | <div class="center"><table class="realtable"> | |
431 | <thead> | |
432 | <tr> | |
433 | <th class="left" >Constant</th> | |
434 | <th class="left" >Platform</th> | |
435 | </tr> | |
436 | </thead> | |
437 | <tbody> | |
438 | <tr><td class="left" valign="baseline"><tt class="constant">VER_PLATFORM_WIN32s</tt></td> | |
439 | <td class="left" >Win32s on Windows 3.1</td></tr> | |
440 | <tr><td class="left" valign="baseline"><tt class="constant">VER_PLATFORM_WIN32_WINDOWS</tt></td> | |
441 | <td class="left" >Windows 95/98/ME</td></tr> | |
442 | <tr><td class="left" valign="baseline"><tt class="constant">VER_PLATFORM_WIN32_NT</tt></td> | |
443 | <td class="left" >Windows NT/2000/XP</td></tr> | |
444 | <tr><td class="left" valign="baseline"><tt class="constant">VER_PLATFORM_WIN32_CE</tt></td> | |
445 | <td class="left" >Windows CE</td></tr></tbody> | |
446 | </table></div> | |
447 | ||
448 | <P> | |
449 | This function wraps the Win32 <tt class="cfunction">GetVersionEx()</tt> function; | |
450 | see the Microsoft documentation for more information about these | |
451 | fields. | |
452 | ||
453 | <P> | |
454 | Availability: Windows. | |
455 | ||
456 | <span class="versionnote">New in version 2.3.</span> | |
457 | ||
458 | </dl> | |
459 | ||
460 | <P> | |
461 | <dl><dt><b><tt id='l2h-353' xml:id='l2h-353'>hexversion</tt></b></dt> | |
462 | <dd> | |
463 | The version number encoded as a single integer. This is guaranteed | |
464 | to increase with each version, including proper support for | |
465 | non-production releases. For example, to test that the Python | |
466 | interpreter is at least version 1.5.2, use: | |
467 | ||
468 | <P> | |
469 | <div class="verbatim"><pre> | |
470 | if sys.hexversion >= 0x010502F0: | |
471 | # use some advanced feature | |
472 | ... | |
473 | else: | |
474 | # use an alternative implementation or warn the user | |
475 | ... | |
476 | </pre></div> | |
477 | ||
478 | <P> | |
479 | This is called "<tt class="samp">hexversion</tt>" since it only really looks | |
480 | meaningful when viewed as the result of passing it to the built-in | |
481 | <tt class="function">hex()</tt> function. The <code>version_info</code> value may be | |
482 | used for a more human-friendly encoding of the same information. | |
483 | ||
484 | <span class="versionnote">New in version 1.5.2.</span> | |
485 | ||
486 | </dd></dl> | |
487 | ||
488 | <P> | |
489 | <dl><dt><b><tt id='l2h-354' xml:id='l2h-354'>last_type</tt></b></dt> | |
490 | <dd> | |
491 | <dt><b><tt id='l2h-384' xml:id='l2h-384'>last_value</tt></b></dt><dd> | |
492 | <dt><b><tt id='l2h-385' xml:id='l2h-385'>last_traceback</tt></b></dt><dd> | |
493 | These three variables are not always defined; they are set when an | |
494 | exception is not handled and the interpreter prints an error message | |
495 | and a stack traceback. Their intended use is to allow an | |
496 | interactive user to import a debugger module and engage in | |
497 | post-mortem debugging without having to re-execute the command that | |
498 | caused the error. (Typical use is "<tt class="samp">import pdb; pdb.pm()</tt>" to | |
499 | enter the post-mortem debugger; see chapter <A href="module-pdb.html#debugger">9</A>, ``The | |
500 | Python Debugger,'' for more information.) | |
501 | ||
502 | <P> | |
503 | The meaning of the variables is the same as that of the return | |
504 | values from <tt class="function">exc_info()</tt> above. (Since there is only one | |
505 | interactive thread, thread-safety is not a concern for these | |
506 | variables, unlike for <code>exc_type</code> etc.) | |
507 | </dd></dl> | |
508 | ||
509 | <P> | |
510 | <dl><dt><b><tt id='l2h-355' xml:id='l2h-355'>maxint</tt></b></dt> | |
511 | <dd> | |
512 | The largest positive integer supported by Python's regular integer | |
513 | type. This is at least 2**31-1. The largest negative integer is | |
514 | <code>-maxint-1</code> -- the asymmetry results from the use of 2's | |
515 | complement binary arithmetic. | |
516 | </dd></dl> | |
517 | ||
518 | <P> | |
519 | <dl><dt><b><tt id='l2h-356' xml:id='l2h-356'>maxunicode</tt></b></dt> | |
520 | <dd> | |
521 | An integer giving the largest supported code point for a Unicode | |
522 | character. The value of this depends on the configuration option | |
523 | that specifies whether Unicode characters are stored as UCS-2 or | |
524 | UCS-4. | |
525 | </dd></dl> | |
526 | ||
527 | <P> | |
528 | <dl><dt><b><tt id='l2h-357' xml:id='l2h-357'>modules</tt></b></dt> | |
529 | <dd> | |
530 | This is a dictionary that maps module names to modules which have | |
531 | already been loaded. This can be manipulated to force reloading of | |
532 | modules and other tricks. Note that removing a module from this | |
533 | dictionary is <em>not</em> the same as calling | |
534 | <tt class="function">reload()</tt><a id='l2h-358' xml:id='l2h-358'></a> on the corresponding module | |
535 | object. | |
536 | </dd></dl> | |
537 | ||
538 | <P> | |
539 | <dl><dt><b><tt id='l2h-359' xml:id='l2h-359'>path</tt></b></dt> | |
540 | <dd> | |
541 | <a id='l2h-360' xml:id='l2h-360'></a> A list of strings that specifies the search path for modules. | |
542 | Initialized from the environment variable <a class="envvar" id='l2h-386' xml:id='l2h-386'>PYTHONPATH</a>, plus an | |
543 | installation-dependent default. | |
544 | ||
545 | <P> | |
546 | As initialized upon program startup, | |
547 | the first item of this list, <code>path[0]</code>, is the directory | |
548 | containing the script that was used to invoke the Python | |
549 | interpreter. If the script directory is not available (e.g. if the | |
550 | interpreter is invoked interactively or if the script is read from | |
551 | standard input), <code>path[0]</code> is the empty string, which directs | |
552 | Python to search modules in the current directory first. Notice | |
553 | that the script directory is inserted <em>before</em> the entries | |
554 | inserted as a result of <a class="envvar" id='l2h-387' xml:id='l2h-387'>PYTHONPATH</a>. | |
555 | ||
556 | <P> | |
557 | A program is free to modify this list for its own purposes. | |
558 | ||
559 | <P> | |
560 | ||
561 | <span class="versionnote">Changed in version 2.3: | |
562 | Unicode strings are no longer ignored.</span> | |
563 | ||
564 | </dd></dl> | |
565 | ||
566 | <P> | |
567 | <dl><dt><b><tt id='l2h-361' xml:id='l2h-361'>platform</tt></b></dt> | |
568 | <dd> | |
569 | This string contains a platform identifier, e.g. <code>'sunos5'</code> or | |
570 | <code>'linux1'</code>. This can be used to append platform-specific | |
571 | components to <code>path</code>, for instance. | |
572 | </dd></dl> | |
573 | ||
574 | <P> | |
575 | <dl><dt><b><tt id='l2h-362' xml:id='l2h-362'>prefix</tt></b></dt> | |
576 | <dd> | |
577 | A string giving the site-specific directory prefix where the | |
578 | platform independent Python files are installed; by default, this is | |
579 | the string <code>'/usr/local'</code>. This can be set at build time with | |
580 | the <b class="programopt">--prefix</b> argument to the <b class="program">configure</b> | |
581 | script. The main collection of Python library modules is installed | |
582 | in the directory <code>prefix + '/lib/python<var>version</var>'</code> while | |
583 | the platform independent header files (all except <span class="file">pyconfig.h</span>) | |
584 | are stored in <code>prefix + '/include/python<var>version</var>'</code>, where | |
585 | <var>version</var> is equal to <code>version[:3]</code>. | |
586 | </dd></dl> | |
587 | ||
588 | <P> | |
589 | <dl><dt><b><tt id='l2h-363' xml:id='l2h-363'>ps1</tt></b></dt> | |
590 | <dd> | |
591 | <dt><b><tt id='l2h-388' xml:id='l2h-388'>ps2</tt></b></dt><dd> | |
592 | <a id='l2h-389' xml:id='l2h-389'></a> | |
593 | Strings specifying the primary and secondary prompt of the | |
594 | interpreter. These are only defined if the interpreter is in | |
595 | interactive mode. Their initial values in this case are | |
596 | <code>'><code>></code>> '</code> and <code>'... '</code>. If a non-string object is | |
597 | assigned to either variable, its <tt class="function">str()</tt> is re-evaluated | |
598 | each time the interpreter prepares to read a new interactive | |
599 | command; this can be used to implement a dynamic prompt. | |
600 | </dd></dl> | |
601 | ||
602 | <P> | |
603 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
604 | <td><nobr><b><tt id='l2h-364' xml:id='l2h-364' class="function">setcheckinterval</tt></b>(</nobr></td> | |
605 | <td><var>interval</var>)</td></tr></table></dt> | |
606 | <dd> | |
607 | Set the interpreter's ``check interval''. This integer value | |
608 | determines how often the interpreter checks for periodic things such | |
609 | as thread switches and signal handlers. The default is <code>100</code>, | |
610 | meaning the check is performed every 100 Python virtual instructions. | |
611 | Setting it to a larger value may increase performance for programs | |
612 | using threads. Setting it to a value <code><=</code> 0 checks every | |
613 | virtual instruction, maximizing responsiveness as well as overhead. | |
614 | </dl> | |
615 | ||
616 | <P> | |
617 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
618 | <td><nobr><b><tt id='l2h-365' xml:id='l2h-365' class="function">setdefaultencoding</tt></b>(</nobr></td> | |
619 | <td><var>name</var>)</td></tr></table></dt> | |
620 | <dd> | |
621 | Set the current default string encoding used by the Unicode | |
622 | implementation. If <var>name</var> does not match any available | |
623 | encoding, <tt class="exception">LookupError</tt> is raised. This function is only | |
624 | intended to be used by the <tt class="module"><a href="module-site.html">site</a></tt> module implementation | |
625 | and, where needed, by <tt class="module">sitecustomize</tt>. Once used by the | |
626 | <tt class="module"><a href="module-site.html">site</a></tt> module, it is removed from the <tt class="module">sys</tt> | |
627 | module's namespace. | |
628 | ||
629 | <span class="versionnote">New in version 2.0.</span> | |
630 | ||
631 | </dl> | |
632 | ||
633 | <P> | |
634 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
635 | <td><nobr><b><tt id='l2h-366' xml:id='l2h-366' class="function">setdlopenflags</tt></b>(</nobr></td> | |
636 | <td><var>n</var>)</td></tr></table></dt> | |
637 | <dd> | |
638 | Set the flags used by the interpreter for <tt class="cfunction">dlopen()</tt> | |
639 | calls, such as when the interpreter loads extension modules. Among | |
640 | other things, this will enable a lazy resolving of symbols when | |
641 | importing a module, if called as <code>sys.setdlopenflags(0)</code>. To | |
642 | share symbols across extension modules, call as | |
643 | <code>sys.setdlopenflags(dl.RTLD_NOW | dl.RTLD_GLOBAL)</code>. Symbolic | |
644 | names for the flag modules can be either found in the <tt class="module"><a href="module-dl.html">dl</a></tt> | |
645 | module, or in the <tt class="module">DLFCN</tt> module. If <tt class="module">DLFCN</tt> is not | |
646 | available, it can be generated from <span class="file">/usr/include/dlfcn.h</span> | |
647 | using the <b class="program">h2py</b> script. | |
648 | Availability: <span class="Unix">Unix</span>. | |
649 | ||
650 | <span class="versionnote">New in version 2.2.</span> | |
651 | ||
652 | </dl> | |
653 | ||
654 | <P> | |
655 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
656 | <td><nobr><b><tt id='l2h-367' xml:id='l2h-367' class="function">setprofile</tt></b>(</nobr></td> | |
657 | <td><var>profilefunc</var>)</td></tr></table></dt> | |
658 | <dd> | |
659 | Set the system's profile function,<a id='l2h-390' xml:id='l2h-390'></a> which | |
660 | allows you to implement a Python source code profiler in | |
661 | Python.<a id='l2h-391' xml:id='l2h-391'></a> See chapter <A href="profile.html#profile">10</A> for more | |
662 | information on the Python profiler. The system's profile function | |
663 | is called similarly to the system's trace function (see | |
664 | <tt class="function">settrace()</tt>), but it isn't called for each executed line | |
665 | of code (only on call and return, but the return event is reported | |
666 | even when an exception has been set). The function is | |
667 | thread-specific, but there is no way for the profiler to know about | |
668 | context switches between threads, so it does not make sense to use | |
669 | this in the presence of multiple threads. | |
670 | Also, its return value is not used, so it can simply return | |
671 | <code>None</code>. | |
672 | </dl> | |
673 | ||
674 | <P> | |
675 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
676 | <td><nobr><b><tt id='l2h-368' xml:id='l2h-368' class="function">setrecursionlimit</tt></b>(</nobr></td> | |
677 | <td><var>limit</var>)</td></tr></table></dt> | |
678 | <dd> | |
679 | Set the maximum depth of the Python interpreter stack to | |
680 | <var>limit</var>. This limit prevents infinite recursion from causing an | |
681 | overflow of the C stack and crashing Python. | |
682 | ||
683 | <P> | |
684 | The highest possible limit is platform-dependent. A user may need | |
685 | to set the limit higher when she has a program that requires deep | |
686 | recursion and a platform that supports a higher limit. This should | |
687 | be done with care, because a too-high limit can lead to a crash. | |
688 | </dl> | |
689 | ||
690 | <P> | |
691 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
692 | <td><nobr><b><tt id='l2h-369' xml:id='l2h-369' class="function">settrace</tt></b>(</nobr></td> | |
693 | <td><var>tracefunc</var>)</td></tr></table></dt> | |
694 | <dd> | |
695 | Set the system's trace function,<a id='l2h-392' xml:id='l2h-392'></a> which allows | |
696 | you to implement a Python source code debugger in Python. See | |
697 | section <A href="debugger-hooks.html#debugger-hooks">9.2</A>, ``How It Works,'' in the chapter on | |
698 | the Python debugger.<a id='l2h-393' xml:id='l2h-393'></a> The function is | |
699 | thread-specific; for a debugger to support multiple threads, it must | |
700 | be registered using <tt class="function">settrace()</tt> for each thread being | |
701 | debugged. <span class="note"><b class="label">Note:</b> | |
702 | The <tt class="function">settrace()</tt> function is intended only | |
703 | for implementing debuggers, profilers, coverage tools and the like. | |
704 | Its behavior is part of the implementation platform, rather than | |
705 | part of the language definition, and thus may not be available in | |
706 | all Python implementations.</span> | |
707 | </dl> | |
708 | ||
709 | <P> | |
710 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
711 | <td><nobr><b><tt id='l2h-370' xml:id='l2h-370' class="function">settscdump</tt></b>(</nobr></td> | |
712 | <td><var>on_flag</var>)</td></tr></table></dt> | |
713 | <dd> | |
714 | Activate dumping of VM measurements using the Pentium timestamp | |
715 | counter, if <var>on_flag</var> is true. Deactivate these dumps if | |
716 | <var>on_flag</var> is off. The function is available only if Python | |
717 | was compiled with <b class="programopt">--with-tsc</b>. To understand the | |
718 | output of this dump, read <span class="file">Python/ceval.c</span> in the Python | |
719 | sources. | |
720 | ||
721 | <span class="versionnote">New in version 2.4.</span> | |
722 | ||
723 | </dl> | |
724 | ||
725 | <P> | |
726 | <dl><dt><b><tt id='l2h-371' xml:id='l2h-371'>stdin</tt></b></dt> | |
727 | <dd> | |
728 | <dt><b><tt id='l2h-394' xml:id='l2h-394'>stdout</tt></b></dt><dd> | |
729 | <dt><b><tt id='l2h-395' xml:id='l2h-395'>stderr</tt></b></dt><dd> | |
730 | File objects corresponding to the interpreter's standard input, | |
731 | output and error streams. <code>stdin</code> is used for all interpreter | |
732 | input except for scripts but including calls to | |
733 | <tt class="function">input()</tt><a id='l2h-372' xml:id='l2h-372'></a> and | |
734 | <tt class="function">raw_input()</tt><a id='l2h-373' xml:id='l2h-373'></a>. <code>stdout</code> is | |
735 | used for the output of <tt class="keyword">print</tt> and expression statements and | |
736 | for the prompts of <tt class="function">input()</tt> and <tt class="function">raw_input()</tt>. | |
737 | The interpreter's own prompts and (almost all of) its error messages | |
738 | go to <code>stderr</code>. <code>stdout</code> and <code>stderr</code> needn't be | |
739 | built-in file objects: any object is acceptable as long as it has a | |
740 | <tt class="method">write()</tt> method that takes a string argument. (Changing | |
741 | these objects doesn't affect the standard I/O streams of processes | |
742 | executed by <tt class="function">os.popen()</tt>, <tt class="function">os.system()</tt> or the | |
743 | <tt class="function">exec*()</tt> family of functions in the <tt class="module"><a href="module-os.html">os</a></tt> | |
744 | module.) | |
745 | </dd></dl> | |
746 | ||
747 | <P> | |
748 | <dl><dt><b><tt id='l2h-374' xml:id='l2h-374'>__stdin__</tt></b></dt> | |
749 | <dd> | |
750 | <dt><b><tt id='l2h-396' xml:id='l2h-396'>__stdout__</tt></b></dt><dd> | |
751 | <dt><b><tt id='l2h-397' xml:id='l2h-397'>__stderr__</tt></b></dt><dd> | |
752 | These objects contain the original values of <code>stdin</code>, | |
753 | <code>stderr</code> and <code>stdout</code> at the start of the program. They | |
754 | are used during finalization, and could be useful to restore the | |
755 | actual files to known working file objects in case they have been | |
756 | overwritten with a broken object. | |
757 | </dd></dl> | |
758 | ||
759 | <P> | |
760 | <dl><dt><b><tt id='l2h-375' xml:id='l2h-375'>tracebacklimit</tt></b></dt> | |
761 | <dd> | |
762 | When this variable is set to an integer value, it determines the | |
763 | maximum number of levels of traceback information printed when an | |
764 | unhandled exception occurs. The default is <code>1000</code>. When set | |
765 | to <code>0</code> or less, all traceback information is suppressed and | |
766 | only the exception type and value are printed. | |
767 | </dd></dl> | |
768 | ||
769 | <P> | |
770 | <dl><dt><b><tt id='l2h-376' xml:id='l2h-376'>version</tt></b></dt> | |
771 | <dd> | |
772 | A string containing the version number of the Python interpreter | |
773 | plus additional information on the build number and compiler used. | |
774 | It has a value of the form <code>'<var>version</var> | |
775 | (#<var>build_number</var>, <var>build_date</var>, <var>build_time</var>) | |
776 | [<var>compiler</var>]'</code>. The first three characters are used to identify | |
777 | the version in the installation directories (where appropriate on | |
778 | each platform). An example: | |
779 | ||
780 | <P> | |
781 | <div class="verbatim"><pre> | |
782 | >>> import sys | |
783 | >>> sys.version | |
784 | '1.5.2 (#0 Apr 13 1999, 10:51:12) [MSC 32 bit (Intel)]' | |
785 | </pre></div> | |
786 | </dd></dl> | |
787 | ||
788 | <P> | |
789 | <dl><dt><b><tt id='l2h-377' xml:id='l2h-377'>api_version</tt></b></dt> | |
790 | <dd> | |
791 | The C API version for this interpreter. Programmers may find this useful | |
792 | when debugging version conflicts between Python and extension | |
793 | modules. | |
794 | <span class="versionnote">New in version 2.3.</span> | |
795 | ||
796 | </dd></dl> | |
797 | ||
798 | <P> | |
799 | <dl><dt><b><tt id='l2h-378' xml:id='l2h-378'>version_info</tt></b></dt> | |
800 | <dd> | |
801 | A tuple containing the five components of the version number: | |
802 | <var>major</var>, <var>minor</var>, <var>micro</var>, <var>releaselevel</var>, and | |
803 | <var>serial</var>. All values except <var>releaselevel</var> are integers; | |
804 | the release level is <code>'alpha'</code>, <code>'beta'</code>, | |
805 | <code>'candidate'</code>, or <code>'final'</code>. The <code>version_info</code> | |
806 | value corresponding to the Python version 2.0 is <code>(2, 0, 0, | |
807 | 'final', 0)</code>. | |
808 | ||
809 | <span class="versionnote">New in version 2.0.</span> | |
810 | ||
811 | </dd></dl> | |
812 | ||
813 | <P> | |
814 | <dl><dt><b><tt id='l2h-379' xml:id='l2h-379'>warnoptions</tt></b></dt> | |
815 | <dd> | |
816 | This is an implementation detail of the warnings framework; do not | |
817 | modify this value. Refer to the <tt class="module"><a href="module-warnings.html">warnings</a></tt> module for | |
818 | more information on the warnings framework. | |
819 | </dd></dl> | |
820 | ||
821 | <P> | |
822 | <dl><dt><b><tt id='l2h-380' xml:id='l2h-380'>winver</tt></b></dt> | |
823 | <dd> | |
824 | The version number used to form registry keys on Windows platforms. | |
825 | This is stored as string resource 1000 in the Python DLL. The value | |
826 | is normally the first three characters of <tt class="constant">version</tt>. It is | |
827 | provided in the <tt class="module">sys</tt> module for informational purposes; | |
828 | modifying this value has no effect on the registry keys used by | |
829 | Python. | |
830 | Availability: Windows. | |
831 | </dd></dl> | |
832 | ||
833 | <P> | |
834 | <div class="seealso"> | |
835 | <p class="heading">See Also:</p> | |
836 | ||
837 | <dl compact="compact" class="seemodule"> | |
838 | <dt>Module <b><tt class="module"><a href="module-site.html">site</a></tt>:</b> | |
839 | <dd>This describes how to use .pth files to extend <code>sys.path</code>. | |
840 | </dl> | |
841 | </div> | |
842 | ||
843 | <DIV CLASS="navigation"> | |
844 | <div class='online-navigation'> | |
845 | <p></p><hr /> | |
846 | <table align="center" width="100%" cellpadding="0" cellspacing="2"> | |
847 | <tr> | |
848 | <td class='online-navigation'><a rel="prev" title="3. Python Runtime Services" | |
849 | href="python.html"><img src='../icons/previous.png' | |
850 | border='0' height='32' alt='Previous Page' width='32' /></A></td> | |
851 | <td class='online-navigation'><a rel="parent" title="3. Python Runtime Services" | |
852 | href="python.html"><img src='../icons/up.png' | |
853 | border='0' height='32' alt='Up One Level' width='32' /></A></td> | |
854 | <td class='online-navigation'><a rel="next" title="3.2 gc " | |
855 | href="module-gc.html"><img src='../icons/next.png' | |
856 | border='0' height='32' alt='Next Page' width='32' /></A></td> | |
857 | <td align="center" width="100%">Python Library Reference</td> | |
858 | <td class='online-navigation'><a rel="contents" title="Table of Contents" | |
859 | href="contents.html"><img src='../icons/contents.png' | |
860 | border='0' height='32' alt='Contents' width='32' /></A></td> | |
861 | <td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png' | |
862 | border='0' height='32' alt='Module Index' width='32' /></a></td> | |
863 | <td class='online-navigation'><a rel="index" title="Index" | |
864 | href="genindex.html"><img src='../icons/index.png' | |
865 | border='0' height='32' alt='Index' width='32' /></A></td> | |
866 | </tr></table> | |
867 | <div class='online-navigation'> | |
868 | <b class="navlabel">Previous:</b> | |
869 | <a class="sectref" rel="prev" href="python.html">3. Python Runtime Services</A> | |
870 | <b class="navlabel">Up:</b> | |
871 | <a class="sectref" rel="parent" href="python.html">3. Python Runtime Services</A> | |
872 | <b class="navlabel">Next:</b> | |
873 | <a class="sectref" rel="next" href="module-gc.html">3.2 gc </A> | |
874 | </div> | |
875 | </div> | |
876 | <hr /> | |
877 | <span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span> | |
878 | </DIV> | |
879 | <!--End of Navigation Panel--> | |
880 | <ADDRESS> | |
881 | See <i><a href="about.html">About this document...</a></i> for information on suggesting changes. | |
882 | </ADDRESS> | |
883 | </BODY> | |
884 | </HTML> |