1 :mod:`sys` --- System-specific parameters and functions 2 ======================================================= 3 4 .. module:: sys 5 :synopsis: Access system-specific parameters and functions. 6 7 8 This module provides access to some variables used or maintained by the 9 interpreter and to functions that interact strongly with the interpreter. It is 10 always available. 11 12 13 .. data:: argv 14 15 The list of command line arguments passed to a Python script. ``argv[0]`` is the 16 script name (it is operating system dependent whether this is a full pathname or 17 not). If the command was executed using the :option:`-c` command line option to 18 the interpreter, ``argv[0]`` is set to the string ``'-c'``. If no script name 19 was passed to the Python interpreter, ``argv[0]`` is the empty string. 20 21 To loop over the standard input, or the list of files given on the 22 command line, see the :mod:`fileinput` module. 23 24 25 .. data:: byteorder 26 27 An indicator of the native byte order. This will have the value ``'big'`` on 28 big-endian (most-significant byte first) platforms, and ``'little'`` on 29 little-endian (least-significant byte first) platforms. 30 31 .. versionadded:: 2.0 32 33 34 .. data:: builtin_module_names 35 36 A tuple of strings giving the names of all modules that are compiled into this 37 Python interpreter. (This information is not available in any other way --- 38 ``modules.keys()`` only lists the imported modules.) 39 40 41 .. function:: call_tracing(func, args) 42 43 Call ``func(*args)``, while tracing is enabled. The tracing state is saved, 44 and restored afterwards. This is intended to be called from a debugger from 45 a checkpoint, to recursively debug some other code. 46 47 48 .. data:: copyright 49 50 A string containing the copyright pertaining to the Python interpreter. 51 52 53 .. function:: _clear_type_cache() 54 55 Clear the internal type cache. The type cache is used to speed up attribute 56 and method lookups. Use the function *only* to drop unnecessary references 57 during reference leak debugging. 58 59 This function should be used for internal and specialized purposes only. 60 61 .. versionadded:: 2.6 62 63 64 .. function:: _current_frames() 65 66 Return a dictionary mapping each thread's identifier to the topmost stack frame 67 currently active in that thread at the time the function is called. Note that 68 functions in the :mod:`traceback` module can build the call stack given such a 69 frame. 70 71 This is most useful for debugging deadlock: this function does not require the 72 deadlocked threads' cooperation, and such threads' call stacks are frozen for as 73 long as they remain deadlocked. The frame returned for a non-deadlocked thread 74 may bear no relationship to that thread's current activity by the time calling 75 code examines the frame. 76 77 This function should be used for internal and specialized purposes only. 78 79 .. versionadded:: 2.5 80 81 82 .. data:: dllhandle 83 84 Integer specifying the handle of the Python DLL. Availability: Windows. 85 86 87 .. function:: displayhook(value) 88 89 If *value* is not ``None``, this function prints it to ``sys.stdout``, and saves 90 it in ``__builtin__._``. 91 92 ``sys.displayhook`` is called on the result of evaluating an :term:`expression` 93 entered in an interactive Python session. The display of these values can be 94 customized by assigning another one-argument function to ``sys.displayhook``. 95 96 97 .. data:: dont_write_bytecode 98 99 If this is true, Python won't try to write ``.pyc`` or ``.pyo`` files on the 100 import of source modules. This value is initially set to ``True`` or 101 ``False`` depending on the :option:`-B` command line option and the 102 :envvar:`PYTHONDONTWRITEBYTECODE` environment variable, but you can set it 103 yourself to control bytecode file generation. 104 105 .. versionadded:: 2.6 106 107 108 .. function:: excepthook(type, value, traceback) 109 110 This function prints out a given traceback and exception to ``sys.stderr``. 111 112 When an exception is raised and uncaught, the interpreter calls 113 ``sys.excepthook`` with three arguments, the exception class, exception 114 instance, and a traceback object. In an interactive session this happens just 115 before control is returned to the prompt; in a Python program this happens just 116 before the program exits. The handling of such top-level exceptions can be 117 customized by assigning another three-argument function to ``sys.excepthook``. 118 119 120 .. data:: __displayhook__ 121 __excepthook__ 122 123 These objects contain the original values of ``displayhook`` and ``excepthook`` 124 at the start of the program. They are saved so that ``displayhook`` and 125 ``excepthook`` can be restored in case they happen to get replaced with broken 126 objects. 127 128 129 .. function:: exc_info() 130 131 This function returns a tuple of three values that give information about the 132 exception that is currently being handled. The information returned is specific 133 both to the current thread and to the current stack frame. If the current stack 134 frame is not handling an exception, the information is taken from the calling 135 stack frame, or its caller, and so on until a stack frame is found that is 136 handling an exception. Here, "handling an exception" is defined as "executing 137 or having executed an except clause." For any stack frame, only information 138 about the most recently handled exception is accessible. 139 140 .. index:: object: traceback 141 142 If no exception is being handled anywhere on the stack, a tuple containing three 143 ``None`` values is returned. Otherwise, the values returned are ``(type, value, 144 traceback)``. Their meaning is: *type* gets the exception type of the exception 145 being handled (a class object); *value* gets the exception parameter (its 146 :dfn:`associated value` or the second argument to :keyword:`raise`, which is 147 always a class instance if the exception type is a class object); *traceback* 148 gets a traceback object (see the Reference Manual) which encapsulates the call 149 stack at the point where the exception originally occurred. 150 151 If :func:`exc_clear` is called, this function will return three ``None`` values 152 until either another exception is raised in the current thread or the execution 153 stack returns to a frame where another exception is being handled. 154 155 .. warning:: 156 157 Assigning the *traceback* return value to a local variable in a function that is 158 handling an exception will cause a circular reference. This will prevent 159 anything referenced by a local variable in the same function or by the traceback 160 from being garbage collected. Since most functions don't need access to the 161 traceback, the best solution is to use something like ``exctype, value = 162 sys.exc_info()[:2]`` to extract only the exception type and value. If you do 163 need the traceback, make sure to delete it after use (best done with a 164 :keyword:`try` ... :keyword:`finally` statement) or to call :func:`exc_info` in 165 a function that does not itself handle an exception. 166 167 .. note:: 168 169 Beginning with Python 2.2, such cycles are automatically reclaimed when garbage 170 collection is enabled and they become unreachable, but it remains more efficient 171 to avoid creating cycles. 172 173 174 .. function:: exc_clear() 175 176 This function clears all information relating to the current or last exception 177 that occurred in the current thread. After calling this function, 178 :func:`exc_info` will return three ``None`` values until another exception is 179 raised in the current thread or the execution stack returns to a frame where 180 another exception is being handled. 181 182 This function is only needed in only a few obscure situations. These include 183 logging and error handling systems that report information on the last or 184 current exception. This function can also be used to try to free resources and 185 trigger object finalization, though no guarantee is made as to what objects will 186 be freed, if any. 187 188 .. versionadded:: 2.3 189 190 191 .. data:: exc_type 192 exc_value 193 exc_traceback 194 195 .. deprecated:: 1.5 196 Use :func:`exc_info` instead. 197 198 Since they are global variables, they are not specific to the current thread, so 199 their use is not safe in a multi-threaded program. When no exception is being 200 handled, ``exc_type`` is set to ``None`` and the other two are undefined. 201 202 203 .. data:: exec_prefix 204 205 A string giving the site-specific directory prefix where the platform-dependent 206 Python files are installed; by default, this is also ``'/usr/local'``. This can 207 be set at build time with the ``--exec-prefix`` argument to the 208 :program:`configure` script. Specifically, all configuration files (e.g. the 209 :file:`pyconfig.h` header file) are installed in the directory 210 :file:`{exec_prefix}/lib/python{X.Y}/config`, and shared library modules are 211 installed in :file:`{exec_prefix}/lib/python{X.Y}/lib-dynload`, where *X.Y* 212 is the version number of Python, for example ``2.7``. 213 214 215 .. data:: executable 216 217 A string giving the absolute path of the executable binary for the Python 218 interpreter, on systems where this makes sense. If Python is unable to retrieve 219 the real path to its executable, :data:`sys.executable` will be an empty string 220 or ``None``. 221 222 223 .. function:: exit([arg]) 224 225 Exit from Python. This is implemented by raising the :exc:`SystemExit` 226 exception, so cleanup actions specified by finally clauses of :keyword:`try` 227 statements are honored, and it is possible to intercept the exit attempt at 228 an outer level. 229 230 The optional argument *arg* can be an integer giving the exit status 231 (defaulting to zero), or another type of object. If it is an integer, zero 232 is considered "successful termination" and any nonzero value is considered 233 "abnormal termination" by shells and the like. Most systems require it to be 234 in the range 0--127, and produce undefined results otherwise. Some systems 235 have a convention for assigning specific meanings to specific exit codes, but 236 these are generally underdeveloped; Unix programs generally use 2 for command 237 line syntax errors and 1 for all other kind of errors. If another type of 238 object is passed, ``None`` is equivalent to passing zero, and any other 239 object is printed to :data:`stderr` and results in an exit code of 1. In 240 particular, ``sys.exit("some error message")`` is a quick way to exit a 241 program when an error occurs. 242 243 Since :func:`exit` ultimately "only" raises an exception, it will only exit 244 the process when called from the main thread, and the exception is not 245 intercepted. 246 247 248 .. data:: exitfunc 249 250 This value is not actually defined by the module, but can be set by the user (or 251 by a program) to specify a clean-up action at program exit. When set, it should 252 be a parameterless function. This function will be called when the interpreter 253 exits. Only one function may be installed in this way; to allow multiple 254 functions which will be called at termination, use the :mod:`atexit` module. 255 256 .. note:: 257 258 The exit function is not called when the program is killed by a signal, when a 259 Python fatal internal error is detected, or when ``os._exit()`` is called. 260 261 .. deprecated:: 2.4 262 Use :mod:`atexit` instead. 263 264 265 .. data:: flags 266 267 The struct sequence *flags* exposes the status of command line flags. The 268 attributes are read only. 269 270 ============================= =================================== 271 attribute flag 272 ============================= =================================== 273 :const:`debug` :option:`-d` 274 :const:`py3k_warning` :option:`-3` 275 :const:`division_warning` :option:`-Q` 276 :const:`division_new` :option:`-Qnew <-Q>` 277 :const:`inspect` :option:`-i` 278 :const:`interactive` :option:`-i` 279 :const:`optimize` :option:`-O` or :option:`-OO` 280 :const:`dont_write_bytecode` :option:`-B` 281 :const:`no_user_site` :option:`-s` 282 :const:`no_site` :option:`-S` 283 :const:`ignore_environment` :option:`-E` 284 :const:`tabcheck` :option:`-t` or :option:`-tt <-t>` 285 :const:`verbose` :option:`-v` 286 :const:`unicode` :option:`-U` 287 :const:`bytes_warning` :option:`-b` 288 :const:`hash_randomization` :option:`-R` 289 ============================= =================================== 290 291 .. versionadded:: 2.6 292 293 .. versionadded:: 2.7.3 294 The ``hash_randomization`` attribute. 295 296 .. data:: float_info 297 298 A structseq holding information about the float type. It contains low level 299 information about the precision and internal representation. The values 300 correspond to the various floating-point constants defined in the standard 301 header file :file:`float.h` for the 'C' programming language; see section 302 5.2.4.2.2 of the 1999 ISO/IEC C standard [C99]_, 'Characteristics of 303 floating types', for details. 304 305 .. tabularcolumns:: |l|l|L| 306 307 +---------------------+----------------+--------------------------------------------------+ 308 | attribute | float.h macro | explanation | 309 +=====================+================+==================================================+ 310 | :const:`epsilon` | DBL_EPSILON | difference between 1 and the least value greater | 311 | | | than 1 that is representable as a float | 312 +---------------------+----------------+--------------------------------------------------+ 313 | :const:`dig` | DBL_DIG | maximum number of decimal digits that can be | 314 | | | faithfully represented in a float; see below | 315 +---------------------+----------------+--------------------------------------------------+ 316 | :const:`mant_dig` | DBL_MANT_DIG | float precision: the number of base-``radix`` | 317 | | | digits in the significand of a float | 318 +---------------------+----------------+--------------------------------------------------+ 319 | :const:`max` | DBL_MAX | maximum representable finite float | 320 +---------------------+----------------+--------------------------------------------------+ 321 | :const:`max_exp` | DBL_MAX_EXP | maximum integer e such that ``radix**(e-1)`` is | 322 | | | a representable finite float | 323 +---------------------+----------------+--------------------------------------------------+ 324 | :const:`max_10_exp` | DBL_MAX_10_EXP | maximum integer e such that ``10**e`` is in the | 325 | | | range of representable finite floats | 326 +---------------------+----------------+--------------------------------------------------+ 327 | :const:`min` | DBL_MIN | minimum positive normalized float | 328 +---------------------+----------------+--------------------------------------------------+ 329 | :const:`min_exp` | DBL_MIN_EXP | minimum integer e such that ``radix**(e-1)`` is | 330 | | | a normalized float | 331 +---------------------+----------------+--------------------------------------------------+ 332 | :const:`min_10_exp` | DBL_MIN_10_EXP | minimum integer e such that ``10**e`` is a | 333 | | | normalized float | 334 +---------------------+----------------+--------------------------------------------------+ 335 | :const:`radix` | FLT_RADIX | radix of exponent representation | 336 +---------------------+----------------+--------------------------------------------------+ 337 | :const:`rounds` | FLT_ROUNDS | integer constant representing the rounding mode | 338 | | | used for arithmetic operations. This reflects | 339 | | | the value of the system FLT_ROUNDS macro at | 340 | | | interpreter startup time. See section 5.2.4.2.2 | 341 | | | of the C99 standard for an explanation of the | 342 | | | possible values and their meanings. | 343 +---------------------+----------------+--------------------------------------------------+ 344 345 The attribute :attr:`sys.float_info.dig` needs further explanation. If 346 ``s`` is any string representing a decimal number with at most 347 :attr:`sys.float_info.dig` significant digits, then converting ``s`` to a 348 float and back again will recover a string representing the same decimal 349 value:: 350 351 >>> import sys 352 >>> sys.float_info.dig 353 15 354 >>> s = '3.14159265358979' # decimal string with 15 significant digits 355 >>> format(float(s), '.15g') # convert to float and back -> same value 356 '3.14159265358979' 357 358 But for strings with more than :attr:`sys.float_info.dig` significant digits, 359 this isn't always true:: 360 361 >>> s = '9876543211234567' # 16 significant digits is too many! 362 >>> format(float(s), '.16g') # conversion changes value 363 '9876543211234568' 364 365 .. versionadded:: 2.6 366 367 .. data:: float_repr_style 368 369 A string indicating how the :func:`repr` function behaves for 370 floats. If the string has value ``'short'`` then for a finite 371 float ``x``, ``repr(x)`` aims to produce a short string with the 372 property that ``float(repr(x)) == x``. This is the usual behaviour 373 in Python 2.7 and later. Otherwise, ``float_repr_style`` has value 374 ``'legacy'`` and ``repr(x)`` behaves in the same way as it did in 375 versions of Python prior to 2.7. 376 377 .. versionadded:: 2.7 378 379 380 .. function:: getcheckinterval() 381 382 Return the interpreter's "check interval"; see :func:`setcheckinterval`. 383 384 .. versionadded:: 2.3 385 386 387 .. function:: getdefaultencoding() 388 389 Return the name of the current default string encoding used by the Unicode 390 implementation. 391 392 .. versionadded:: 2.0 393 394 395 .. function:: getdlopenflags() 396 397 Return the current value of the flags that are used for :c:func:`dlopen` calls. 398 The flag constants are defined in the :mod:`dl` and :mod:`DLFCN` modules. 399 Availability: Unix. 400 401 .. versionadded:: 2.2 402 403 404 .. function:: getfilesystemencoding() 405 406 Return the name of the encoding used to convert Unicode filenames into system 407 file names, or ``None`` if the system default encoding is used. The result value 408 depends on the operating system: 409 410 * On Mac OS X, the encoding is ``'utf-8'``. 411 412 * On Unix, the encoding is the user's preference according to the result of 413 nl_langinfo(CODESET), or ``None`` if the ``nl_langinfo(CODESET)`` 414 failed. 415 416 * On Windows NT+, file names are Unicode natively, so no conversion is 417 performed. :func:`getfilesystemencoding` still returns ``'mbcs'``, as 418 this is the encoding that applications should use when they explicitly 419 want to convert Unicode strings to byte strings that are equivalent when 420 used as file names. 421 422 * On Windows 9x, the encoding is ``'mbcs'``. 423 424 .. versionadded:: 2.3 425 426 427 .. function:: getrefcount(object) 428 429 Return the reference count of the *object*. The count returned is generally one 430 higher than you might expect, because it includes the (temporary) reference as 431 an argument to :func:`getrefcount`. 432 433 434 .. function:: getrecursionlimit() 435 436 Return the current value of the recursion limit, the maximum depth of the Python 437 interpreter stack. This limit prevents infinite recursion from causing an 438 overflow of the C stack and crashing Python. It can be set by 439 :func:`setrecursionlimit`. 440 441 442 .. function:: getsizeof(object[, default]) 443 444 Return the size of an object in bytes. The object can be any type of 445 object. All built-in objects will return correct results, but this 446 does not have to hold true for third-party extensions as it is implementation 447 specific. 448 449 If given, *default* will be returned if the object does not provide means to 450 retrieve the size. Otherwise a :exc:`TypeError` will be raised. 451 452 :func:`getsizeof` calls the object's ``__sizeof__`` method and adds an 453 additional garbage collector overhead if the object is managed by the garbage 454 collector. 455 456 .. versionadded:: 2.6 457 458 459 .. function:: _getframe([depth]) 460 461 Return a frame object from the call stack. If optional integer *depth* is 462 given, return the frame object that many calls below the top of the stack. If 463 that is deeper than the call stack, :exc:`ValueError` is raised. The default 464 for *depth* is zero, returning the frame at the top of the call stack. 465 466 .. impl-detail:: 467 468 This function should be used for internal and specialized purposes only. 469 It is not guaranteed to exist in all implementations of Python. 470 471 472 .. function:: getprofile() 473 474 .. index:: 475 single: profile function 476 single: profiler 477 478 Get the profiler function as set by :func:`setprofile`. 479 480 .. versionadded:: 2.6 481 482 483 .. function:: gettrace() 484 485 .. index:: 486 single: trace function 487 single: debugger 488 489 Get the trace function as set by :func:`settrace`. 490 491 .. impl-detail:: 492 493 The :func:`gettrace` function is intended only for implementing debuggers, 494 profilers, coverage tools and the like. Its behavior is part of the 495 implementation platform, rather than part of the language definition, and 496 thus may not be available in all Python implementations. 497 498 .. versionadded:: 2.6 499 500 501 .. function:: getwindowsversion() 502 503 Return a named tuple describing the Windows version 504 currently running. The named elements are *major*, *minor*, 505 *build*, *platform*, *service_pack*, *service_pack_minor*, 506 *service_pack_major*, *suite_mask*, and *product_type*. 507 *service_pack* contains a string while all other values are 508 integers. The components can also be accessed by name, so 509 ``sys.getwindowsversion()[0]`` is equivalent to 510 ``sys.getwindowsversion().major``. For compatibility with prior 511 versions, only the first 5 elements are retrievable by indexing. 512 513 *platform* may be one of the following values: 514 515 +-----------------------------------------+-------------------------+ 516 | Constant | Platform | 517 +=========================================+=========================+ 518 | :const:`0 (VER_PLATFORM_WIN32s)` | Win32s on Windows 3.1 | 519 +-----------------------------------------+-------------------------+ 520 | :const:`1 (VER_PLATFORM_WIN32_WINDOWS)` | Windows 95/98/ME | 521 +-----------------------------------------+-------------------------+ 522 | :const:`2 (VER_PLATFORM_WIN32_NT)` | Windows NT/2000/XP/x64 | 523 +-----------------------------------------+-------------------------+ 524 | :const:`3 (VER_PLATFORM_WIN32_CE)` | Windows CE | 525 +-----------------------------------------+-------------------------+ 526 527 *product_type* may be one of the following values: 528 529 +---------------------------------------+---------------------------------+ 530 | Constant | Meaning | 531 +=======================================+=================================+ 532 | :const:`1 (VER_NT_WORKSTATION)` | The system is a workstation. | 533 +---------------------------------------+---------------------------------+ 534 | :const:`2 (VER_NT_DOMAIN_CONTROLLER)` | The system is a domain | 535 | | controller. | 536 +---------------------------------------+---------------------------------+ 537 | :const:`3 (VER_NT_SERVER)` | The system is a server, but not | 538 | | a domain controller. | 539 +---------------------------------------+---------------------------------+ 540 541 542 This function wraps the Win32 :c:func:`GetVersionEx` function; see the 543 Microsoft documentation on :c:func:`OSVERSIONINFOEX` for more information 544 about these fields. 545 546 Availability: Windows. 547 548 .. versionadded:: 2.3 549 .. versionchanged:: 2.7 550 Changed to a named tuple and added *service_pack_minor*, 551 *service_pack_major*, *suite_mask*, and *product_type*. 552 553 554 .. data:: hexversion 555 556 The version number encoded as a single integer. This is guaranteed to increase 557 with each version, including proper support for non-production releases. For 558 example, to test that the Python interpreter is at least version 1.5.2, use:: 559 560 if sys.hexversion >= 0x010502F0: 561 # use some advanced feature 562 ... 563 else: 564 # use an alternative implementation or warn the user 565 ... 566 567 This is called ``hexversion`` since it only really looks meaningful when viewed 568 as the result of passing it to the built-in :func:`hex` function. The 569 ``version_info`` value may be used for a more human-friendly encoding of the 570 same information. 571 572 The ``hexversion`` is a 32-bit number with the following layout: 573 574 +-------------------------+------------------------------------------------+ 575 | Bits (big endian order) | Meaning | 576 +=========================+================================================+ 577 | :const:`1-8` | ``PY_MAJOR_VERSION`` (the ``2`` in | 578 | | ``2.1.0a3``) | 579 +-------------------------+------------------------------------------------+ 580 | :const:`9-16` | ``PY_MINOR_VERSION`` (the ``1`` in | 581 | | ``2.1.0a3``) | 582 +-------------------------+------------------------------------------------+ 583 | :const:`17-24` | ``PY_MICRO_VERSION`` (the ``0`` in | 584 | | ``2.1.0a3``) | 585 +-------------------------+------------------------------------------------+ 586 | :const:`25-28` | ``PY_RELEASE_LEVEL`` (``0xA`` for alpha, | 587 | | ``0xB`` for beta, ``0xC`` for release | 588 | | candidate and ``0xF`` for final) | 589 +-------------------------+------------------------------------------------+ 590 | :const:`29-32` | ``PY_RELEASE_SERIAL`` (the ``3`` in | 591 | | ``2.1.0a3``, zero for final releases) | 592 +-------------------------+------------------------------------------------+ 593 594 Thus ``2.1.0a3`` is hexversion ``0x020100a3``. 595 596 .. versionadded:: 1.5.2 597 598 599 .. data:: long_info 600 601 A struct sequence that holds information about Python's 602 internal representation of integers. The attributes are read only. 603 604 .. tabularcolumns:: |l|L| 605 606 +-------------------------+----------------------------------------------+ 607 | Attribute | Explanation | 608 +=========================+==============================================+ 609 | :const:`bits_per_digit` | number of bits held in each digit. Python | 610 | | integers are stored internally in base | 611 | | ``2**long_info.bits_per_digit`` | 612 +-------------------------+----------------------------------------------+ 613 | :const:`sizeof_digit` | size in bytes of the C type used to | 614 | | represent a digit | 615 +-------------------------+----------------------------------------------+ 616 617 .. versionadded:: 2.7 618 619 620 .. data:: last_type 621 last_value 622 last_traceback 623 624 These three variables are not always defined; they are set when an exception is 625 not handled and the interpreter prints an error message and a stack traceback. 626 Their intended use is to allow an interactive user to import a debugger module 627 and engage in post-mortem debugging without having to re-execute the command 628 that caused the error. (Typical use is ``import pdb; pdb.pm()`` to enter the 629 post-mortem debugger; see chapter :ref:`debugger` for 630 more information.) 631 632 The meaning of the variables is the same as that of the return values from 633 :func:`exc_info` above. (Since there is only one interactive thread, 634 thread-safety is not a concern for these variables, unlike for ``exc_type`` 635 etc.) 636 637 638 .. data:: maxint 639 640 The largest positive integer supported by Python's regular integer type. This 641 is at least 2\*\*31-1. The largest negative integer is ``-maxint-1`` --- the 642 asymmetry results from the use of 2's complement binary arithmetic. 643 644 .. data:: maxsize 645 646 The largest positive integer supported by the platform's Py_ssize_t type, 647 and thus the maximum size lists, strings, dicts, and many other containers 648 can have. 649 650 .. data:: maxunicode 651 652 An integer giving the largest supported code point for a Unicode character. The 653 value of this depends on the configuration option that specifies whether Unicode 654 characters are stored as UCS-2 or UCS-4. 655 656 657 .. data:: meta_path 658 659 A list of :term:`finder` objects that have their :meth:`find_module` 660 methods called to see if one of the objects can find the module to be 661 imported. The :meth:`find_module` method is called at least with the 662 absolute name of the module being imported. If the module to be imported is 663 contained in package then the parent package's :attr:`__path__` attribute 664 is passed in as a second argument. The method returns ``None`` if 665 the module cannot be found, else returns a :term:`loader`. 666 667 :data:`sys.meta_path` is searched before any implicit default finders or 668 :data:`sys.path`. 669 670 See :pep:`302` for the original specification. 671 672 673 .. data:: modules 674 675 .. index:: builtin: reload 676 677 This is a dictionary that maps module names to modules which have already been 678 loaded. This can be manipulated to force reloading of modules and other tricks. 679 Note that removing a module from this dictionary is *not* the same as calling 680 :func:`reload` on the corresponding module object. 681 682 683 .. data:: path 684 685 .. index:: triple: module; search; path 686 687 A list of strings that specifies the search path for modules. Initialized from 688 the environment variable :envvar:`PYTHONPATH`, plus an installation-dependent 689 default. 690 691 As initialized upon program startup, the first item of this list, ``path[0]``, 692 is the directory containing the script that was used to invoke the Python 693 interpreter. If the script directory is not available (e.g. if the interpreter 694 is invoked interactively or if the script is read from standard input), 695 ``path[0]`` is the empty string, which directs Python to search modules in the 696 current directory first. Notice that the script directory is inserted *before* 697 the entries inserted as a result of :envvar:`PYTHONPATH`. 698 699 A program is free to modify this list for its own purposes. 700 701 .. versionchanged:: 2.3 702 Unicode strings are no longer ignored. 703 704 .. seealso:: 705 Module :mod:`site` This describes how to use .pth files to extend 706 :data:`sys.path`. 707 708 709 .. data:: path_hooks 710 711 A list of callables that take a path argument to try to create a 712 :term:`finder` for the path. If a finder can be created, it is to be 713 returned by the callable, else raise :exc:`ImportError`. 714 715 Originally specified in :pep:`302`. 716 717 718 .. data:: path_importer_cache 719 720 A dictionary acting as a cache for :term:`finder` objects. The keys are 721 paths that have been passed to :data:`sys.path_hooks` and the values are 722 the finders that are found. If a path is a valid file system path but no 723 explicit finder is found on :data:`sys.path_hooks` then ``None`` is 724 stored to represent the implicit default finder should be used. If the path 725 is not an existing path then :class:`imp.NullImporter` is set. 726 727 Originally specified in :pep:`302`. 728 729 730 .. data:: platform 731 732 This string contains a platform identifier that can be used to append 733 platform-specific components to :data:`sys.path`, for instance. 734 735 For most Unix systems, this is the lowercased OS name as returned by ``uname 736 -s`` with the first part of the version as returned by ``uname -r`` appended, 737 e.g. ``'sunos5'``, *at the time when Python was built*. Unless you want to 738 test for a specific system version, it is therefore recommended to use the 739 following idiom:: 740 741 if sys.platform.startswith('freebsd'): 742 # FreeBSD-specific code here... 743 elif sys.platform.startswith('linux'): 744 # Linux-specific code here... 745 746 .. versionchanged:: 2.7.3 747 Since lots of code check for ``sys.platform == 'linux2'``, and there is 748 no essential change between Linux 2.x and 3.x, ``sys.platform`` is always 749 set to ``'linux2'``, even on Linux 3.x. In Python 3.3 and later, the 750 value will always be set to ``'linux'``, so it is recommended to always 751 use the ``startswith`` idiom presented above. 752 753 For other systems, the values are: 754 755 ===================== =========================== 756 System :data:`platform` value 757 ===================== =========================== 758 Linux (2.x *and* 3.x) ``'linux2'`` 759 Windows ``'win32'`` 760 Windows/Cygwin ``'cygwin'`` 761 Mac OS X ``'darwin'`` 762 OS/2 ``'os2'`` 763 OS/2 EMX ``'os2emx'`` 764 RiscOS ``'riscos'`` 765 AtheOS ``'atheos'`` 766 ===================== =========================== 767 768 .. seealso:: 769 :attr:`os.name` has a coarser granularity. :func:`os.uname` gives 770 system-dependent version information. 771 772 The :mod:`platform` module provides detailed checks for the 773 system's identity. 774 775 .. data:: prefix 776 777 A string giving the site-specific directory prefix where the platform 778 independent Python files are installed; by default, this is the string 779 ``'/usr/local'``. This can be set at build time with the ``--prefix`` 780 argument to the :program:`configure` script. The main collection of Python 781 library modules is installed in the directory :file:`{prefix}/lib/python{X.Y}` 782 while the platform independent header files (all except :file:`pyconfig.h`) are 783 stored in :file:`{prefix}/include/python{X.Y}`, where *X.Y* is the version 784 number of Python, for example ``2.7``. 785 786 787 .. data:: ps1 788 ps2 789 790 .. index:: 791 single: interpreter prompts 792 single: prompts, interpreter 793 794 Strings specifying the primary and secondary prompt of the interpreter. These 795 are only defined if the interpreter is in interactive mode. Their initial 796 values in this case are ``'>>> '`` and ``'... '``. If a non-string object is 797 assigned to either variable, its :func:`str` is re-evaluated each time the 798 interpreter prepares to read a new interactive command; this can be used to 799 implement a dynamic prompt. 800 801 802 .. data:: py3kwarning 803 804 Bool containing the status of the Python 3 warning flag. It's ``True`` 805 when Python is started with the -3 option. (This should be considered 806 read-only; setting it to a different value doesn't have an effect on 807 Python 3 warnings.) 808 809 .. versionadded:: 2.6 810 811 812 .. function:: setcheckinterval(interval) 813 814 Set the interpreter's "check interval". This integer value determines how often 815 the interpreter checks for periodic things such as thread switches and signal 816 handlers. The default is ``100``, meaning the check is performed every 100 817 Python virtual instructions. Setting it to a larger value may increase 818 performance for programs using threads. Setting it to a value ``<=`` 0 checks 819 every virtual instruction, maximizing responsiveness as well as overhead. 820 821 822 .. function:: setdefaultencoding(name) 823 824 Set the current default string encoding used by the Unicode implementation. If 825 *name* does not match any available encoding, :exc:`LookupError` is raised. 826 This function is only intended to be used by the :mod:`site` module 827 implementation and, where needed, by :mod:`sitecustomize`. Once used by the 828 :mod:`site` module, it is removed from the :mod:`sys` module's namespace. 829 830 .. Note that :mod:`site` is not imported if the :option:`-S` option is passed 831 to the interpreter, in which case this function will remain available. 832 833 .. versionadded:: 2.0 834 835 836 .. function:: setdlopenflags(n) 837 838 Set the flags used by the interpreter for :c:func:`dlopen` calls, such as when 839 the interpreter loads extension modules. Among other things, this will enable a 840 lazy resolving of symbols when importing a module, if called as 841 ``sys.setdlopenflags(0)``. To share symbols across extension modules, call as 842 ``sys.setdlopenflags(dl.RTLD_NOW | dl.RTLD_GLOBAL)``. Symbolic names for the 843 flag modules can be either found in the :mod:`dl` module, or in the :mod:`DLFCN` 844 module. If :mod:`DLFCN` is not available, it can be generated from 845 :file:`/usr/include/dlfcn.h` using the :program:`h2py` script. Availability: 846 Unix. 847 848 .. versionadded:: 2.2 849 850 851 .. function:: setprofile(profilefunc) 852 853 .. index:: 854 single: profile function 855 single: profiler 856 857 Set the system's profile function, which allows you to implement a Python source 858 code profiler in Python. See chapter :ref:`profile` for more information on the 859 Python profiler. The system's profile function is called similarly to the 860 system's trace function (see :func:`settrace`), but it is called with different events, 861 for example it isn't called for each executed line of code (only on call and return, 862 but the return event is reported even when an exception has been set). The function is 863 thread-specific, but there is no way for the profiler to know about context switches between 864 threads, so it does not make sense to use this in the presence of multiple threads. Also, 865 its return value is not used, so it can simply return ``None``. 866 867 Profile functions should have three arguments: *frame*, *event*, and 868 *arg*. *frame* is the current stack frame. *event* is a string: ``'call'``, 869 ``'return'``, ``'c_call'``, ``'c_return'``, or ``'c_exception'``. *arg* depends 870 on the event type. 871 872 The events have the following meaning: 873 874 ``'call'`` 875 A function is called (or some other code block entered). The 876 profile function is called; *arg* is ``None``. 877 878 ``'return'`` 879 A function (or other code block) is about to return. The profile 880 function is called; *arg* is the value that will be returned, or ``None`` 881 if the event is caused by an exception being raised. 882 883 ``'c_call'`` 884 A C function is about to be called. This may be an extension function or 885 a built-in. *arg* is the C function object. 886 887 ``'c_return'`` 888 A C function has returned. *arg* is the C function object. 889 890 ``'c_exception'`` 891 A C function has raised an exception. *arg* is the C function object. 892 893 .. function:: setrecursionlimit(limit) 894 895 Set the maximum depth of the Python interpreter stack to *limit*. This limit 896 prevents infinite recursion from causing an overflow of the C stack and crashing 897 Python. 898 899 The highest possible limit is platform-dependent. A user may need to set the 900 limit higher when she has a program that requires deep recursion and a platform 901 that supports a higher limit. This should be done with care, because a too-high 902 limit can lead to a crash. 903 904 905 .. function:: settrace(tracefunc) 906 907 .. index:: 908 single: trace function 909 single: debugger 910 911 Set the system's trace function, which allows you to implement a Python 912 source code debugger in Python. The function is thread-specific; for a 913 debugger to support multiple threads, it must be registered using 914 :func:`settrace` for each thread being debugged. 915 916 Trace functions should have three arguments: *frame*, *event*, and 917 *arg*. *frame* is the current stack frame. *event* is a string: ``'call'``, 918 ``'line'``, ``'return'`` or ``'exception'``. *arg* depends on 919 the event type. 920 921 The trace function is invoked (with *event* set to ``'call'``) whenever a new 922 local scope is entered; it should return a reference to a local trace 923 function to be used that scope, or ``None`` if the scope shouldn't be traced. 924 925 The local trace function should return a reference to itself (or to another 926 function for further tracing in that scope), or ``None`` to turn off tracing 927 in that scope. 928 929 The events have the following meaning: 930 931 ``'call'`` 932 A function is called (or some other code block entered). The 933 global trace function is called; *arg* is ``None``; the return value 934 specifies the local trace function. 935 936 ``'line'`` 937 The interpreter is about to execute a new line of code or re-execute the 938 condition of a loop. The local trace function is called; *arg* is 939 ``None``; the return value specifies the new local trace function. See 940 :file:`Objects/lnotab_notes.txt` for a detailed explanation of how this 941 works. 942 943 ``'return'`` 944 A function (or other code block) is about to return. The local trace 945 function is called; *arg* is the value that will be returned, or ``None`` 946 if the event is caused by an exception being raised. The trace function's 947 return value is ignored. 948 949 ``'exception'`` 950 An exception has occurred. The local trace function is called; *arg* is a 951 tuple ``(exception, value, traceback)``; the return value specifies the 952 new local trace function. 953 954 Note that as an exception is propagated down the chain of callers, an 955 ``'exception'`` event is generated at each level. 956 957 For more information on code and frame objects, refer to :ref:`types`. 958 959 .. impl-detail:: 960 961 The :func:`settrace` function is intended only for implementing debuggers, 962 profilers, coverage tools and the like. Its behavior is part of the 963 implementation platform, rather than part of the language definition, and 964 thus may not be available in all Python implementations. 965 966 967 .. function:: settscdump(on_flag) 968 969 Activate dumping of VM measurements using the Pentium timestamp counter, if 970 *on_flag* is true. Deactivate these dumps if *on_flag* is off. The function is 971 available only if Python was compiled with ``--with-tsc``. To understand 972 the output of this dump, read :file:`Python/ceval.c` in the Python sources. 973 974 .. versionadded:: 2.4 975 976 .. impl-detail:: 977 978 This function is intimately bound to CPython implementation details and 979 thus not likely to be implemented elsewhere. 980 981 982 .. data:: stdin 983 stdout 984 stderr 985 986 .. index:: 987 builtin: input 988 builtin: raw_input 989 990 File objects corresponding to the interpreter's standard input, output and error 991 streams. ``stdin`` is used for all interpreter input except for scripts but 992 including calls to :func:`input` and :func:`raw_input`. ``stdout`` is used for 993 the output of :keyword:`print` and :term:`expression` statements and for the 994 prompts of :func:`input` and :func:`raw_input`. The interpreter's own prompts 995 and (almost all of) its error messages go to ``stderr``. ``stdout`` and 996 ``stderr`` needn't be built-in file objects: any object is acceptable as long 997 as it has a :meth:`write` method that takes a string argument. (Changing these 998 objects doesn't affect the standard I/O streams of processes executed by 999 :func:`os.popen`, :func:`os.system` or the :func:`exec\*` family of functions in 1000 the :mod:`os` module.) 1001 1002 1003 .. data:: __stdin__ 1004 __stdout__ 1005 __stderr__ 1006 1007 These objects contain the original values of ``stdin``, ``stderr`` and 1008 ``stdout`` at the start of the program. They are used during finalization, 1009 and could be useful to print to the actual standard stream no matter if the 1010 ``sys.std*`` object has been redirected. 1011 1012 It can also be used to restore the actual files to known working file objects 1013 in case they have been overwritten with a broken object. However, the 1014 preferred way to do this is to explicitly save the previous stream before 1015 replacing it, and restore the saved object. 1016 1017 1018 .. data:: subversion 1019 1020 A triple (repo, branch, version) representing the Subversion information of the 1021 Python interpreter. *repo* is the name of the repository, ``'CPython'``. 1022 *branch* is a string of one of the forms ``'trunk'``, ``'branches/name'`` or 1023 ``'tags/name'``. *version* is the output of ``svnversion``, if the interpreter 1024 was built from a Subversion checkout; it contains the revision number (range) 1025 and possibly a trailing 'M' if there were local modifications. If the tree was 1026 exported (or svnversion was not available), it is the revision of 1027 ``Include/patchlevel.h`` if the branch is a tag. Otherwise, it is ``None``. 1028 1029 .. versionadded:: 2.5 1030 1031 .. note:: 1032 Python is now `developed <https://docs.python.org/devguide/>`_ using 1033 Mercurial. In recent Python 2.7 bugfix releases, :data:`subversion` 1034 therefore contains placeholder information. It is removed in Python 1035 3.3. 1036 1037 1038 .. data:: tracebacklimit 1039 1040 When this variable is set to an integer value, it determines the maximum number 1041 of levels of traceback information printed when an unhandled exception occurs. 1042 The default is ``1000``. When set to ``0`` or less, all traceback information 1043 is suppressed and only the exception type and value are printed. 1044 1045 1046 .. data:: version 1047 1048 A string containing the version number of the Python interpreter plus additional 1049 information on the build number and compiler used. This string is displayed 1050 when the interactive interpreter is started. Do not extract version information 1051 out of it, rather, use :data:`version_info` and the functions provided by the 1052 :mod:`platform` module. 1053 1054 1055 .. data:: api_version 1056 1057 The C API version for this interpreter. Programmers may find this useful when 1058 debugging version conflicts between Python and extension modules. 1059 1060 .. versionadded:: 2.3 1061 1062 1063 .. data:: version_info 1064 1065 A tuple containing the five components of the version number: *major*, *minor*, 1066 *micro*, *releaselevel*, and *serial*. All values except *releaselevel* are 1067 integers; the release level is ``'alpha'``, ``'beta'``, ``'candidate'``, or 1068 ``'final'``. The ``version_info`` value corresponding to the Python version 2.0 1069 is ``(2, 0, 0, 'final', 0)``. The components can also be accessed by name, 1070 so ``sys.version_info[0]`` is equivalent to ``sys.version_info.major`` 1071 and so on. 1072 1073 .. versionadded:: 2.0 1074 .. versionchanged:: 2.7 1075 Added named component attributes 1076 1077 1078 .. data:: warnoptions 1079 1080 This is an implementation detail of the warnings framework; do not modify this 1081 value. Refer to the :mod:`warnings` module for more information on the warnings 1082 framework. 1083 1084 1085 .. data:: winver 1086 1087 The version number used to form registry keys on Windows platforms. This is 1088 stored as string resource 1000 in the Python DLL. The value is normally the 1089 first three characters of :const:`version`. It is provided in the :mod:`sys` 1090 module for informational purposes; modifying this value has no effect on the 1091 registry keys used by Python. Availability: Windows. 1092 1093 .. rubric:: Citations 1094 1095 .. [C99] ISO/IEC 9899:1999. "Programming languages -- C." A public draft of this standard is available at http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1256.pdf\ . 1096
