cpython-lru_cache-weakref: Doc/library/sys.rst annotate

annotate Doc/library/sys.rst @ 54294:dba767bc3155 legacy-trunk

remove mention of old ctypes version

author	Benjamin Peterson <benjamin@python.org>
date	Sat, 23 May 2009 20:59:09 +0000
parents	e70a6c46b3ab
children	dddf424bd669

rev	line source
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2 :mod:`sys` --- System-specific parameters and functions
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	3 =======================================================
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	4
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	5 .. module:: sys
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	6 :synopsis: Access system-specific parameters and functions.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	7
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	8
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	9 This module provides access to some variables used or maintained by the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	10 interpreter and to functions that interact strongly with the interpreter. It is
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	11 always available.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	12
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	13
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	14 .. data:: argv
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	15
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	16 The list of command line arguments passed to a Python script. ``argv[0]`` is the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	17 script name (it is operating system dependent whether this is a full pathname or
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	18 not). If the command was executed using the :option:`-c` command line option to
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	19 the interpreter, ``argv[0]`` is set to the string ``'-c'``. If no script name
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	20 was passed to the Python interpreter, ``argv[0]`` is the empty string.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	21
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	22 To loop over the standard input, or the list of files given on the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	23 command line, see the :mod:`fileinput` module.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	24
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	25
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	26 .. data:: byteorder
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	27
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	28 An indicator of the native byte order. This will have the value ``'big'`` on
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	29 big-endian (most-significant byte first) platforms, and ``'little'`` on
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	30 little-endian (least-significant byte first) platforms.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	31
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	32 .. versionadded:: 2.0
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	33
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	34
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	35 .. data:: subversion
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	36
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	37 A triple (repo, branch, version) representing the Subversion information of the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	38 Python interpreter. repo is the name of the repository, ``'CPython'``.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	39 branch is a string of one of the forms ``'trunk'``, ``'branches/name'`` or
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	40 ``'tags/name'``. version is the output of ``svnversion``, if the interpreter
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	41 was built from a Subversion checkout; it contains the revision number (range)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	42 and possibly a trailing 'M' if there were local modifications. If the tree was
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	43 exported (or svnversion was not available), it is the revision of
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	44 ``Include/patchlevel.h`` if the branch is a tag. Otherwise, it is ``None``.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	45
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	46 .. versionadded:: 2.5
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	47
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	48
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	49 .. data:: builtin_module_names
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	50
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	51 A tuple of strings giving the names of all modules that are compiled into this
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	52 Python interpreter. (This information is not available in any other way ---
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	53 ``modules.keys()`` only lists the imported modules.)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	54
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	55
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	56 .. data:: copyright
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	57
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	58 A string containing the copyright pertaining to the Python interpreter.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	59
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	60
45143 8fdd6d62ea55 Patch #1953 Christian Heimes <christian@cheimes.de> parents: 45025 diff changeset	61 .. function:: _clear_type_cache()
8fdd6d62ea55 Patch #1953 Christian Heimes <christian@cheimes.de> parents: 45025 diff changeset	62
8fdd6d62ea55 Patch #1953 Christian Heimes <christian@cheimes.de> parents: 45025 diff changeset	63 Clear the internal type cache. The type cache is used to speed up attribute
8fdd6d62ea55 Patch #1953 Christian Heimes <christian@cheimes.de> parents: 45025 diff changeset	64 and method lookups. Use the function only to drop unnecessary references
8fdd6d62ea55 Patch #1953 Christian Heimes <christian@cheimes.de> parents: 45025 diff changeset	65 during reference leak debugging.
8fdd6d62ea55 Patch #1953 Christian Heimes <christian@cheimes.de> parents: 45025 diff changeset	66
8fdd6d62ea55 Patch #1953 Christian Heimes <christian@cheimes.de> parents: 45025 diff changeset	67 This function should be used for internal and specialized purposes only.
45025 ea3fe302d392 Added clear cache methods to clear the internal type lookup cache for ref leak test runs. Christian Heimes <christian@cheimes.de> parents: 44822 diff changeset	68
ea3fe302d392 Added clear cache methods to clear the internal type lookup cache for ref leak test runs. Christian Heimes <christian@cheimes.de> parents: 44822 diff changeset	69 .. versionadded:: 2.6
ea3fe302d392 Added clear cache methods to clear the internal type lookup cache for ref leak test runs. Christian Heimes <christian@cheimes.de> parents: 44822 diff changeset	70
ea3fe302d392 Added clear cache methods to clear the internal type lookup cache for ref leak test runs. Christian Heimes <christian@cheimes.de> parents: 44822 diff changeset	71
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	72 .. function:: _current_frames()
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	73
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	74 Return a dictionary mapping each thread's identifier to the topmost stack frame
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	75 currently active in that thread at the time the function is called. Note that
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	76 functions in the :mod:`traceback` module can build the call stack given such a
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	77 frame.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	78
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	79 This is most useful for debugging deadlock: this function does not require the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	80 deadlocked threads' cooperation, and such threads' call stacks are frozen for as
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	81 long as they remain deadlocked. The frame returned for a non-deadlocked thread
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	82 may bear no relationship to that thread's current activity by the time calling
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	83 code examines the frame.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	84
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	85 This function should be used for internal and specialized purposes only.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	86
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	87 .. versionadded:: 2.5
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	88
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	89
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	90 .. data:: dllhandle
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	91
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	92 Integer specifying the handle of the Python DLL. Availability: Windows.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	93
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	94
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	95 .. function:: displayhook(value)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	96
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	97 If value is not ``None``, this function prints it to ``sys.stdout``, and saves
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	98 it in ``__builtin__._``.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	99
44103 1e266015cf5b Add more entries to the glossary. Georg Brandl <georg@python.org> parents: 44089 diff changeset	100 ``sys.displayhook`` is called on the result of evaluating an :term:`expression`
1e266015cf5b Add more entries to the glossary. Georg Brandl <georg@python.org> parents: 44089 diff changeset	101 entered in an interactive Python session. The display of these values can be
1e266015cf5b Add more entries to the glossary. Georg Brandl <georg@python.org> parents: 44089 diff changeset	102 customized by assigning another one-argument function to ``sys.displayhook``.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	103
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	104
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	105 .. function:: excepthook(type, value, traceback)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	106
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	107 This function prints out a given traceback and exception to ``sys.stderr``.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	108
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	109 When an exception is raised and uncaught, the interpreter calls
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	110 ``sys.excepthook`` with three arguments, the exception class, exception
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	111 instance, and a traceback object. In an interactive session this happens just
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	112 before control is returned to the prompt; in a Python program this happens just
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	113 before the program exits. The handling of such top-level exceptions can be
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	114 customized by assigning another three-argument function to ``sys.excepthook``.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	115
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	116
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	117 .. data:: __displayhook__
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	118 __excepthook__
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	119
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	120 These objects contain the original values of ``displayhook`` and ``excepthook``
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	121 at the start of the program. They are saved so that ``displayhook`` and
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	122 ``excepthook`` can be restored in case they happen to get replaced with broken
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	123 objects.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	124
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	125
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	126 .. function:: exc_info()
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	127
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	128 This function returns a tuple of three values that give information about the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	129 exception that is currently being handled. The information returned is specific
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	130 both to the current thread and to the current stack frame. If the current stack
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	131 frame is not handling an exception, the information is taken from the calling
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	132 stack frame, or its caller, and so on until a stack frame is found that is
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	133 handling an exception. Here, "handling an exception" is defined as "executing
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	134 or having executed an except clause." For any stack frame, only information
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	135 about the most recently handled exception is accessible.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	136
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	137 .. index:: object: traceback
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	138
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	139 If no exception is being handled anywhere on the stack, a tuple containing three
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	140 ``None`` values is returned. Otherwise, the values returned are ``(type, value,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	141 traceback)``. Their meaning is: type gets the exception type of the exception
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	142 being handled (a class object); value gets the exception parameter (its
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	143 :dfn:`associated value` or the second argument to :keyword:`raise`, which is
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	144 always a class instance if the exception type is a class object); traceback
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	145 gets a traceback object (see the Reference Manual) which encapsulates the call
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	146 stack at the point where the exception originally occurred.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	147
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	148 If :func:`exc_clear` is called, this function will return three ``None`` values
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	149 until either another exception is raised in the current thread or the execution
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	150 stack returns to a frame where another exception is being handled.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	151
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	152 .. warning::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	153
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	154 Assigning the traceback return value to a local variable in a function that is
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	155 handling an exception will cause a circular reference. This will prevent
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	156 anything referenced by a local variable in the same function or by the traceback
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	157 from being garbage collected. Since most functions don't need access to the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	158 traceback, the best solution is to use something like ``exctype, value =
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	159 sys.exc_info()[:2]`` to extract only the exception type and value. If you do
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	160 need the traceback, make sure to delete it after use (best done with a
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	161 :keyword:`try` ... :keyword:`finally` statement) or to call :func:`exc_info` in
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	162 a function that does not itself handle an exception.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	163
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	164 .. note::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	165
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	166 Beginning with Python 2.2, such cycles are automatically reclaimed when garbage
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	167 collection is enabled and they become unreachable, but it remains more efficient
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	168 to avoid creating cycles.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	169
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	170
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	171 .. function:: exc_clear()
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	172
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	173 This function clears all information relating to the current or last exception
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	174 that occurred in the current thread. After calling this function,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	175 :func:`exc_info` will return three ``None`` values until another exception is
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	176 raised in the current thread or the execution stack returns to a frame where
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	177 another exception is being handled.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	178
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	179 This function is only needed in only a few obscure situations. These include
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	180 logging and error handling systems that report information on the last or
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	181 current exception. This function can also be used to try to free resources and
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	182 trigger object finalization, though no guarantee is made as to what objects will
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	183 be freed, if any.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	184
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	185 .. versionadded:: 2.3
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	186
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	187
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	188 .. data:: exc_type
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	189 exc_value
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	190 exc_traceback
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	191
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	192 .. deprecated:: 1.5
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	193 Use :func:`exc_info` instead.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	194
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	195 Since they are global variables, they are not specific to the current thread, so
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	196 their use is not safe in a multi-threaded program. When no exception is being
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	197 handled, ``exc_type`` is set to ``None`` and the other two are undefined.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	198
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	199
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	200 .. data:: exec_prefix
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	201
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	202 A string giving the site-specific directory prefix where the platform-dependent
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	203 Python files are installed; by default, this is also ``'/usr/local'``. This can
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	204 be set at build time with the :option:`--exec-prefix` argument to the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	205 :program:`configure` script. Specifically, all configuration files (e.g. the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	206 :file:`pyconfig.h` header file) are installed in the directory ``exec_prefix +
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	207 '/lib/pythonversion/config'``, and shared library modules are installed in
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	208 ``exec_prefix + '/lib/pythonversion/lib-dynload'``, where version is equal to
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	209 ``version[:3]``.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	210
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	211
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	212 .. data:: executable
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	213
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	214 A string giving the name of the executable binary for the Python interpreter, on
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	215 systems where this makes sense.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	216
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	217
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	218 .. function:: exit([arg])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	219
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	220 Exit from Python. This is implemented by raising the :exc:`SystemExit`
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	221 exception, so cleanup actions specified by finally clauses of :keyword:`try`
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	222 statements are honored, and it is possible to intercept the exit attempt at an
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	223 outer level. The optional argument arg can be an integer giving the exit
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	224 status (defaulting to zero), or another type of object. If it is an integer,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	225 zero is considered "successful termination" and any nonzero value is considered
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	226 "abnormal termination" by shells and the like. Most systems require it to be in
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	227 the range 0-127, and produce undefined results otherwise. Some systems have a
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	228 convention for assigning specific meanings to specific exit codes, but these are
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	229 generally underdeveloped; Unix programs generally use 2 for command line syntax
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	230 errors and 1 for all other kind of errors. If another type of object is passed,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	231 ``None`` is equivalent to passing zero, and any other object is printed to
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	232 ``sys.stderr`` and results in an exit code of 1. In particular,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	233 ``sys.exit("some error message")`` is a quick way to exit a program when an
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	234 error occurs.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	235
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	236
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	237 .. data:: exitfunc
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	238
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	239 This value is not actually defined by the module, but can be set by the user (or
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	240 by a program) to specify a clean-up action at program exit. When set, it should
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	241 be a parameterless function. This function will be called when the interpreter
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	242 exits. Only one function may be installed in this way; to allow multiple
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	243 functions which will be called at termination, use the :mod:`atexit` module.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	244
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	245 .. note::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	246
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	247 The exit function is not called when the program is killed by a signal, when a
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	248 Python fatal internal error is detected, or when ``os._exit()`` is called.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	249
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	250 .. deprecated:: 2.4
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	251 Use :mod:`atexit` instead.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	252
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	253
44669 9b6d348cec87 Applied patch #1816: sys.flags patch Christian Heimes <christian@cheimes.de> parents: 44566 diff changeset	254 .. data:: flags
9b6d348cec87 Applied patch #1816: sys.flags patch Christian Heimes <christian@cheimes.de> parents: 44566 diff changeset	255
9b6d348cec87 Applied patch #1816: sys.flags patch Christian Heimes <christian@cheimes.de> parents: 44566 diff changeset	256 The struct sequence flags exposes the status of command line flags. The
9b6d348cec87 Applied patch #1816: sys.flags patch Christian Heimes <christian@cheimes.de> parents: 44566 diff changeset	257 attributes are read only.
9b6d348cec87 Applied patch #1816: sys.flags patch Christian Heimes <christian@cheimes.de> parents: 44566 diff changeset	258
9b6d348cec87 Applied patch #1816: sys.flags patch Christian Heimes <christian@cheimes.de> parents: 44566 diff changeset	259 +------------------------------+------------------------------------------+
9b6d348cec87 Applied patch #1816: sys.flags patch Christian Heimes <christian@cheimes.de> parents: 44566 diff changeset	260 \| attribute \| flag \|
9b6d348cec87 Applied patch #1816: sys.flags patch Christian Heimes <christian@cheimes.de> parents: 44566 diff changeset	261 +==============================+==========================================+
9b6d348cec87 Applied patch #1816: sys.flags patch Christian Heimes <christian@cheimes.de> parents: 44566 diff changeset	262 \| :const:`debug` \| -d \|
9b6d348cec87 Applied patch #1816: sys.flags patch Christian Heimes <christian@cheimes.de> parents: 44566 diff changeset	263 +------------------------------+------------------------------------------+
9b6d348cec87 Applied patch #1816: sys.flags patch Christian Heimes <christian@cheimes.de> parents: 44566 diff changeset	264 \| :const:`py3k_warning` \| -3 \|
9b6d348cec87 Applied patch #1816: sys.flags patch Christian Heimes <christian@cheimes.de> parents: 44566 diff changeset	265 +------------------------------+------------------------------------------+
9b6d348cec87 Applied patch #1816: sys.flags patch Christian Heimes <christian@cheimes.de> parents: 44566 diff changeset	266 \| :const:`division_warning` \| -Q \|
9b6d348cec87 Applied patch #1816: sys.flags patch Christian Heimes <christian@cheimes.de> parents: 44566 diff changeset	267 +------------------------------+------------------------------------------+
9b6d348cec87 Applied patch #1816: sys.flags patch Christian Heimes <christian@cheimes.de> parents: 44566 diff changeset	268 \| :const:`division_new` \| -Qnew \|
9b6d348cec87 Applied patch #1816: sys.flags patch Christian Heimes <christian@cheimes.de> parents: 44566 diff changeset	269 +------------------------------+------------------------------------------+
9b6d348cec87 Applied patch #1816: sys.flags patch Christian Heimes <christian@cheimes.de> parents: 44566 diff changeset	270 \| :const:`inspect` \| -i \|
9b6d348cec87 Applied patch #1816: sys.flags patch Christian Heimes <christian@cheimes.de> parents: 44566 diff changeset	271 +------------------------------+------------------------------------------+
9b6d348cec87 Applied patch #1816: sys.flags patch Christian Heimes <christian@cheimes.de> parents: 44566 diff changeset	272 \| :const:`interactive` \| -i \|
9b6d348cec87 Applied patch #1816: sys.flags patch Christian Heimes <christian@cheimes.de> parents: 44566 diff changeset	273 +------------------------------+------------------------------------------+
9b6d348cec87 Applied patch #1816: sys.flags patch Christian Heimes <christian@cheimes.de> parents: 44566 diff changeset	274 \| :const:`optimize` \| -O or -OO \|
9b6d348cec87 Applied patch #1816: sys.flags patch Christian Heimes <christian@cheimes.de> parents: 44566 diff changeset	275 +------------------------------+------------------------------------------+
9b6d348cec87 Applied patch #1816: sys.flags patch Christian Heimes <christian@cheimes.de> parents: 44566 diff changeset	276 \| :const:`dont_write_bytecode` \| -B \|
9b6d348cec87 Applied patch #1816: sys.flags patch Christian Heimes <christian@cheimes.de> parents: 44566 diff changeset	277 +------------------------------+------------------------------------------+
9b6d348cec87 Applied patch #1816: sys.flags patch Christian Heimes <christian@cheimes.de> parents: 44566 diff changeset	278 \| :const:`no_site` \| -S \|
9b6d348cec87 Applied patch #1816: sys.flags patch Christian Heimes <christian@cheimes.de> parents: 44566 diff changeset	279 +------------------------------+------------------------------------------+
44678 5dfded9ad8a0 Typo fixes Andrew M. Kuchling <amk@amk.ca> parents: 44670 diff changeset	280 \| :const:`ignore_environment` \| -E \|
44669 9b6d348cec87 Applied patch #1816: sys.flags patch Christian Heimes <christian@cheimes.de> parents: 44566 diff changeset	281 +------------------------------+------------------------------------------+
9b6d348cec87 Applied patch #1816: sys.flags patch Christian Heimes <christian@cheimes.de> parents: 44566 diff changeset	282 \| :const:`tabcheck` \| -t or -tt \|
9b6d348cec87 Applied patch #1816: sys.flags patch Christian Heimes <christian@cheimes.de> parents: 44566 diff changeset	283 +------------------------------+------------------------------------------+
9b6d348cec87 Applied patch #1816: sys.flags patch Christian Heimes <christian@cheimes.de> parents: 44566 diff changeset	284 \| :const:`verbose` \| -v \|
9b6d348cec87 Applied patch #1816: sys.flags patch Christian Heimes <christian@cheimes.de> parents: 44566 diff changeset	285 +------------------------------+------------------------------------------+
9b6d348cec87 Applied patch #1816: sys.flags patch Christian Heimes <christian@cheimes.de> parents: 44566 diff changeset	286 \| :const:`unicode` \| -U \|
9b6d348cec87 Applied patch #1816: sys.flags patch Christian Heimes <christian@cheimes.de> parents: 44566 diff changeset	287 +------------------------------+------------------------------------------+
9b6d348cec87 Applied patch #1816: sys.flags patch Christian Heimes <christian@cheimes.de> parents: 44566 diff changeset	288
9b6d348cec87 Applied patch #1816: sys.flags patch Christian Heimes <christian@cheimes.de> parents: 44566 diff changeset	289 .. versionadded:: 2.6
9b6d348cec87 Applied patch #1816: sys.flags patch Christian Heimes <christian@cheimes.de> parents: 44566 diff changeset	290
9b6d348cec87 Applied patch #1816: sys.flags patch Christian Heimes <christian@cheimes.de> parents: 44566 diff changeset	291
44085 c218d1ac916e Feature #1534 Christian Heimes <christian@cheimes.de> parents: 44041 diff changeset	292 .. data:: float_info
c218d1ac916e Feature #1534 Christian Heimes <christian@cheimes.de> parents: 44041 diff changeset	293
44670 d66e5837aa57 Now that I've learnt about structseq objects I felt like converting sys.float_info to a structseq. It's Christian Heimes <christian@cheimes.de> parents: 44669 diff changeset	294 A structseq holding information about the float type. It contains low level
44085 c218d1ac916e Feature #1534 Christian Heimes <christian@cheimes.de> parents: 44041 diff changeset	295 information about the precision and internal representation. Please study
c218d1ac916e Feature #1534 Christian Heimes <christian@cheimes.de> parents: 44041 diff changeset	296 your system's :file:`float.h` for more information.
c218d1ac916e Feature #1534 Christian Heimes <christian@cheimes.de> parents: 44041 diff changeset	297
c218d1ac916e Feature #1534 Christian Heimes <christian@cheimes.de> parents: 44041 diff changeset	298 +---------------------+--------------------------------------------------+
44670 d66e5837aa57 Now that I've learnt about structseq objects I felt like converting sys.float_info to a structseq. It's Christian Heimes <christian@cheimes.de> parents: 44669 diff changeset	299 \| attribute \| explanation \|
44085 c218d1ac916e Feature #1534 Christian Heimes <christian@cheimes.de> parents: 44041 diff changeset	300 +=====================+==================================================+
c218d1ac916e Feature #1534 Christian Heimes <christian@cheimes.de> parents: 44041 diff changeset	301 \| :const:`epsilon` \| Difference between 1 and the next representable \|
c218d1ac916e Feature #1534 Christian Heimes <christian@cheimes.de> parents: 44041 diff changeset	302 \| \| floating point number \|
c218d1ac916e Feature #1534 Christian Heimes <christian@cheimes.de> parents: 44041 diff changeset	303 +---------------------+--------------------------------------------------+
c218d1ac916e Feature #1534 Christian Heimes <christian@cheimes.de> parents: 44041 diff changeset	304 \| :const:`dig` \| digits (see :file:`float.h`) \|
c218d1ac916e Feature #1534 Christian Heimes <christian@cheimes.de> parents: 44041 diff changeset	305 +---------------------+--------------------------------------------------+
c218d1ac916e Feature #1534 Christian Heimes <christian@cheimes.de> parents: 44041 diff changeset	306 \| :const:`mant_dig` \| mantissa digits (see :file:`float.h`) \|
c218d1ac916e Feature #1534 Christian Heimes <christian@cheimes.de> parents: 44041 diff changeset	307 +---------------------+--------------------------------------------------+
c218d1ac916e Feature #1534 Christian Heimes <christian@cheimes.de> parents: 44041 diff changeset	308 \| :const:`max` \| maximum representable finite float \|
c218d1ac916e Feature #1534 Christian Heimes <christian@cheimes.de> parents: 44041 diff changeset	309 +---------------------+--------------------------------------------------+
c218d1ac916e Feature #1534 Christian Heimes <christian@cheimes.de> parents: 44041 diff changeset	310 \| :const:`max_exp` \| maximum int e such that radix**(e-1) is in the \|
c218d1ac916e Feature #1534 Christian Heimes <christian@cheimes.de> parents: 44041 diff changeset	311 \| \| range of finite representable floats \|
c218d1ac916e Feature #1534 Christian Heimes <christian@cheimes.de> parents: 44041 diff changeset	312 +---------------------+--------------------------------------------------+
c218d1ac916e Feature #1534 Christian Heimes <christian@cheimes.de> parents: 44041 diff changeset	313 \| :const:`max_10_exp` \| maximum int e such that 10**e is in the \|
c218d1ac916e Feature #1534 Christian Heimes <christian@cheimes.de> parents: 44041 diff changeset	314 \| \| range of finite representable floats \|
c218d1ac916e Feature #1534 Christian Heimes <christian@cheimes.de> parents: 44041 diff changeset	315 +---------------------+--------------------------------------------------+
c218d1ac916e Feature #1534 Christian Heimes <christian@cheimes.de> parents: 44041 diff changeset	316 \| :const:`min` \| Minimum positive normalizer float \|
c218d1ac916e Feature #1534 Christian Heimes <christian@cheimes.de> parents: 44041 diff changeset	317 +---------------------+--------------------------------------------------+
c218d1ac916e Feature #1534 Christian Heimes <christian@cheimes.de> parents: 44041 diff changeset	318 \| :const:`min_exp` \| minimum int e such that radix**(e-1) is a \|
c218d1ac916e Feature #1534 Christian Heimes <christian@cheimes.de> parents: 44041 diff changeset	319 \| \| normalized float \|
c218d1ac916e Feature #1534 Christian Heimes <christian@cheimes.de> parents: 44041 diff changeset	320 +---------------------+--------------------------------------------------+
c218d1ac916e Feature #1534 Christian Heimes <christian@cheimes.de> parents: 44041 diff changeset	321 \| :const:`min_10_exp` \| minimum int e such that 10**e is a normalized \|
c218d1ac916e Feature #1534 Christian Heimes <christian@cheimes.de> parents: 44041 diff changeset	322 \| \| float \|
c218d1ac916e Feature #1534 Christian Heimes <christian@cheimes.de> parents: 44041 diff changeset	323 +---------------------+--------------------------------------------------+
c218d1ac916e Feature #1534 Christian Heimes <christian@cheimes.de> parents: 44041 diff changeset	324 \| :const:`radix` \| radix of exponent \|
c218d1ac916e Feature #1534 Christian Heimes <christian@cheimes.de> parents: 44041 diff changeset	325 +---------------------+--------------------------------------------------+
c218d1ac916e Feature #1534 Christian Heimes <christian@cheimes.de> parents: 44041 diff changeset	326 \| :const:`rounds` \| addition rounds (see :file:`float.h`) \|
c218d1ac916e Feature #1534 Christian Heimes <christian@cheimes.de> parents: 44041 diff changeset	327 +---------------------+--------------------------------------------------+
c218d1ac916e Feature #1534 Christian Heimes <christian@cheimes.de> parents: 44041 diff changeset	328
c218d1ac916e Feature #1534 Christian Heimes <christian@cheimes.de> parents: 44041 diff changeset	329 .. note::
c218d1ac916e Feature #1534 Christian Heimes <christian@cheimes.de> parents: 44041 diff changeset	330
c218d1ac916e Feature #1534 Christian Heimes <christian@cheimes.de> parents: 44041 diff changeset	331 The information in the table is simplified.
c218d1ac916e Feature #1534 Christian Heimes <christian@cheimes.de> parents: 44041 diff changeset	332
44089 21321dcf0ab5 Added one more missing versionadded tag Christian Heimes <christian@cheimes.de> parents: 44085 diff changeset	333 .. versionadded:: 2.6
21321dcf0ab5 Added one more missing versionadded tag Christian Heimes <christian@cheimes.de> parents: 44085 diff changeset	334
44085 c218d1ac916e Feature #1534 Christian Heimes <christian@cheimes.de> parents: 44041 diff changeset	335
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	336 .. function:: getcheckinterval()
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	337
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	338 Return the interpreter's "check interval"; see :func:`setcheckinterval`.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	339
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	340 .. versionadded:: 2.3
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	341
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	342
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	343 .. function:: getdefaultencoding()
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	344
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	345 Return the name of the current default string encoding used by the Unicode
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	346 implementation.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	347
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	348 .. versionadded:: 2.0
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	349
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	350
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	351 .. function:: getdlopenflags()
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	352
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	353 Return the current value of the flags that are used for :cfunc:`dlopen` calls.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	354 The flag constants are defined in the :mod:`dl` and :mod:`DLFCN` modules.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	355 Availability: Unix.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	356
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	357 .. versionadded:: 2.2
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	358
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	359
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	360 .. function:: getfilesystemencoding()
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	361
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	362 Return the name of the encoding used to convert Unicode filenames into system
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	363 file names, or ``None`` if the system default encoding is used. The result value
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	364 depends on the operating system:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	365
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	366 * On Windows 9x, the encoding is "mbcs".
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	367
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	368 * On Mac OS X, the encoding is "utf-8".
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	369
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	370 * On Unix, the encoding is the user's preference according to the result of
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	371 nl_langinfo(CODESET), or :const:`None` if the ``nl_langinfo(CODESET)`` failed.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	372
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	373 * On Windows NT+, file names are Unicode natively, so no conversion is
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	374 performed. :func:`getfilesystemencoding` still returns ``'mbcs'``, as this is
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	375 the encoding that applications should use when they explicitly want to convert
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	376 Unicode strings to byte strings that are equivalent when used as file names.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	377
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	378 .. versionadded:: 2.3
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	379
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	380
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	381 .. function:: getrefcount(object)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	382
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	383 Return the reference count of the object. The count returned is generally one
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	384 higher than you might expect, because it includes the (temporary) reference as
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	385 an argument to :func:`getrefcount`.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	386
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	387
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	388 .. function:: getrecursionlimit()
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	389
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	390 Return the current value of the recursion limit, the maximum depth of the Python
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	391 interpreter stack. This limit prevents infinite recursion from causing an
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	392 overflow of the C stack and crashing Python. It can be set by
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	393 :func:`setrecursionlimit`.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	394
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	395
47925 fd054e73e2f2 Added garbage collector overhead and optional default return value to Robert Schuppenies <okkotonushi@googlemail.com> parents: 47897 diff changeset	396 .. function:: getsizeof(object[, default])
47419 88bd07c0a847 Issue #2898: Added sys.getsizeof() to retrieve size of objects in bytes. Robert Schuppenies <okkotonushi@googlemail.com> parents: 47194 diff changeset	397
88bd07c0a847 Issue #2898: Added sys.getsizeof() to retrieve size of objects in bytes. Robert Schuppenies <okkotonushi@googlemail.com> parents: 47194 diff changeset	398 Return the size of an object in bytes. The object can be any type of
88bd07c0a847 Issue #2898: Added sys.getsizeof() to retrieve size of objects in bytes. Robert Schuppenies <okkotonushi@googlemail.com> parents: 47194 diff changeset	399 object. All built-in objects will return correct results, but this
47925 fd054e73e2f2 Added garbage collector overhead and optional default return value to Robert Schuppenies <okkotonushi@googlemail.com> parents: 47897 diff changeset	400 does not have to hold true for third-party extensions as it is implementation
47419 88bd07c0a847 Issue #2898: Added sys.getsizeof() to retrieve size of objects in bytes. Robert Schuppenies <okkotonushi@googlemail.com> parents: 47194 diff changeset	401 specific.
88bd07c0a847 Issue #2898: Added sys.getsizeof() to retrieve size of objects in bytes. Robert Schuppenies <okkotonushi@googlemail.com> parents: 47194 diff changeset	402
47925 fd054e73e2f2 Added garbage collector overhead and optional default return value to Robert Schuppenies <okkotonushi@googlemail.com> parents: 47897 diff changeset	403 The default argument allows to define a value which will be returned
fd054e73e2f2 Added garbage collector overhead and optional default return value to Robert Schuppenies <okkotonushi@googlemail.com> parents: 47897 diff changeset	404 if the object type does not provide means to retrieve the size and would
50508 c52177f36852 Remove trailing whitespace. Georg Brandl <georg@python.org> parents: 49777 diff changeset	405 cause a `TypeError`.
47925 fd054e73e2f2 Added garbage collector overhead and optional default return value to Robert Schuppenies <okkotonushi@googlemail.com> parents: 47897 diff changeset	406
fd054e73e2f2 Added garbage collector overhead and optional default return value to Robert Schuppenies <okkotonushi@googlemail.com> parents: 47897 diff changeset	407 func:`getsizeof` calls the object's __sizeof__ method and adds an additional
fd054e73e2f2 Added garbage collector overhead and optional default return value to Robert Schuppenies <okkotonushi@googlemail.com> parents: 47897 diff changeset	408 garbage collector overhead if the object is managed by the garbage collector.
fd054e73e2f2 Added garbage collector overhead and optional default return value to Robert Schuppenies <okkotonushi@googlemail.com> parents: 47897 diff changeset	409
47419 88bd07c0a847 Issue #2898: Added sys.getsizeof() to retrieve size of objects in bytes. Robert Schuppenies <okkotonushi@googlemail.com> parents: 47194 diff changeset	410 .. versionadded:: 2.6
88bd07c0a847 Issue #2898: Added sys.getsizeof() to retrieve size of objects in bytes. Robert Schuppenies <okkotonushi@googlemail.com> parents: 47194 diff changeset	411
88bd07c0a847 Issue #2898: Added sys.getsizeof() to retrieve size of objects in bytes. Robert Schuppenies <okkotonushi@googlemail.com> parents: 47194 diff changeset	412
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	413 .. function:: _getframe([depth])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	414
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	415 Return a frame object from the call stack. If optional integer depth is
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	416 given, return the frame object that many calls below the top of the stack. If
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	417 that is deeper than the call stack, :exc:`ValueError` is raised. The default
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	418 for depth is zero, returning the frame at the top of the call stack.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	419
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	420 This function should be used for internal and specialized purposes only.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	421
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	422
44822 424cccfd2baa #1648: add sys.gettrace() and sys.getprofile(). Georg Brandl <georg@python.org> parents: 44820 diff changeset	423 .. function:: getprofile()
424cccfd2baa #1648: add sys.gettrace() and sys.getprofile(). Georg Brandl <georg@python.org> parents: 44820 diff changeset	424
424cccfd2baa #1648: add sys.gettrace() and sys.getprofile(). Georg Brandl <georg@python.org> parents: 44820 diff changeset	425 .. index::
424cccfd2baa #1648: add sys.gettrace() and sys.getprofile(). Georg Brandl <georg@python.org> parents: 44820 diff changeset	426 single: profile function
424cccfd2baa #1648: add sys.gettrace() and sys.getprofile(). Georg Brandl <georg@python.org> parents: 44820 diff changeset	427 single: profiler
424cccfd2baa #1648: add sys.gettrace() and sys.getprofile(). Georg Brandl <georg@python.org> parents: 44820 diff changeset	428
424cccfd2baa #1648: add sys.gettrace() and sys.getprofile(). Georg Brandl <georg@python.org> parents: 44820 diff changeset	429 Get the profiler function as set by :func:`setprofile`.
424cccfd2baa #1648: add sys.gettrace() and sys.getprofile(). Georg Brandl <georg@python.org> parents: 44820 diff changeset	430
424cccfd2baa #1648: add sys.gettrace() and sys.getprofile(). Georg Brandl <georg@python.org> parents: 44820 diff changeset	431 .. versionadded:: 2.6
424cccfd2baa #1648: add sys.gettrace() and sys.getprofile(). Georg Brandl <georg@python.org> parents: 44820 diff changeset	432
424cccfd2baa #1648: add sys.gettrace() and sys.getprofile(). Georg Brandl <georg@python.org> parents: 44820 diff changeset	433
424cccfd2baa #1648: add sys.gettrace() and sys.getprofile(). Georg Brandl <georg@python.org> parents: 44820 diff changeset	434 .. function:: gettrace()
424cccfd2baa #1648: add sys.gettrace() and sys.getprofile(). Georg Brandl <georg@python.org> parents: 44820 diff changeset	435
424cccfd2baa #1648: add sys.gettrace() and sys.getprofile(). Georg Brandl <georg@python.org> parents: 44820 diff changeset	436 .. index::
424cccfd2baa #1648: add sys.gettrace() and sys.getprofile(). Georg Brandl <georg@python.org> parents: 44820 diff changeset	437 single: trace function
424cccfd2baa #1648: add sys.gettrace() and sys.getprofile(). Georg Brandl <georg@python.org> parents: 44820 diff changeset	438 single: debugger
424cccfd2baa #1648: add sys.gettrace() and sys.getprofile(). Georg Brandl <georg@python.org> parents: 44820 diff changeset	439
424cccfd2baa #1648: add sys.gettrace() and sys.getprofile(). Georg Brandl <georg@python.org> parents: 44820 diff changeset	440 Get the trace function as set by :func:`settrace`.
424cccfd2baa #1648: add sys.gettrace() and sys.getprofile(). Georg Brandl <georg@python.org> parents: 44820 diff changeset	441
424cccfd2baa #1648: add sys.gettrace() and sys.getprofile(). Georg Brandl <georg@python.org> parents: 44820 diff changeset	442 .. note::
424cccfd2baa #1648: add sys.gettrace() and sys.getprofile(). Georg Brandl <georg@python.org> parents: 44820 diff changeset	443
424cccfd2baa #1648: add sys.gettrace() and sys.getprofile(). Georg Brandl <georg@python.org> parents: 44820 diff changeset	444 The :func:`gettrace` function is intended only for implementing debuggers,
424cccfd2baa #1648: add sys.gettrace() and sys.getprofile(). Georg Brandl <georg@python.org> parents: 44820 diff changeset	445 profilers, coverage tools and the like. Its behavior is part of the
424cccfd2baa #1648: add sys.gettrace() and sys.getprofile(). Georg Brandl <georg@python.org> parents: 44820 diff changeset	446 implementation platform, rather than part of the language definition,
424cccfd2baa #1648: add sys.gettrace() and sys.getprofile(). Georg Brandl <georg@python.org> parents: 44820 diff changeset	447 and thus may not be available in all Python implementations.
424cccfd2baa #1648: add sys.gettrace() and sys.getprofile(). Georg Brandl <georg@python.org> parents: 44820 diff changeset	448
424cccfd2baa #1648: add sys.gettrace() and sys.getprofile(). Georg Brandl <georg@python.org> parents: 44820 diff changeset	449 .. versionadded:: 2.6
424cccfd2baa #1648: add sys.gettrace() and sys.getprofile(). Georg Brandl <georg@python.org> parents: 44820 diff changeset	450
424cccfd2baa #1648: add sys.gettrace() and sys.getprofile(). Georg Brandl <georg@python.org> parents: 44820 diff changeset	451
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	452 .. function:: getwindowsversion()
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	453
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	454 Return a tuple containing five components, describing the Windows version
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	455 currently running. The elements are major, minor, build, platform, and
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	456 text. text contains a string while all other values are integers.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	457
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	458 platform may be one of the following values:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	459
46522 b7df30ac5b5a Windows x64 also falls under VER_PLATFORM_WIN32_NT. Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45990 diff changeset	460 +-----------------------------------------+-------------------------+
b7df30ac5b5a Windows x64 also falls under VER_PLATFORM_WIN32_NT. Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45990 diff changeset	461 \| Constant \| Platform \|
b7df30ac5b5a Windows x64 also falls under VER_PLATFORM_WIN32_NT. Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45990 diff changeset	462 +=========================================+=========================+
b7df30ac5b5a Windows x64 also falls under VER_PLATFORM_WIN32_NT. Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45990 diff changeset	463 \| :const:`0 (VER_PLATFORM_WIN32s)` \| Win32s on Windows 3.1 \|
b7df30ac5b5a Windows x64 also falls under VER_PLATFORM_WIN32_NT. Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45990 diff changeset	464 +-----------------------------------------+-------------------------+
b7df30ac5b5a Windows x64 also falls under VER_PLATFORM_WIN32_NT. Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45990 diff changeset	465 \| :const:`1 (VER_PLATFORM_WIN32_WINDOWS)` \| Windows 95/98/ME \|
b7df30ac5b5a Windows x64 also falls under VER_PLATFORM_WIN32_NT. Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45990 diff changeset	466 +-----------------------------------------+-------------------------+
b7df30ac5b5a Windows x64 also falls under VER_PLATFORM_WIN32_NT. Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45990 diff changeset	467 \| :const:`2 (VER_PLATFORM_WIN32_NT)` \| Windows NT/2000/XP/x64 \|
b7df30ac5b5a Windows x64 also falls under VER_PLATFORM_WIN32_NT. Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45990 diff changeset	468 +-----------------------------------------+-------------------------+
b7df30ac5b5a Windows x64 also falls under VER_PLATFORM_WIN32_NT. Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45990 diff changeset	469 \| :const:`3 (VER_PLATFORM_WIN32_CE)` \| Windows CE \|
b7df30ac5b5a Windows x64 also falls under VER_PLATFORM_WIN32_NT. Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 45990 diff changeset	470 +-----------------------------------------+-------------------------+
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	471
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	472 This function wraps the Win32 :cfunc:`GetVersionEx` function; see the Microsoft
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	473 documentation for more information about these fields.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	474
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	475 Availability: Windows.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	476
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	477 .. versionadded:: 2.3
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	478
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	479
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	480 .. data:: hexversion
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	481
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	482 The version number encoded as a single integer. This is guaranteed to increase
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	483 with each version, including proper support for non-production releases. For
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	484 example, to test that the Python interpreter is at least version 1.5.2, use::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	485
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	486 if sys.hexversion >= 0x010502F0:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	487 # use some advanced feature
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	488 ...
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	489 else:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	490 # use an alternative implementation or warn the user
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	491 ...
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	492
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	493 This is called ``hexversion`` since it only really looks meaningful when viewed
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	494 as the result of passing it to the built-in :func:`hex` function. The
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	495 ``version_info`` value may be used for a more human-friendly encoding of the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	496 same information.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	497
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	498 .. versionadded:: 1.5.2
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	499
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	500
52233 9b358eae532a Issue #4258: Use 30-bit digits for Python longs, on 64-bit platforms. Mark Dickinson <dickinsm@gmail.com> parents: 51870 diff changeset	501 .. data:: long_info
9b358eae532a Issue #4258: Use 30-bit digits for Python longs, on 64-bit platforms. Mark Dickinson <dickinsm@gmail.com> parents: 51870 diff changeset	502
9b358eae532a Issue #4258: Use 30-bit digits for Python longs, on 64-bit platforms. Mark Dickinson <dickinsm@gmail.com> parents: 51870 diff changeset	503 A struct sequence that holds information about Python's
9b358eae532a Issue #4258: Use 30-bit digits for Python longs, on 64-bit platforms. Mark Dickinson <dickinsm@gmail.com> parents: 51870 diff changeset	504 internal representation of integers. The attributes are read only.
9b358eae532a Issue #4258: Use 30-bit digits for Python longs, on 64-bit platforms. Mark Dickinson <dickinsm@gmail.com> parents: 51870 diff changeset	505
9b358eae532a Issue #4258: Use 30-bit digits for Python longs, on 64-bit platforms. Mark Dickinson <dickinsm@gmail.com> parents: 51870 diff changeset	506 +-------------------------+----------------------------------------------+
9b358eae532a Issue #4258: Use 30-bit digits for Python longs, on 64-bit platforms. Mark Dickinson <dickinsm@gmail.com> parents: 51870 diff changeset	507 \| attribute \| explanation \|
9b358eae532a Issue #4258: Use 30-bit digits for Python longs, on 64-bit platforms. Mark Dickinson <dickinsm@gmail.com> parents: 51870 diff changeset	508 +=========================+==============================================+
9b358eae532a Issue #4258: Use 30-bit digits for Python longs, on 64-bit platforms. Mark Dickinson <dickinsm@gmail.com> parents: 51870 diff changeset	509 \| :const:`bits_per_digit` \| number of bits held in each digit. Python \|
9b358eae532a Issue #4258: Use 30-bit digits for Python longs, on 64-bit platforms. Mark Dickinson <dickinsm@gmail.com> parents: 51870 diff changeset	510 \| \| integers are stored internally in base \|
9b358eae532a Issue #4258: Use 30-bit digits for Python longs, on 64-bit platforms. Mark Dickinson <dickinsm@gmail.com> parents: 51870 diff changeset	511 \| \| ``2**long_info.bits_per_digit`` \|
9b358eae532a Issue #4258: Use 30-bit digits for Python longs, on 64-bit platforms. Mark Dickinson <dickinsm@gmail.com> parents: 51870 diff changeset	512 +-------------------------+----------------------------------------------+
9b358eae532a Issue #4258: Use 30-bit digits for Python longs, on 64-bit platforms. Mark Dickinson <dickinsm@gmail.com> parents: 51870 diff changeset	513 \| :const:`sizeof_digit` \| size in bytes of the C type used to \|
9b358eae532a Issue #4258: Use 30-bit digits for Python longs, on 64-bit platforms. Mark Dickinson <dickinsm@gmail.com> parents: 51870 diff changeset	514 \| \| represent a digit \|
9b358eae532a Issue #4258: Use 30-bit digits for Python longs, on 64-bit platforms. Mark Dickinson <dickinsm@gmail.com> parents: 51870 diff changeset	515 +-------------------------+----------------------------------------------+
9b358eae532a Issue #4258: Use 30-bit digits for Python longs, on 64-bit platforms. Mark Dickinson <dickinsm@gmail.com> parents: 51870 diff changeset	516
9b358eae532a Issue #4258: Use 30-bit digits for Python longs, on 64-bit platforms. Mark Dickinson <dickinsm@gmail.com> parents: 51870 diff changeset	517 .. versionadded:: 2.7
9b358eae532a Issue #4258: Use 30-bit digits for Python longs, on 64-bit platforms. Mark Dickinson <dickinsm@gmail.com> parents: 51870 diff changeset	518
9b358eae532a Issue #4258: Use 30-bit digits for Python longs, on 64-bit platforms. Mark Dickinson <dickinsm@gmail.com> parents: 51870 diff changeset	519
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	520 .. data:: last_type
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	521 last_value
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	522 last_traceback
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	523
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	524 These three variables are not always defined; they are set when an exception is
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	525 not handled and the interpreter prints an error message and a stack traceback.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	526 Their intended use is to allow an interactive user to import a debugger module
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	527 and engage in post-mortem debugging without having to re-execute the command
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	528 that caused the error. (Typical use is ``import pdb; pdb.pm()`` to enter the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	529 post-mortem debugger; see chapter :ref:`debugger` for
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	530 more information.)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	531
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	532 The meaning of the variables is the same as that of the return values from
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	533 :func:`exc_info` above. (Since there is only one interactive thread,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	534 thread-safety is not a concern for these variables, unlike for ``exc_type``
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	535 etc.)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	536
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	537
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	538 .. data:: maxint
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	539
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	540 The largest positive integer supported by Python's regular integer type. This
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	541 is at least 2\\31-1. The largest negative integer is ``-maxint-1`` --- the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	542 asymmetry results from the use of 2's complement binary arithmetic.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	543
47194 59ab2cf002fa Patch #2488: Add sys.maxsize. Martin v. Löwis <martin@v.loewis.de> parents: 46522 diff changeset	544 .. data:: maxsize
59ab2cf002fa Patch #2488: Add sys.maxsize. Martin v. Löwis <martin@v.loewis.de> parents: 46522 diff changeset	545
59ab2cf002fa Patch #2488: Add sys.maxsize. Martin v. Löwis <martin@v.loewis.de> parents: 46522 diff changeset	546 The largest positive integer supported by the platform's Py_ssize_t type,
59ab2cf002fa Patch #2488: Add sys.maxsize. Martin v. Löwis <martin@v.loewis.de> parents: 46522 diff changeset	547 and thus the maximum size lists, strings, dicts, and many other containers
59ab2cf002fa Patch #2488: Add sys.maxsize. Martin v. Löwis <martin@v.loewis.de> parents: 46522 diff changeset	548 can have.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	549
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	550 .. data:: maxunicode
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	551
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	552 An integer giving the largest supported code point for a Unicode character. The
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	553 value of this depends on the configuration option that specifies whether Unicode
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	554 characters are stored as UCS-2 or UCS-4.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	555
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	556
52535 ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 52233 diff changeset	557 .. data:: meta_path
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 52233 diff changeset	558
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 52233 diff changeset	559 A list of :term:`finder` objects that have their :meth:`find_module`
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 52233 diff changeset	560 methods called to see if one of the objects can find the module to be
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 52233 diff changeset	561 imported. The :meth:`find_module` method is called at least with the
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 52233 diff changeset	562 absolute name of the module being imported. If the module to be imported is
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 52233 diff changeset	563 contained in package then the parent package's :attr:`__path__` attribute
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 52233 diff changeset	564 is passed in as a second argument. The method returns :keyword:`None` if
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 52233 diff changeset	565 the module cannot be found, else returns a :term:`loader`.
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 52233 diff changeset	566
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 52233 diff changeset	567 :data:`sys.meta_path` is searched before any implicit default finders or
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 52233 diff changeset	568 :data:`sys.path`.
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 52233 diff changeset	569
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 52233 diff changeset	570 See :pep:`302` for the original specification.
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 52233 diff changeset	571
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 52233 diff changeset	572
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	573 .. data:: modules
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	574
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	575 .. index:: builtin: reload
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	576
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	577 This is a dictionary that maps module names to modules which have already been
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	578 loaded. This can be manipulated to force reloading of modules and other tricks.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	579 Note that removing a module from this dictionary is not the same as calling
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	580 :func:`reload` on the corresponding module object.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	581
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	582
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	583 .. data:: path
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	584
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	585 .. index:: triple: module; search; path
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	586
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	587 A list of strings that specifies the search path for modules. Initialized from
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	588 the environment variable :envvar:`PYTHONPATH`, plus an installation-dependent
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	589 default.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	590
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	591 As initialized upon program startup, the first item of this list, ``path[0]``,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	592 is the directory containing the script that was used to invoke the Python
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	593 interpreter. If the script directory is not available (e.g. if the interpreter
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	594 is invoked interactively or if the script is read from standard input),
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	595 ``path[0]`` is the empty string, which directs Python to search modules in the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	596 current directory first. Notice that the script directory is inserted before
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	597 the entries inserted as a result of :envvar:`PYTHONPATH`.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	598
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	599 A program is free to modify this list for its own purposes.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	600
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	601 .. versionchanged:: 2.3
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	602 Unicode strings are no longer ignored.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	603
50721 44e0c69a5304 move seealso to a more appropiate place Benjamin Peterson <benjamin@python.org> parents: 50508 diff changeset	604 .. seealso::
44e0c69a5304 move seealso to a more appropiate place Benjamin Peterson <benjamin@python.org> parents: 50508 diff changeset	605 Module :mod:`site` This describes how to use .pth files to extend
44e0c69a5304 move seealso to a more appropiate place Benjamin Peterson <benjamin@python.org> parents: 50508 diff changeset	606 :data:`sys.path`.
44e0c69a5304 move seealso to a more appropiate place Benjamin Peterson <benjamin@python.org> parents: 50508 diff changeset	607
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	608
52535 ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 52233 diff changeset	609 .. data:: path_hooks
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 52233 diff changeset	610
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 52233 diff changeset	611 A list of callables that take a path argument to try to create a
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 52233 diff changeset	612 :term:`finder` for the path. If a finder can be created, it is to be
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 52233 diff changeset	613 returned by the callable, else raise :exc:`ImportError`.
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 52233 diff changeset	614
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 52233 diff changeset	615 Originally specified in :pep:`302`.
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 52233 diff changeset	616
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 52233 diff changeset	617
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 52233 diff changeset	618 .. data:: path_importer_cache
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 52233 diff changeset	619
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 52233 diff changeset	620 A dictionary acting as a cache for :term:`finder` objects. The keys are
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 52233 diff changeset	621 paths that have been passed to :data:`sys.path_hooks` and the values are
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 52233 diff changeset	622 the finders that are found. If a path is a valid file system path but no
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 52233 diff changeset	623 explicit finder is found on :data:`sys.path_hooks` then :keyword:`None` is
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 52233 diff changeset	624 stored to represent the implicit default finder should be used. If the path
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 52233 diff changeset	625 is not an existing path then :class:`imp.NullImporter` is set.
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 52233 diff changeset	626
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 52233 diff changeset	627 Originally specified in :pep:`302`.
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 52233 diff changeset	628
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 52233 diff changeset	629
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	630 .. data:: platform
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	631
44820 145b3e605378 #799369: document possible sys.platform values. Georg Brandl <georg@python.org> parents: 44678 diff changeset	632 This string contains a platform identifier that can be used to append
145b3e605378 #799369: document possible sys.platform values. Georg Brandl <georg@python.org> parents: 44678 diff changeset	633 platform-specific components to :data:`sys.path`, for instance.
145b3e605378 #799369: document possible sys.platform values. Georg Brandl <georg@python.org> parents: 44678 diff changeset	634
145b3e605378 #799369: document possible sys.platform values. Georg Brandl <georg@python.org> parents: 44678 diff changeset	635 For Unix systems, this is the lowercased OS name as returned by ``uname -s``
145b3e605378 #799369: document possible sys.platform values. Georg Brandl <georg@python.org> parents: 44678 diff changeset	636 with the first part of the version as returned by ``uname -r`` appended,
145b3e605378 #799369: document possible sys.platform values. Georg Brandl <georg@python.org> parents: 44678 diff changeset	637 e.g. ``'sunos5'`` or ``'linux2'``, at the time when Python was built.
145b3e605378 #799369: document possible sys.platform values. Georg Brandl <georg@python.org> parents: 44678 diff changeset	638 For other systems, the values are:
145b3e605378 #799369: document possible sys.platform values. Georg Brandl <georg@python.org> parents: 44678 diff changeset	639
145b3e605378 #799369: document possible sys.platform values. Georg Brandl <georg@python.org> parents: 44678 diff changeset	640 ================ ===========================
145b3e605378 #799369: document possible sys.platform values. Georg Brandl <georg@python.org> parents: 44678 diff changeset	641 System :data:`platform` value
145b3e605378 #799369: document possible sys.platform values. Georg Brandl <georg@python.org> parents: 44678 diff changeset	642 ================ ===========================
145b3e605378 #799369: document possible sys.platform values. Georg Brandl <georg@python.org> parents: 44678 diff changeset	643 Windows ``'win32'``
145b3e605378 #799369: document possible sys.platform values. Georg Brandl <georg@python.org> parents: 44678 diff changeset	644 Windows/Cygwin ``'cygwin'``
49184 59db4b3a06b0 Remove things specific to the old Macintosh, and spell "Mac OS X" consistently. Georg Brandl <georg@python.org> parents: 47925 diff changeset	645 Mac OS X ``'darwin'``
44820 145b3e605378 #799369: document possible sys.platform values. Georg Brandl <georg@python.org> parents: 44678 diff changeset	646 OS/2 ``'os2'``
145b3e605378 #799369: document possible sys.platform values. Georg Brandl <georg@python.org> parents: 44678 diff changeset	647 OS/2 EMX ``'os2emx'``
145b3e605378 #799369: document possible sys.platform values. Georg Brandl <georg@python.org> parents: 44678 diff changeset	648 RiscOS ``'riscos'``
145b3e605378 #799369: document possible sys.platform values. Georg Brandl <georg@python.org> parents: 44678 diff changeset	649 AtheOS ``'atheos'``
145b3e605378 #799369: document possible sys.platform values. Georg Brandl <georg@python.org> parents: 44678 diff changeset	650 ================ ===========================
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	651
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	652
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	653 .. data:: prefix
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	654
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	655 A string giving the site-specific directory prefix where the platform
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	656 independent Python files are installed; by default, this is the string
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	657 ``'/usr/local'``. This can be set at build time with the :option:`--prefix`
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	658 argument to the :program:`configure` script. The main collection of Python
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	659 library modules is installed in the directory ``prefix + '/lib/pythonversion'``
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	660 while the platform independent header files (all except :file:`pyconfig.h`) are
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	661 stored in ``prefix + '/include/pythonversion'``, where version is equal to
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	662 ``version[:3]``.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	663
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	664
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	665 .. data:: ps1
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	666 ps2
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	667
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	668 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	669 single: interpreter prompts
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	670 single: prompts, interpreter
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	671
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	672 Strings specifying the primary and secondary prompt of the interpreter. These
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	673 are only defined if the interpreter is in interactive mode. Their initial
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	674 values in this case are ``'>>> '`` and ``'... '``. If a non-string object is
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	675 assigned to either variable, its :func:`str` is re-evaluated each time the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	676 interpreter prepares to read a new interactive command; this can be used to
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	677 implement a dynamic prompt.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	678
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	679
44041 7e8e8797f9d0 Added py3kwarning to the documentation of the sys module. Christian Heimes <christian@cheimes.de> parents: 42603 diff changeset	680 .. data:: py3kwarning
7e8e8797f9d0 Added py3kwarning to the documentation of the sys module. Christian Heimes <christian@cheimes.de> parents: 42603 diff changeset	681
7e8e8797f9d0 Added py3kwarning to the documentation of the sys module. Christian Heimes <christian@cheimes.de> parents: 42603 diff changeset	682 Bool containing the status of the Python 3.0 warning flag. It's ``True``
51870 698175fe8b3d Document that setting sys.py3kwarning wont do anything. Georg Brandl <georg@python.org> parents: 51365 diff changeset	683 when Python is started with the -3 option. (This should be considered
698175fe8b3d Document that setting sys.py3kwarning wont do anything. Georg Brandl <georg@python.org> parents: 51365 diff changeset	684 read-only; setting it to a different value doesn't have an effect on
698175fe8b3d Document that setting sys.py3kwarning wont do anything. Georg Brandl <georg@python.org> parents: 51365 diff changeset	685 Python 3.0 warnings.)
44041 7e8e8797f9d0 Added py3kwarning to the documentation of the sys module. Christian Heimes <christian@cheimes.de> parents: 42603 diff changeset	686
45990 2e3f86e73fa2 Add missing versionadded tag. Georg Brandl <georg@python.org> parents: 45143 diff changeset	687 .. versionadded:: 2.6
2e3f86e73fa2 Add missing versionadded tag. Georg Brandl <georg@python.org> parents: 45143 diff changeset	688
44041 7e8e8797f9d0 Added py3kwarning to the documentation of the sys module. Christian Heimes <christian@cheimes.de> parents: 42603 diff changeset	689
44566 599f22a349a2 Patch #602345 by Neal Norwitz and me: add -B option and PYTHONDONTWRITEBYTECODE envvar to skip writing bytecode. Georg Brandl <georg@python.org> parents: 44383 diff changeset	690 .. data:: dont_write_bytecode
599f22a349a2 Patch #602345 by Neal Norwitz and me: add -B option and PYTHONDONTWRITEBYTECODE envvar to skip writing bytecode. Georg Brandl <georg@python.org> parents: 44383 diff changeset	691
599f22a349a2 Patch #602345 by Neal Norwitz and me: add -B option and PYTHONDONTWRITEBYTECODE envvar to skip writing bytecode. Georg Brandl <georg@python.org> parents: 44383 diff changeset	692 If this is true, Python won't try to write ``.pyc`` or ``.pyo`` files on the
599f22a349a2 Patch #602345 by Neal Norwitz and me: add -B option and PYTHONDONTWRITEBYTECODE envvar to skip writing bytecode. Georg Brandl <georg@python.org> parents: 44383 diff changeset	693 import of source modules. This value is initially set to ``True`` or ``False``
599f22a349a2 Patch #602345 by Neal Norwitz and me: add -B option and PYTHONDONTWRITEBYTECODE envvar to skip writing bytecode. Georg Brandl <georg@python.org> parents: 44383 diff changeset	694 depending on the ``-B`` command line option and the ``PYTHONDONTWRITEBYTECODE``
599f22a349a2 Patch #602345 by Neal Norwitz and me: add -B option and PYTHONDONTWRITEBYTECODE envvar to skip writing bytecode. Georg Brandl <georg@python.org> parents: 44383 diff changeset	695 environment variable, but you can set it yourself to control bytecode file
599f22a349a2 Patch #602345 by Neal Norwitz and me: add -B option and PYTHONDONTWRITEBYTECODE envvar to skip writing bytecode. Georg Brandl <georg@python.org> parents: 44383 diff changeset	696 generation.
599f22a349a2 Patch #602345 by Neal Norwitz and me: add -B option and PYTHONDONTWRITEBYTECODE envvar to skip writing bytecode. Georg Brandl <georg@python.org> parents: 44383 diff changeset	697
599f22a349a2 Patch #602345 by Neal Norwitz and me: add -B option and PYTHONDONTWRITEBYTECODE envvar to skip writing bytecode. Georg Brandl <georg@python.org> parents: 44383 diff changeset	698 .. versionadded:: 2.6
599f22a349a2 Patch #602345 by Neal Norwitz and me: add -B option and PYTHONDONTWRITEBYTECODE envvar to skip writing bytecode. Georg Brandl <georg@python.org> parents: 44383 diff changeset	699
599f22a349a2 Patch #602345 by Neal Norwitz and me: add -B option and PYTHONDONTWRITEBYTECODE envvar to skip writing bytecode. Georg Brandl <georg@python.org> parents: 44383 diff changeset	700
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	701 .. function:: setcheckinterval(interval)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	702
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	703 Set the interpreter's "check interval". This integer value determines how often
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	704 the interpreter checks for periodic things such as thread switches and signal
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	705 handlers. The default is ``100``, meaning the check is performed every 100
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	706 Python virtual instructions. Setting it to a larger value may increase
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	707 performance for programs using threads. Setting it to a value ``<=`` 0 checks
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	708 every virtual instruction, maximizing responsiveness as well as overhead.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	709
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	710
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	711 .. function:: setdefaultencoding(name)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	712
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	713 Set the current default string encoding used by the Unicode implementation. If
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	714 name does not match any available encoding, :exc:`LookupError` is raised.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	715 This function is only intended to be used by the :mod:`site` module
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	716 implementation and, where needed, by :mod:`sitecustomize`. Once used by the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	717 :mod:`site` module, it is removed from the :mod:`sys` module's namespace.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	718
44383 3625234bf3d2 Some cleanup in the docs. Georg Brandl <georg@python.org> parents: 44103 diff changeset	719 .. Note that :mod:`site` is not imported if the :option:`-S` option is passed
3625234bf3d2 Some cleanup in the docs. Georg Brandl <georg@python.org> parents: 44103 diff changeset	720 to the interpreter, in which case this function will remain available.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	721
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	722 .. versionadded:: 2.0
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	723
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	724
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	725 .. function:: setdlopenflags(n)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	726
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	727 Set the flags used by the interpreter for :cfunc:`dlopen` calls, such as when
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	728 the interpreter loads extension modules. Among other things, this will enable a
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	729 lazy resolving of symbols when importing a module, if called as
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	730 ``sys.setdlopenflags(0)``. To share symbols across extension modules, call as
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	731 ``sys.setdlopenflags(dl.RTLD_NOW \| dl.RTLD_GLOBAL)``. Symbolic names for the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	732 flag modules can be either found in the :mod:`dl` module, or in the :mod:`DLFCN`
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	733 module. If :mod:`DLFCN` is not available, it can be generated from
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	734 :file:`/usr/include/dlfcn.h` using the :program:`h2py` script. Availability:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	735 Unix.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	736
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	737 .. versionadded:: 2.2
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	738
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	739
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	740 .. function:: setprofile(profilefunc)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	741
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	742 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	743 single: profile function
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	744 single: profiler
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	745
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	746 Set the system's profile function, which allows you to implement a Python source
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	747 code profiler in Python. See chapter :ref:`profile` for more information on the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	748 Python profiler. The system's profile function is called similarly to the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	749 system's trace function (see :func:`settrace`), but it isn't called for each
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	750 executed line of code (only on call and return, but the return event is reported
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	751 even when an exception has been set). The function is thread-specific, but
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	752 there is no way for the profiler to know about context switches between threads,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	753 so it does not make sense to use this in the presence of multiple threads. Also,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	754 its return value is not used, so it can simply return ``None``.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	755
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	756
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	757 .. function:: setrecursionlimit(limit)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	758
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	759 Set the maximum depth of the Python interpreter stack to limit. This limit
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	760 prevents infinite recursion from causing an overflow of the C stack and crashing
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	761 Python.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	762
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	763 The highest possible limit is platform-dependent. A user may need to set the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	764 limit higher when she has a program that requires deep recursion and a platform
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	765 that supports a higher limit. This should be done with care, because a too-high
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	766 limit can lead to a crash.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	767
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	768
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	769 .. function:: settrace(tracefunc)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	770
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	771 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	772 single: trace function
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	773 single: debugger
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	774
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	775 Set the system's trace function, which allows you to implement a Python
49777 cb8039d82af3 fix indentation and a sphinx warning Benjamin Peterson <benjamin@python.org> parents: 49773 diff changeset	776 source code debugger in Python. The function is thread-specific; for a
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	777 debugger to support multiple threads, it must be registered using
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	778 :func:`settrace` for each thread being debugged.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	779
49773 a290a51ff8e2 move useful sys.settrace information to the function's documentation from the debugger Benjamin Peterson <benjamin@python.org> parents: 49184 diff changeset	780 Trace functions should have three arguments: frame, event, and
a290a51ff8e2 move useful sys.settrace information to the function's documentation from the debugger Benjamin Peterson <benjamin@python.org> parents: 49184 diff changeset	781 arg. frame is the current stack frame. event is a string: ``'call'``,
a290a51ff8e2 move useful sys.settrace information to the function's documentation from the debugger Benjamin Peterson <benjamin@python.org> parents: 49184 diff changeset	782 ``'line'``, ``'return'``, ``'exception'``, ``'c_call'``, ``'c_return'``, or
a290a51ff8e2 move useful sys.settrace information to the function's documentation from the debugger Benjamin Peterson <benjamin@python.org> parents: 49184 diff changeset	783 ``'c_exception'``. arg depends on the event type.
a290a51ff8e2 move useful sys.settrace information to the function's documentation from the debugger Benjamin Peterson <benjamin@python.org> parents: 49184 diff changeset	784
a290a51ff8e2 move useful sys.settrace information to the function's documentation from the debugger Benjamin Peterson <benjamin@python.org> parents: 49184 diff changeset	785 The trace function is invoked (with event set to ``'call'``) whenever a new
a290a51ff8e2 move useful sys.settrace information to the function's documentation from the debugger Benjamin Peterson <benjamin@python.org> parents: 49184 diff changeset	786 local scope is entered; it should return a reference to a local trace
a290a51ff8e2 move useful sys.settrace information to the function's documentation from the debugger Benjamin Peterson <benjamin@python.org> parents: 49184 diff changeset	787 function to be used that scope, or ``None`` if the scope shouldn't be traced.
a290a51ff8e2 move useful sys.settrace information to the function's documentation from the debugger Benjamin Peterson <benjamin@python.org> parents: 49184 diff changeset	788
a290a51ff8e2 move useful sys.settrace information to the function's documentation from the debugger Benjamin Peterson <benjamin@python.org> parents: 49184 diff changeset	789 The local trace function should return a reference to itself (or to another
a290a51ff8e2 move useful sys.settrace information to the function's documentation from the debugger Benjamin Peterson <benjamin@python.org> parents: 49184 diff changeset	790 function for further tracing in that scope), or ``None`` to turn off tracing
a290a51ff8e2 move useful sys.settrace information to the function's documentation from the debugger Benjamin Peterson <benjamin@python.org> parents: 49184 diff changeset	791 in that scope.
a290a51ff8e2 move useful sys.settrace information to the function's documentation from the debugger Benjamin Peterson <benjamin@python.org> parents: 49184 diff changeset	792
a290a51ff8e2 move useful sys.settrace information to the function's documentation from the debugger Benjamin Peterson <benjamin@python.org> parents: 49184 diff changeset	793 The events have the following meaning:
a290a51ff8e2 move useful sys.settrace information to the function's documentation from the debugger Benjamin Peterson <benjamin@python.org> parents: 49184 diff changeset	794
50508 c52177f36852 Remove trailing whitespace. Georg Brandl <georg@python.org> parents: 49777 diff changeset	795 ``'call'``
49773 a290a51ff8e2 move useful sys.settrace information to the function's documentation from the debugger Benjamin Peterson <benjamin@python.org> parents: 49184 diff changeset	796 A function is called (or some other code block entered). The
a290a51ff8e2 move useful sys.settrace information to the function's documentation from the debugger Benjamin Peterson <benjamin@python.org> parents: 49184 diff changeset	797 global trace function is called; arg is ``None``; the return value
a290a51ff8e2 move useful sys.settrace information to the function's documentation from the debugger Benjamin Peterson <benjamin@python.org> parents: 49184 diff changeset	798 specifies the local trace function.
a290a51ff8e2 move useful sys.settrace information to the function's documentation from the debugger Benjamin Peterson <benjamin@python.org> parents: 49184 diff changeset	799
a290a51ff8e2 move useful sys.settrace information to the function's documentation from the debugger Benjamin Peterson <benjamin@python.org> parents: 49184 diff changeset	800 ``'line'``
a290a51ff8e2 move useful sys.settrace information to the function's documentation from the debugger Benjamin Peterson <benjamin@python.org> parents: 49184 diff changeset	801 The interpreter is about to execute a new line of code (sometimes multiple
a290a51ff8e2 move useful sys.settrace information to the function's documentation from the debugger Benjamin Peterson <benjamin@python.org> parents: 49184 diff changeset	802 line events on one line exist). The local trace function is called; arg
a290a51ff8e2 move useful sys.settrace information to the function's documentation from the debugger Benjamin Peterson <benjamin@python.org> parents: 49184 diff changeset	803 is ``None``; the return value specifies the new local trace function.
a290a51ff8e2 move useful sys.settrace information to the function's documentation from the debugger Benjamin Peterson <benjamin@python.org> parents: 49184 diff changeset	804
a290a51ff8e2 move useful sys.settrace information to the function's documentation from the debugger Benjamin Peterson <benjamin@python.org> parents: 49184 diff changeset	805 ``'return'``
a290a51ff8e2 move useful sys.settrace information to the function's documentation from the debugger Benjamin Peterson <benjamin@python.org> parents: 49184 diff changeset	806 A function (or other code block) is about to return. The local trace
a290a51ff8e2 move useful sys.settrace information to the function's documentation from the debugger Benjamin Peterson <benjamin@python.org> parents: 49184 diff changeset	807 function is called; arg is the value that will be returned. The trace
a290a51ff8e2 move useful sys.settrace information to the function's documentation from the debugger Benjamin Peterson <benjamin@python.org> parents: 49184 diff changeset	808 function's return value is ignored.
a290a51ff8e2 move useful sys.settrace information to the function's documentation from the debugger Benjamin Peterson <benjamin@python.org> parents: 49184 diff changeset	809
a290a51ff8e2 move useful sys.settrace information to the function's documentation from the debugger Benjamin Peterson <benjamin@python.org> parents: 49184 diff changeset	810 ``'exception'``
a290a51ff8e2 move useful sys.settrace information to the function's documentation from the debugger Benjamin Peterson <benjamin@python.org> parents: 49184 diff changeset	811 An exception has occurred. The local trace function is called; arg is a
a290a51ff8e2 move useful sys.settrace information to the function's documentation from the debugger Benjamin Peterson <benjamin@python.org> parents: 49184 diff changeset	812 tuple ``(exception, value, traceback)``; the return value specifies the
a290a51ff8e2 move useful sys.settrace information to the function's documentation from the debugger Benjamin Peterson <benjamin@python.org> parents: 49184 diff changeset	813 new local trace function.
a290a51ff8e2 move useful sys.settrace information to the function's documentation from the debugger Benjamin Peterson <benjamin@python.org> parents: 49184 diff changeset	814
a290a51ff8e2 move useful sys.settrace information to the function's documentation from the debugger Benjamin Peterson <benjamin@python.org> parents: 49184 diff changeset	815 ``'c_call'``
a290a51ff8e2 move useful sys.settrace information to the function's documentation from the debugger Benjamin Peterson <benjamin@python.org> parents: 49184 diff changeset	816 A C function is about to be called. This may be an extension function or
a290a51ff8e2 move useful sys.settrace information to the function's documentation from the debugger Benjamin Peterson <benjamin@python.org> parents: 49184 diff changeset	817 a builtin. arg is the C function object.
a290a51ff8e2 move useful sys.settrace information to the function's documentation from the debugger Benjamin Peterson <benjamin@python.org> parents: 49184 diff changeset	818
a290a51ff8e2 move useful sys.settrace information to the function's documentation from the debugger Benjamin Peterson <benjamin@python.org> parents: 49184 diff changeset	819 ``'c_return'``
a290a51ff8e2 move useful sys.settrace information to the function's documentation from the debugger Benjamin Peterson <benjamin@python.org> parents: 49184 diff changeset	820 A C function has returned. arg is ``None``.
a290a51ff8e2 move useful sys.settrace information to the function's documentation from the debugger Benjamin Peterson <benjamin@python.org> parents: 49184 diff changeset	821
a290a51ff8e2 move useful sys.settrace information to the function's documentation from the debugger Benjamin Peterson <benjamin@python.org> parents: 49184 diff changeset	822 ``'c_exception'``
a290a51ff8e2 move useful sys.settrace information to the function's documentation from the debugger Benjamin Peterson <benjamin@python.org> parents: 49184 diff changeset	823 A C function has thrown an exception. arg is ``None``.
a290a51ff8e2 move useful sys.settrace information to the function's documentation from the debugger Benjamin Peterson <benjamin@python.org> parents: 49184 diff changeset	824
49777 cb8039d82af3 fix indentation and a sphinx warning Benjamin Peterson <benjamin@python.org> parents: 49773 diff changeset	825 Note that as an exception is propagated down the chain of callers, an
cb8039d82af3 fix indentation and a sphinx warning Benjamin Peterson <benjamin@python.org> parents: 49773 diff changeset	826 ``'exception'`` event is generated at each level.
49773 a290a51ff8e2 move useful sys.settrace information to the function's documentation from the debugger Benjamin Peterson <benjamin@python.org> parents: 49184 diff changeset	827
49777 cb8039d82af3 fix indentation and a sphinx warning Benjamin Peterson <benjamin@python.org> parents: 49773 diff changeset	828 For more information on code and frame objects, refer to :ref:`types`.
49773 a290a51ff8e2 move useful sys.settrace information to the function's documentation from the debugger Benjamin Peterson <benjamin@python.org> parents: 49184 diff changeset	829
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	830 .. note::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	831
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	832 The :func:`settrace` function is intended only for implementing debuggers,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	833 profilers, coverage tools and the like. Its behavior is part of the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	834 implementation platform, rather than part of the language definition, and thus
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	835 may not be available in all Python implementations.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	836
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	837
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	838 .. function:: settscdump(on_flag)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	839
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	840 Activate dumping of VM measurements using the Pentium timestamp counter, if
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	841 on_flag is true. Deactivate these dumps if on_flag is off. The function is
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	842 available only if Python was compiled with :option:`--with-tsc`. To understand
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	843 the output of this dump, read :file:`Python/ceval.c` in the Python sources.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	844
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	845 .. versionadded:: 2.4
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	846
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	847
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	848 .. data:: stdin
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	849 stdout
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	850 stderr
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	851
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	852 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	853 builtin: input
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	854 builtin: raw_input
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	855
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	856 File objects corresponding to the interpreter's standard input, output and error
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	857 streams. ``stdin`` is used for all interpreter input except for scripts but
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	858 including calls to :func:`input` and :func:`raw_input`. ``stdout`` is used for
44103 1e266015cf5b Add more entries to the glossary. Georg Brandl <georg@python.org> parents: 44089 diff changeset	859 the output of :keyword:`print` and :term:`expression` statements and for the
1e266015cf5b Add more entries to the glossary. Georg Brandl <georg@python.org> parents: 44089 diff changeset	860 prompts of :func:`input` and :func:`raw_input`. The interpreter's own prompts
1e266015cf5b Add more entries to the glossary. Georg Brandl <georg@python.org> parents: 44089 diff changeset	861 and (almost all of) its error messages go to ``stderr``. ``stdout`` and
1e266015cf5b Add more entries to the glossary. Georg Brandl <georg@python.org> parents: 44089 diff changeset	862 ``stderr`` needn't be built-in file objects: any object is acceptable as long
50508 c52177f36852 Remove trailing whitespace. Georg Brandl <georg@python.org> parents: 49777 diff changeset	863 as it has a :meth:`write` method that takes a string argument. (Changing these
44103 1e266015cf5b Add more entries to the glossary. Georg Brandl <georg@python.org> parents: 44089 diff changeset	864 objects doesn't affect the standard I/O streams of processes executed by
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	865 :func:`os.popen`, :func:`os.system` or the :func:`exec\*` family of functions in
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	866 the :mod:`os` module.)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	867
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	868
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	869 .. data:: __stdin__
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	870 __stdout__
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	871 __stderr__
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	872
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	873 These objects contain the original values of ``stdin``, ``stderr`` and
52566 e70a6c46b3ab #1096310: document usage of sys.__std__ a bit better. Georg Brandl <georg@python.org>* parents: 52535 diff changeset	874 ``stdout`` at the start of the program. They are used during finalization,
e70a6c46b3ab #1096310: document usage of sys.__std__ a bit better. Georg Brandl <georg@python.org>* parents: 52535 diff changeset	875 and could be useful to print to the actual standard stream no matter if the
e70a6c46b3ab #1096310: document usage of sys.__std__ a bit better. Georg Brandl <georg@python.org>* parents: 52535 diff changeset	876 ``sys.std*`` object has been redirected.
e70a6c46b3ab #1096310: document usage of sys.__std__ a bit better. Georg Brandl <georg@python.org>* parents: 52535 diff changeset	877
e70a6c46b3ab #1096310: document usage of sys.__std__ a bit better. Georg Brandl <georg@python.org>* parents: 52535 diff changeset	878 It can also be used to restore the actual files to known working file objects
e70a6c46b3ab #1096310: document usage of sys.__std__ a bit better. Georg Brandl <georg@python.org>* parents: 52535 diff changeset	879 in case they have been overwritten with a broken object. However, the
e70a6c46b3ab #1096310: document usage of sys.__std__ a bit better. Georg Brandl <georg@python.org>* parents: 52535 diff changeset	880 preferred way to do this is to explicitly save the previous stream before
e70a6c46b3ab #1096310: document usage of sys.__std__ a bit better. Georg Brandl <georg@python.org>* parents: 52535 diff changeset	881 replacing it, and restore the saved object.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	882
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	883
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	884 .. data:: tracebacklimit
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	885
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	886 When this variable is set to an integer value, it determines the maximum number
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	887 of levels of traceback information printed when an unhandled exception occurs.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	888 The default is ``1000``. When set to ``0`` or less, all traceback information
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	889 is suppressed and only the exception type and value are printed.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	890
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	891
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	892 .. data:: version
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	893
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	894 A string containing the version number of the Python interpreter plus additional
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	895 information on the build number and compiler used. It has a value of the form
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	896 ``'version (#build_number, build_date, build_time) [compiler]'``. The first
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	897 three characters are used to identify the version in the installation
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	898 directories (where appropriate on each platform). An example::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	899
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	900 >>> import sys
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	901 >>> sys.version
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	902 '1.5.2 (#0 Apr 13 1999, 10:51:12) [MSC 32 bit (Intel)]'
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	903
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	904
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	905 .. data:: api_version
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	906
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	907 The C API version for this interpreter. Programmers may find this useful when
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	908 debugging version conflicts between Python and extension modules.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	909
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	910 .. versionadded:: 2.3
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	911
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	912
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	913 .. data:: version_info
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	914
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	915 A tuple containing the five components of the version number: major, minor,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	916 micro, releaselevel, and serial. All values except releaselevel are
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	917 integers; the release level is ``'alpha'``, ``'beta'``, ``'candidate'``, or
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	918 ``'final'``. The ``version_info`` value corresponding to the Python version 2.0
51365 e239e977bb32 Implement issue #4285, convert sys.version_info to a named Eric Smith <eric@trueblade.com> parents: 50722 diff changeset	919 is ``(2, 0, 0, 'final', 0)``. The components can also be accessed by name,
e239e977bb32 Implement issue #4285, convert sys.version_info to a named Eric Smith <eric@trueblade.com> parents: 50722 diff changeset	920 so ``sys.version_info[0]`` is equivalent to ``sys.version_info.major``
e239e977bb32 Implement issue #4285, convert sys.version_info to a named Eric Smith <eric@trueblade.com> parents: 50722 diff changeset	921 and so on.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	922
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	923 .. versionadded:: 2.0
51365 e239e977bb32 Implement issue #4285, convert sys.version_info to a named Eric Smith <eric@trueblade.com> parents: 50722 diff changeset	924 .. versionchanged:: 2.7
e239e977bb32 Implement issue #4285, convert sys.version_info to a named Eric Smith <eric@trueblade.com> parents: 50722 diff changeset	925 Added named component attributes
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	926
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	927
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	928 .. data:: warnoptions
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	929
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	930 This is an implementation detail of the warnings framework; do not modify this
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	931 value. Refer to the :mod:`warnings` module for more information on the warnings
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	932 framework.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	933
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	934
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	935 .. data:: winver
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	936
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	937 The version number used to form registry keys on Windows platforms. This is
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	938 stored as string resource 1000 in the Python DLL. The value is normally the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	939 first three characters of :const:`version`. It is provided in the :mod:`sys`
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	940 module for informational purposes; modifying this value has no effect on the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	941 registry keys used by Python. Availability: Windows.

Mercurial > cpython-lru_cache-weakref

annotate Doc/library/sys.rst @ 54294:dba767bc3155 legacy-trunk