1
:mod:`sys` --- System-specific parameters and functions
2
=======================================================
5
:synopsis: Access system-specific parameters and functions.
8
This module provides access to some variables used or maintained by the
9
interpreter and to functions that interact strongly with the interpreter. It is
15
On POSIX systems where Python is build with the standard ``configure``
16
script, this contains the ABI flags as specified by :pep:`3149`.
22
The list of command line arguments passed to a Python script. ``argv[0]`` is the
23
script name (it is operating system dependent whether this is a full pathname or
24
not). If the command was executed using the :option:`-c` command line option to
25
the interpreter, ``argv[0]`` is set to the string ``'-c'``. If no script name
26
was passed to the Python interpreter, ``argv[0]`` is the empty string.
28
To loop over the standard input, or the list of files given on the
29
command line, see the :mod:`fileinput` module.
32
.. data:: base_exec_prefix
34
Set during Python startup, before ``site.py`` is run, to the same value as
35
:data:`exec_prefix`. If not running in a
36
:ref:`virtual environment <venv-def>`, the values will stay the same; if
37
``site.py`` finds that a virtual environment is in use, the values of
38
:data:`prefix` and :data:`exec_prefix` will be changed to point to the
39
virtual environment, whereas :data:`base_prefix` and
40
:data:`base_exec_prefix` will remain pointing to the base Python
41
installation (the one which the virtual environment was created from).
48
Set during Python startup, before ``site.py`` is run, to the same value as
49
:data:`prefix`. If not running in a :ref:`virtual environment <venv-def>`, the values
50
will stay the same; if ``site.py`` finds that a virtual environment is in
51
use, the values of :data:`prefix` and :data:`exec_prefix` will be changed to
52
point to the virtual environment, whereas :data:`base_prefix` and
53
:data:`base_exec_prefix` will remain pointing to the base Python
54
installation (the one which the virtual environment was created from).
61
An indicator of the native byte order. This will have the value ``'big'`` on
62
big-endian (most-significant byte first) platforms, and ``'little'`` on
63
little-endian (least-significant byte first) platforms.
66
.. data:: builtin_module_names
68
A tuple of strings giving the names of all modules that are compiled into this
69
Python interpreter. (This information is not available in any other way ---
70
``modules.keys()`` only lists the imported modules.)
73
.. function:: call_tracing(func, args)
75
Call ``func(*args)``, while tracing is enabled. The tracing state is saved,
76
and restored afterwards. This is intended to be called from a debugger from
77
a checkpoint, to recursively debug some other code.
82
A string containing the copyright pertaining to the Python interpreter.
85
.. function:: _clear_type_cache()
87
Clear the internal type cache. The type cache is used to speed up attribute
88
and method lookups. Use the function *only* to drop unnecessary references
89
during reference leak debugging.
91
This function should be used for internal and specialized purposes only.
94
.. function:: _current_frames()
96
Return a dictionary mapping each thread's identifier to the topmost stack frame
97
currently active in that thread at the time the function is called. Note that
98
functions in the :mod:`traceback` module can build the call stack given such a
101
This is most useful for debugging deadlock: this function does not require the
102
deadlocked threads' cooperation, and such threads' call stacks are frozen for as
103
long as they remain deadlocked. The frame returned for a non-deadlocked thread
104
may bear no relationship to that thread's current activity by the time calling
105
code examines the frame.
107
This function should be used for internal and specialized purposes only.
110
.. function:: _debugmallocstats()
112
Print low-level information to stderr about the state of CPython's memory
115
If Python is configured --with-pydebug, it also performs some expensive
116
internal consistency checks.
118
.. versionadded:: 3.3
122
This function is specific to CPython. The exact output format is not
123
defined here, and may change.
128
Integer specifying the handle of the Python DLL. Availability: Windows.
131
.. function:: displayhook(value)
133
If *value* is not ``None``, this function prints ``repr(value)`` to
134
``sys.stdout``, and saves *value* in ``builtins._``. If ``repr(value)`` is
135
not encodable to ``sys.stdout.encoding`` with ``sys.stdout.errors`` error
136
handler (which is probably ``'strict'``), encode it to
137
``sys.stdout.encoding`` with ``'backslashreplace'`` error handler.
139
``sys.displayhook`` is called on the result of evaluating an :term:`expression`
140
entered in an interactive Python session. The display of these values can be
141
customized by assigning another one-argument function to ``sys.displayhook``.
145
def displayhook(value):
148
# Set '_' to None to avoid recursion
152
sys.stdout.write(text)
153
except UnicodeEncodeError:
154
bytes = text.encode(sys.stdout.encoding, 'backslashreplace')
155
if hasattr(sys.stdout, 'buffer'):
156
sys.stdout.buffer.write(bytes)
158
text = bytes.decode(sys.stdout.encoding, 'strict')
159
sys.stdout.write(text)
160
sys.stdout.write("\n")
163
.. versionchanged:: 3.2
164
Use ``'backslashreplace'`` error handler on :exc:`UnicodeEncodeError`.
167
.. data:: dont_write_bytecode
169
If this is true, Python won't try to write ``.pyc`` or ``.pyo`` files on the
170
import of source modules. This value is initially set to ``True`` or
171
``False`` depending on the :option:`-B` command line option and the
172
:envvar:`PYTHONDONTWRITEBYTECODE` environment variable, but you can set it
173
yourself to control bytecode file generation.
176
.. function:: excepthook(type, value, traceback)
178
This function prints out a given traceback and exception to ``sys.stderr``.
180
When an exception is raised and uncaught, the interpreter calls
181
``sys.excepthook`` with three arguments, the exception class, exception
182
instance, and a traceback object. In an interactive session this happens just
183
before control is returned to the prompt; in a Python program this happens just
184
before the program exits. The handling of such top-level exceptions can be
185
customized by assigning another three-argument function to ``sys.excepthook``.
188
.. data:: __displayhook__
191
These objects contain the original values of ``displayhook`` and ``excepthook``
192
at the start of the program. They are saved so that ``displayhook`` and
193
``excepthook`` can be restored in case they happen to get replaced with broken
197
.. function:: exc_info()
199
This function returns a tuple of three values that give information about the
200
exception that is currently being handled. The information returned is specific
201
both to the current thread and to the current stack frame. If the current stack
202
frame is not handling an exception, the information is taken from the calling
203
stack frame, or its caller, and so on until a stack frame is found that is
204
handling an exception. Here, "handling an exception" is defined as "executing
205
an except clause." For any stack frame, only information about the exception
206
being currently handled is accessible.
208
.. index:: object: traceback
210
If no exception is being handled anywhere on the stack, a tuple containing
211
three ``None`` values is returned. Otherwise, the values returned are
212
``(type, value, traceback)``. Their meaning is: *type* gets the type of the
213
exception being handled (a subclass of :exc:`BaseException`); *value* gets
214
the exception instance (an instance of the exception type); *traceback* gets
215
a traceback object (see the Reference Manual) which encapsulates the call
216
stack at the point where the exception originally occurred.
219
.. data:: exec_prefix
221
A string giving the site-specific directory prefix where the platform-dependent
222
Python files are installed; by default, this is also ``'/usr/local'``. This can
223
be set at build time with the ``--exec-prefix`` argument to the
224
:program:`configure` script. Specifically, all configuration files (e.g. the
225
:file:`pyconfig.h` header file) are installed in the directory
226
:file:`{exec_prefix}/lib/python{X.Y}/config`, and shared library modules are
227
installed in :file:`{exec_prefix}/lib/python{X.Y}/lib-dynload`, where *X.Y*
228
is the version number of Python, for example ``3.2``.
230
.. note:: If a :ref:`virtual environment <venv-def>` is in effect, this
231
value will be changed in ``site.py`` to point to the virtual environment.
232
The value for the Python installation will still be available, via
233
:data:`base_exec_prefix`.
238
A string giving the absolute path of the executable binary for the Python
239
interpreter, on systems where this makes sense. If Python is unable to retrieve
240
the real path to its executable, :data:`sys.executable` will be an empty string
244
.. function:: exit([arg])
246
Exit from Python. This is implemented by raising the :exc:`SystemExit`
247
exception, so cleanup actions specified by finally clauses of :keyword:`try`
248
statements are honored, and it is possible to intercept the exit attempt at
251
The optional argument *arg* can be an integer giving the exit status
252
(defaulting to zero), or another type of object. If it is an integer, zero
253
is considered "successful termination" and any nonzero value is considered
254
"abnormal termination" by shells and the like. Most systems require it to be
255
in the range 0-127, and produce undefined results otherwise. Some systems
256
have a convention for assigning specific meanings to specific exit codes, but
257
these are generally underdeveloped; Unix programs generally use 2 for command
258
line syntax errors and 1 for all other kind of errors. If another type of
259
object is passed, ``None`` is equivalent to passing zero, and any other
260
object is printed to :data:`stderr` and results in an exit code of 1. In
261
particular, ``sys.exit("some error message")`` is a quick way to exit a
262
program when an error occurs.
264
Since :func:`exit` ultimately "only" raises an exception, it will only exit
265
the process when called from the main thread, and the exception is not
271
The :term:`struct sequence` *flags* exposes the status of command line
272
flags. The attributes are read only.
274
============================= =============================
276
============================= =============================
277
:const:`debug` :option:`-d`
278
:const:`inspect` :option:`-i`
279
:const:`interactive` :option:`-i`
280
:const:`optimize` :option:`-O` or :option:`-OO`
281
:const:`dont_write_bytecode` :option:`-B`
282
:const:`no_user_site` :option:`-s`
283
:const:`no_site` :option:`-S`
284
:const:`ignore_environment` :option:`-E`
285
:const:`verbose` :option:`-v`
286
:const:`bytes_warning` :option:`-b`
287
:const:`quiet` :option:`-q`
288
:const:`hash_randomization` :option:`-R`
289
============================= =============================
291
.. versionchanged:: 3.2
292
Added ``quiet`` attribute for the new :option:`-q` flag.
294
.. versionadded:: 3.2.3
295
The ``hash_randomization`` attribute.
297
.. versionchanged:: 3.3
298
Removed obsolete ``division_warning`` attribute.
303
A :term:`struct sequence` holding information about the float type. It
304
contains low level information about the precision and internal
305
representation. The values correspond to the various floating-point
306
constants defined in the standard header file :file:`float.h` for the 'C'
307
programming language; see section 5.2.4.2.2 of the 1999 ISO/IEC C standard
308
[C99]_, 'Characteristics of floating types', for details.
310
.. tabularcolumns:: |l|l|L|
312
+---------------------+----------------+--------------------------------------------------+
313
| attribute | float.h macro | explanation |
314
+=====================+================+==================================================+
315
| :const:`epsilon` | DBL_EPSILON | difference between 1 and the least value greater |
316
| | | than 1 that is representable as a float |
317
+---------------------+----------------+--------------------------------------------------+
318
| :const:`dig` | DBL_DIG | maximum number of decimal digits that can be |
319
| | | faithfully represented in a float; see below |
320
+---------------------+----------------+--------------------------------------------------+
321
| :const:`mant_dig` | DBL_MANT_DIG | float precision: the number of base-``radix`` |
322
| | | digits in the significand of a float |
323
+---------------------+----------------+--------------------------------------------------+
324
| :const:`max` | DBL_MAX | maximum representable finite float |
325
+---------------------+----------------+--------------------------------------------------+
326
| :const:`max_exp` | DBL_MAX_EXP | maximum integer e such that ``radix**(e-1)`` is |
327
| | | a representable finite float |
328
+---------------------+----------------+--------------------------------------------------+
329
| :const:`max_10_exp` | DBL_MAX_10_EXP | maximum integer e such that ``10**e`` is in the |
330
| | | range of representable finite floats |
331
+---------------------+----------------+--------------------------------------------------+
332
| :const:`min` | DBL_MIN | minimum positive normalized float |
333
+---------------------+----------------+--------------------------------------------------+
334
| :const:`min_exp` | DBL_MIN_EXP | minimum integer e such that ``radix**(e-1)`` is |
335
| | | a normalized float |
336
+---------------------+----------------+--------------------------------------------------+
337
| :const:`min_10_exp` | DBL_MIN_10_EXP | minimum integer e such that ``10**e`` is a |
338
| | | normalized float |
339
+---------------------+----------------+--------------------------------------------------+
340
| :const:`radix` | FLT_RADIX | radix of exponent representation |
341
+---------------------+----------------+--------------------------------------------------+
342
| :const:`rounds` | FLT_ROUNDS | integer constant representing the rounding mode |
343
| | | used for arithmetic operations. This reflects |
344
| | | the value of the system FLT_ROUNDS macro at |
345
| | | interpreter startup time. See section 5.2.4.2.2 |
346
| | | of the C99 standard for an explanation of the |
347
| | | possible values and their meanings. |
348
+---------------------+----------------+--------------------------------------------------+
350
The attribute :attr:`sys.float_info.dig` needs further explanation. If
351
``s`` is any string representing a decimal number with at most
352
:attr:`sys.float_info.dig` significant digits, then converting ``s`` to a
353
float and back again will recover a string representing the same decimal
357
>>> sys.float_info.dig
359
>>> s = '3.14159265358979' # decimal string with 15 significant digits
360
>>> format(float(s), '.15g') # convert to float and back -> same value
363
But for strings with more than :attr:`sys.float_info.dig` significant digits,
364
this isn't always true::
366
>>> s = '9876543211234567' # 16 significant digits is too many!
367
>>> format(float(s), '.16g') # conversion changes value
370
.. data:: float_repr_style
372
A string indicating how the :func:`repr` function behaves for
373
floats. If the string has value ``'short'`` then for a finite
374
float ``x``, ``repr(x)`` aims to produce a short string with the
375
property that ``float(repr(x)) == x``. This is the usual behaviour
376
in Python 3.1 and later. Otherwise, ``float_repr_style`` has value
377
``'legacy'`` and ``repr(x)`` behaves in the same way as it did in
378
versions of Python prior to 3.1.
380
.. versionadded:: 3.1
383
.. function:: getallocatedblocks()
385
Return the number of memory blocks currently allocated by the interpreter,
386
regardless of their size. This function is mainly useful for tracking
387
and debugging memory leaks. Because of the interpreter's internal
388
caches, the result can vary from call to call; you may have to call
389
:func:`_clear_type_cache()` and :func:`gc.collect()` to get more
392
If a Python build or implementation cannot reasonably compute this
393
information, :func:`getallocatedblocks()` is allowed to return 0 instead.
395
.. versionadded:: 3.4
398
.. function:: getcheckinterval()
400
Return the interpreter's "check interval"; see :func:`setcheckinterval`.
403
Use :func:`getswitchinterval` instead.
406
.. function:: getdefaultencoding()
408
Return the name of the current default string encoding used by the Unicode
412
.. function:: getdlopenflags()
414
Return the current value of the flags that are used for
415
:c:func:`dlopen` calls. Symbolic names for the flag values can be
416
found in the :mod:`os` module (``RTLD_xxx`` constants, e.g.
417
:data:`os.RTLD_LAZY`). Availability: Unix.
420
.. function:: getfilesystemencoding()
422
Return the name of the encoding used to convert Unicode filenames into
423
system file names. The result value depends on the operating system:
425
* On Mac OS X, the encoding is ``'utf-8'``.
427
* On Unix, the encoding is the user's preference according to the result of
428
nl_langinfo(CODESET), or ``'utf-8'`` if ``nl_langinfo(CODESET)`` failed.
430
* On Windows NT+, file names are Unicode natively, so no conversion is
431
performed. :func:`getfilesystemencoding` still returns ``'mbcs'``, as
432
this is the encoding that applications should use when they explicitly
433
want to convert Unicode strings to byte strings that are equivalent when
436
* On Windows 9x, the encoding is ``'mbcs'``.
438
.. versionchanged:: 3.2
439
On Unix, use ``'utf-8'`` instead of ``None`` if ``nl_langinfo(CODESET)``
440
failed. :func:`getfilesystemencoding` result cannot be ``None``.
443
.. function:: getrefcount(object)
445
Return the reference count of the *object*. The count returned is generally one
446
higher than you might expect, because it includes the (temporary) reference as
447
an argument to :func:`getrefcount`.
450
.. function:: getrecursionlimit()
452
Return the current value of the recursion limit, the maximum depth of the Python
453
interpreter stack. This limit prevents infinite recursion from causing an
454
overflow of the C stack and crashing Python. It can be set by
455
:func:`setrecursionlimit`.
458
.. function:: getsizeof(object[, default])
460
Return the size of an object in bytes. The object can be any type of
461
object. All built-in objects will return correct results, but this
462
does not have to hold true for third-party extensions as it is implementation
465
Only the memory consumption directly attributed to the object is
466
accounted for, not the memory consumption of objects it refers to.
468
If given, *default* will be returned if the object does not provide means to
469
retrieve the size. Otherwise a :exc:`TypeError` will be raised.
471
:func:`getsizeof` calls the object's ``__sizeof__`` method and adds an
472
additional garbage collector overhead if the object is managed by the garbage
475
See `recursive sizeof recipe <http://code.activestate.com/recipes/577504>`_
476
for an example of using :func:`getsizeof` recursively to find the size of
477
containers and all their contents.
479
.. function:: getswitchinterval()
481
Return the interpreter's "thread switch interval"; see
482
:func:`setswitchinterval`.
484
.. versionadded:: 3.2
487
.. function:: _getframe([depth])
489
Return a frame object from the call stack. If optional integer *depth* is
490
given, return the frame object that many calls below the top of the stack. If
491
that is deeper than the call stack, :exc:`ValueError` is raised. The default
492
for *depth* is zero, returning the frame at the top of the call stack.
496
This function should be used for internal and specialized purposes only.
497
It is not guaranteed to exist in all implementations of Python.
500
.. function:: getprofile()
503
single: profile function
506
Get the profiler function as set by :func:`setprofile`.
509
.. function:: gettrace()
512
single: trace function
515
Get the trace function as set by :func:`settrace`.
519
The :func:`gettrace` function is intended only for implementing debuggers,
520
profilers, coverage tools and the like. Its behavior is part of the
521
implementation platform, rather than part of the language definition, and
522
thus may not be available in all Python implementations.
525
.. function:: getwindowsversion()
527
Return a named tuple describing the Windows version
528
currently running. The named elements are *major*, *minor*,
529
*build*, *platform*, *service_pack*, *service_pack_minor*,
530
*service_pack_major*, *suite_mask*, and *product_type*.
531
*service_pack* contains a string while all other values are
532
integers. The components can also be accessed by name, so
533
``sys.getwindowsversion()[0]`` is equivalent to
534
``sys.getwindowsversion().major``. For compatibility with prior
535
versions, only the first 5 elements are retrievable by indexing.
537
*platform* may be one of the following values:
539
+-----------------------------------------+-------------------------+
540
| Constant | Platform |
541
+=========================================+=========================+
542
| :const:`0 (VER_PLATFORM_WIN32s)` | Win32s on Windows 3.1 |
543
+-----------------------------------------+-------------------------+
544
| :const:`1 (VER_PLATFORM_WIN32_WINDOWS)` | Windows 95/98/ME |
545
+-----------------------------------------+-------------------------+
546
| :const:`2 (VER_PLATFORM_WIN32_NT)` | Windows NT/2000/XP/x64 |
547
+-----------------------------------------+-------------------------+
548
| :const:`3 (VER_PLATFORM_WIN32_CE)` | Windows CE |
549
+-----------------------------------------+-------------------------+
551
*product_type* may be one of the following values:
553
+---------------------------------------+---------------------------------+
554
| Constant | Meaning |
555
+=======================================+=================================+
556
| :const:`1 (VER_NT_WORKSTATION)` | The system is a workstation. |
557
+---------------------------------------+---------------------------------+
558
| :const:`2 (VER_NT_DOMAIN_CONTROLLER)` | The system is a domain |
560
+---------------------------------------+---------------------------------+
561
| :const:`3 (VER_NT_SERVER)` | The system is a server, but not |
562
| | a domain controller. |
563
+---------------------------------------+---------------------------------+
566
This function wraps the Win32 :c:func:`GetVersionEx` function; see the
567
Microsoft documentation on :c:func:`OSVERSIONINFOEX` for more information
570
Availability: Windows.
572
.. versionchanged:: 3.2
573
Changed to a named tuple and added *service_pack_minor*,
574
*service_pack_major*, *suite_mask*, and *product_type*.
579
A :term:`struct sequence` giving parameters of the numeric hash
580
implementation. For more details about hashing of numeric types, see
583
+---------------------+--------------------------------------------------+
584
| attribute | explanation |
585
+=====================+==================================================+
586
| :const:`width` | width in bits used for hash values |
587
+---------------------+--------------------------------------------------+
588
| :const:`modulus` | prime modulus P used for numeric hash scheme |
589
+---------------------+--------------------------------------------------+
590
| :const:`inf` | hash value returned for a positive infinity |
591
+---------------------+--------------------------------------------------+
592
| :const:`nan` | hash value returned for a nan |
593
+---------------------+--------------------------------------------------+
594
| :const:`imag` | multiplier used for the imaginary part of a |
596
+---------------------+--------------------------------------------------+
597
| :const:`algorithm` | name of the algorithm for hashing of str, bytes, |
599
+---------------------+--------------------------------------------------+
600
| :const:`hash_bits` | internal output size of the hash algorithm |
601
+---------------------+--------------------------------------------------+
602
| :const:`seed_bits` | size of the seed key of the hash algorithm |
603
+---------------------+--------------------------------------------------+
606
.. versionadded:: 3.2
608
.. versionchanged: 3.4
609
Added *algorithm*, *hash_bits* and *seed_bits*
614
The version number encoded as a single integer. This is guaranteed to increase
615
with each version, including proper support for non-production releases. For
616
example, to test that the Python interpreter is at least version 1.5.2, use::
618
if sys.hexversion >= 0x010502F0:
619
# use some advanced feature
622
# use an alternative implementation or warn the user
625
This is called ``hexversion`` since it only really looks meaningful when viewed
626
as the result of passing it to the built-in :func:`hex` function. The
627
:term:`struct sequence` :data:`sys.version_info` may be used for a more
628
human-friendly encoding of the same information.
630
More details of ``hexversion`` can be found at :ref:`apiabiversion`
633
.. data:: implementation
635
An object containing information about the implementation of the
636
currently running Python interpreter. The following attributes are
637
required to exist in all Python implementations.
639
*name* is the implementation's identifier, e.g. ``'cpython'``. The actual
640
string is defined by the Python implementation, but it is guaranteed to be
643
*version* is a named tuple, in the same format as
644
:data:`sys.version_info`. It represents the version of the Python
645
*implementation*. This has a distinct meaning from the specific
646
version of the Python *language* to which the currently running
647
interpreter conforms, which ``sys.version_info`` represents. For
648
example, for PyPy 1.8 ``sys.implementation.version`` might be
649
``sys.version_info(1, 8, 0, 'final', 0)``, whereas ``sys.version_info``
650
would be ``sys.version_info(2, 7, 2, 'final', 0)``. For CPython they
651
are the same value, since it is the reference implementation.
653
*hexversion* is the implementation version in hexadecimal format, like
654
:data:`sys.hexversion`.
656
*cache_tag* is the tag used by the import machinery in the filenames of
657
cached modules. By convention, it would be a composite of the
658
implementation's name and version, like ``'cpython-33'``. However, a
659
Python implementation may use some other value if appropriate. If
660
``cache_tag`` is set to ``None``, it indicates that module caching should
663
:data:`sys.implementation` may contain additional attributes specific to
664
the Python implementation. These non-standard attributes must start with
665
an underscore, and are not described here. Regardless of its contents,
666
:data:`sys.implementation` will not change during a run of the interpreter,
667
nor between implementation versions. (It may change between Python
668
language versions, however.) See `PEP 421` for more information.
670
.. versionadded:: 3.3
675
A :term:`struct sequence` that holds information about Python's internal
676
representation of integers. The attributes are read only.
678
.. tabularcolumns:: |l|L|
680
+-------------------------+----------------------------------------------+
681
| Attribute | Explanation |
682
+=========================+==============================================+
683
| :const:`bits_per_digit` | number of bits held in each digit. Python |
684
| | integers are stored internally in base |
685
| | ``2**int_info.bits_per_digit`` |
686
+-------------------------+----------------------------------------------+
687
| :const:`sizeof_digit` | size in bytes of the C type used to |
688
| | represent a digit |
689
+-------------------------+----------------------------------------------+
691
.. versionadded:: 3.1
694
.. data:: __interactivehook__
696
When present, this function is automatically called (with no arguments)
697
when the interpreter is launched in :ref:`interactive mode <tut-interactive>`.
698
This is done after the :envvar:`PYTHONSTARTUP` file is read, so that you
699
can set this hook there.
701
.. versionadded:: 3.4
704
.. function:: intern(string)
706
Enter *string* in the table of "interned" strings and return the interned string
707
-- which is *string* itself or a copy. Interning strings is useful to gain a
708
little performance on dictionary lookup -- if the keys in a dictionary are
709
interned, and the lookup key is interned, the key comparisons (after hashing)
710
can be done by a pointer compare instead of a string compare. Normally, the
711
names used in Python programs are automatically interned, and the dictionaries
712
used to hold module, class or instance attributes have interned keys.
714
Interned strings are not immortal; you must keep a reference to the return
715
value of :func:`intern` around to benefit from it.
722
These three variables are not always defined; they are set when an exception is
723
not handled and the interpreter prints an error message and a stack traceback.
724
Their intended use is to allow an interactive user to import a debugger module
725
and engage in post-mortem debugging without having to re-execute the command
726
that caused the error. (Typical use is ``import pdb; pdb.pm()`` to enter the
727
post-mortem debugger; see :mod:`pdb` module for
730
The meaning of the variables is the same as that of the return values from
731
:func:`exc_info` above.
736
An integer giving the maximum value a variable of type :c:type:`Py_ssize_t` can
737
take. It's usually ``2**31 - 1`` on a 32-bit platform and ``2**63 - 1`` on a
743
An integer giving the value of the largest Unicode code point,
744
i.e. ``1114111`` (``0x10FFFF`` in hexadecimal).
746
.. versionchanged:: 3.3
747
Before :pep:`393`, ``sys.maxunicode`` used to be either ``0xFFFF``
748
or ``0x10FFFF``, depending on the configuration option that specified
749
whether Unicode characters were stored as UCS-2 or UCS-4.
754
A list of :term:`finder` objects that have their :meth:`find_module`
755
methods called to see if one of the objects can find the module to be
756
imported. The :meth:`find_module` method is called at least with the
757
absolute name of the module being imported. If the module to be imported is
758
contained in package then the parent package's :attr:`__path__` attribute
759
is passed in as a second argument. The method returns ``None`` if
760
the module cannot be found, else returns a :term:`loader`.
762
:data:`sys.meta_path` is searched before any implicit default finders or
765
See :pep:`302` for the original specification.
770
This is a dictionary that maps module names to modules which have already been
771
loaded. This can be manipulated to force reloading of modules and other tricks.
772
However, replacing the dictionary will not necessarily work as expected and
773
deleting essential items from the dictionary may cause Python to fail.
778
.. index:: triple: module; search; path
780
A list of strings that specifies the search path for modules. Initialized from
781
the environment variable :envvar:`PYTHONPATH`, plus an installation-dependent
784
As initialized upon program startup, the first item of this list, ``path[0]``,
785
is the directory containing the script that was used to invoke the Python
786
interpreter. If the script directory is not available (e.g. if the interpreter
787
is invoked interactively or if the script is read from standard input),
788
``path[0]`` is the empty string, which directs Python to search modules in the
789
current directory first. Notice that the script directory is inserted *before*
790
the entries inserted as a result of :envvar:`PYTHONPATH`.
792
A program is free to modify this list for its own purposes. Only strings
793
and bytes should be added to :data:`sys.path`; all other data types are
794
ignored during import.
798
Module :mod:`site` This describes how to use .pth files to extend
804
A list of callables that take a path argument to try to create a
805
:term:`finder` for the path. If a finder can be created, it is to be
806
returned by the callable, else raise :exc:`ImportError`.
808
Originally specified in :pep:`302`.
811
.. data:: path_importer_cache
813
A dictionary acting as a cache for :term:`finder` objects. The keys are
814
paths that have been passed to :data:`sys.path_hooks` and the values are
815
the finders that are found. If a path is a valid file system path but no
816
finder is found on :data:`sys.path_hooks` then ``None`` is
819
Originally specified in :pep:`302`.
821
.. versionchanged:: 3.3
822
``None`` is stored instead of :class:`imp.NullImporter` when no finder
828
This string contains a platform identifier that can be used to append
829
platform-specific components to :data:`sys.path`, for instance.
831
For Unix systems, except on Linux, this is the lowercased OS name as
832
returned by ``uname -s`` with the first part of the version as returned by
833
``uname -r`` appended, e.g. ``'sunos5'`` or ``'freebsd8'``, *at the time
834
when Python was built*. Unless you want to test for a specific system
835
version, it is therefore recommended to use the following idiom::
837
if sys.platform.startswith('freebsd'):
838
# FreeBSD-specific code here...
839
elif sys.platform.startswith('linux'):
840
# Linux-specific code here...
842
For other systems, the values are:
844
================ ===========================
845
System ``platform`` value
846
================ ===========================
849
Windows/Cygwin ``'cygwin'``
850
Mac OS X ``'darwin'``
851
================ ===========================
853
.. versionchanged:: 3.3
854
On Linux, :attr:`sys.platform` doesn't contain the major version anymore.
855
It is always ``'linux'``, instead of ``'linux2'`` or ``'linux3'``. Since
856
older Python versions include the version number, it is recommended to
857
always use the ``startswith`` idiom presented above.
861
:attr:`os.name` has a coarser granularity. :func:`os.uname` gives
862
system-dependent version information.
864
The :mod:`platform` module provides detailed checks for the
870
A string giving the site-specific directory prefix where the platform
871
independent Python files are installed; by default, this is the string
872
``'/usr/local'``. This can be set at build time with the ``--prefix``
873
argument to the :program:`configure` script. The main collection of Python
874
library modules is installed in the directory :file:`{prefix}/lib/python{X.Y}`
875
while the platform independent header files (all except :file:`pyconfig.h`) are
876
stored in :file:`{prefix}/include/python{X.Y}`, where *X.Y* is the version
877
number of Python, for example ``3.2``.
879
.. note:: If a :ref:`virtual environment <venv-def>` is in effect, this
880
value will be changed in ``site.py`` to point to the virtual
881
environment. The value for the Python installation will still be
882
available, via :data:`base_prefix`.
889
single: interpreter prompts
890
single: prompts, interpreter
892
Strings specifying the primary and secondary prompt of the interpreter. These
893
are only defined if the interpreter is in interactive mode. Their initial
894
values in this case are ``'>>> '`` and ``'... '``. If a non-string object is
895
assigned to either variable, its :func:`str` is re-evaluated each time the
896
interpreter prepares to read a new interactive command; this can be used to
897
implement a dynamic prompt.
900
.. function:: setcheckinterval(interval)
902
Set the interpreter's "check interval". This integer value determines how often
903
the interpreter checks for periodic things such as thread switches and signal
904
handlers. The default is ``100``, meaning the check is performed every 100
905
Python virtual instructions. Setting it to a larger value may increase
906
performance for programs using threads. Setting it to a value ``<=`` 0 checks
907
every virtual instruction, maximizing responsiveness as well as overhead.
910
This function doesn't have an effect anymore, as the internal logic for
911
thread switching and asynchronous tasks has been rewritten. Use
912
:func:`setswitchinterval` instead.
915
.. function:: setdlopenflags(n)
917
Set the flags used by the interpreter for :c:func:`dlopen` calls, such as when
918
the interpreter loads extension modules. Among other things, this will enable a
919
lazy resolving of symbols when importing a module, if called as
920
``sys.setdlopenflags(0)``. To share symbols across extension modules, call as
921
``sys.setdlopenflags(os.RTLD_GLOBAL)``. Symbolic names for the flag values
922
can be found in the :mod:`os` module (``RTLD_xxx`` constants, e.g.
923
:data:`os.RTLD_LAZY`).
927
.. function:: setprofile(profilefunc)
930
single: profile function
933
Set the system's profile function, which allows you to implement a Python source
934
code profiler in Python. See chapter :ref:`profile` for more information on the
935
Python profiler. The system's profile function is called similarly to the
936
system's trace function (see :func:`settrace`), but it isn't called for each
937
executed line of code (only on call and return, but the return event is reported
938
even when an exception has been set). The function is thread-specific, but
939
there is no way for the profiler to know about context switches between threads,
940
so it does not make sense to use this in the presence of multiple threads. Also,
941
its return value is not used, so it can simply return ``None``.
944
.. function:: setrecursionlimit(limit)
946
Set the maximum depth of the Python interpreter stack to *limit*. This limit
947
prevents infinite recursion from causing an overflow of the C stack and crashing
950
The highest possible limit is platform-dependent. A user may need to set the
951
limit higher when they have a program that requires deep recursion and a platform
952
that supports a higher limit. This should be done with care, because a too-high
953
limit can lead to a crash.
956
.. function:: setswitchinterval(interval)
958
Set the interpreter's thread switch interval (in seconds). This floating-point
959
value determines the ideal duration of the "timeslices" allocated to
960
concurrently running Python threads. Please note that the actual value
961
can be higher, especially if long-running internal functions or methods
962
are used. Also, which thread becomes scheduled at the end of the interval
963
is the operating system's decision. The interpreter doesn't have its
966
.. versionadded:: 3.2
969
.. function:: settrace(tracefunc)
972
single: trace function
975
Set the system's trace function, which allows you to implement a Python
976
source code debugger in Python. The function is thread-specific; for a
977
debugger to support multiple threads, it must be registered using
978
:func:`settrace` for each thread being debugged.
980
Trace functions should have three arguments: *frame*, *event*, and
981
*arg*. *frame* is the current stack frame. *event* is a string: ``'call'``,
982
``'line'``, ``'return'``, ``'exception'``, ``'c_call'``, ``'c_return'``, or
983
``'c_exception'``. *arg* depends on the event type.
985
The trace function is invoked (with *event* set to ``'call'``) whenever a new
986
local scope is entered; it should return a reference to a local trace
987
function to be used that scope, or ``None`` if the scope shouldn't be traced.
989
The local trace function should return a reference to itself (or to another
990
function for further tracing in that scope), or ``None`` to turn off tracing
993
The events have the following meaning:
996
A function is called (or some other code block entered). The
997
global trace function is called; *arg* is ``None``; the return value
998
specifies the local trace function.
1001
The interpreter is about to execute a new line of code or re-execute the
1002
condition of a loop. The local trace function is called; *arg* is
1003
``None``; the return value specifies the new local trace function. See
1004
:file:`Objects/lnotab_notes.txt` for a detailed explanation of how this
1008
A function (or other code block) is about to return. The local trace
1009
function is called; *arg* is the value that will be returned, or ``None``
1010
if the event is caused by an exception being raised. The trace function's
1011
return value is ignored.
1014
An exception has occurred. The local trace function is called; *arg* is a
1015
tuple ``(exception, value, traceback)``; the return value specifies the
1016
new local trace function.
1019
A C function is about to be called. This may be an extension function or
1020
a built-in. *arg* is the C function object.
1023
A C function has returned. *arg* is the C function object.
1026
A C function has raised an exception. *arg* is the C function object.
1028
Note that as an exception is propagated down the chain of callers, an
1029
``'exception'`` event is generated at each level.
1031
For more information on code and frame objects, refer to :ref:`types`.
1035
The :func:`settrace` function is intended only for implementing debuggers,
1036
profilers, coverage tools and the like. Its behavior is part of the
1037
implementation platform, rather than part of the language definition, and
1038
thus may not be available in all Python implementations.
1041
.. function:: settscdump(on_flag)
1043
Activate dumping of VM measurements using the Pentium timestamp counter, if
1044
*on_flag* is true. Deactivate these dumps if *on_flag* is off. The function is
1045
available only if Python was compiled with ``--with-tsc``. To understand
1046
the output of this dump, read :file:`Python/ceval.c` in the Python sources.
1049
This function is intimately bound to CPython implementation details and
1050
thus not likely to be implemented elsewhere.
1057
:term:`File objects <file object>` used by the interpreter for standard
1058
input, output and errors:
1060
* ``stdin`` is used for all interactive input (including calls to
1062
* ``stdout`` is used for the output of :func:`print` and :term:`expression`
1063
statements and for the prompts of :func:`input`;
1064
* The interpreter's own prompts and its error messages go to ``stderr``.
1066
By default, these streams are regular text streams as returned by the
1067
:func:`open` function. Their parameters are chosen as follows:
1069
* The character encoding is platform-dependent. Under Windows, if the stream
1070
is interactive (that is, if its :meth:`isatty` method returns True), the
1071
console codepage is used, otherwise the ANSI code page. Under other
1072
platforms, the locale encoding is used (see :meth:`locale.getpreferredencoding`).
1074
Under all platforms though, you can override this value by setting the
1075
:envvar:`PYTHONIOENCODING` environment variable.
1077
* When interactive, standard streams are line-buffered. Otherwise, they
1078
are block-buffered like regular text files. You can override this
1079
value with the :option:`-u` command-line option.
1081
To write or read binary data from/to the standard streams, use the
1082
underlying binary :data:`~io.TextIOBase.buffer`. For example, to write
1083
bytes to :data:`stdout`, use ``sys.stdout.buffer.write(b'abc')``. Using
1084
:meth:`io.TextIOBase.detach`, streams can be made binary by default. This
1085
function sets :data:`stdin` and :data:`stdout` to binary::
1087
def make_streams_binary():
1088
sys.stdin = sys.stdin.detach()
1089
sys.stdout = sys.stdout.detach()
1091
Note that the streams may be replaced with objects (like :class:`io.StringIO`)
1092
that do not support the :attr:`~io.BufferedIOBase.buffer` attribute or the
1093
:meth:`~io.BufferedIOBase.detach` method and can raise :exc:`AttributeError`
1094
or :exc:`io.UnsupportedOperation`.
1101
These objects contain the original values of ``stdin``, ``stderr`` and
1102
``stdout`` at the start of the program. They are used during finalization,
1103
and could be useful to print to the actual standard stream no matter if the
1104
``sys.std*`` object has been redirected.
1106
It can also be used to restore the actual files to known working file objects
1107
in case they have been overwritten with a broken object. However, the
1108
preferred way to do this is to explicitly save the previous stream before
1109
replacing it, and restore the saved object.
1112
Under some conditions ``stdin``, ``stdout`` and ``stderr`` as well as the
1113
original values ``__stdin__``, ``__stdout__`` and ``__stderr__`` can be
1114
None. It is usually the case for Windows GUI apps that aren't connected
1115
to a console and Python apps started with :program:`pythonw`.
1118
.. data:: thread_info
1120
A :term:`struct sequence` holding information about the thread
1123
.. tabularcolumns:: |l|p{0.7\linewidth}|
1125
+------------------+---------------------------------------------------------+
1126
| Attribute | Explanation |
1127
+==================+=========================================================+
1128
| :const:`name` | Name of the thread implementation: |
1130
| | * ``'nt'``: Windows threads |
1131
| | * ``'pthread'``: POSIX threads |
1132
| | * ``'solaris'``: Solaris threads |
1133
+------------------+---------------------------------------------------------+
1134
| :const:`lock` | Name of the lock implementation: |
1136
| | * ``'semaphore'``: a lock uses a semaphore |
1137
| | * ``'mutex+cond'``: a lock uses a mutex |
1138
| | and a condition variable |
1139
| | * ``None`` if this information is unknown |
1140
+------------------+---------------------------------------------------------+
1141
| :const:`version` | Name and version of the thread library. It is a string, |
1142
| | or ``None`` if these informations are unknown. |
1143
+------------------+---------------------------------------------------------+
1145
.. versionadded:: 3.3
1148
.. data:: tracebacklimit
1150
When this variable is set to an integer value, it determines the maximum number
1151
of levels of traceback information printed when an unhandled exception occurs.
1152
The default is ``1000``. When set to ``0`` or less, all traceback information
1153
is suppressed and only the exception type and value are printed.
1158
A string containing the version number of the Python interpreter plus additional
1159
information on the build number and compiler used. This string is displayed
1160
when the interactive interpreter is started. Do not extract version information
1161
out of it, rather, use :data:`version_info` and the functions provided by the
1162
:mod:`platform` module.
1165
.. data:: api_version
1167
The C API version for this interpreter. Programmers may find this useful when
1168
debugging version conflicts between Python and extension modules.
1171
.. data:: version_info
1173
A tuple containing the five components of the version number: *major*, *minor*,
1174
*micro*, *releaselevel*, and *serial*. All values except *releaselevel* are
1175
integers; the release level is ``'alpha'``, ``'beta'``, ``'candidate'``, or
1176
``'final'``. The ``version_info`` value corresponding to the Python version 2.0
1177
is ``(2, 0, 0, 'final', 0)``. The components can also be accessed by name,
1178
so ``sys.version_info[0]`` is equivalent to ``sys.version_info.major``
1181
.. versionchanged:: 3.1
1182
Added named component attributes.
1184
.. data:: warnoptions
1186
This is an implementation detail of the warnings framework; do not modify this
1187
value. Refer to the :mod:`warnings` module for more information on the warnings
1193
The version number used to form registry keys on Windows platforms. This is
1194
stored as string resource 1000 in the Python DLL. The value is normally the
1195
first three characters of :const:`version`. It is provided in the :mod:`sys`
1196
module for informational purposes; modifying this value has no effect on the
1197
registry keys used by Python. Availability: Windows.
1202
A dictionary of the various implementation-specific flags passed through
1203
the :option:`-X` command-line option. Option names are either mapped to
1204
their values, if given explicitly, or to :const:`True`. Example::
1206
$ ./python -Xa=b -Xc
1207
Python 3.2a3+ (py3k, Oct 16 2010, 20:14:50)
1208
[GCC 4.4.3] on linux2
1209
Type "help", "copyright", "credits" or "license" for more information.
1212
{'a': 'b', 'c': True}
1216
This is a CPython-specific way of accessing options passed through
1217
:option:`-X`. Other implementations may export them through other
1218
means, or not at all.
1220
.. versionadded:: 3.2
1223
.. rubric:: Citations
1225
.. [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 .
added
removed
Doc/library/sys.rst
