blob: ed5db0551674ef943710c7aa0b50b414ac89b0fe [file] [log] [blame]
Georg Brandl116aa622007-08-15 14:28:22 +00001:mod:`sys` --- System-specific parameters and functions
2=======================================================
3
4.. module:: sys
5 :synopsis: Access system-specific parameters and functions.
6
Terry Jan Reedyfa089b92016-06-11 15:02:54 -04007--------------
Georg Brandl116aa622007-08-15 14:28:22 +00008
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
Barry Warsawa40453d2010-10-16 14:17:50 +000014.. data:: abiflags
15
Georg Brandldf48b972014-03-24 09:06:18 +010016 On POSIX systems where Python was built with the standard ``configure``
Barry Warsawa40453d2010-10-16 14:17:50 +000017 script, this contains the ABI flags as specified by :pep:`3149`.
18
19 .. versionadded:: 3.2
20
Georg Brandldf48b972014-03-24 09:06:18 +010021
Georg Brandl116aa622007-08-15 14:28:22 +000022.. data:: argv
23
24 The list of command line arguments passed to a Python script. ``argv[0]`` is the
25 script name (it is operating system dependent whether this is a full pathname or
26 not). If the command was executed using the :option:`-c` command line option to
27 the interpreter, ``argv[0]`` is set to the string ``'-c'``. If no script name
28 was passed to the Python interpreter, ``argv[0]`` is the empty string.
29
30 To loop over the standard input, or the list of files given on the
31 command line, see the :mod:`fileinput` module.
32
33
Vinay Sajip7ded1f02012-05-26 03:45:29 +010034.. data:: base_exec_prefix
35
36 Set during Python startup, before ``site.py`` is run, to the same value as
Vinay Sajipcd9b7462012-07-09 10:37:01 +010037 :data:`exec_prefix`. If not running in a
38 :ref:`virtual environment <venv-def>`, the values will stay the same; if
39 ``site.py`` finds that a virtual environment is in use, the values of
40 :data:`prefix` and :data:`exec_prefix` will be changed to point to the
41 virtual environment, whereas :data:`base_prefix` and
Vinay Sajip7ded1f02012-05-26 03:45:29 +010042 :data:`base_exec_prefix` will remain pointing to the base Python
43 installation (the one which the virtual environment was created from).
44
Georg Brandl039b01d2012-05-26 09:11:22 +020045 .. versionadded:: 3.3
46
47
Vinay Sajip7ded1f02012-05-26 03:45:29 +010048.. data:: base_prefix
49
50 Set during Python startup, before ``site.py`` is run, to the same value as
Vinay Sajipcd9b7462012-07-09 10:37:01 +010051 :data:`prefix`. If not running in a :ref:`virtual environment <venv-def>`, the values
Vinay Sajip7ded1f02012-05-26 03:45:29 +010052 will stay the same; if ``site.py`` finds that a virtual environment is in
53 use, the values of :data:`prefix` and :data:`exec_prefix` will be changed to
54 point to the virtual environment, whereas :data:`base_prefix` and
55 :data:`base_exec_prefix` will remain pointing to the base Python
56 installation (the one which the virtual environment was created from).
57
Georg Brandl039b01d2012-05-26 09:11:22 +020058 .. versionadded:: 3.3
59
60
Georg Brandl116aa622007-08-15 14:28:22 +000061.. data:: byteorder
62
63 An indicator of the native byte order. This will have the value ``'big'`` on
64 big-endian (most-significant byte first) platforms, and ``'little'`` on
65 little-endian (least-significant byte first) platforms.
66
Georg Brandl116aa622007-08-15 14:28:22 +000067
Georg Brandl116aa622007-08-15 14:28:22 +000068.. data:: builtin_module_names
69
70 A tuple of strings giving the names of all modules that are compiled into this
71 Python interpreter. (This information is not available in any other way ---
72 ``modules.keys()`` only lists the imported modules.)
73
74
Georg Brandl85271262010-10-17 11:06:14 +000075.. function:: call_tracing(func, args)
76
77 Call ``func(*args)``, while tracing is enabled. The tracing state is saved,
78 and restored afterwards. This is intended to be called from a debugger from
79 a checkpoint, to recursively debug some other code.
80
81
Georg Brandl116aa622007-08-15 14:28:22 +000082.. data:: copyright
83
84 A string containing the copyright pertaining to the Python interpreter.
85
86
Christian Heimes15ebc882008-02-04 18:48:49 +000087.. function:: _clear_type_cache()
88
89 Clear the internal type cache. The type cache is used to speed up attribute
90 and method lookups. Use the function *only* to drop unnecessary references
91 during reference leak debugging.
92
93 This function should be used for internal and specialized purposes only.
Christian Heimes26855632008-01-27 23:50:43 +000094
Christian Heimes26855632008-01-27 23:50:43 +000095
Georg Brandl116aa622007-08-15 14:28:22 +000096.. function:: _current_frames()
97
98 Return a dictionary mapping each thread's identifier to the topmost stack frame
99 currently active in that thread at the time the function is called. Note that
100 functions in the :mod:`traceback` module can build the call stack given such a
101 frame.
102
103 This is most useful for debugging deadlock: this function does not require the
104 deadlocked threads' cooperation, and such threads' call stacks are frozen for as
105 long as they remain deadlocked. The frame returned for a non-deadlocked thread
106 may bear no relationship to that thread's current activity by the time calling
107 code examines the frame.
108
109 This function should be used for internal and specialized purposes only.
110
Georg Brandl116aa622007-08-15 14:28:22 +0000111
David Malcolm49526f42012-06-22 14:55:41 -0400112.. function:: _debugmallocstats()
113
114 Print low-level information to stderr about the state of CPython's memory
115 allocator.
116
117 If Python is configured --with-pydebug, it also performs some expensive
118 internal consistency checks.
119
120 .. versionadded:: 3.3
121
122 .. impl-detail::
123
124 This function is specific to CPython. The exact output format is not
125 defined here, and may change.
126
127
Georg Brandl116aa622007-08-15 14:28:22 +0000128.. data:: dllhandle
129
130 Integer specifying the handle of the Python DLL. Availability: Windows.
131
132
133.. function:: displayhook(value)
134
Victor Stinner13d49ee2010-12-04 17:24:33 +0000135 If *value* is not ``None``, this function prints ``repr(value)`` to
136 ``sys.stdout``, and saves *value* in ``builtins._``. If ``repr(value)`` is
137 not encodable to ``sys.stdout.encoding`` with ``sys.stdout.errors`` error
138 handler (which is probably ``'strict'``), encode it to
139 ``sys.stdout.encoding`` with ``'backslashreplace'`` error handler.
Georg Brandl116aa622007-08-15 14:28:22 +0000140
Christian Heimesd8654cf2007-12-02 15:22:16 +0000141 ``sys.displayhook`` is called on the result of evaluating an :term:`expression`
142 entered in an interactive Python session. The display of these values can be
143 customized by assigning another one-argument function to ``sys.displayhook``.
Georg Brandl116aa622007-08-15 14:28:22 +0000144
Victor Stinner13d49ee2010-12-04 17:24:33 +0000145 Pseudo-code::
146
147 def displayhook(value):
148 if value is None:
149 return
150 # Set '_' to None to avoid recursion
151 builtins._ = None
152 text = repr(value)
153 try:
154 sys.stdout.write(text)
155 except UnicodeEncodeError:
156 bytes = text.encode(sys.stdout.encoding, 'backslashreplace')
157 if hasattr(sys.stdout, 'buffer'):
158 sys.stdout.buffer.write(bytes)
159 else:
160 text = bytes.decode(sys.stdout.encoding, 'strict')
161 sys.stdout.write(text)
162 sys.stdout.write("\n")
163 builtins._ = value
164
165 .. versionchanged:: 3.2
166 Use ``'backslashreplace'`` error handler on :exc:`UnicodeEncodeError`.
167
Georg Brandl116aa622007-08-15 14:28:22 +0000168
Éric Araujoda272632011-10-05 01:17:38 +0200169.. data:: dont_write_bytecode
170
Brett Cannonf299abd2015-04-13 14:21:02 -0400171 If this is true, Python won't try to write ``.pyc`` files on the
Éric Araujoda272632011-10-05 01:17:38 +0200172 import of source modules. This value is initially set to ``True`` or
173 ``False`` depending on the :option:`-B` command line option and the
174 :envvar:`PYTHONDONTWRITEBYTECODE` environment variable, but you can set it
175 yourself to control bytecode file generation.
176
177
Georg Brandl116aa622007-08-15 14:28:22 +0000178.. function:: excepthook(type, value, traceback)
179
180 This function prints out a given traceback and exception to ``sys.stderr``.
181
182 When an exception is raised and uncaught, the interpreter calls
183 ``sys.excepthook`` with three arguments, the exception class, exception
184 instance, and a traceback object. In an interactive session this happens just
185 before control is returned to the prompt; in a Python program this happens just
186 before the program exits. The handling of such top-level exceptions can be
187 customized by assigning another three-argument function to ``sys.excepthook``.
188
189
190.. data:: __displayhook__
191 __excepthook__
192
193 These objects contain the original values of ``displayhook`` and ``excepthook``
194 at the start of the program. They are saved so that ``displayhook`` and
195 ``excepthook`` can be restored in case they happen to get replaced with broken
196 objects.
197
198
199.. function:: exc_info()
200
201 This function returns a tuple of three values that give information about the
202 exception that is currently being handled. The information returned is specific
203 both to the current thread and to the current stack frame. If the current stack
204 frame is not handling an exception, the information is taken from the calling
205 stack frame, or its caller, and so on until a stack frame is found that is
206 handling an exception. Here, "handling an exception" is defined as "executing
Benjamin Petersoneec3d712008-06-11 15:59:43 +0000207 an except clause." For any stack frame, only information about the exception
208 being currently handled is accessible.
Georg Brandl116aa622007-08-15 14:28:22 +0000209
210 .. index:: object: traceback
211
Georg Brandl482b1512010-03-21 09:02:59 +0000212 If no exception is being handled anywhere on the stack, a tuple containing
213 three ``None`` values is returned. Otherwise, the values returned are
214 ``(type, value, traceback)``. Their meaning is: *type* gets the type of the
215 exception being handled (a subclass of :exc:`BaseException`); *value* gets
216 the exception instance (an instance of the exception type); *traceback* gets
217 a traceback object (see the Reference Manual) which encapsulates the call
Georg Brandl116aa622007-08-15 14:28:22 +0000218 stack at the point where the exception originally occurred.
219
Georg Brandl116aa622007-08-15 14:28:22 +0000220
221.. data:: exec_prefix
222
223 A string giving the site-specific directory prefix where the platform-dependent
224 Python files are installed; by default, this is also ``'/usr/local'``. This can
Éric Araujo713d3032010-11-18 16:38:46 +0000225 be set at build time with the ``--exec-prefix`` argument to the
Georg Brandl116aa622007-08-15 14:28:22 +0000226 :program:`configure` script. Specifically, all configuration files (e.g. the
Éric Araujo58a91532011-10-05 01:28:24 +0200227 :file:`pyconfig.h` header file) are installed in the directory
Georg Brandleb25fb72012-02-23 21:12:39 +0100228 :file:`{exec_prefix}/lib/python{X.Y}/config`, and shared library modules are
Éric Araujo58a91532011-10-05 01:28:24 +0200229 installed in :file:`{exec_prefix}/lib/python{X.Y}/lib-dynload`, where *X.Y*
230 is the version number of Python, for example ``3.2``.
Georg Brandl116aa622007-08-15 14:28:22 +0000231
Larry Hastings3732ed22014-03-15 21:13:56 -0700232 .. note::
233
234 If a :ref:`virtual environment <venv-def>` is in effect, this
Vinay Sajipcd9b7462012-07-09 10:37:01 +0100235 value will be changed in ``site.py`` to point to the virtual environment.
236 The value for the Python installation will still be available, via
237 :data:`base_exec_prefix`.
Vinay Sajip7ded1f02012-05-26 03:45:29 +0100238
Georg Brandl116aa622007-08-15 14:28:22 +0000239
240.. data:: executable
241
Petri Lehtinen97133212012-02-02 20:59:48 +0200242 A string giving the absolute path of the executable binary for the Python
243 interpreter, on systems where this makes sense. If Python is unable to retrieve
244 the real path to its executable, :data:`sys.executable` will be an empty string
245 or ``None``.
Georg Brandl116aa622007-08-15 14:28:22 +0000246
247
248.. function:: exit([arg])
249
250 Exit from Python. This is implemented by raising the :exc:`SystemExit`
251 exception, so cleanup actions specified by finally clauses of :keyword:`try`
Georg Brandl6f4e68d2010-10-17 10:51:45 +0000252 statements are honored, and it is possible to intercept the exit attempt at
253 an outer level.
254
255 The optional argument *arg* can be an integer giving the exit status
256 (defaulting to zero), or another type of object. If it is an integer, zero
257 is considered "successful termination" and any nonzero value is considered
258 "abnormal termination" by shells and the like. Most systems require it to be
259 in the range 0-127, and produce undefined results otherwise. Some systems
260 have a convention for assigning specific meanings to specific exit codes, but
261 these are generally underdeveloped; Unix programs generally use 2 for command
262 line syntax errors and 1 for all other kind of errors. If another type of
263 object is passed, ``None`` is equivalent to passing zero, and any other
264 object is printed to :data:`stderr` and results in an exit code of 1. In
265 particular, ``sys.exit("some error message")`` is a quick way to exit a
266 program when an error occurs.
267
268 Since :func:`exit` ultimately "only" raises an exception, it will only exit
269 the process when called from the main thread, and the exception is not
270 intercepted.
Georg Brandl116aa622007-08-15 14:28:22 +0000271
272
Christian Heimesd32ed6f2008-01-14 18:49:24 +0000273.. data:: flags
274
Benjamin Peterson2b8ef2d2011-04-20 18:31:22 -0500275 The :term:`struct sequence` *flags* exposes the status of command line
276 flags. The attributes are read only.
Christian Heimesd32ed6f2008-01-14 18:49:24 +0000277
Éric Araujo5ab47762011-03-26 00:47:04 +0100278 ============================= =============================
279 attribute flag
280 ============================= =============================
281 :const:`debug` :option:`-d`
Éric Araujo5ab47762011-03-26 00:47:04 +0100282 :const:`inspect` :option:`-i`
283 :const:`interactive` :option:`-i`
284 :const:`optimize` :option:`-O` or :option:`-OO`
285 :const:`dont_write_bytecode` :option:`-B`
286 :const:`no_user_site` :option:`-s`
287 :const:`no_site` :option:`-S`
288 :const:`ignore_environment` :option:`-E`
289 :const:`verbose` :option:`-v`
290 :const:`bytes_warning` :option:`-b`
Éric Araujo722bec42011-03-26 01:59:47 +0100291 :const:`quiet` :option:`-q`
Georg Brandl2daf6ae2012-02-20 19:54:16 +0100292 :const:`hash_randomization` :option:`-R`
Éric Araujo5ab47762011-03-26 00:47:04 +0100293 ============================= =============================
Georg Brandl8aa7e992010-12-28 18:30:18 +0000294
295 .. versionchanged:: 3.2
296 Added ``quiet`` attribute for the new :option:`-q` flag.
Christian Heimesd32ed6f2008-01-14 18:49:24 +0000297
Georg Brandl09a7c722012-02-20 21:31:46 +0100298 .. versionadded:: 3.2.3
Georg Brandl2daf6ae2012-02-20 19:54:16 +0100299 The ``hash_randomization`` attribute.
300
Éric Araujo3e898702011-04-24 04:37:00 +0200301 .. versionchanged:: 3.3
302 Removed obsolete ``division_warning`` attribute.
303
Christian Heimesd32ed6f2008-01-14 18:49:24 +0000304
Christian Heimes93852662007-12-01 12:22:32 +0000305.. data:: float_info
306
Benjamin Peterson2b8ef2d2011-04-20 18:31:22 -0500307 A :term:`struct sequence` holding information about the float type. It
308 contains low level information about the precision and internal
309 representation. The values correspond to the various floating-point
310 constants defined in the standard header file :file:`float.h` for the 'C'
311 programming language; see section 5.2.4.2.2 of the 1999 ISO/IEC C standard
312 [C99]_, 'Characteristics of floating types', for details.
Christian Heimes93852662007-12-01 12:22:32 +0000313
Georg Brandl44ea77b2013-03-28 13:28:44 +0100314 .. tabularcolumns:: |l|l|L|
315
Mark Dickinsonbe5846b2010-07-02 20:26:07 +0000316 +---------------------+----------------+--------------------------------------------------+
317 | attribute | float.h macro | explanation |
318 +=====================+================+==================================================+
Mark Dickinson39af05f2010-07-03 09:17:16 +0000319 | :const:`epsilon` | DBL_EPSILON | difference between 1 and the least value greater |
Mark Dickinsonbe5846b2010-07-02 20:26:07 +0000320 | | | than 1 that is representable as a float |
321 +---------------------+----------------+--------------------------------------------------+
322 | :const:`dig` | DBL_DIG | maximum number of decimal digits that can be |
323 | | | faithfully represented in a float; see below |
324 +---------------------+----------------+--------------------------------------------------+
325 | :const:`mant_dig` | DBL_MANT_DIG | float precision: the number of base-``radix`` |
326 | | | digits in the significand of a float |
327 +---------------------+----------------+--------------------------------------------------+
328 | :const:`max` | DBL_MAX | maximum representable finite float |
329 +---------------------+----------------+--------------------------------------------------+
330 | :const:`max_exp` | DBL_MAX_EXP | maximum integer e such that ``radix**(e-1)`` is |
331 | | | a representable finite float |
332 +---------------------+----------------+--------------------------------------------------+
333 | :const:`max_10_exp` | DBL_MAX_10_EXP | maximum integer e such that ``10**e`` is in the |
334 | | | range of representable finite floats |
335 +---------------------+----------------+--------------------------------------------------+
336 | :const:`min` | DBL_MIN | minimum positive normalized float |
337 +---------------------+----------------+--------------------------------------------------+
338 | :const:`min_exp` | DBL_MIN_EXP | minimum integer e such that ``radix**(e-1)`` is |
339 | | | a normalized float |
340 +---------------------+----------------+--------------------------------------------------+
341 | :const:`min_10_exp` | DBL_MIN_10_EXP | minimum integer e such that ``10**e`` is a |
342 | | | normalized float |
343 +---------------------+----------------+--------------------------------------------------+
344 | :const:`radix` | FLT_RADIX | radix of exponent representation |
345 +---------------------+----------------+--------------------------------------------------+
Mark Dickinsonb1e58fe2011-11-19 16:26:45 +0000346 | :const:`rounds` | FLT_ROUNDS | integer constant representing the rounding mode |
347 | | | used for arithmetic operations. This reflects |
348 | | | the value of the system FLT_ROUNDS macro at |
349 | | | interpreter startup time. See section 5.2.4.2.2 |
350 | | | of the C99 standard for an explanation of the |
351 | | | possible values and their meanings. |
Mark Dickinsonbe5846b2010-07-02 20:26:07 +0000352 +---------------------+----------------+--------------------------------------------------+
Christian Heimes93852662007-12-01 12:22:32 +0000353
Mark Dickinsonbe5846b2010-07-02 20:26:07 +0000354 The attribute :attr:`sys.float_info.dig` needs further explanation. If
355 ``s`` is any string representing a decimal number with at most
356 :attr:`sys.float_info.dig` significant digits, then converting ``s`` to a
357 float and back again will recover a string representing the same decimal
358 value::
Christian Heimes93852662007-12-01 12:22:32 +0000359
Mark Dickinsonbe5846b2010-07-02 20:26:07 +0000360 >>> import sys
361 >>> sys.float_info.dig
362 15
363 >>> s = '3.14159265358979' # decimal string with 15 significant digits
364 >>> format(float(s), '.15g') # convert to float and back -> same value
365 '3.14159265358979'
Christian Heimes93852662007-12-01 12:22:32 +0000366
Mark Dickinsonbe5846b2010-07-02 20:26:07 +0000367 But for strings with more than :attr:`sys.float_info.dig` significant digits,
368 this isn't always true::
369
370 >>> s = '9876543211234567' # 16 significant digits is too many!
371 >>> format(float(s), '.16g') # conversion changes value
372 '9876543211234568'
Christian Heimes93852662007-12-01 12:22:32 +0000373
Mark Dickinsonb08a53a2009-04-16 19:52:09 +0000374.. data:: float_repr_style
375
376 A string indicating how the :func:`repr` function behaves for
377 floats. If the string has value ``'short'`` then for a finite
378 float ``x``, ``repr(x)`` aims to produce a short string with the
379 property that ``float(repr(x)) == x``. This is the usual behaviour
380 in Python 3.1 and later. Otherwise, ``float_repr_style`` has value
381 ``'legacy'`` and ``repr(x)`` behaves in the same way as it did in
382 versions of Python prior to 3.1.
383
384 .. versionadded:: 3.1
385
386
Antoine Pitrouf9d0b122012-12-09 14:28:26 +0100387.. function:: getallocatedblocks()
388
389 Return the number of memory blocks currently allocated by the interpreter,
Antoine Pitrou92840532012-12-17 23:05:59 +0100390 regardless of their size. This function is mainly useful for tracking
391 and debugging memory leaks. Because of the interpreter's internal
392 caches, the result can vary from call to call; you may have to call
393 :func:`_clear_type_cache()` and :func:`gc.collect()` to get more
394 predictable results.
395
396 If a Python build or implementation cannot reasonably compute this
397 information, :func:`getallocatedblocks()` is allowed to return 0 instead.
Antoine Pitrouf9d0b122012-12-09 14:28:26 +0100398
399 .. versionadded:: 3.4
400
Antoine Pitrouf9d0b122012-12-09 14:28:26 +0100401
Georg Brandl116aa622007-08-15 14:28:22 +0000402.. function:: getcheckinterval()
403
404 Return the interpreter's "check interval"; see :func:`setcheckinterval`.
405
Antoine Pitroud42bc512009-11-10 23:18:31 +0000406 .. deprecated:: 3.2
407 Use :func:`getswitchinterval` instead.
408
Georg Brandl116aa622007-08-15 14:28:22 +0000409
410.. function:: getdefaultencoding()
411
412 Return the name of the current default string encoding used by the Unicode
413 implementation.
414
Georg Brandl116aa622007-08-15 14:28:22 +0000415
416.. function:: getdlopenflags()
417
Andrew Kuchlingc61b9132013-06-21 10:58:41 -0400418 Return the current value of the flags that are used for
419 :c:func:`dlopen` calls. Symbolic names for the flag values can be
420 found in the :mod:`os` module (``RTLD_xxx`` constants, e.g.
421 :data:`os.RTLD_LAZY`). Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +0000422
Georg Brandl116aa622007-08-15 14:28:22 +0000423
424.. function:: getfilesystemencoding()
425
Victor Stinnerb744ba12010-05-15 12:27:16 +0000426 Return the name of the encoding used to convert Unicode filenames into
427 system file names. The result value depends on the operating system:
Georg Brandl116aa622007-08-15 14:28:22 +0000428
Ezio Melottid5334e12010-04-29 16:24:51 +0000429 * On Mac OS X, the encoding is ``'utf-8'``.
Georg Brandl116aa622007-08-15 14:28:22 +0000430
431 * On Unix, the encoding is the user's preference according to the result of
Victor Stinner22d04182013-12-02 12:16:46 +0100432 nl_langinfo(CODESET).
Georg Brandl116aa622007-08-15 14:28:22 +0000433
434 * On Windows NT+, file names are Unicode natively, so no conversion is
Ezio Melottid5334e12010-04-29 16:24:51 +0000435 performed. :func:`getfilesystemencoding` still returns ``'mbcs'``, as
436 this is the encoding that applications should use when they explicitly
437 want to convert Unicode strings to byte strings that are equivalent when
438 used as file names.
439
440 * On Windows 9x, the encoding is ``'mbcs'``.
Georg Brandl116aa622007-08-15 14:28:22 +0000441
Victor Stinnerb744ba12010-05-15 12:27:16 +0000442 .. versionchanged:: 3.2
Victor Stinner22d04182013-12-02 12:16:46 +0100443 :func:`getfilesystemencoding` result cannot be ``None`` anymore.
Victor Stinnerb744ba12010-05-15 12:27:16 +0000444
Georg Brandl116aa622007-08-15 14:28:22 +0000445
446.. function:: getrefcount(object)
447
448 Return the reference count of the *object*. The count returned is generally one
449 higher than you might expect, because it includes the (temporary) reference as
450 an argument to :func:`getrefcount`.
451
452
453.. function:: getrecursionlimit()
454
455 Return the current value of the recursion limit, the maximum depth of the Python
456 interpreter stack. This limit prevents infinite recursion from causing an
457 overflow of the C stack and crashing Python. It can be set by
458 :func:`setrecursionlimit`.
459
460
Robert Schuppeniesfbe94c52008-07-14 10:13:31 +0000461.. function:: getsizeof(object[, default])
Martin v. Löwis00709aa2008-06-04 14:18:43 +0000462
463 Return the size of an object in bytes. The object can be any type of
464 object. All built-in objects will return correct results, but this
Robert Schuppeniesfbe94c52008-07-14 10:13:31 +0000465 does not have to hold true for third-party extensions as it is implementation
Martin v. Löwis00709aa2008-06-04 14:18:43 +0000466 specific.
467
Martin v. Löwis1e5d0ff2012-06-17 10:40:16 +0200468 Only the memory consumption directly attributed to the object is
469 accounted for, not the memory consumption of objects it refers to.
470
Benjamin Peterson4ac9ce42009-10-04 14:49:41 +0000471 If given, *default* will be returned if the object does not provide means to
Georg Brandlef871f62010-03-12 10:06:40 +0000472 retrieve the size. Otherwise a :exc:`TypeError` will be raised.
Robert Schuppeniesfbe94c52008-07-14 10:13:31 +0000473
Benjamin Peterson4ac9ce42009-10-04 14:49:41 +0000474 :func:`getsizeof` calls the object's ``__sizeof__`` method and adds an
475 additional garbage collector overhead if the object is managed by the garbage
476 collector.
Robert Schuppeniesfbe94c52008-07-14 10:13:31 +0000477
Serhiy Storchaka6dff0202016-05-07 10:49:07 +0300478 See `recursive sizeof recipe <https://code.activestate.com/recipes/577504>`_
Raymond Hettingerc539a2a2010-12-17 23:31:30 +0000479 for an example of using :func:`getsizeof` recursively to find the size of
480 containers and all their contents.
Martin v. Löwis00709aa2008-06-04 14:18:43 +0000481
Antoine Pitroud42bc512009-11-10 23:18:31 +0000482.. function:: getswitchinterval()
483
484 Return the interpreter's "thread switch interval"; see
485 :func:`setswitchinterval`.
486
Antoine Pitrou79707ca2009-11-11 22:03:32 +0000487 .. versionadded:: 3.2
488
Antoine Pitroud42bc512009-11-10 23:18:31 +0000489
Georg Brandl116aa622007-08-15 14:28:22 +0000490.. function:: _getframe([depth])
491
492 Return a frame object from the call stack. If optional integer *depth* is
493 given, return the frame object that many calls below the top of the stack. If
494 that is deeper than the call stack, :exc:`ValueError` is raised. The default
495 for *depth* is zero, returning the frame at the top of the call stack.
496
Georg Brandl495f7b52009-10-27 15:28:25 +0000497 .. impl-detail::
498
499 This function should be used for internal and specialized purposes only.
500 It is not guaranteed to exist in all implementations of Python.
Georg Brandl116aa622007-08-15 14:28:22 +0000501
502
Christian Heimes9bd667a2008-01-20 15:14:11 +0000503.. function:: getprofile()
504
505 .. index::
506 single: profile function
507 single: profiler
508
509 Get the profiler function as set by :func:`setprofile`.
510
Christian Heimes9bd667a2008-01-20 15:14:11 +0000511
512.. function:: gettrace()
513
514 .. index::
515 single: trace function
516 single: debugger
517
518 Get the trace function as set by :func:`settrace`.
519
Georg Brandl495f7b52009-10-27 15:28:25 +0000520 .. impl-detail::
Christian Heimes9bd667a2008-01-20 15:14:11 +0000521
522 The :func:`gettrace` function is intended only for implementing debuggers,
Georg Brandl495f7b52009-10-27 15:28:25 +0000523 profilers, coverage tools and the like. Its behavior is part of the
524 implementation platform, rather than part of the language definition, and
525 thus may not be available in all Python implementations.
Christian Heimes9bd667a2008-01-20 15:14:11 +0000526
Christian Heimes9bd667a2008-01-20 15:14:11 +0000527
Georg Brandl116aa622007-08-15 14:28:22 +0000528.. function:: getwindowsversion()
529
Eric Smith7338a392010-01-27 00:56:30 +0000530 Return a named tuple describing the Windows version
Eric Smithf7bb5782010-01-27 00:44:57 +0000531 currently running. The named elements are *major*, *minor*,
532 *build*, *platform*, *service_pack*, *service_pack_minor*,
533 *service_pack_major*, *suite_mask*, and *product_type*.
534 *service_pack* contains a string while all other values are
535 integers. The components can also be accessed by name, so
536 ``sys.getwindowsversion()[0]`` is equivalent to
537 ``sys.getwindowsversion().major``. For compatibility with prior
538 versions, only the first 5 elements are retrievable by indexing.
Georg Brandl116aa622007-08-15 14:28:22 +0000539
540 *platform* may be one of the following values:
541
Christian Heimes81ee3ef2008-05-04 22:42:01 +0000542 +-----------------------------------------+-------------------------+
543 | Constant | Platform |
544 +=========================================+=========================+
545 | :const:`0 (VER_PLATFORM_WIN32s)` | Win32s on Windows 3.1 |
546 +-----------------------------------------+-------------------------+
547 | :const:`1 (VER_PLATFORM_WIN32_WINDOWS)` | Windows 95/98/ME |
548 +-----------------------------------------+-------------------------+
549 | :const:`2 (VER_PLATFORM_WIN32_NT)` | Windows NT/2000/XP/x64 |
550 +-----------------------------------------+-------------------------+
551 | :const:`3 (VER_PLATFORM_WIN32_CE)` | Windows CE |
552 +-----------------------------------------+-------------------------+
Georg Brandl116aa622007-08-15 14:28:22 +0000553
Eric Smithf7bb5782010-01-27 00:44:57 +0000554 *product_type* may be one of the following values:
555
556 +---------------------------------------+---------------------------------+
557 | Constant | Meaning |
558 +=======================================+=================================+
559 | :const:`1 (VER_NT_WORKSTATION)` | The system is a workstation. |
560 +---------------------------------------+---------------------------------+
561 | :const:`2 (VER_NT_DOMAIN_CONTROLLER)` | The system is a domain |
562 | | controller. |
563 +---------------------------------------+---------------------------------+
564 | :const:`3 (VER_NT_SERVER)` | The system is a server, but not |
565 | | a domain controller. |
566 +---------------------------------------+---------------------------------+
567
568
Georg Brandl60203b42010-10-06 10:11:56 +0000569 This function wraps the Win32 :c:func:`GetVersionEx` function; see the
570 Microsoft documentation on :c:func:`OSVERSIONINFOEX` for more information
Eric Smithf7bb5782010-01-27 00:44:57 +0000571 about these fields.
Georg Brandl116aa622007-08-15 14:28:22 +0000572
573 Availability: Windows.
574
Ezio Melotti83fc6dd2010-01-27 22:44:03 +0000575 .. versionchanged:: 3.2
Eric Smithf7bb5782010-01-27 00:44:57 +0000576 Changed to a named tuple and added *service_pack_minor*,
577 *service_pack_major*, *suite_mask*, and *product_type*.
Georg Brandl116aa622007-08-15 14:28:22 +0000578
Mark Dickinsondc787d22010-05-23 13:33:13 +0000579
Yury Selivanovd4cbbeb2015-05-31 17:13:08 -0400580.. function:: get_coroutine_wrapper()
581
582 Returns ``None``, or a wrapper set by :func:`set_coroutine_wrapper`.
583
584 .. versionadded:: 3.5
585 See :pep:`492` for more details.
586
587 .. note::
588 This function has been added on a provisional basis (see :pep:`411`
Yury Selivanov4180e432015-06-04 11:10:24 -0400589 for details.) Use it only for debugging purposes.
Yury Selivanovd4cbbeb2015-05-31 17:13:08 -0400590
591
Mark Dickinsondc787d22010-05-23 13:33:13 +0000592.. data:: hash_info
593
Benjamin Peterson2b8ef2d2011-04-20 18:31:22 -0500594 A :term:`struct sequence` giving parameters of the numeric hash
595 implementation. For more details about hashing of numeric types, see
596 :ref:`numeric-hash`.
Mark Dickinsondc787d22010-05-23 13:33:13 +0000597
598 +---------------------+--------------------------------------------------+
599 | attribute | explanation |
600 +=====================+==================================================+
601 | :const:`width` | width in bits used for hash values |
602 +---------------------+--------------------------------------------------+
603 | :const:`modulus` | prime modulus P used for numeric hash scheme |
604 +---------------------+--------------------------------------------------+
605 | :const:`inf` | hash value returned for a positive infinity |
606 +---------------------+--------------------------------------------------+
607 | :const:`nan` | hash value returned for a nan |
608 +---------------------+--------------------------------------------------+
609 | :const:`imag` | multiplier used for the imaginary part of a |
610 | | complex number |
611 +---------------------+--------------------------------------------------+
Christian Heimes985ecdc2013-11-20 11:46:18 +0100612 | :const:`algorithm` | name of the algorithm for hashing of str, bytes, |
613 | | and memoryview |
614 +---------------------+--------------------------------------------------+
615 | :const:`hash_bits` | internal output size of the hash algorithm |
616 +---------------------+--------------------------------------------------+
617 | :const:`seed_bits` | size of the seed key of the hash algorithm |
618 +---------------------+--------------------------------------------------+
619
Mark Dickinsondc787d22010-05-23 13:33:13 +0000620
621 .. versionadded:: 3.2
622
R David Murrayf93d3df2014-03-17 11:20:29 -0400623 .. versionchanged:: 3.4
Christian Heimes985ecdc2013-11-20 11:46:18 +0100624 Added *algorithm*, *hash_bits* and *seed_bits*
625
Mark Dickinsondc787d22010-05-23 13:33:13 +0000626
Georg Brandl116aa622007-08-15 14:28:22 +0000627.. data:: hexversion
628
629 The version number encoded as a single integer. This is guaranteed to increase
630 with each version, including proper support for non-production releases. For
631 example, to test that the Python interpreter is at least version 1.5.2, use::
632
633 if sys.hexversion >= 0x010502F0:
634 # use some advanced feature
635 ...
636 else:
637 # use an alternative implementation or warn the user
638 ...
639
640 This is called ``hexversion`` since it only really looks meaningful when viewed
641 as the result of passing it to the built-in :func:`hex` function. The
Éric Araujo0abb8b72011-04-27 16:32:36 +0200642 :term:`struct sequence` :data:`sys.version_info` may be used for a more
643 human-friendly encoding of the same information.
Georg Brandl116aa622007-08-15 14:28:22 +0000644
Martin Panterd21e0b52015-10-10 10:36:22 +0000645 More details of ``hexversion`` can be found at :ref:`apiabiversion`.
Georg Brandl116aa622007-08-15 14:28:22 +0000646
Barry Warsaw409da152012-06-03 16:18:47 -0400647
648.. data:: implementation
649
Barry Warsaw9b10e1f2012-06-04 11:06:45 -0400650 An object containing information about the implementation of the
651 currently running Python interpreter. The following attributes are
652 required to exist in all Python implementations.
Barry Warsaw409da152012-06-03 16:18:47 -0400653
Barry Warsaw9b10e1f2012-06-04 11:06:45 -0400654 *name* is the implementation's identifier, e.g. ``'cpython'``. The actual
655 string is defined by the Python implementation, but it is guaranteed to be
656 lower case.
Barry Warsaw409da152012-06-03 16:18:47 -0400657
658 *version* is a named tuple, in the same format as
659 :data:`sys.version_info`. It represents the version of the Python
660 *implementation*. This has a distinct meaning from the specific
661 version of the Python *language* to which the currently running
662 interpreter conforms, which ``sys.version_info`` represents. For
663 example, for PyPy 1.8 ``sys.implementation.version`` might be
664 ``sys.version_info(1, 8, 0, 'final', 0)``, whereas ``sys.version_info``
Barry Warsaw9b10e1f2012-06-04 11:06:45 -0400665 would be ``sys.version_info(2, 7, 2, 'final', 0)``. For CPython they
Barry Warsaw409da152012-06-03 16:18:47 -0400666 are the same value, since it is the reference implementation.
667
668 *hexversion* is the implementation version in hexadecimal format, like
669 :data:`sys.hexversion`.
670
671 *cache_tag* is the tag used by the import machinery in the filenames of
672 cached modules. By convention, it would be a composite of the
673 implementation's name and version, like ``'cpython-33'``. However, a
674 Python implementation may use some other value if appropriate. If
675 ``cache_tag`` is set to ``None``, it indicates that module caching should
676 be disabled.
677
Barry Warsaw9b10e1f2012-06-04 11:06:45 -0400678 :data:`sys.implementation` may contain additional attributes specific to
679 the Python implementation. These non-standard attributes must start with
680 an underscore, and are not described here. Regardless of its contents,
681 :data:`sys.implementation` will not change during a run of the interpreter,
682 nor between implementation versions. (It may change between Python
Georg Brandl93a56cd2014-10-30 22:25:41 +0100683 language versions, however.) See :pep:`421` for more information.
Barry Warsaw409da152012-06-03 16:18:47 -0400684
685 .. versionadded:: 3.3
686
687
Mark Dickinsonbd792642009-03-18 20:06:12 +0000688.. data:: int_info
689
Benjamin Peterson2b8ef2d2011-04-20 18:31:22 -0500690 A :term:`struct sequence` that holds information about Python's internal
691 representation of integers. The attributes are read only.
Mark Dickinsonbd792642009-03-18 20:06:12 +0000692
Georg Brandl44ea77b2013-03-28 13:28:44 +0100693 .. tabularcolumns:: |l|L|
694
Mark Dickinsonbd792642009-03-18 20:06:12 +0000695 +-------------------------+----------------------------------------------+
R David Murray9beb34e2011-04-30 16:35:29 -0400696 | Attribute | Explanation |
Mark Dickinsonbd792642009-03-18 20:06:12 +0000697 +=========================+==============================================+
698 | :const:`bits_per_digit` | number of bits held in each digit. Python |
699 | | integers are stored internally in base |
700 | | ``2**int_info.bits_per_digit`` |
701 +-------------------------+----------------------------------------------+
702 | :const:`sizeof_digit` | size in bytes of the C type used to |
703 | | represent a digit |
704 +-------------------------+----------------------------------------------+
705
Mark Dickinsond72c7b62009-03-20 16:00:49 +0000706 .. versionadded:: 3.1
707
Mark Dickinsonbd792642009-03-18 20:06:12 +0000708
Antoine Pitrou1a6cb302013-05-04 20:08:35 +0200709.. data:: __interactivehook__
710
Larry Hastings3732ed22014-03-15 21:13:56 -0700711 When this attribute exists, its value is automatically called (with no
712 arguments) when the interpreter is launched in :ref:`interactive mode
713 <tut-interactive>`. This is done after the :envvar:`PYTHONSTARTUP` file is
714 read, so that you can set this hook there. The :mod:`site` module
715 :ref:`sets this <rlcompleter-config>`.
Antoine Pitrou1a6cb302013-05-04 20:08:35 +0200716
717 .. versionadded:: 3.4
718
719
Georg Brandl116aa622007-08-15 14:28:22 +0000720.. function:: intern(string)
721
722 Enter *string* in the table of "interned" strings and return the interned string
723 -- which is *string* itself or a copy. Interning strings is useful to gain a
724 little performance on dictionary lookup -- if the keys in a dictionary are
725 interned, and the lookup key is interned, the key comparisons (after hashing)
726 can be done by a pointer compare instead of a string compare. Normally, the
727 names used in Python programs are automatically interned, and the dictionaries
728 used to hold module, class or instance attributes have interned keys.
729
Georg Brandl55ac8f02007-09-01 13:51:09 +0000730 Interned strings are not immortal; you must keep a reference to the return
731 value of :func:`intern` around to benefit from it.
Georg Brandl116aa622007-08-15 14:28:22 +0000732
733
Antoine Pitrou5db1bb82014-12-07 01:28:27 +0100734.. function:: is_finalizing()
735
736 Return :const:`True` if the Python interpreter is
737 :term:`shutting down <interpreter shutdown>`, :const:`False` otherwise.
738
739 .. versionadded:: 3.5
740
741
Georg Brandl116aa622007-08-15 14:28:22 +0000742.. data:: last_type
743 last_value
744 last_traceback
745
746 These three variables are not always defined; they are set when an exception is
747 not handled and the interpreter prints an error message and a stack traceback.
748 Their intended use is to allow an interactive user to import a debugger module
749 and engage in post-mortem debugging without having to re-execute the command
750 that caused the error. (Typical use is ``import pdb; pdb.pm()`` to enter the
Alexander Belopolskyf0a0d142010-10-27 03:06:43 +0000751 post-mortem debugger; see :mod:`pdb` module for
Georg Brandl116aa622007-08-15 14:28:22 +0000752 more information.)
753
754 The meaning of the variables is the same as that of the return values from
Georg Brandl482b1512010-03-21 09:02:59 +0000755 :func:`exc_info` above.
Georg Brandl116aa622007-08-15 14:28:22 +0000756
757
Christian Heimesa37d4c62007-12-04 23:02:19 +0000758.. data:: maxsize
Georg Brandl116aa622007-08-15 14:28:22 +0000759
Georg Brandl60203b42010-10-06 10:11:56 +0000760 An integer giving the maximum value a variable of type :c:type:`Py_ssize_t` can
Georg Brandl33770552007-12-15 09:55:35 +0000761 take. It's usually ``2**31 - 1`` on a 32-bit platform and ``2**63 - 1`` on a
762 64-bit platform.
Christian Heimesa37d4c62007-12-04 23:02:19 +0000763
Georg Brandl116aa622007-08-15 14:28:22 +0000764
765.. data:: maxunicode
766
Ezio Melotti48a2f8f2011-09-29 00:18:19 +0300767 An integer giving the value of the largest Unicode code point,
768 i.e. ``1114111`` (``0x10FFFF`` in hexadecimal).
769
770 .. versionchanged:: 3.3
Éric Araujo525b1e92011-10-05 01:06:31 +0200771 Before :pep:`393`, ``sys.maxunicode`` used to be either ``0xFFFF``
Ezio Melotti48a2f8f2011-09-29 00:18:19 +0300772 or ``0x10FFFF``, depending on the configuration option that specified
773 whether Unicode characters were stored as UCS-2 or UCS-4.
Georg Brandl116aa622007-08-15 14:28:22 +0000774
775
Brett Cannone43b0602009-03-21 03:11:16 +0000776.. data:: meta_path
777
Brett Cannonccddbb12015-12-04 15:46:21 -0800778 A list of :term:`meta path finder` objects that have their
779 :meth:`~importlib.abc.MetaPathFinder.find_spec` methods called to see if one
780 of the objects can find the module to be imported. The
781 :meth:`~importlib.abc.MetaPathFinder.find_spec` method is called with at
782 least the absolute name of the module being imported. If the module to be
783 imported is contained in a package, then the parent package's :attr:`__path__`
784 attribute is passed in as a second argument. The method returns a
785 :term:`module spec`, or ``None`` if the module cannot be found.
Brett Cannone43b0602009-03-21 03:11:16 +0000786
Brett Cannonccddbb12015-12-04 15:46:21 -0800787 .. seealso::
Brett Cannone43b0602009-03-21 03:11:16 +0000788
Brett Cannonccddbb12015-12-04 15:46:21 -0800789 :class:`importlib.abc.MetaPathFinder`
790 The abstract base class defining the interface of finder objects on
791 :data:`meta_path`.
792 :class:`importlib.machinery.ModuleSpec`
793 The concrete class which
794 :meth:`~importlib.abc.MetaPathFinder.find_spec` should return
795 instances of.
Brett Cannone43b0602009-03-21 03:11:16 +0000796
Brett Cannonccddbb12015-12-04 15:46:21 -0800797 .. versionchanged:: 3.4
798
799 :term:`Module specs <module spec>` were introduced in Python 3.4, by
800 :pep:`451`. Earlier versions of Python looked for a method called
801 :meth:`~importlib.abc.MetaPathFinder.find_module`.
802 This is still called as a fallback if a :data:`meta_path` entry doesn't
803 have a :meth:`~importlib.abc.MetaPathFinder.find_spec` method.
Brett Cannone43b0602009-03-21 03:11:16 +0000804
Georg Brandl116aa622007-08-15 14:28:22 +0000805.. data:: modules
806
807 This is a dictionary that maps module names to modules which have already been
808 loaded. This can be manipulated to force reloading of modules and other tricks.
Brett Cannonc3511c12013-05-24 08:05:07 -0400809 However, replacing the dictionary will not necessarily work as expected and
810 deleting essential items from the dictionary may cause Python to fail.
Georg Brandl116aa622007-08-15 14:28:22 +0000811
812
813.. data:: path
814
815 .. index:: triple: module; search; path
816
817 A list of strings that specifies the search path for modules. Initialized from
818 the environment variable :envvar:`PYTHONPATH`, plus an installation-dependent
819 default.
820
821 As initialized upon program startup, the first item of this list, ``path[0]``,
822 is the directory containing the script that was used to invoke the Python
823 interpreter. If the script directory is not available (e.g. if the interpreter
824 is invoked interactively or if the script is read from standard input),
825 ``path[0]`` is the empty string, which directs Python to search modules in the
826 current directory first. Notice that the script directory is inserted *before*
827 the entries inserted as a result of :envvar:`PYTHONPATH`.
828
Barry Warsaw82c1c782012-11-20 15:22:51 -0500829 A program is free to modify this list for its own purposes. Only strings
830 and bytes should be added to :data:`sys.path`; all other data types are
831 ignored during import.
Georg Brandl116aa622007-08-15 14:28:22 +0000832
Georg Brandl116aa622007-08-15 14:28:22 +0000833
Benjamin Peterson058e31e2009-01-16 03:54:08 +0000834 .. seealso::
835 Module :mod:`site` This describes how to use .pth files to extend
836 :data:`sys.path`.
837
838
Brett Cannone43b0602009-03-21 03:11:16 +0000839.. data:: path_hooks
840
841 A list of callables that take a path argument to try to create a
842 :term:`finder` for the path. If a finder can be created, it is to be
843 returned by the callable, else raise :exc:`ImportError`.
844
845 Originally specified in :pep:`302`.
846
847
848.. data:: path_importer_cache
849
850 A dictionary acting as a cache for :term:`finder` objects. The keys are
851 paths that have been passed to :data:`sys.path_hooks` and the values are
852 the finders that are found. If a path is a valid file system path but no
Brett Cannon2514b482013-03-13 10:46:22 -0700853 finder is found on :data:`sys.path_hooks` then ``None`` is
854 stored.
Brett Cannone43b0602009-03-21 03:11:16 +0000855
856 Originally specified in :pep:`302`.
857
Brett Cannon2514b482013-03-13 10:46:22 -0700858 .. versionchanged:: 3.3
859 ``None`` is stored instead of :class:`imp.NullImporter` when no finder
860 is found.
861
Brett Cannone43b0602009-03-21 03:11:16 +0000862
Georg Brandl116aa622007-08-15 14:28:22 +0000863.. data:: platform
864
Christian Heimes9bd667a2008-01-20 15:14:11 +0000865 This string contains a platform identifier that can be used to append
866 platform-specific components to :data:`sys.path`, for instance.
867
Victor Stinner795eaeb2011-08-21 12:08:11 +0200868 For Unix systems, except on Linux, this is the lowercased OS name as
869 returned by ``uname -s`` with the first part of the version as returned by
870 ``uname -r`` appended, e.g. ``'sunos5'`` or ``'freebsd8'``, *at the time
871 when Python was built*. Unless you want to test for a specific system
872 version, it is therefore recommended to use the following idiom::
Antoine Pitroua83cdaa2011-07-09 15:54:23 +0200873
Victor Stinner795eaeb2011-08-21 12:08:11 +0200874 if sys.platform.startswith('freebsd'):
875 # FreeBSD-specific code here...
Georg Brandla47e53e2011-09-03 09:26:09 +0200876 elif sys.platform.startswith('linux'):
Antoine Pitroua83cdaa2011-07-09 15:54:23 +0200877 # Linux-specific code here...
878
Christian Heimes9bd667a2008-01-20 15:14:11 +0000879 For other systems, the values are:
880
881 ================ ===========================
Éric Araujo3f7c0e42012-12-08 22:53:43 -0500882 System ``platform`` value
Christian Heimes9bd667a2008-01-20 15:14:11 +0000883 ================ ===========================
Victor Stinner795eaeb2011-08-21 12:08:11 +0200884 Linux ``'linux'``
Christian Heimes9bd667a2008-01-20 15:14:11 +0000885 Windows ``'win32'``
886 Windows/Cygwin ``'cygwin'``
Georg Brandlc575c902008-09-13 17:46:05 +0000887 Mac OS X ``'darwin'``
Christian Heimes9bd667a2008-01-20 15:14:11 +0000888 ================ ===========================
Georg Brandl116aa622007-08-15 14:28:22 +0000889
Victor Stinner795eaeb2011-08-21 12:08:11 +0200890 .. versionchanged:: 3.3
891 On Linux, :attr:`sys.platform` doesn't contain the major version anymore.
Georg Brandlfbd1e042011-09-04 08:42:26 +0200892 It is always ``'linux'``, instead of ``'linux2'`` or ``'linux3'``. Since
893 older Python versions include the version number, it is recommended to
894 always use the ``startswith`` idiom presented above.
Victor Stinner795eaeb2011-08-21 12:08:11 +0200895
Antoine Pitroua83cdaa2011-07-09 15:54:23 +0200896 .. seealso::
Georg Brandleb25fb72012-02-23 21:12:39 +0100897
Antoine Pitroua83cdaa2011-07-09 15:54:23 +0200898 :attr:`os.name` has a coarser granularity. :func:`os.uname` gives
899 system-dependent version information.
900
901 The :mod:`platform` module provides detailed checks for the
902 system's identity.
Georg Brandl116aa622007-08-15 14:28:22 +0000903
Georg Brandlfbd1e042011-09-04 08:42:26 +0200904
Georg Brandl116aa622007-08-15 14:28:22 +0000905.. data:: prefix
906
907 A string giving the site-specific directory prefix where the platform
908 independent Python files are installed; by default, this is the string
Éric Araujo713d3032010-11-18 16:38:46 +0000909 ``'/usr/local'``. This can be set at build time with the ``--prefix``
Georg Brandl116aa622007-08-15 14:28:22 +0000910 argument to the :program:`configure` script. The main collection of Python
Georg Brandla673eb82012-03-04 16:17:05 +0100911 library modules is installed in the directory :file:`{prefix}/lib/python{X.Y}`
Georg Brandl116aa622007-08-15 14:28:22 +0000912 while the platform independent header files (all except :file:`pyconfig.h`) are
Georg Brandleb25fb72012-02-23 21:12:39 +0100913 stored in :file:`{prefix}/include/python{X.Y}`, where *X.Y* is the version
Éric Araujo58a91532011-10-05 01:28:24 +0200914 number of Python, for example ``3.2``.
Georg Brandl116aa622007-08-15 14:28:22 +0000915
Vinay Sajipcd9b7462012-07-09 10:37:01 +0100916 .. note:: If a :ref:`virtual environment <venv-def>` is in effect, this
917 value will be changed in ``site.py`` to point to the virtual
918 environment. The value for the Python installation will still be
919 available, via :data:`base_prefix`.
Vinay Sajip7ded1f02012-05-26 03:45:29 +0100920
Georg Brandl116aa622007-08-15 14:28:22 +0000921
922.. data:: ps1
923 ps2
924
925 .. index::
926 single: interpreter prompts
927 single: prompts, interpreter
928
929 Strings specifying the primary and secondary prompt of the interpreter. These
930 are only defined if the interpreter is in interactive mode. Their initial
931 values in this case are ``'>>> '`` and ``'... '``. If a non-string object is
932 assigned to either variable, its :func:`str` is re-evaluated each time the
933 interpreter prepares to read a new interactive command; this can be used to
934 implement a dynamic prompt.
935
936
937.. function:: setcheckinterval(interval)
938
939 Set the interpreter's "check interval". This integer value determines how often
940 the interpreter checks for periodic things such as thread switches and signal
941 handlers. The default is ``100``, meaning the check is performed every 100
942 Python virtual instructions. Setting it to a larger value may increase
943 performance for programs using threads. Setting it to a value ``<=`` 0 checks
944 every virtual instruction, maximizing responsiveness as well as overhead.
945
Antoine Pitroud42bc512009-11-10 23:18:31 +0000946 .. deprecated:: 3.2
Georg Brandl67b21b72010-08-17 15:07:14 +0000947 This function doesn't have an effect anymore, as the internal logic for
948 thread switching and asynchronous tasks has been rewritten. Use
949 :func:`setswitchinterval` instead.
Antoine Pitroud42bc512009-11-10 23:18:31 +0000950
Georg Brandl116aa622007-08-15 14:28:22 +0000951
Georg Brandl116aa622007-08-15 14:28:22 +0000952.. function:: setdlopenflags(n)
953
Georg Brandl60203b42010-10-06 10:11:56 +0000954 Set the flags used by the interpreter for :c:func:`dlopen` calls, such as when
Georg Brandl116aa622007-08-15 14:28:22 +0000955 the interpreter loads extension modules. Among other things, this will enable a
956 lazy resolving of symbols when importing a module, if called as
957 ``sys.setdlopenflags(0)``. To share symbols across extension modules, call as
Andrew Kuchlingc61b9132013-06-21 10:58:41 -0400958 ``sys.setdlopenflags(os.RTLD_GLOBAL)``. Symbolic names for the flag values
Victor Stinner8b905bd2011-10-25 13:34:04 +0200959 can be found in the :mod:`os` module (``RTLD_xxx`` constants, e.g.
960 :data:`os.RTLD_LAZY`).
961
962 Availability: Unix.
Georg Brandl116aa622007-08-15 14:28:22 +0000963
Georg Brandl116aa622007-08-15 14:28:22 +0000964.. function:: setprofile(profilefunc)
965
966 .. index::
967 single: profile function
968 single: profiler
969
970 Set the system's profile function, which allows you to implement a Python source
971 code profiler in Python. See chapter :ref:`profile` for more information on the
972 Python profiler. The system's profile function is called similarly to the
973 system's trace function (see :func:`settrace`), but it isn't called for each
974 executed line of code (only on call and return, but the return event is reported
975 even when an exception has been set). The function is thread-specific, but
976 there is no way for the profiler to know about context switches between threads,
977 so it does not make sense to use this in the presence of multiple threads. Also,
978 its return value is not used, so it can simply return ``None``.
979
980
981.. function:: setrecursionlimit(limit)
982
983 Set the maximum depth of the Python interpreter stack to *limit*. This limit
984 prevents infinite recursion from causing an overflow of the C stack and crashing
985 Python.
986
987 The highest possible limit is platform-dependent. A user may need to set the
Georg Brandl51663752011-05-13 06:55:28 +0200988 limit higher when they have a program that requires deep recursion and a platform
Georg Brandl116aa622007-08-15 14:28:22 +0000989 that supports a higher limit. This should be done with care, because a too-high
990 limit can lead to a crash.
991
Victor Stinner50856d52015-10-13 00:11:21 +0200992 If the new limit is too low at the current recursion depth, a
993 :exc:`RecursionError` exception is raised.
994
995 .. versionchanged:: 3.5.1
996 A :exc:`RecursionError` exception is now raised if the new limit is too
997 low at the current recursion depth.
998
Georg Brandl116aa622007-08-15 14:28:22 +0000999
Antoine Pitroud42bc512009-11-10 23:18:31 +00001000.. function:: setswitchinterval(interval)
1001
1002 Set the interpreter's thread switch interval (in seconds). This floating-point
1003 value determines the ideal duration of the "timeslices" allocated to
1004 concurrently running Python threads. Please note that the actual value
1005 can be higher, especially if long-running internal functions or methods
1006 are used. Also, which thread becomes scheduled at the end of the interval
1007 is the operating system's decision. The interpreter doesn't have its
1008 own scheduler.
1009
Antoine Pitrou79707ca2009-11-11 22:03:32 +00001010 .. versionadded:: 3.2
1011
Antoine Pitroud42bc512009-11-10 23:18:31 +00001012
Georg Brandl116aa622007-08-15 14:28:22 +00001013.. function:: settrace(tracefunc)
1014
1015 .. index::
1016 single: trace function
1017 single: debugger
1018
1019 Set the system's trace function, which allows you to implement a Python
Amaury Forgeot d'Arcb0c29162008-11-22 22:18:04 +00001020 source code debugger in Python. The function is thread-specific; for a
Georg Brandl116aa622007-08-15 14:28:22 +00001021 debugger to support multiple threads, it must be registered using
1022 :func:`settrace` for each thread being debugged.
1023
Amaury Forgeot d'Arcb0c29162008-11-22 22:18:04 +00001024 Trace functions should have three arguments: *frame*, *event*, and
1025 *arg*. *frame* is the current stack frame. *event* is a string: ``'call'``,
1026 ``'line'``, ``'return'``, ``'exception'``, ``'c_call'``, ``'c_return'``, or
1027 ``'c_exception'``. *arg* depends on the event type.
1028
1029 The trace function is invoked (with *event* set to ``'call'``) whenever a new
1030 local scope is entered; it should return a reference to a local trace
1031 function to be used that scope, or ``None`` if the scope shouldn't be traced.
1032
1033 The local trace function should return a reference to itself (or to another
1034 function for further tracing in that scope), or ``None`` to turn off tracing
1035 in that scope.
1036
1037 The events have the following meaning:
1038
Georg Brandl48310cd2009-01-03 21:18:54 +00001039 ``'call'``
Amaury Forgeot d'Arcb0c29162008-11-22 22:18:04 +00001040 A function is called (or some other code block entered). The
1041 global trace function is called; *arg* is ``None``; the return value
1042 specifies the local trace function.
1043
1044 ``'line'``
Alexandre Vassalotti7b82b402009-07-21 04:30:03 +00001045 The interpreter is about to execute a new line of code or re-execute the
1046 condition of a loop. The local trace function is called; *arg* is
1047 ``None``; the return value specifies the new local trace function. See
1048 :file:`Objects/lnotab_notes.txt` for a detailed explanation of how this
1049 works.
Amaury Forgeot d'Arcb0c29162008-11-22 22:18:04 +00001050
1051 ``'return'``
1052 A function (or other code block) is about to return. The local trace
Georg Brandld0b0e1d2010-10-15 16:42:37 +00001053 function is called; *arg* is the value that will be returned, or ``None``
1054 if the event is caused by an exception being raised. The trace function's
1055 return value is ignored.
Amaury Forgeot d'Arcb0c29162008-11-22 22:18:04 +00001056
1057 ``'exception'``
1058 An exception has occurred. The local trace function is called; *arg* is a
1059 tuple ``(exception, value, traceback)``; the return value specifies the
1060 new local trace function.
1061
1062 ``'c_call'``
1063 A C function is about to be called. This may be an extension function or
Georg Brandl22b34312009-07-26 14:54:51 +00001064 a built-in. *arg* is the C function object.
Amaury Forgeot d'Arcb0c29162008-11-22 22:18:04 +00001065
1066 ``'c_return'``
Georg Brandld0b0e1d2010-10-15 16:42:37 +00001067 A C function has returned. *arg* is the C function object.
Amaury Forgeot d'Arcb0c29162008-11-22 22:18:04 +00001068
1069 ``'c_exception'``
Georg Brandld0b0e1d2010-10-15 16:42:37 +00001070 A C function has raised an exception. *arg* is the C function object.
Amaury Forgeot d'Arcb0c29162008-11-22 22:18:04 +00001071
1072 Note that as an exception is propagated down the chain of callers, an
1073 ``'exception'`` event is generated at each level.
1074
1075 For more information on code and frame objects, refer to :ref:`types`.
1076
Georg Brandl495f7b52009-10-27 15:28:25 +00001077 .. impl-detail::
Georg Brandl116aa622007-08-15 14:28:22 +00001078
1079 The :func:`settrace` function is intended only for implementing debuggers,
Georg Brandl495f7b52009-10-27 15:28:25 +00001080 profilers, coverage tools and the like. Its behavior is part of the
1081 implementation platform, rather than part of the language definition, and
1082 thus may not be available in all Python implementations.
Georg Brandl116aa622007-08-15 14:28:22 +00001083
1084
1085.. function:: settscdump(on_flag)
1086
1087 Activate dumping of VM measurements using the Pentium timestamp counter, if
1088 *on_flag* is true. Deactivate these dumps if *on_flag* is off. The function is
Éric Araujo713d3032010-11-18 16:38:46 +00001089 available only if Python was compiled with ``--with-tsc``. To understand
Georg Brandl116aa622007-08-15 14:28:22 +00001090 the output of this dump, read :file:`Python/ceval.c` in the Python sources.
1091
Benjamin Peterson21896a32010-03-21 22:03:03 +00001092 .. impl-detail::
1093 This function is intimately bound to CPython implementation details and
1094 thus not likely to be implemented elsewhere.
1095
Georg Brandl116aa622007-08-15 14:28:22 +00001096
Yury Selivanovd4cbbeb2015-05-31 17:13:08 -04001097.. function:: set_coroutine_wrapper(wrapper)
1098
Yury Selivanov5376ba92015-06-22 12:19:30 -04001099 Allows intercepting creation of :term:`coroutine` objects (only ones that
1100 are created by an :keyword:`async def` function; generators decorated with
1101 :func:`types.coroutine` or :func:`asyncio.coroutine` will not be
1102 intercepted).
Yury Selivanovd4cbbeb2015-05-31 17:13:08 -04001103
Yury Selivanov66f88282015-06-24 11:04:15 -04001104 The *wrapper* argument must be either:
Yury Selivanovd4cbbeb2015-05-31 17:13:08 -04001105
1106 * a callable that accepts one argument (a coroutine object);
1107 * ``None``, to reset the wrapper.
1108
1109 If called twice, the new wrapper replaces the previous one. The function
1110 is thread-specific.
1111
Yury Selivanovaab3c4a2015-06-02 18:43:51 -04001112 The *wrapper* callable cannot define new coroutines directly or indirectly::
1113
1114 def wrapper(coro):
1115 async def wrap(coro):
1116 return await coro
1117 return wrap(coro)
1118 sys.set_coroutine_wrapper(wrapper)
1119
Yury Selivanov66f88282015-06-24 11:04:15 -04001120 async def foo():
1121 pass
Yury Selivanovaab3c4a2015-06-02 18:43:51 -04001122
1123 # The following line will fail with a RuntimeError, because
Zachary Ware3d3aedc2015-07-07 00:07:25 -05001124 # ``wrapper`` creates a ``wrap(coro)`` coroutine:
Yury Selivanovaab3c4a2015-06-02 18:43:51 -04001125 foo()
1126
Yury Selivanovd4cbbeb2015-05-31 17:13:08 -04001127 See also :func:`get_coroutine_wrapper`.
1128
1129 .. versionadded:: 3.5
1130 See :pep:`492` for more details.
1131
1132 .. note::
1133 This function has been added on a provisional basis (see :pep:`411`
Yury Selivanov4180e432015-06-04 11:10:24 -04001134 for details.) Use it only for debugging purposes.
Yury Selivanovd4cbbeb2015-05-31 17:13:08 -04001135
1136
Georg Brandl116aa622007-08-15 14:28:22 +00001137.. data:: stdin
1138 stdout
1139 stderr
1140
Antoine Pitrou7158e062011-12-15 16:25:34 +01001141 :term:`File objects <file object>` used by the interpreter for standard
1142 input, output and errors:
Georg Brandl116aa622007-08-15 14:28:22 +00001143
Antoine Pitrou7158e062011-12-15 16:25:34 +01001144 * ``stdin`` is used for all interactive input (including calls to
1145 :func:`input`);
1146 * ``stdout`` is used for the output of :func:`print` and :term:`expression`
1147 statements and for the prompts of :func:`input`;
1148 * The interpreter's own prompts and its error messages go to ``stderr``.
1149
Antoine Pitrou2d1ec062014-05-15 22:38:56 +02001150 These streams are regular :term:`text files <text file>` like those
1151 returned by the :func:`open` function. Their parameters are chosen as
1152 follows:
Antoine Pitrou7158e062011-12-15 16:25:34 +01001153
1154 * The character encoding is platform-dependent. Under Windows, if the stream
Serhiy Storchakafbc1c262013-11-29 12:17:13 +02001155 is interactive (that is, if its :meth:`isatty` method returns ``True``), the
Antoine Pitrou7158e062011-12-15 16:25:34 +01001156 console codepage is used, otherwise the ANSI code page. Under other
1157 platforms, the locale encoding is used (see :meth:`locale.getpreferredencoding`).
1158
1159 Under all platforms though, you can override this value by setting the
Antoine Pitrou2d1ec062014-05-15 22:38:56 +02001160 :envvar:`PYTHONIOENCODING` environment variable before starting Python.
Antoine Pitrou7158e062011-12-15 16:25:34 +01001161
1162 * When interactive, standard streams are line-buffered. Otherwise, they
1163 are block-buffered like regular text files. You can override this
1164 value with the :option:`-u` command-line option.
1165
Antoine Pitrou2d1ec062014-05-15 22:38:56 +02001166 .. note::
Benjamin Peterson4199d602009-05-12 20:47:57 +00001167
Antoine Pitrou2d1ec062014-05-15 22:38:56 +02001168 To write or read binary data from/to the standard streams, use the
1169 underlying binary :data:`~io.TextIOBase.buffer` object. For example, to
1170 write bytes to :data:`stdout`, use ``sys.stdout.buffer.write(b'abc')``.
Benjamin Peterson995bb472009-06-14 18:41:18 +00001171
Antoine Pitrou2d1ec062014-05-15 22:38:56 +02001172 However, if you are writing a library (and do not control in which
1173 context its code will be executed), be aware that the standard streams
1174 may be replaced with file-like objects like :class:`io.StringIO` which
1175 do not support the :attr:`~io.BufferedIOBase.buffer` attribute.
Benjamin Petersoneb9fc522008-12-07 14:58:03 +00001176
Georg Brandl116aa622007-08-15 14:28:22 +00001177
1178.. data:: __stdin__
1179 __stdout__
1180 __stderr__
1181
1182 These objects contain the original values of ``stdin``, ``stderr`` and
Benjamin Petersond23f8222009-04-05 19:13:16 +00001183 ``stdout`` at the start of the program. They are used during finalization,
1184 and could be useful to print to the actual standard stream no matter if the
1185 ``sys.std*`` object has been redirected.
Georg Brandl116aa622007-08-15 14:28:22 +00001186
Benjamin Petersond23f8222009-04-05 19:13:16 +00001187 It can also be used to restore the actual files to known working file objects
1188 in case they have been overwritten with a broken object. However, the
1189 preferred way to do this is to explicitly save the previous stream before
1190 replacing it, and restore the saved object.
Christian Heimes58cb1b82007-11-13 02:19:40 +00001191
Benjamin Petersond23f8222009-04-05 19:13:16 +00001192 .. note::
1193 Under some conditions ``stdin``, ``stdout`` and ``stderr`` as well as the
1194 original values ``__stdin__``, ``__stdout__`` and ``__stderr__`` can be
1195 None. It is usually the case for Windows GUI apps that aren't connected
1196 to a console and Python apps started with :program:`pythonw`.
Christian Heimes58cb1b82007-11-13 02:19:40 +00001197
Georg Brandl116aa622007-08-15 14:28:22 +00001198
Victor Stinnerd5c355c2011-04-30 14:53:09 +02001199.. data:: thread_info
1200
1201 A :term:`struct sequence` holding information about the thread
1202 implementation.
1203
Georg Brandl44ea77b2013-03-28 13:28:44 +01001204 .. tabularcolumns:: |l|p{0.7\linewidth}|
1205
Victor Stinnerd5c355c2011-04-30 14:53:09 +02001206 +------------------+---------------------------------------------------------+
1207 | Attribute | Explanation |
1208 +==================+=========================================================+
1209 | :const:`name` | Name of the thread implementation: |
1210 | | |
1211 | | * ``'nt'``: Windows threads |
Victor Stinnerd5c355c2011-04-30 14:53:09 +02001212 | | * ``'pthread'``: POSIX threads |
1213 | | * ``'solaris'``: Solaris threads |
1214 +------------------+---------------------------------------------------------+
1215 | :const:`lock` | Name of the lock implementation: |
1216 | | |
1217 | | * ``'semaphore'``: a lock uses a semaphore |
1218 | | * ``'mutex+cond'``: a lock uses a mutex |
1219 | | and a condition variable |
1220 | | * ``None`` if this information is unknown |
1221 +------------------+---------------------------------------------------------+
1222 | :const:`version` | Name and version of the thread library. It is a string, |
1223 | | or ``None`` if these informations are unknown. |
1224 +------------------+---------------------------------------------------------+
1225
1226 .. versionadded:: 3.3
1227
1228
Georg Brandl116aa622007-08-15 14:28:22 +00001229.. data:: tracebacklimit
1230
1231 When this variable is set to an integer value, it determines the maximum number
1232 of levels of traceback information printed when an unhandled exception occurs.
1233 The default is ``1000``. When set to ``0`` or less, all traceback information
1234 is suppressed and only the exception type and value are printed.
1235
1236
1237.. data:: version
1238
1239 A string containing the version number of the Python interpreter plus additional
Georg Brandle42a59d2010-07-31 20:05:31 +00001240 information on the build number and compiler used. This string is displayed
1241 when the interactive interpreter is started. Do not extract version information
1242 out of it, rather, use :data:`version_info` and the functions provided by the
1243 :mod:`platform` module.
Georg Brandl116aa622007-08-15 14:28:22 +00001244
1245
1246.. data:: api_version
1247
1248 The C API version for this interpreter. Programmers may find this useful when
1249 debugging version conflicts between Python and extension modules.
1250
Georg Brandl116aa622007-08-15 14:28:22 +00001251
1252.. data:: version_info
1253
1254 A tuple containing the five components of the version number: *major*, *minor*,
1255 *micro*, *releaselevel*, and *serial*. All values except *releaselevel* are
1256 integers; the release level is ``'alpha'``, ``'beta'``, ``'candidate'``, or
1257 ``'final'``. The ``version_info`` value corresponding to the Python version 2.0
Eric Smith0e5b5622009-02-06 01:32:42 +00001258 is ``(2, 0, 0, 'final', 0)``. The components can also be accessed by name,
1259 so ``sys.version_info[0]`` is equivalent to ``sys.version_info.major``
1260 and so on.
Georg Brandl116aa622007-08-15 14:28:22 +00001261
Raymond Hettinger35a88362009-04-09 00:08:24 +00001262 .. versionchanged:: 3.1
Georg Brandl67b21b72010-08-17 15:07:14 +00001263 Added named component attributes.
Georg Brandl116aa622007-08-15 14:28:22 +00001264
1265.. data:: warnoptions
1266
1267 This is an implementation detail of the warnings framework; do not modify this
1268 value. Refer to the :mod:`warnings` module for more information on the warnings
1269 framework.
1270
1271
1272.. data:: winver
1273
1274 The version number used to form registry keys on Windows platforms. This is
1275 stored as string resource 1000 in the Python DLL. The value is normally the
1276 first three characters of :const:`version`. It is provided in the :mod:`sys`
1277 module for informational purposes; modifying this value has no effect on the
1278 registry keys used by Python. Availability: Windows.
Mark Dickinsonbe5846b2010-07-02 20:26:07 +00001279
Antoine Pitrou9583cac2010-10-21 13:42:28 +00001280
1281.. data:: _xoptions
1282
1283 A dictionary of the various implementation-specific flags passed through
1284 the :option:`-X` command-line option. Option names are either mapped to
Martin Panter1050d2d2016-07-26 11:18:21 +02001285 their values, if given explicitly, or to :const:`True`. Example:
1286
1287 .. code-block:: shell-session
Antoine Pitrou9583cac2010-10-21 13:42:28 +00001288
1289 $ ./python -Xa=b -Xc
1290 Python 3.2a3+ (py3k, Oct 16 2010, 20:14:50)
1291 [GCC 4.4.3] on linux2
1292 Type "help", "copyright", "credits" or "license" for more information.
1293 >>> import sys
1294 >>> sys._xoptions
1295 {'a': 'b', 'c': True}
1296
1297 .. impl-detail::
1298
1299 This is a CPython-specific way of accessing options passed through
1300 :option:`-X`. Other implementations may export them through other
1301 means, or not at all.
1302
1303 .. versionadded:: 3.2
1304
1305
Mark Dickinsonbe5846b2010-07-02 20:26:07 +00001306.. rubric:: Citations
1307
Serhiy Storchakaa4d170d2013-12-23 18:20:51 +02001308.. [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\ .