1 :mod:`sys` --- System-specific parameters and functions 2 ======================================================= 3 4 .. module:: sys 5 :synopsis: Access system-specific parameters and functions. 6 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:: abiflags 15 16 On POSIX systems where Python was built with the standard ``configure`` 17 script, this contains the ABI flags as specified by :pep:`3149`. 18 19 .. versionadded:: 3.2 20 21 22 .. data:: argv 23 24 The list of command line arguments passed to a Python script. ``argv[0]`` is the 25 script name (it is operating system dependent whether this is a full pathname or 26 not). If the command was executed using the :option:`-c` command line option to 27 the interpreter, ``argv[0]`` is set to the string ``'-c'``. If no script name 28 was passed to the Python interpreter, ``argv[0]`` is the empty string. 29 30 To loop over the standard input, or the list of files given on the 31 command line, see the :mod:`fileinput` module. 32 33 34 .. data:: base_exec_prefix 35 36 Set during Python startup, before ``site.py`` is run, to the same value as 37 :data:`exec_prefix`. If not running in a 38 :ref:`virtual environment <venv-def>`, the values will stay the same; if 39 ``site.py`` finds that a virtual environment is in use, the values of 40 :data:`prefix` and :data:`exec_prefix` will be changed to point to the 41 virtual environment, whereas :data:`base_prefix` and 42 :data:`base_exec_prefix` will remain pointing to the base Python 43 installation (the one which the virtual environment was created from). 44 45 .. versionadded:: 3.3 46 47 48 .. data:: base_prefix 49 50 Set during Python startup, before ``site.py`` is run, to the same value as 51 :data:`prefix`. If not running in a :ref:`virtual environment <venv-def>`, the values 52 will stay the same; if ``site.py`` finds that a virtual environment is in 53 use, the values of :data:`prefix` and :data:`exec_prefix` will be changed to 54 point to the virtual environment, whereas :data:`base_prefix` and 55 :data:`base_exec_prefix` will remain pointing to the base Python 56 installation (the one which the virtual environment was created from). 57 58 .. versionadded:: 3.3 59 60 61 .. data:: byteorder 62 63 An indicator of the native byte order. This will have the value ``'big'`` on 64 big-endian (most-significant byte first) platforms, and ``'little'`` on 65 little-endian (least-significant byte first) platforms. 66 67 68 .. data:: builtin_module_names 69 70 A tuple of strings giving the names of all modules that are compiled into this 71 Python interpreter. (This information is not available in any other way --- 72 ``modules.keys()`` only lists the imported modules.) 73 74 75 .. function:: call_tracing(func, args) 76 77 Call ``func(*args)``, while tracing is enabled. The tracing state is saved, 78 and restored afterwards. This is intended to be called from a debugger from 79 a checkpoint, to recursively debug some other code. 80 81 82 .. data:: copyright 83 84 A string containing the copyright pertaining to the Python interpreter. 85 86 87 .. function:: _clear_type_cache() 88 89 Clear the internal type cache. The type cache is used to speed up attribute 90 and method lookups. Use the function *only* to drop unnecessary references 91 during reference leak debugging. 92 93 This function should be used for internal and specialized purposes only. 94 95 96 .. function:: _current_frames() 97 98 Return a dictionary mapping each thread's identifier to the topmost stack frame 99 currently active in that thread at the time the function is called. Note that 100 functions in the :mod:`traceback` module can build the call stack given such a 101 frame. 102 103 This is most useful for debugging deadlock: this function does not require the 104 deadlocked threads' cooperation, and such threads' call stacks are frozen for as 105 long as they remain deadlocked. The frame returned for a non-deadlocked thread 106 may bear no relationship to that thread's current activity by the time calling 107 code examines the frame. 108 109 This function should be used for internal and specialized purposes only. 110 111 112 .. function:: breakpointhook() 113 114 This hook function is called by built-in :func:`breakpoint`. By default, 115 it drops you into the :mod:`pdb` debugger, but it can be set to any other 116 function so that you can choose which debugger gets used. 117 118 The signature of this function is dependent on what it calls. For example, 119 the default binding (e.g. ``pdb.set_trace()``) expects no arguments, but 120 you might bind it to a function that expects additional arguments 121 (positional and/or keyword). The built-in ``breakpoint()`` function passes 122 its ``*args`` and ``**kws`` straight through. Whatever 123 ``breakpointhooks()`` returns is returned from ``breakpoint()``. 124 125 The default implementation first consults the environment variable 126 :envvar:`PYTHONBREAKPOINT`. If that is set to ``"0"`` then this function 127 returns immediately; i.e. it is a no-op. If the environment variable is 128 not set, or is set to the empty string, ``pdb.set_trace()`` is called. 129 Otherwise this variable should name a function to run, using Python's 130 dotted-import nomenclature, e.g. ``package.subpackage.module.function``. 131 In this case, ``package.subpackage.module`` would be imported and the 132 resulting module must have a callable named ``function()``. This is run, 133 passing in ``*args`` and ``**kws``, and whatever ``function()`` returns, 134 ``sys.breakpointhook()`` returns to the built-in :func:`breakpoint` 135 function. 136 137 Note that if anything goes wrong while importing the callable named by 138 :envvar:`PYTHONBREAKPOINT`, a :exc:`RuntimeWarning` is reported and the 139 breakpoint is ignored. 140 141 Also note that if ``sys.breakpointhook()`` is overridden programmatically, 142 :envvar:`PYTHONBREAKPOINT` is *not* consulted. 143 144 .. versionadded:: 3.7 145 146 .. function:: _debugmallocstats() 147 148 Print low-level information to stderr about the state of CPython's memory 149 allocator. 150 151 If Python is configured --with-pydebug, it also performs some expensive 152 internal consistency checks. 153 154 .. versionadded:: 3.3 155 156 .. impl-detail:: 157 158 This function is specific to CPython. The exact output format is not 159 defined here, and may change. 160 161 162 .. data:: dllhandle 163 164 Integer specifying the handle of the Python DLL. 165 166 .. availability:: Windows. 167 168 169 .. function:: displayhook(value) 170 171 If *value* is not ``None``, this function prints ``repr(value)`` to 172 ``sys.stdout``, and saves *value* in ``builtins._``. If ``repr(value)`` is 173 not encodable to ``sys.stdout.encoding`` with ``sys.stdout.errors`` error 174 handler (which is probably ``'strict'``), encode it to 175 ``sys.stdout.encoding`` with ``'backslashreplace'`` error handler. 176 177 ``sys.displayhook`` is called on the result of evaluating an :term:`expression` 178 entered in an interactive Python session. The display of these values can be 179 customized by assigning another one-argument function to ``sys.displayhook``. 180 181 Pseudo-code:: 182 183 def displayhook(value): 184 if value is None: 185 return 186 # Set '_' to None to avoid recursion 187 builtins._ = None 188 text = repr(value) 189 try: 190 sys.stdout.write(text) 191 except UnicodeEncodeError: 192 bytes = text.encode(sys.stdout.encoding, 'backslashreplace') 193 if hasattr(sys.stdout, 'buffer'): 194 sys.stdout.buffer.write(bytes) 195 else: 196 text = bytes.decode(sys.stdout.encoding, 'strict') 197 sys.stdout.write(text) 198 sys.stdout.write("\n") 199 builtins._ = value 200 201 .. versionchanged:: 3.2 202 Use ``'backslashreplace'`` error handler on :exc:`UnicodeEncodeError`. 203 204 205 .. data:: dont_write_bytecode 206 207 If this is true, Python won't try to write ``.pyc`` files on the 208 import of source modules. This value is initially set to ``True`` or 209 ``False`` depending on the :option:`-B` command line option and the 210 :envvar:`PYTHONDONTWRITEBYTECODE` environment variable, but you can set it 211 yourself to control bytecode file generation. 212 213 214 .. function:: excepthook(type, value, traceback) 215 216 This function prints out a given traceback and exception to ``sys.stderr``. 217 218 When an exception is raised and uncaught, the interpreter calls 219 ``sys.excepthook`` with three arguments, the exception class, exception 220 instance, and a traceback object. In an interactive session this happens just 221 before control is returned to the prompt; in a Python program this happens just 222 before the program exits. The handling of such top-level exceptions can be 223 customized by assigning another three-argument function to ``sys.excepthook``. 224 225 226 .. data:: __breakpointhook__ 227 __displayhook__ 228 __excepthook__ 229 230 These objects contain the original values of ``breakpointhook``, 231 ``displayhook``, and ``excepthook`` at the start of the program. They are 232 saved so that ``breakpointhook``, ``displayhook`` and ``excepthook`` can be 233 restored in case they happen to get replaced with broken or alternative 234 objects. 235 236 .. versionadded:: 3.7 237 __breakpointhook__ 238 239 240 .. function:: exc_info() 241 242 This function returns a tuple of three values that give information about the 243 exception that is currently being handled. The information returned is specific 244 both to the current thread and to the current stack frame. If the current stack 245 frame is not handling an exception, the information is taken from the calling 246 stack frame, or its caller, and so on until a stack frame is found that is 247 handling an exception. Here, "handling an exception" is defined as "executing 248 an except clause." For any stack frame, only information about the exception 249 being currently handled is accessible. 250 251 .. index:: object: traceback 252 253 If no exception is being handled anywhere on the stack, a tuple containing 254 three ``None`` values is returned. Otherwise, the values returned are 255 ``(type, value, traceback)``. Their meaning is: *type* gets the type of the 256 exception being handled (a subclass of :exc:`BaseException`); *value* gets 257 the exception instance (an instance of the exception type); *traceback* gets 258 a traceback object (see the Reference Manual) which encapsulates the call 259 stack at the point where the exception originally occurred. 260 261 262 .. data:: exec_prefix 263 264 A string giving the site-specific directory prefix where the platform-dependent 265 Python files are installed; by default, this is also ``'/usr/local'``. This can 266 be set at build time with the ``--exec-prefix`` argument to the 267 :program:`configure` script. Specifically, all configuration files (e.g. the 268 :file:`pyconfig.h` header file) are installed in the directory 269 :file:`{exec_prefix}/lib/python{X.Y}/config`, and shared library modules are 270 installed in :file:`{exec_prefix}/lib/python{X.Y}/lib-dynload`, where *X.Y* 271 is the version number of Python, for example ``3.2``. 272 273 .. note:: 274 275 If a :ref:`virtual environment <venv-def>` is in effect, this 276 value will be changed in ``site.py`` to point to the virtual environment. 277 The value for the Python installation will still be available, via 278 :data:`base_exec_prefix`. 279 280 281 .. data:: executable 282 283 A string giving the absolute path of the executable binary for the Python 284 interpreter, on systems where this makes sense. If Python is unable to retrieve 285 the real path to its executable, :data:`sys.executable` will be an empty string 286 or ``None``. 287 288 289 .. function:: exit([arg]) 290 291 Exit from Python. This is implemented by raising the :exc:`SystemExit` 292 exception, so cleanup actions specified by finally clauses of :keyword:`try` 293 statements are honored, and it is possible to intercept the exit attempt at 294 an outer level. 295 296 The optional argument *arg* can be an integer giving the exit status 297 (defaulting to zero), or another type of object. If it is an integer, zero 298 is considered "successful termination" and any nonzero value is considered 299 "abnormal termination" by shells and the like. Most systems require it to be 300 in the range 0--127, and produce undefined results otherwise. Some systems 301 have a convention for assigning specific meanings to specific exit codes, but 302 these are generally underdeveloped; Unix programs generally use 2 for command 303 line syntax errors and 1 for all other kind of errors. If another type of 304 object is passed, ``None`` is equivalent to passing zero, and any other 305 object is printed to :data:`stderr` and results in an exit code of 1. In 306 particular, ``sys.exit("some error message")`` is a quick way to exit a 307 program when an error occurs. 308 309 Since :func:`exit` ultimately "only" raises an exception, it will only exit 310 the process when called from the main thread, and the exception is not 311 intercepted. 312 313 .. versionchanged:: 3.6 314 If an error occurs in the cleanup after the Python interpreter 315 has caught :exc:`SystemExit` (such as an error flushing buffered data 316 in the standard streams), the exit status is changed to 120. 317 318 319 .. data:: flags 320 321 The :term:`struct sequence` *flags* exposes the status of command line 322 flags. The attributes are read only. 323 324 ============================= ============================= 325 attribute flag 326 ============================= ============================= 327 :const:`debug` :option:`-d` 328 :const:`inspect` :option:`-i` 329 :const:`interactive` :option:`-i` 330 :const:`isolated` :option:`-I` 331 :const:`optimize` :option:`-O` or :option:`-OO` 332 :const:`dont_write_bytecode` :option:`-B` 333 :const:`no_user_site` :option:`-s` 334 :const:`no_site` :option:`-S` 335 :const:`ignore_environment` :option:`-E` 336 :const:`verbose` :option:`-v` 337 :const:`bytes_warning` :option:`-b` 338 :const:`quiet` :option:`-q` 339 :const:`hash_randomization` :option:`-R` 340 :const:`dev_mode` :option:`-X` ``dev`` 341 :const:`utf8_mode` :option:`-X` ``utf8`` 342 ============================= ============================= 343 344 .. versionchanged:: 3.2 345 Added ``quiet`` attribute for the new :option:`-q` flag. 346 347 .. versionadded:: 3.2.3 348 The ``hash_randomization`` attribute. 349 350 .. versionchanged:: 3.3 351 Removed obsolete ``division_warning`` attribute. 352 353 .. versionchanged:: 3.4 354 Added ``isolated`` attribute for :option:`-I` ``isolated`` flag. 355 356 .. versionchanged:: 3.7 357 Added ``dev_mode`` attribute for the new :option:`-X` ``dev`` flag 358 and ``utf8_mode`` attribute for the new :option:`-X` ``utf8`` flag. 359 360 361 .. data:: float_info 362 363 A :term:`struct sequence` holding information about the float type. It 364 contains low level information about the precision and internal 365 representation. The values correspond to the various floating-point 366 constants defined in the standard header file :file:`float.h` for the 'C' 367 programming language; see section 5.2.4.2.2 of the 1999 ISO/IEC C standard 368 [C99]_, 'Characteristics of floating types', for details. 369 370 .. tabularcolumns:: |l|l|L| 371 372 +---------------------+----------------+--------------------------------------------------+ 373 | attribute | float.h macro | explanation | 374 +=====================+================+==================================================+ 375 | :const:`epsilon` | DBL_EPSILON | difference between 1 and the least value greater | 376 | | | than 1 that is representable as a float | 377 +---------------------+----------------+--------------------------------------------------+ 378 | :const:`dig` | DBL_DIG | maximum number of decimal digits that can be | 379 | | | faithfully represented in a float; see below | 380 +---------------------+----------------+--------------------------------------------------+ 381 | :const:`mant_dig` | DBL_MANT_DIG | float precision: the number of base-``radix`` | 382 | | | digits in the significand of a float | 383 +---------------------+----------------+--------------------------------------------------+ 384 | :const:`max` | DBL_MAX | maximum representable finite float | 385 +---------------------+----------------+--------------------------------------------------+ 386 | :const:`max_exp` | DBL_MAX_EXP | maximum integer e such that ``radix**(e-1)`` is | 387 | | | a representable finite float | 388 +---------------------+----------------+--------------------------------------------------+ 389 | :const:`max_10_exp` | DBL_MAX_10_EXP | maximum integer e such that ``10**e`` is in the | 390 | | | range of representable finite floats | 391 +---------------------+----------------+--------------------------------------------------+ 392 | :const:`min` | DBL_MIN | minimum positive normalized float | 393 +---------------------+----------------+--------------------------------------------------+ 394 | :const:`min_exp` | DBL_MIN_EXP | minimum integer e such that ``radix**(e-1)`` is | 395 | | | a normalized float | 396 +---------------------+----------------+--------------------------------------------------+ 397 | :const:`min_10_exp` | DBL_MIN_10_EXP | minimum integer e such that ``10**e`` is a | 398 | | | normalized float | 399 +---------------------+----------------+--------------------------------------------------+ 400 | :const:`radix` | FLT_RADIX | radix of exponent representation | 401 +---------------------+----------------+--------------------------------------------------+ 402 | :const:`rounds` | FLT_ROUNDS | integer constant representing the rounding mode | 403 | | | used for arithmetic operations. This reflects | 404 | | | the value of the system FLT_ROUNDS macro at | 405 | | | interpreter startup time. See section 5.2.4.2.2 | 406 | | | of the C99 standard for an explanation of the | 407 | | | possible values and their meanings. | 408 +---------------------+----------------+--------------------------------------------------+ 409 410 The attribute :attr:`sys.float_info.dig` needs further explanation. If 411 ``s`` is any string representing a decimal number with at most 412 :attr:`sys.float_info.dig` significant digits, then converting ``s`` to a 413 float and back again will recover a string representing the same decimal 414 value:: 415 416 >>> import sys 417 >>> sys.float_info.dig 418 15 419 >>> s = '3.14159265358979' # decimal string with 15 significant digits 420 >>> format(float(s), '.15g') # convert to float and back -> same value 421 '3.14159265358979' 422 423 But for strings with more than :attr:`sys.float_info.dig` significant digits, 424 this isn't always true:: 425 426 >>> s = '9876543211234567' # 16 significant digits is too many! 427 >>> format(float(s), '.16g') # conversion changes value 428 '9876543211234568' 429 430 .. data:: float_repr_style 431 432 A string indicating how the :func:`repr` function behaves for 433 floats. If the string has value ``'short'`` then for a finite 434 float ``x``, ``repr(x)`` aims to produce a short string with the 435 property that ``float(repr(x)) == x``. This is the usual behaviour 436 in Python 3.1 and later. Otherwise, ``float_repr_style`` has value 437 ``'legacy'`` and ``repr(x)`` behaves in the same way as it did in 438 versions of Python prior to 3.1. 439 440 .. versionadded:: 3.1 441 442 443 .. function:: getallocatedblocks() 444 445 Return the number of memory blocks currently allocated by the interpreter, 446 regardless of their size. This function is mainly useful for tracking 447 and debugging memory leaks. Because of the interpreter's internal 448 caches, the result can vary from call to call; you may have to call 449 :func:`_clear_type_cache()` and :func:`gc.collect()` to get more 450 predictable results. 451 452 If a Python build or implementation cannot reasonably compute this 453 information, :func:`getallocatedblocks()` is allowed to return 0 instead. 454 455 .. versionadded:: 3.4 456 457 458 .. function:: getandroidapilevel() 459 460 Return the build time API version of Android as an integer. 461 462 .. availability:: Android. 463 464 .. versionadded:: 3.7 465 466 467 .. function:: getcheckinterval() 468 469 Return the interpreter's "check interval"; see :func:`setcheckinterval`. 470 471 .. deprecated:: 3.2 472 Use :func:`getswitchinterval` instead. 473 474 475 .. function:: getdefaultencoding() 476 477 Return the name of the current default string encoding used by the Unicode 478 implementation. 479 480 481 .. function:: getdlopenflags() 482 483 Return the current value of the flags that are used for 484 :c:func:`dlopen` calls. Symbolic names for the flag values can be 485 found in the :mod:`os` module (``RTLD_xxx`` constants, e.g. 486 :data:`os.RTLD_LAZY`). 487 488 .. availability:: Unix. 489 490 491 .. function:: getfilesystemencoding() 492 493 Return the name of the encoding used to convert between Unicode 494 filenames and bytes filenames. For best compatibility, str should be 495 used for filenames in all cases, although representing filenames as bytes 496 is also supported. Functions accepting or returning filenames should support 497 either str or bytes and internally convert to the system's preferred 498 representation. 499 500 This encoding is always ASCII-compatible. 501 502 :func:`os.fsencode` and :func:`os.fsdecode` should be used to ensure that 503 the correct encoding and errors mode are used. 504 505 * In the UTF-8 mode, the encoding is ``utf-8`` on any platform. 506 507 * On Mac OS X, the encoding is ``'utf-8'``. 508 509 * On Unix, the encoding is the locale encoding. 510 511 * On Windows, the encoding may be ``'utf-8'`` or ``'mbcs'``, depending 512 on user configuration. 513 514 .. versionchanged:: 3.2 515 :func:`getfilesystemencoding` result cannot be ``None`` anymore. 516 517 .. versionchanged:: 3.6 518 Windows is no longer guaranteed to return ``'mbcs'``. See :pep:`529` 519 and :func:`_enablelegacywindowsfsencoding` for more information. 520 521 .. versionchanged:: 3.7 522 Return 'utf-8' in the UTF-8 mode. 523 524 525 .. function:: getfilesystemencodeerrors() 526 527 Return the name of the error mode used to convert between Unicode filenames 528 and bytes filenames. The encoding name is returned from 529 :func:`getfilesystemencoding`. 530 531 :func:`os.fsencode` and :func:`os.fsdecode` should be used to ensure that 532 the correct encoding and errors mode are used. 533 534 .. versionadded:: 3.6 535 536 .. function:: getrefcount(object) 537 538 Return the reference count of the *object*. The count returned is generally one 539 higher than you might expect, because it includes the (temporary) reference as 540 an argument to :func:`getrefcount`. 541 542 543 .. function:: getrecursionlimit() 544 545 Return the current value of the recursion limit, the maximum depth of the Python 546 interpreter stack. This limit prevents infinite recursion from causing an 547 overflow of the C stack and crashing Python. It can be set by 548 :func:`setrecursionlimit`. 549 550 551 .. function:: getsizeof(object[, default]) 552 553 Return the size of an object in bytes. The object can be any type of 554 object. All built-in objects will return correct results, but this 555 does not have to hold true for third-party extensions as it is implementation 556 specific. 557 558 Only the memory consumption directly attributed to the object is 559 accounted for, not the memory consumption of objects it refers to. 560 561 If given, *default* will be returned if the object does not provide means to 562 retrieve the size. Otherwise a :exc:`TypeError` will be raised. 563 564 :func:`getsizeof` calls the object's ``__sizeof__`` method and adds an 565 additional garbage collector overhead if the object is managed by the garbage 566 collector. 567 568 See `recursive sizeof recipe <https://code.activestate.com/recipes/577504>`_ 569 for an example of using :func:`getsizeof` recursively to find the size of 570 containers and all their contents. 571 572 .. function:: getswitchinterval() 573 574 Return the interpreter's "thread switch interval"; see 575 :func:`setswitchinterval`. 576 577 .. versionadded:: 3.2 578 579 580 .. function:: _getframe([depth]) 581 582 Return a frame object from the call stack. If optional integer *depth* is 583 given, return the frame object that many calls below the top of the stack. If 584 that is deeper than the call stack, :exc:`ValueError` is raised. The default 585 for *depth* is zero, returning the frame at the top of the call stack. 586 587 .. impl-detail:: 588 589 This function should be used for internal and specialized purposes only. 590 It is not guaranteed to exist in all implementations of Python. 591 592 593 .. function:: getprofile() 594 595 .. index:: 596 single: profile function 597 single: profiler 598 599 Get the profiler function as set by :func:`setprofile`. 600 601 602 .. function:: gettrace() 603 604 .. index:: 605 single: trace function 606 single: debugger 607 608 Get the trace function as set by :func:`settrace`. 609 610 .. impl-detail:: 611 612 The :func:`gettrace` function is intended only for implementing debuggers, 613 profilers, coverage tools and the like. Its behavior is part of the 614 implementation platform, rather than part of the language definition, and 615 thus may not be available in all Python implementations. 616 617 618 .. function:: getwindowsversion() 619 620 Return a named tuple describing the Windows version 621 currently running. The named elements are *major*, *minor*, 622 *build*, *platform*, *service_pack*, *service_pack_minor*, 623 *service_pack_major*, *suite_mask*, *product_type* and 624 *platform_version*. *service_pack* contains a string, 625 *platform_version* a 3-tuple and all other values are 626 integers. The components can also be accessed by name, so 627 ``sys.getwindowsversion()[0]`` is equivalent to 628 ``sys.getwindowsversion().major``. For compatibility with prior 629 versions, only the first 5 elements are retrievable by indexing. 630 631 *platform* will be :const:`2 (VER_PLATFORM_WIN32_NT)`. 632 633 *product_type* may be one of the following values: 634 635 +---------------------------------------+---------------------------------+ 636 | Constant | Meaning | 637 +=======================================+=================================+ 638 | :const:`1 (VER_NT_WORKSTATION)` | The system is a workstation. | 639 +---------------------------------------+---------------------------------+ 640 | :const:`2 (VER_NT_DOMAIN_CONTROLLER)` | The system is a domain | 641 | | controller. | 642 +---------------------------------------+---------------------------------+ 643 | :const:`3 (VER_NT_SERVER)` | The system is a server, but not | 644 | | a domain controller. | 645 +---------------------------------------+---------------------------------+ 646 647 This function wraps the Win32 :c:func:`GetVersionEx` function; see the 648 Microsoft documentation on :c:func:`OSVERSIONINFOEX` for more information 649 about these fields. 650 651 *platform_version* returns the accurate major version, minor version and 652 build number of the current operating system, rather than the version that 653 is being emulated for the process. It is intended for use in logging rather 654 than for feature detection. 655 656 .. availability:: Windows. 657 658 .. versionchanged:: 3.2 659 Changed to a named tuple and added *service_pack_minor*, 660 *service_pack_major*, *suite_mask*, and *product_type*. 661 662 .. versionchanged:: 3.6 663 Added *platform_version* 664 665 666 .. function:: get_asyncgen_hooks() 667 668 Returns an *asyncgen_hooks* object, which is similar to a 669 :class:`~collections.namedtuple` of the form `(firstiter, finalizer)`, 670 where *firstiter* and *finalizer* are expected to be either ``None`` or 671 functions which take an :term:`asynchronous generator iterator` as an 672 argument, and are used to schedule finalization of an asynchronous 673 generator by an event loop. 674 675 .. versionadded:: 3.6 676 See :pep:`525` for more details. 677 678 .. note:: 679 This function has been added on a provisional basis (see :pep:`411` 680 for details.) 681 682 683 .. function:: get_coroutine_origin_tracking_depth() 684 685 Get the current coroutine origin tracking depth, as set by 686 :func:`set_coroutine_origin_tracking_depth`. 687 688 .. versionadded:: 3.7 689 690 .. note:: 691 This function has been added on a provisional basis (see :pep:`411` 692 for details.) Use it only for debugging purposes. 693 694 695 .. function:: get_coroutine_wrapper() 696 697 Returns ``None``, or a wrapper set by :func:`set_coroutine_wrapper`. 698 699 .. versionadded:: 3.5 700 See :pep:`492` for more details. 701 702 .. note:: 703 This function has been added on a provisional basis (see :pep:`411` 704 for details.) Use it only for debugging purposes. 705 706 .. deprecated:: 3.7 707 The coroutine wrapper functionality has been deprecated, and 708 will be removed in 3.8. See :issue:`32591` for details. 709 710 711 .. data:: hash_info 712 713 A :term:`struct sequence` giving parameters of the numeric hash 714 implementation. For more details about hashing of numeric types, see 715 :ref:`numeric-hash`. 716 717 +---------------------+--------------------------------------------------+ 718 | attribute | explanation | 719 +=====================+==================================================+ 720 | :const:`width` | width in bits used for hash values | 721 +---------------------+--------------------------------------------------+ 722 | :const:`modulus` | prime modulus P used for numeric hash scheme | 723 +---------------------+--------------------------------------------------+ 724 | :const:`inf` | hash value returned for a positive infinity | 725 +---------------------+--------------------------------------------------+ 726 | :const:`nan` | hash value returned for a nan | 727 +---------------------+--------------------------------------------------+ 728 | :const:`imag` | multiplier used for the imaginary part of a | 729 | | complex number | 730 +---------------------+--------------------------------------------------+ 731 | :const:`algorithm` | name of the algorithm for hashing of str, bytes, | 732 | | and memoryview | 733 +---------------------+--------------------------------------------------+ 734 | :const:`hash_bits` | internal output size of the hash algorithm | 735 +---------------------+--------------------------------------------------+ 736 | :const:`seed_bits` | size of the seed key of the hash algorithm | 737 +---------------------+--------------------------------------------------+ 738 739 740 .. versionadded:: 3.2 741 742 .. versionchanged:: 3.4 743 Added *algorithm*, *hash_bits* and *seed_bits* 744 745 746 .. data:: hexversion 747 748 The version number encoded as a single integer. This is guaranteed to increase 749 with each version, including proper support for non-production releases. For 750 example, to test that the Python interpreter is at least version 1.5.2, use:: 751 752 if sys.hexversion >= 0x010502F0: 753 # use some advanced feature 754 ... 755 else: 756 # use an alternative implementation or warn the user 757 ... 758 759 This is called ``hexversion`` since it only really looks meaningful when viewed 760 as the result of passing it to the built-in :func:`hex` function. The 761 :term:`struct sequence` :data:`sys.version_info` may be used for a more 762 human-friendly encoding of the same information. 763 764 More details of ``hexversion`` can be found at :ref:`apiabiversion`. 765 766 767 .. data:: implementation 768 769 An object containing information about the implementation of the 770 currently running Python interpreter. The following attributes are 771 required to exist in all Python implementations. 772 773 *name* is the implementation's identifier, e.g. ``'cpython'``. The actual 774 string is defined by the Python implementation, but it is guaranteed to be 775 lower case. 776 777 *version* is a named tuple, in the same format as 778 :data:`sys.version_info`. It represents the version of the Python 779 *implementation*. This has a distinct meaning from the specific 780 version of the Python *language* to which the currently running 781 interpreter conforms, which ``sys.version_info`` represents. For 782 example, for PyPy 1.8 ``sys.implementation.version`` might be 783 ``sys.version_info(1, 8, 0, 'final', 0)``, whereas ``sys.version_info`` 784 would be ``sys.version_info(2, 7, 2, 'final', 0)``. For CPython they 785 are the same value, since it is the reference implementation. 786 787 *hexversion* is the implementation version in hexadecimal format, like 788 :data:`sys.hexversion`. 789 790 *cache_tag* is the tag used by the import machinery in the filenames of 791 cached modules. By convention, it would be a composite of the 792 implementation's name and version, like ``'cpython-33'``. However, a 793 Python implementation may use some other value if appropriate. If 794 ``cache_tag`` is set to ``None``, it indicates that module caching should 795 be disabled. 796 797 :data:`sys.implementation` may contain additional attributes specific to 798 the Python implementation. These non-standard attributes must start with 799 an underscore, and are not described here. Regardless of its contents, 800 :data:`sys.implementation` will not change during a run of the interpreter, 801 nor between implementation versions. (It may change between Python 802 language versions, however.) See :pep:`421` for more information. 803 804 .. versionadded:: 3.3 805 806 807 .. data:: int_info 808 809 A :term:`struct sequence` that holds information about Python's internal 810 representation of integers. The attributes are read only. 811 812 .. tabularcolumns:: |l|L| 813 814 +-------------------------+----------------------------------------------+ 815 | Attribute | Explanation | 816 +=========================+==============================================+ 817 | :const:`bits_per_digit` | number of bits held in each digit. Python | 818 | | integers are stored internally in base | 819 | | ``2**int_info.bits_per_digit`` | 820 +-------------------------+----------------------------------------------+ 821 | :const:`sizeof_digit` | size in bytes of the C type used to | 822 | | represent a digit | 823 +-------------------------+----------------------------------------------+ 824 825 .. versionadded:: 3.1 826 827 828 .. data:: __interactivehook__ 829 830 When this attribute exists, its value is automatically called (with no 831 arguments) when the interpreter is launched in :ref:`interactive mode 832 <tut-interactive>`. This is done after the :envvar:`PYTHONSTARTUP` file is 833 read, so that you can set this hook there. The :mod:`site` module 834 :ref:`sets this <rlcompleter-config>`. 835 836 .. versionadded:: 3.4 837 838 839 .. function:: intern(string) 840 841 Enter *string* in the table of "interned" strings and return the interned string 842 -- which is *string* itself or a copy. Interning strings is useful to gain a 843 little performance on dictionary lookup -- if the keys in a dictionary are 844 interned, and the lookup key is interned, the key comparisons (after hashing) 845 can be done by a pointer compare instead of a string compare. Normally, the 846 names used in Python programs are automatically interned, and the dictionaries 847 used to hold module, class or instance attributes have interned keys. 848 849 Interned strings are not immortal; you must keep a reference to the return 850 value of :func:`intern` around to benefit from it. 851 852 853 .. function:: is_finalizing() 854 855 Return :const:`True` if the Python interpreter is 856 :term:`shutting down <interpreter shutdown>`, :const:`False` otherwise. 857 858 .. versionadded:: 3.5 859 860 861 .. data:: last_type 862 last_value 863 last_traceback 864 865 These three variables are not always defined; they are set when an exception is 866 not handled and the interpreter prints an error message and a stack traceback. 867 Their intended use is to allow an interactive user to import a debugger module 868 and engage in post-mortem debugging without having to re-execute the command 869 that caused the error. (Typical use is ``import pdb; pdb.pm()`` to enter the 870 post-mortem debugger; see :mod:`pdb` module for 871 more information.) 872 873 The meaning of the variables is the same as that of the return values from 874 :func:`exc_info` above. 875 876 877 .. data:: maxsize 878 879 An integer giving the maximum value a variable of type :c:type:`Py_ssize_t` can 880 take. It's usually ``2**31 - 1`` on a 32-bit platform and ``2**63 - 1`` on a 881 64-bit platform. 882 883 884 .. data:: maxunicode 885 886 An integer giving the value of the largest Unicode code point, 887 i.e. ``1114111`` (``0x10FFFF`` in hexadecimal). 888 889 .. versionchanged:: 3.3 890 Before :pep:`393`, ``sys.maxunicode`` used to be either ``0xFFFF`` 891 or ``0x10FFFF``, depending on the configuration option that specified 892 whether Unicode characters were stored as UCS-2 or UCS-4. 893 894 895 .. data:: meta_path 896 897 A list of :term:`meta path finder` objects that have their 898 :meth:`~importlib.abc.MetaPathFinder.find_spec` methods called to see if one 899 of the objects can find the module to be imported. The 900 :meth:`~importlib.abc.MetaPathFinder.find_spec` method is called with at 901 least the absolute name of the module being imported. If the module to be 902 imported is contained in a package, then the parent package's :attr:`__path__` 903 attribute is passed in as a second argument. The method returns a 904 :term:`module spec`, or ``None`` if the module cannot be found. 905 906 .. seealso:: 907 908 :class:`importlib.abc.MetaPathFinder` 909 The abstract base class defining the interface of finder objects on 910 :data:`meta_path`. 911 :class:`importlib.machinery.ModuleSpec` 912 The concrete class which 913 :meth:`~importlib.abc.MetaPathFinder.find_spec` should return 914 instances of. 915 916 .. versionchanged:: 3.4 917 918 :term:`Module specs <module spec>` were introduced in Python 3.4, by 919 :pep:`451`. Earlier versions of Python looked for a method called 920 :meth:`~importlib.abc.MetaPathFinder.find_module`. 921 This is still called as a fallback if a :data:`meta_path` entry doesn't 922 have a :meth:`~importlib.abc.MetaPathFinder.find_spec` method. 923 924 .. data:: modules 925 926 This is a dictionary that maps module names to modules which have already been 927 loaded. This can be manipulated to force reloading of modules and other tricks. 928 However, replacing the dictionary will not necessarily work as expected and 929 deleting essential items from the dictionary may cause Python to fail. 930 931 932 .. data:: path 933 934 .. index:: triple: module; search; path 935 936 A list of strings that specifies the search path for modules. Initialized from 937 the environment variable :envvar:`PYTHONPATH`, plus an installation-dependent 938 default. 939 940 As initialized upon program startup, the first item of this list, ``path[0]``, 941 is the directory containing the script that was used to invoke the Python 942 interpreter. If the script directory is not available (e.g. if the interpreter 943 is invoked interactively or if the script is read from standard input), 944 ``path[0]`` is the empty string, which directs Python to search modules in the 945 current directory first. Notice that the script directory is inserted *before* 946 the entries inserted as a result of :envvar:`PYTHONPATH`. 947 948 A program is free to modify this list for its own purposes. Only strings 949 and bytes should be added to :data:`sys.path`; all other data types are 950 ignored during import. 951 952 953 .. seealso:: 954 Module :mod:`site` This describes how to use .pth files to extend 955 :data:`sys.path`. 956 957 958 .. data:: path_hooks 959 960 A list of callables that take a path argument to try to create a 961 :term:`finder` for the path. If a finder can be created, it is to be 962 returned by the callable, else raise :exc:`ImportError`. 963 964 Originally specified in :pep:`302`. 965 966 967 .. data:: path_importer_cache 968 969 A dictionary acting as a cache for :term:`finder` objects. The keys are 970 paths that have been passed to :data:`sys.path_hooks` and the values are 971 the finders that are found. If a path is a valid file system path but no 972 finder is found on :data:`sys.path_hooks` then ``None`` is 973 stored. 974 975 Originally specified in :pep:`302`. 976 977 .. versionchanged:: 3.3 978 ``None`` is stored instead of :class:`imp.NullImporter` when no finder 979 is found. 980 981 982 .. data:: platform 983 984 This string contains a platform identifier that can be used to append 985 platform-specific components to :data:`sys.path`, for instance. 986 987 For Unix systems, except on Linux, this is the lowercased OS name as 988 returned by ``uname -s`` with the first part of the version as returned by 989 ``uname -r`` appended, e.g. ``'sunos5'`` or ``'freebsd8'``, *at the time 990 when Python was built*. Unless you want to test for a specific system 991 version, it is therefore recommended to use the following idiom:: 992 993 if sys.platform.startswith('freebsd'): 994 # FreeBSD-specific code here... 995 elif sys.platform.startswith('linux'): 996 # Linux-specific code here... 997 998 For other systems, the values are: 999 1000 ================ =========================== 1001 System ``platform`` value 1002 ================ =========================== 1003 Linux ``'linux'`` 1004 Windows ``'win32'`` 1005 Windows/Cygwin ``'cygwin'`` 1006 Mac OS X ``'darwin'`` 1007 ================ =========================== 1008 1009 .. versionchanged:: 3.3 1010 On Linux, :attr:`sys.platform` doesn't contain the major version anymore. 1011 It is always ``'linux'``, instead of ``'linux2'`` or ``'linux3'``. Since 1012 older Python versions include the version number, it is recommended to 1013 always use the ``startswith`` idiom presented above. 1014 1015 .. seealso:: 1016 1017 :attr:`os.name` has a coarser granularity. :func:`os.uname` gives 1018 system-dependent version information. 1019 1020 The :mod:`platform` module provides detailed checks for the 1021 system's identity. 1022 1023 1024 .. data:: prefix 1025 1026 A string giving the site-specific directory prefix where the platform 1027 independent Python files are installed; by default, this is the string 1028 ``'/usr/local'``. This can be set at build time with the ``--prefix`` 1029 argument to the :program:`configure` script. The main collection of Python 1030 library modules is installed in the directory :file:`{prefix}/lib/python{X.Y}` 1031 while the platform independent header files (all except :file:`pyconfig.h`) are 1032 stored in :file:`{prefix}/include/python{X.Y}`, where *X.Y* is the version 1033 number of Python, for example ``3.2``. 1034 1035 .. note:: If a :ref:`virtual environment <venv-def>` is in effect, this 1036 value will be changed in ``site.py`` to point to the virtual 1037 environment. The value for the Python installation will still be 1038 available, via :data:`base_prefix`. 1039 1040 1041 .. data:: ps1 1042 ps2 1043 1044 .. index:: 1045 single: interpreter prompts 1046 single: prompts, interpreter 1047 single: >>>; interpreter prompt 1048 single: ...; interpreter prompt 1049 1050 Strings specifying the primary and secondary prompt of the interpreter. These 1051 are only defined if the interpreter is in interactive mode. Their initial 1052 values in this case are ``'>>> '`` and ``'... '``. If a non-string object is 1053 assigned to either variable, its :func:`str` is re-evaluated each time the 1054 interpreter prepares to read a new interactive command; this can be used to 1055 implement a dynamic prompt. 1056 1057 1058 .. function:: setcheckinterval(interval) 1059 1060 Set the interpreter's "check interval". This integer value determines how often 1061 the interpreter checks for periodic things such as thread switches and signal 1062 handlers. The default is ``100``, meaning the check is performed every 100 1063 Python virtual instructions. Setting it to a larger value may increase 1064 performance for programs using threads. Setting it to a value ``<=`` 0 checks 1065 every virtual instruction, maximizing responsiveness as well as overhead. 1066 1067 .. deprecated:: 3.2 1068 This function doesn't have an effect anymore, as the internal logic for 1069 thread switching and asynchronous tasks has been rewritten. Use 1070 :func:`setswitchinterval` instead. 1071 1072 1073 .. function:: setdlopenflags(n) 1074 1075 Set the flags used by the interpreter for :c:func:`dlopen` calls, such as when 1076 the interpreter loads extension modules. Among other things, this will enable a 1077 lazy resolving of symbols when importing a module, if called as 1078 ``sys.setdlopenflags(0)``. To share symbols across extension modules, call as 1079 ``sys.setdlopenflags(os.RTLD_GLOBAL)``. Symbolic names for the flag values 1080 can be found in the :mod:`os` module (``RTLD_xxx`` constants, e.g. 1081 :data:`os.RTLD_LAZY`). 1082 1083 .. availability:: Unix. 1084 1085 .. function:: setprofile(profilefunc) 1086 1087 .. index:: 1088 single: profile function 1089 single: profiler 1090 1091 Set the system's profile function, which allows you to implement a Python source 1092 code profiler in Python. See chapter :ref:`profile` for more information on the 1093 Python profiler. The system's profile function is called similarly to the 1094 system's trace function (see :func:`settrace`), but it is called with different events, 1095 for example it isn't called for each executed line of code (only on call and return, 1096 but the return event is reported even when an exception has been set). The function is 1097 thread-specific, but there is no way for the profiler to know about context switches between 1098 threads, so it does not make sense to use this in the presence of multiple threads. Also, 1099 its return value is not used, so it can simply return ``None``. Error in the profile 1100 function will cause itself unset. 1101 1102 Profile functions should have three arguments: *frame*, *event*, and 1103 *arg*. *frame* is the current stack frame. *event* is a string: ``'call'``, 1104 ``'return'``, ``'c_call'``, ``'c_return'``, or ``'c_exception'``. *arg* depends 1105 on the event type. 1106 1107 The events have the following meaning: 1108 1109 ``'call'`` 1110 A function is called (or some other code block entered). The 1111 profile function is called; *arg* is ``None``. 1112 1113 ``'return'`` 1114 A function (or other code block) is about to return. The profile 1115 function is called; *arg* is the value that will be returned, or ``None`` 1116 if the event is caused by an exception being raised. 1117 1118 ``'c_call'`` 1119 A C function is about to be called. This may be an extension function or 1120 a built-in. *arg* is the C function object. 1121 1122 ``'c_return'`` 1123 A C function has returned. *arg* is the C function object. 1124 1125 ``'c_exception'`` 1126 A C function has raised an exception. *arg* is the C function object. 1127 1128 .. function:: setrecursionlimit(limit) 1129 1130 Set the maximum depth of the Python interpreter stack to *limit*. This limit 1131 prevents infinite recursion from causing an overflow of the C stack and crashing 1132 Python. 1133 1134 The highest possible limit is platform-dependent. A user may need to set the 1135 limit higher when they have a program that requires deep recursion and a platform 1136 that supports a higher limit. This should be done with care, because a too-high 1137 limit can lead to a crash. 1138 1139 If the new limit is too low at the current recursion depth, a 1140 :exc:`RecursionError` exception is raised. 1141 1142 .. versionchanged:: 3.5.1 1143 A :exc:`RecursionError` exception is now raised if the new limit is too 1144 low at the current recursion depth. 1145 1146 1147 .. function:: setswitchinterval(interval) 1148 1149 Set the interpreter's thread switch interval (in seconds). This floating-point 1150 value determines the ideal duration of the "timeslices" allocated to 1151 concurrently running Python threads. Please note that the actual value 1152 can be higher, especially if long-running internal functions or methods 1153 are used. Also, which thread becomes scheduled at the end of the interval 1154 is the operating system's decision. The interpreter doesn't have its 1155 own scheduler. 1156 1157 .. versionadded:: 3.2 1158 1159 1160 .. function:: settrace(tracefunc) 1161 1162 .. index:: 1163 single: trace function 1164 single: debugger 1165 1166 Set the system's trace function, which allows you to implement a Python 1167 source code debugger in Python. The function is thread-specific; for a 1168 debugger to support multiple threads, it must be registered using 1169 :func:`settrace` for each thread being debugged. 1170 1171 Trace functions should have three arguments: *frame*, *event*, and 1172 *arg*. *frame* is the current stack frame. *event* is a string: ``'call'``, 1173 ``'line'``, ``'return'``, ``'exception'`` or ``'opcode'``. *arg* depends on 1174 the event type. 1175 1176 The trace function is invoked (with *event* set to ``'call'``) whenever a new 1177 local scope is entered; it should return a reference to a local trace 1178 function to be used that scope, or ``None`` if the scope shouldn't be traced. 1179 1180 The local trace function should return a reference to itself (or to another 1181 function for further tracing in that scope), or ``None`` to turn off tracing 1182 in that scope. 1183 1184 If there is any error occurred in the trace function, it will be unset, just 1185 like ``settrace(None)`` is called. 1186 1187 The events have the following meaning: 1188 1189 ``'call'`` 1190 A function is called (or some other code block entered). The 1191 global trace function is called; *arg* is ``None``; the return value 1192 specifies the local trace function. 1193 1194 ``'line'`` 1195 The interpreter is about to execute a new line of code or re-execute the 1196 condition of a loop. The local trace function is called; *arg* is 1197 ``None``; the return value specifies the new local trace function. See 1198 :file:`Objects/lnotab_notes.txt` for a detailed explanation of how this 1199 works. 1200 Per-line events may be disabled for a frame by setting 1201 :attr:`f_trace_lines` to :const:`False` on that frame. 1202 1203 ``'return'`` 1204 A function (or other code block) is about to return. The local trace 1205 function is called; *arg* is the value that will be returned, or ``None`` 1206 if the event is caused by an exception being raised. The trace function's 1207 return value is ignored. 1208 1209 ``'exception'`` 1210 An exception has occurred. The local trace function is called; *arg* is a 1211 tuple ``(exception, value, traceback)``; the return value specifies the 1212 new local trace function. 1213 1214 ``'opcode'`` 1215 The interpreter is about to execute a new opcode (see :mod:`dis` for 1216 opcode details). The local trace function is called; *arg* is 1217 ``None``; the return value specifies the new local trace function. 1218 Per-opcode events are not emitted by default: they must be explicitly 1219 requested by setting :attr:`f_trace_opcodes` to :const:`True` on the 1220 frame. 1221 1222 Note that as an exception is propagated down the chain of callers, an 1223 ``'exception'`` event is generated at each level. 1224 1225 For more information on code and frame objects, refer to :ref:`types`. 1226 1227 .. impl-detail:: 1228 1229 The :func:`settrace` function is intended only for implementing debuggers, 1230 profilers, coverage tools and the like. Its behavior is part of the 1231 implementation platform, rather than part of the language definition, and 1232 thus may not be available in all Python implementations. 1233 1234 .. versionchanged:: 3.7 1235 1236 ``'opcode'`` event type added; :attr:`f_trace_lines` and 1237 :attr:`f_trace_opcodes` attributes added to frames 1238 1239 .. function:: set_asyncgen_hooks(firstiter, finalizer) 1240 1241 Accepts two optional keyword arguments which are callables that accept an 1242 :term:`asynchronous generator iterator` as an argument. The *firstiter* 1243 callable will be called when an asynchronous generator is iterated for the 1244 first time. The *finalizer* will be called when an asynchronous generator 1245 is about to be garbage collected. 1246 1247 .. versionadded:: 3.6 1248 See :pep:`525` for more details, and for a reference example of a 1249 *finalizer* method see the implementation of 1250 ``asyncio.Loop.shutdown_asyncgens`` in 1251 :source:`Lib/asyncio/base_events.py` 1252 1253 .. note:: 1254 This function has been added on a provisional basis (see :pep:`411` 1255 for details.) 1256 1257 .. function:: set_coroutine_origin_tracking_depth(depth) 1258 1259 Allows enabling or disabling coroutine origin tracking. When 1260 enabled, the ``cr_origin`` attribute on coroutine objects will 1261 contain a tuple of (filename, line number, function name) tuples 1262 describing the traceback where the coroutine object was created, 1263 with the most recent call first. When disabled, ``cr_origin`` will 1264 be None. 1265 1266 To enable, pass a *depth* value greater than zero; this sets the 1267 number of frames whose information will be captured. To disable, 1268 pass set *depth* to zero. 1269 1270 This setting is thread-specific. 1271 1272 .. versionadded:: 3.7 1273 1274 .. note:: 1275 This function has been added on a provisional basis (see :pep:`411` 1276 for details.) Use it only for debugging purposes. 1277 1278 .. function:: set_coroutine_wrapper(wrapper) 1279 1280 Allows intercepting creation of :term:`coroutine` objects (only ones that 1281 are created by an :keyword:`async def` function; generators decorated with 1282 :func:`types.coroutine` or :func:`asyncio.coroutine` will not be 1283 intercepted). 1284 1285 The *wrapper* argument must be either: 1286 1287 * a callable that accepts one argument (a coroutine object); 1288 * ``None``, to reset the wrapper. 1289 1290 If called twice, the new wrapper replaces the previous one. The function 1291 is thread-specific. 1292 1293 The *wrapper* callable cannot define new coroutines directly or indirectly:: 1294 1295 def wrapper(coro): 1296 async def wrap(coro): 1297 return await coro 1298 return wrap(coro) 1299 sys.set_coroutine_wrapper(wrapper) 1300 1301 async def foo(): 1302 pass 1303 1304 # The following line will fail with a RuntimeError, because 1305 # ``wrapper`` creates a ``wrap(coro)`` coroutine: 1306 foo() 1307 1308 See also :func:`get_coroutine_wrapper`. 1309 1310 .. versionadded:: 3.5 1311 See :pep:`492` for more details. 1312 1313 .. note:: 1314 This function has been added on a provisional basis (see :pep:`411` 1315 for details.) Use it only for debugging purposes. 1316 1317 .. deprecated:: 3.7 1318 The coroutine wrapper functionality has been deprecated, and 1319 will be removed in 3.8. See :issue:`32591` for details. 1320 1321 .. function:: _enablelegacywindowsfsencoding() 1322 1323 Changes the default filesystem encoding and errors mode to 'mbcs' and 1324 'replace' respectively, for consistency with versions of Python prior to 3.6. 1325 1326 This is equivalent to defining the :envvar:`PYTHONLEGACYWINDOWSFSENCODING` 1327 environment variable before launching Python. 1328 1329 .. availability:: Windows. 1330 1331 .. versionadded:: 3.6 1332 See :pep:`529` for more details. 1333 1334 .. data:: stdin 1335 stdout 1336 stderr 1337 1338 :term:`File objects <file object>` used by the interpreter for standard 1339 input, output and errors: 1340 1341 * ``stdin`` is used for all interactive input (including calls to 1342 :func:`input`); 1343 * ``stdout`` is used for the output of :func:`print` and :term:`expression` 1344 statements and for the prompts of :func:`input`; 1345 * The interpreter's own prompts and its error messages go to ``stderr``. 1346 1347 These streams are regular :term:`text files <text file>` like those 1348 returned by the :func:`open` function. Their parameters are chosen as 1349 follows: 1350 1351 * The character encoding is platform-dependent. Non-Windows 1352 platforms use the locale encoding (see 1353 :meth:`locale.getpreferredencoding()`). 1354 1355 On Windows, UTF-8 is used for the console device. Non-character 1356 devices such as disk files and pipes use the system locale 1357 encoding (i.e. the ANSI codepage). Non-console character 1358 devices such as NUL (i.e. where isatty() returns True) use the 1359 value of the console input and output codepages at startup, 1360 respectively for stdin and stdout/stderr. This defaults to the 1361 system locale encoding if the process is not initially attached 1362 to a console. 1363 1364 The special behaviour of the console can be overridden 1365 by setting the environment variable PYTHONLEGACYWINDOWSSTDIO 1366 before starting Python. In that case, the console codepages are 1367 used as for any other character device. 1368 1369 Under all platforms, you can override the character encoding by 1370 setting the :envvar:`PYTHONIOENCODING` environment variable before 1371 starting Python or by using the new :option:`-X` ``utf8`` command 1372 line option and :envvar:`PYTHONUTF8` environment variable. However, 1373 for the Windows console, this only applies when 1374 :envvar:`PYTHONLEGACYWINDOWSSTDIO` is also set. 1375 1376 * When interactive, ``stdout`` and ``stderr`` streams are line-buffered. 1377 Otherwise, they are block-buffered like regular text files. You can 1378 override this value with the :option:`-u` command-line option. 1379 1380 .. note:: 1381 1382 To write or read binary data from/to the standard streams, use the 1383 underlying binary :data:`~io.TextIOBase.buffer` object. For example, to 1384 write bytes to :data:`stdout`, use ``sys.stdout.buffer.write(b'abc')``. 1385 1386 However, if you are writing a library (and do not control in which 1387 context its code will be executed), be aware that the standard streams 1388 may be replaced with file-like objects like :class:`io.StringIO` which 1389 do not support the :attr:`~io.BufferedIOBase.buffer` attribute. 1390 1391 1392 .. data:: __stdin__ 1393 __stdout__ 1394 __stderr__ 1395 1396 These objects contain the original values of ``stdin``, ``stderr`` and 1397 ``stdout`` at the start of the program. They are used during finalization, 1398 and could be useful to print to the actual standard stream no matter if the 1399 ``sys.std*`` object has been redirected. 1400 1401 It can also be used to restore the actual files to known working file objects 1402 in case they have been overwritten with a broken object. However, the 1403 preferred way to do this is to explicitly save the previous stream before 1404 replacing it, and restore the saved object. 1405 1406 .. note:: 1407 Under some conditions ``stdin``, ``stdout`` and ``stderr`` as well as the 1408 original values ``__stdin__``, ``__stdout__`` and ``__stderr__`` can be 1409 ``None``. It is usually the case for Windows GUI apps that aren't connected 1410 to a console and Python apps started with :program:`pythonw`. 1411 1412 1413 .. data:: thread_info 1414 1415 A :term:`struct sequence` holding information about the thread 1416 implementation. 1417 1418 .. tabularcolumns:: |l|p{0.7\linewidth}| 1419 1420 +------------------+---------------------------------------------------------+ 1421 | Attribute | Explanation | 1422 +==================+=========================================================+ 1423 | :const:`name` | Name of the thread implementation: | 1424 | | | 1425 | | * ``'nt'``: Windows threads | 1426 | | * ``'pthread'``: POSIX threads | 1427 | | * ``'solaris'``: Solaris threads | 1428 +------------------+---------------------------------------------------------+ 1429 | :const:`lock` | Name of the lock implementation: | 1430 | | | 1431 | | * ``'semaphore'``: a lock uses a semaphore | 1432 | | * ``'mutex+cond'``: a lock uses a mutex | 1433 | | and a condition variable | 1434 | | * ``None`` if this information is unknown | 1435 +------------------+---------------------------------------------------------+ 1436 | :const:`version` | Name and version of the thread library. It is a string, | 1437 | | or ``None`` if this information is unknown. | 1438 +------------------+---------------------------------------------------------+ 1439 1440 .. versionadded:: 3.3 1441 1442 1443 .. data:: tracebacklimit 1444 1445 When this variable is set to an integer value, it determines the maximum number 1446 of levels of traceback information printed when an unhandled exception occurs. 1447 The default is ``1000``. When set to ``0`` or less, all traceback information 1448 is suppressed and only the exception type and value are printed. 1449 1450 1451 .. data:: version 1452 1453 A string containing the version number of the Python interpreter plus additional 1454 information on the build number and compiler used. This string is displayed 1455 when the interactive interpreter is started. Do not extract version information 1456 out of it, rather, use :data:`version_info` and the functions provided by the 1457 :mod:`platform` module. 1458 1459 1460 .. data:: api_version 1461 1462 The C API version for this interpreter. Programmers may find this useful when 1463 debugging version conflicts between Python and extension modules. 1464 1465 1466 .. data:: version_info 1467 1468 A tuple containing the five components of the version number: *major*, *minor*, 1469 *micro*, *releaselevel*, and *serial*. All values except *releaselevel* are 1470 integers; the release level is ``'alpha'``, ``'beta'``, ``'candidate'``, or 1471 ``'final'``. The ``version_info`` value corresponding to the Python version 2.0 1472 is ``(2, 0, 0, 'final', 0)``. The components can also be accessed by name, 1473 so ``sys.version_info[0]`` is equivalent to ``sys.version_info.major`` 1474 and so on. 1475 1476 .. versionchanged:: 3.1 1477 Added named component attributes. 1478 1479 .. data:: warnoptions 1480 1481 This is an implementation detail of the warnings framework; do not modify this 1482 value. Refer to the :mod:`warnings` module for more information on the warnings 1483 framework. 1484 1485 1486 .. data:: winver 1487 1488 The version number used to form registry keys on Windows platforms. This is 1489 stored as string resource 1000 in the Python DLL. The value is normally the 1490 first three characters of :const:`version`. It is provided in the :mod:`sys` 1491 module for informational purposes; modifying this value has no effect on the 1492 registry keys used by Python. 1493 1494 .. availability:: Windows. 1495 1496 1497 .. data:: _xoptions 1498 1499 A dictionary of the various implementation-specific flags passed through 1500 the :option:`-X` command-line option. Option names are either mapped to 1501 their values, if given explicitly, or to :const:`True`. Example: 1502 1503 .. code-block:: shell-session 1504 1505 $ ./python -Xa=b -Xc 1506 Python 3.2a3+ (py3k, Oct 16 2010, 20:14:50) 1507 [GCC 4.4.3] on linux2 1508 Type "help", "copyright", "credits" or "license" for more information. 1509 >>> import sys 1510 >>> sys._xoptions 1511 {'a': 'b', 'c': True} 1512 1513 .. impl-detail:: 1514 1515 This is a CPython-specific way of accessing options passed through 1516 :option:`-X`. Other implementations may export them through other 1517 means, or not at all. 1518 1519 .. versionadded:: 3.2 1520 1521 1522 .. rubric:: Citations 1523 1524 .. [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\ . 1525
