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