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