diff options
Diffstat (limited to 'Doc/library/sys.rst')
| -rw-r--r-- | Doc/library/sys.rst | 667 |
1 files changed, 279 insertions, 388 deletions
diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst index e7e853d..6f8b8bb 100644 --- a/Doc/library/sys.rst +++ b/Doc/library/sys.rst @@ -10,13 +10,6 @@ interpreter and to functions that interact strongly with the interpreter. It is always available. -.. data:: abiflags - - On POSIX systems where Python is build with the standard ``configure`` - script, this contains the ABI flags as specified by :pep:`3149`. - - .. versionadded:: 3.2 - .. data:: argv The list of command line arguments passed to a Python script. ``argv[0]`` is the @@ -29,39 +22,14 @@ always available. command line, see the :mod:`fileinput` module. -.. data:: base_exec_prefix - - Set during Python startup, before ``site.py`` is run, to the same value as - :data:`exec_prefix`. If not running in a - :ref:`virtual environment <venv-def>`, the values will stay the same; if - ``site.py`` finds that a virtual environment is in use, the values of - :data:`prefix` and :data:`exec_prefix` will be changed to point to the - virtual environment, whereas :data:`base_prefix` and - :data:`base_exec_prefix` will remain pointing to the base Python - installation (the one which the virtual environment was created from). - - .. versionadded:: 3.3 - - -.. data:: base_prefix - - Set during Python startup, before ``site.py`` is run, to the same value as - :data:`prefix`. If not running in a :ref:`virtual environment <venv-def>`, the values - will stay the same; if ``site.py`` finds that a virtual environment is in - use, the values of :data:`prefix` and :data:`exec_prefix` will be changed to - point to the virtual environment, whereas :data:`base_prefix` and - :data:`base_exec_prefix` will remain pointing to the base Python - installation (the one which the virtual environment was created from). - - .. versionadded:: 3.3 - - .. data:: byteorder An indicator of the native byte order. This will have the value ``'big'`` on big-endian (most-significant byte first) platforms, and ``'little'`` on little-endian (least-significant byte first) platforms. + .. versionadded:: 2.0 + .. data:: builtin_module_names @@ -90,6 +58,8 @@ always available. This function should be used for internal and specialized purposes only. + .. versionadded:: 2.6 + .. function:: _current_frames() @@ -106,21 +76,7 @@ always available. This function should be used for internal and specialized purposes only. - -.. function:: _debugmallocstats() - - Print low-level information to stderr about the state of CPython's memory - allocator. - - If Python is configured --with-pydebug, it also performs some expensive - internal consistency checks. - - .. versionadded:: 3.3 - - .. impl-detail:: - - This function is specific to CPython. The exact output format is not - defined here, and may change. + .. versionadded:: 2.5 .. data:: dllhandle @@ -130,39 +86,13 @@ always available. .. function:: displayhook(value) - If *value* is not ``None``, this function prints ``repr(value)`` to - ``sys.stdout``, and saves *value* in ``builtins._``. If ``repr(value)`` is - not encodable to ``sys.stdout.encoding`` with ``sys.stdout.errors`` error - handler (which is probably ``'strict'``), encode it to - ``sys.stdout.encoding`` with ``'backslashreplace'`` error handler. + If *value* is not ``None``, this function prints it to ``sys.stdout``, and saves + it in ``__builtin__._``. ``sys.displayhook`` is called on the result of evaluating an :term:`expression` entered in an interactive Python session. The display of these values can be customized by assigning another one-argument function to ``sys.displayhook``. - Pseudo-code:: - - def displayhook(value): - if value is None: - return - # Set '_' to None to avoid recursion - builtins._ = None - text = repr(value) - try: - sys.stdout.write(text) - except UnicodeEncodeError: - bytes = text.encode(sys.stdout.encoding, 'backslashreplace') - if hasattr(sys.stdout, 'buffer'): - sys.stdout.buffer.write(bytes) - else: - text = bytes.decode(sys.stdout.encoding, 'strict') - sys.stdout.write(text) - sys.stdout.write("\n") - builtins._ = value - - .. versionchanged:: 3.2 - Use ``'backslashreplace'`` error handler on :exc:`UnicodeEncodeError`. - .. data:: dont_write_bytecode @@ -172,6 +102,8 @@ always available. :envvar:`PYTHONDONTWRITEBYTECODE` environment variable, but you can set it yourself to control bytecode file generation. + .. versionadded:: 2.6 + .. function:: excepthook(type, value, traceback) @@ -202,19 +134,71 @@ always available. frame is not handling an exception, the information is taken from the calling stack frame, or its caller, and so on until a stack frame is found that is handling an exception. Here, "handling an exception" is defined as "executing - an except clause." For any stack frame, only information about the exception - being currently handled is accessible. + or having executed an except clause." For any stack frame, only information + about the most recently handled exception is accessible. .. index:: object: traceback - If no exception is being handled anywhere on the stack, a tuple containing - three ``None`` values is returned. Otherwise, the values returned are - ``(type, value, traceback)``. Their meaning is: *type* gets the type of the - exception being handled (a subclass of :exc:`BaseException`); *value* gets - the exception instance (an instance of the exception type); *traceback* gets - a traceback object (see the Reference Manual) which encapsulates the call + If no exception is being handled anywhere on the stack, a tuple containing three + ``None`` values is returned. Otherwise, the values returned are ``(type, value, + traceback)``. Their meaning is: *type* gets the exception type of the exception + being handled (a class object); *value* gets the exception parameter (its + :dfn:`associated value` or the second argument to :keyword:`raise`, which is + always a class instance if the exception type is a class object); *traceback* + gets a traceback object (see the Reference Manual) which encapsulates the call stack at the point where the exception originally occurred. + If :func:`exc_clear` is called, this function will return three ``None`` values + until either another exception is raised in the current thread or the execution + stack returns to a frame where another exception is being handled. + + .. warning:: + + Assigning the *traceback* return value to a local variable in a function that is + handling an exception will cause a circular reference. This will prevent + anything referenced by a local variable in the same function or by the traceback + from being garbage collected. Since most functions don't need access to the + traceback, the best solution is to use something like ``exctype, value = + sys.exc_info()[:2]`` to extract only the exception type and value. If you do + need the traceback, make sure to delete it after use (best done with a + :keyword:`try` ... :keyword:`finally` statement) or to call :func:`exc_info` in + a function that does not itself handle an exception. + + .. note:: + + Beginning with Python 2.2, such cycles are automatically reclaimed when garbage + collection is enabled and they become unreachable, but it remains more efficient + to avoid creating cycles. + + +.. function:: exc_clear() + + This function clears all information relating to the current or last exception + that occurred in the current thread. After calling this function, + :func:`exc_info` will return three ``None`` values until another exception is + raised in the current thread or the execution stack returns to a frame where + another exception is being handled. + + This function is only needed in only a few obscure situations. These include + logging and error handling systems that report information on the last or + current exception. This function can also be used to try to free resources and + trigger object finalization, though no guarantee is made as to what objects will + be freed, if any. + + .. versionadded:: 2.3 + + +.. data:: exc_type + exc_value + exc_traceback + + .. deprecated:: 1.5 + Use :func:`exc_info` instead. + + Since they are global variables, they are not specific to the current thread, so + their use is not safe in a multi-threaded program. When no exception is being + handled, ``exc_type`` is set to ``None`` and the other two are undefined. + .. data:: exec_prefix @@ -225,12 +209,7 @@ always available. :file:`pyconfig.h` header file) are installed in the directory :file:`{exec_prefix}/lib/python{X.Y}/config`, and shared library modules are installed in :file:`{exec_prefix}/lib/python{X.Y}/lib-dynload`, where *X.Y* - is the version number of Python, for example ``3.2``. - - .. note:: If a :ref:`virtual environment <venv-def>` is in effect, this - value will be changed in ``site.py`` to point to the virtual environment. - The value for the Python installation will still be available, via - :data:`base_exec_prefix`. + is the version number of Python, for example ``2.7``. .. data:: executable @@ -266,15 +245,35 @@ always available. intercepted. +.. data:: exitfunc + + This value is not actually defined by the module, but can be set by the user (or + by a program) to specify a clean-up action at program exit. When set, it should + be a parameterless function. This function will be called when the interpreter + exits. Only one function may be installed in this way; to allow multiple + functions which will be called at termination, use the :mod:`atexit` module. + + .. note:: + + The exit function is not called when the program is killed by a signal, when a + Python fatal internal error is detected, or when ``os._exit()`` is called. + + .. deprecated:: 2.4 + Use :mod:`atexit` instead. + + .. data:: flags - The :term:`struct sequence` *flags* exposes the status of command line - flags. The attributes are read only. + The struct sequence *flags* exposes the status of command line flags. The + attributes are read only. - ============================= ============================= + ============================= =================================== attribute flag - ============================= ============================= + ============================= =================================== :const:`debug` :option:`-d` + :const:`py3k_warning` :option:`-3` + :const:`division_warning` :option:`-Q` + :const:`division_new` :option:`-Qnew <-Q>` :const:`inspect` :option:`-i` :const:`interactive` :option:`-i` :const:`optimize` :option:`-O` or :option:`-OO` @@ -282,30 +281,26 @@ always available. :const:`no_user_site` :option:`-s` :const:`no_site` :option:`-S` :const:`ignore_environment` :option:`-E` + :const:`tabcheck` :option:`-t` or :option:`-tt <-t>` :const:`verbose` :option:`-v` + :const:`unicode` :option:`-U` :const:`bytes_warning` :option:`-b` - :const:`quiet` :option:`-q` :const:`hash_randomization` :option:`-R` - ============================= ============================= + ============================= =================================== - .. versionchanged:: 3.2 - Added ``quiet`` attribute for the new :option:`-q` flag. + .. versionadded:: 2.6 - .. versionadded:: 3.2.3 + .. versionadded:: 2.7.3 The ``hash_randomization`` attribute. - .. versionchanged:: 3.3 - Removed obsolete ``division_warning`` attribute. - - .. data:: float_info - A :term:`struct sequence` holding information about the float type. It - contains low level information about the precision and internal - representation. The values correspond to the various floating-point - constants defined in the standard header file :file:`float.h` for the 'C' - programming language; see section 5.2.4.2.2 of the 1999 ISO/IEC C standard - [C99]_, 'Characteristics of floating types', for details. + A structseq holding information about the float type. It contains low level + information about the precision and internal representation. The values + correspond to the various floating-point constants defined in the standard + header file :file:`float.h` for the 'C' programming language; see section + 5.2.4.2.2 of the 1999 ISO/IEC C standard [C99]_, 'Characteristics of + floating types', for details. .. tabularcolumns:: |l|l|L| @@ -367,25 +362,26 @@ always available. >>> format(float(s), '.16g') # conversion changes value '9876543211234568' + .. versionadded:: 2.6 + .. data:: float_repr_style A string indicating how the :func:`repr` function behaves for floats. If the string has value ``'short'`` then for a finite float ``x``, ``repr(x)`` aims to produce a short string with the property that ``float(repr(x)) == x``. This is the usual behaviour - in Python 3.1 and later. Otherwise, ``float_repr_style`` has value + in Python 2.7 and later. Otherwise, ``float_repr_style`` has value ``'legacy'`` and ``repr(x)`` behaves in the same way as it did in - versions of Python prior to 3.1. + versions of Python prior to 2.7. - .. versionadded:: 3.1 + .. versionadded:: 2.7 .. function:: getcheckinterval() Return the interpreter's "check interval"; see :func:`setcheckinterval`. - .. deprecated:: 3.2 - Use :func:`getswitchinterval` instead. + .. versionadded:: 2.3 .. function:: getdefaultencoding() @@ -393,23 +389,29 @@ always available. Return the name of the current default string encoding used by the Unicode implementation. + .. versionadded:: 2.0 + .. function:: getdlopenflags() Return the current value of the flags that are used for :c:func:`dlopen` calls. - The flag constants are defined in the :mod:`ctypes` and :mod:`DLFCN` modules. + The flag constants are defined in the :mod:`dl` and :mod:`DLFCN` modules. Availability: Unix. + .. versionadded:: 2.2 + .. function:: getfilesystemencoding() - Return the name of the encoding used to convert Unicode filenames into - system file names. The result value depends on the operating system: + Return the name of the encoding used to convert Unicode filenames into system + file names, or ``None`` if the system default encoding is used. The result value + depends on the operating system: * On Mac OS X, the encoding is ``'utf-8'``. * On Unix, the encoding is the user's preference according to the result of - nl_langinfo(CODESET), or ``'utf-8'`` if ``nl_langinfo(CODESET)`` failed. + nl_langinfo(CODESET), or ``None`` if the ``nl_langinfo(CODESET)`` + failed. * On Windows NT+, file names are Unicode natively, so no conversion is performed. :func:`getfilesystemencoding` still returns ``'mbcs'``, as @@ -419,9 +421,7 @@ always available. * On Windows 9x, the encoding is ``'mbcs'``. - .. versionchanged:: 3.2 - On Unix, use ``'utf-8'`` instead of ``None`` if ``nl_langinfo(CODESET)`` - failed. :func:`getfilesystemencoding` result cannot be ``None``. + .. versionadded:: 2.3 .. function:: getrefcount(object) @@ -446,9 +446,6 @@ always available. does not have to hold true for third-party extensions as it is implementation specific. - Only the memory consumption directly attributed to the object is - accounted for, not the memory consumption of objects it refers to. - If given, *default* will be returned if the object does not provide means to retrieve the size. Otherwise a :exc:`TypeError` will be raised. @@ -456,16 +453,7 @@ always available. additional garbage collector overhead if the object is managed by the garbage collector. - See `recursive sizeof recipe <http://code.activestate.com/recipes/577504>`_ - for an example of using :func:`getsizeof` recursively to find the size of - containers and all their contents. - -.. function:: getswitchinterval() - - Return the interpreter's "thread switch interval"; see - :func:`setswitchinterval`. - - .. versionadded:: 3.2 + .. versionadded:: 2.6 .. function:: _getframe([depth]) @@ -489,6 +477,8 @@ always available. Get the profiler function as set by :func:`setprofile`. + .. versionadded:: 2.6 + .. function:: gettrace() @@ -505,6 +495,8 @@ always available. implementation platform, rather than part of the language definition, and thus may not be available in all Python implementations. + .. versionadded:: 2.6 + .. function:: getwindowsversion() @@ -553,35 +545,12 @@ always available. Availability: Windows. - .. versionchanged:: 3.2 + .. versionadded:: 2.3 + .. versionchanged:: 2.7 Changed to a named tuple and added *service_pack_minor*, *service_pack_major*, *suite_mask*, and *product_type*. -.. data:: hash_info - - A :term:`struct sequence` giving parameters of the numeric hash - implementation. For more details about hashing of numeric types, see - :ref:`numeric-hash`. - - +---------------------+--------------------------------------------------+ - | attribute | explanation | - +=====================+==================================================+ - | :const:`width` | width in bits used for hash values | - +---------------------+--------------------------------------------------+ - | :const:`modulus` | prime modulus P used for numeric hash scheme | - +---------------------+--------------------------------------------------+ - | :const:`inf` | hash value returned for a positive infinity | - +---------------------+--------------------------------------------------+ - | :const:`nan` | hash value returned for a nan | - +---------------------+--------------------------------------------------+ - | :const:`imag` | multiplier used for the imaginary part of a | - | | complex number | - +---------------------+--------------------------------------------------+ - - .. versionadded:: 3.2 - - .. data:: hexversion The version number encoded as a single integer. This is guaranteed to increase @@ -597,56 +566,40 @@ always available. This is called ``hexversion`` since it only really looks meaningful when viewed as the result of passing it to the built-in :func:`hex` function. The - :term:`struct sequence` :data:`sys.version_info` may be used for a more - human-friendly encoding of the same information. + ``version_info`` value may be used for a more human-friendly encoding of the + same information. - More details of ``hexversion`` can be found at :ref:`apiabiversion` + The ``hexversion`` is a 32-bit number with the following layout: + +-------------------------+------------------------------------------------+ + | Bits (big endian order) | Meaning | + +=========================+================================================+ + | :const:`1-8` | ``PY_MAJOR_VERSION`` (the ``2`` in | + | | ``2.1.0a3``) | + +-------------------------+------------------------------------------------+ + | :const:`9-16` | ``PY_MINOR_VERSION`` (the ``1`` in | + | | ``2.1.0a3``) | + +-------------------------+------------------------------------------------+ + | :const:`17-24` | ``PY_MICRO_VERSION`` (the ``0`` in | + | | ``2.1.0a3``) | + +-------------------------+------------------------------------------------+ + | :const:`25-28` | ``PY_RELEASE_LEVEL`` (``0xA`` for alpha, | + | | ``0xB`` for beta, ``0xC`` for release | + | | candidate and ``0xF`` for final) | + +-------------------------+------------------------------------------------+ + | :const:`29-32` | ``PY_RELEASE_SERIAL`` (the ``3`` in | + | | ``2.1.0a3``, zero for final releases) | + +-------------------------+------------------------------------------------+ -.. data:: implementation + Thus ``2.1.0a3`` is hexversion ``0x020100a3``. - An object containing information about the implementation of the - currently running Python interpreter. The following attributes are - required to exist in all Python implementations. + .. versionadded:: 1.5.2 - *name* is the implementation's identifier, e.g. ``'cpython'``. The actual - string is defined by the Python implementation, but it is guaranteed to be - lower case. - *version* is a named tuple, in the same format as - :data:`sys.version_info`. It represents the version of the Python - *implementation*. This has a distinct meaning from the specific - version of the Python *language* to which the currently running - interpreter conforms, which ``sys.version_info`` represents. For - example, for PyPy 1.8 ``sys.implementation.version`` might be - ``sys.version_info(1, 8, 0, 'final', 0)``, whereas ``sys.version_info`` - would be ``sys.version_info(2, 7, 2, 'final', 0)``. For CPython they - are the same value, since it is the reference implementation. +.. data:: long_info - *hexversion* is the implementation version in hexadecimal format, like - :data:`sys.hexversion`. - - *cache_tag* is the tag used by the import machinery in the filenames of - cached modules. By convention, it would be a composite of the - implementation's name and version, like ``'cpython-33'``. However, a - Python implementation may use some other value if appropriate. If - ``cache_tag`` is set to ``None``, it indicates that module caching should - be disabled. - - :data:`sys.implementation` may contain additional attributes specific to - the Python implementation. These non-standard attributes must start with - an underscore, and are not described here. Regardless of its contents, - :data:`sys.implementation` will not change during a run of the interpreter, - nor between implementation versions. (It may change between Python - language versions, however.) See `PEP 421` for more information. - - .. versionadded:: 3.3 - - -.. data:: int_info - - A :term:`struct sequence` that holds information about Python's internal - representation of integers. The attributes are read only. + A struct sequence that holds information about Python's + internal representation of integers. The attributes are read only. .. tabularcolumns:: |l|L| @@ -655,27 +608,13 @@ always available. +=========================+==============================================+ | :const:`bits_per_digit` | number of bits held in each digit. Python | | | integers are stored internally in base | - | | ``2**int_info.bits_per_digit`` | + | | ``2**long_info.bits_per_digit`` | +-------------------------+----------------------------------------------+ | :const:`sizeof_digit` | size in bytes of the C type used to | | | represent a digit | +-------------------------+----------------------------------------------+ - .. versionadded:: 3.1 - - -.. function:: intern(string) - - Enter *string* in the table of "interned" strings and return the interned string - -- which is *string* itself or a copy. Interning strings is useful to gain a - little performance on dictionary lookup -- if the keys in a dictionary are - interned, and the lookup key is interned, the key comparisons (after hashing) - can be done by a pointer compare instead of a string compare. Normally, the - names used in Python programs are automatically interned, and the dictionaries - used to hold module, class or instance attributes have interned keys. - - Interned strings are not immortal; you must keep a reference to the return - value of :func:`intern` around to benefit from it. + .. versionadded:: 2.7 .. data:: last_type @@ -687,29 +626,32 @@ always available. Their intended use is to allow an interactive user to import a debugger module and engage in post-mortem debugging without having to re-execute the command that caused the error. (Typical use is ``import pdb; pdb.pm()`` to enter the - post-mortem debugger; see :mod:`pdb` module for + post-mortem debugger; see chapter :ref:`debugger` for more information.) The meaning of the variables is the same as that of the return values from - :func:`exc_info` above. + :func:`exc_info` above. (Since there is only one interactive thread, + thread-safety is not a concern for these variables, unlike for ``exc_type`` + etc.) -.. data:: maxsize +.. data:: maxint - An integer giving the maximum value a variable of type :c:type:`Py_ssize_t` can - take. It's usually ``2**31 - 1`` on a 32-bit platform and ``2**63 - 1`` on a - 64-bit platform. + The largest positive integer supported by Python's regular integer type. This + is at least 2\*\*31-1. The largest negative integer is ``-maxint-1`` --- the + asymmetry results from the use of 2's complement binary arithmetic. +.. data:: maxsize -.. data:: maxunicode + The largest positive integer supported by the platform's Py_ssize_t type, + and thus the maximum size lists, strings, dicts, and many other containers + can have. - An integer giving the value of the largest Unicode code point, - i.e. ``1114111`` (``0x10FFFF`` in hexadecimal). +.. data:: maxunicode - .. versionchanged:: 3.3 - Before :pep:`393`, ``sys.maxunicode`` used to be either ``0xFFFF`` - or ``0x10FFFF``, depending on the configuration option that specified - whether Unicode characters were stored as UCS-2 or UCS-4. + An integer giving the largest supported code point for a Unicode character. The + value of this depends on the configuration option that specifies whether Unicode + characters are stored as UCS-2 or UCS-4. .. data:: meta_path @@ -730,8 +672,12 @@ always available. .. data:: modules + .. index:: builtin: reload + This is a dictionary that maps module names to modules which have already been loaded. This can be manipulated to force reloading of modules and other tricks. + Note that removing a module from this dictionary is *not* the same as calling + :func:`reload` on the corresponding module object. .. data:: path @@ -750,10 +696,10 @@ always available. current directory first. Notice that the script directory is inserted *before* the entries inserted as a result of :envvar:`PYTHONPATH`. - A program is free to modify this list for its own purposes. Only strings - and bytes should be added to :data:`sys.path`; all other data types are - ignored during import. + A program is free to modify this list for its own purposes. + .. versionchanged:: 2.3 + Unicode strings are no longer ignored. .. seealso:: Module :mod:`site` This describes how to use .pth files to extend @@ -774,60 +720,58 @@ always available. A dictionary acting as a cache for :term:`finder` objects. The keys are paths that have been passed to :data:`sys.path_hooks` and the values are the finders that are found. If a path is a valid file system path but no - finder is found on :data:`sys.path_hooks` then ``None`` is - stored. + explicit finder is found on :data:`sys.path_hooks` then ``None`` is + stored to represent the implicit default finder should be used. If the path + is not an existing path then :class:`imp.NullImporter` is set. Originally specified in :pep:`302`. - .. versionchanged:: 3.3 - ``None`` is stored instead of :class:`imp.NullImporter` when no finder - is found. - .. data:: platform This string contains a platform identifier that can be used to append platform-specific components to :data:`sys.path`, for instance. - For Unix systems, except on Linux, this is the lowercased OS name as - returned by ``uname -s`` with the first part of the version as returned by - ``uname -r`` appended, e.g. ``'sunos5'`` or ``'freebsd8'``, *at the time - when Python was built*. Unless you want to test for a specific system - version, it is therefore recommended to use the following idiom:: + For most Unix systems, this is the lowercased OS name as returned by ``uname + -s`` with the first part of the version as returned by ``uname -r`` appended, + e.g. ``'sunos5'``, *at the time when Python was built*. Unless you want to + test for a specific system version, it is therefore recommended to use the + following idiom:: if sys.platform.startswith('freebsd'): # FreeBSD-specific code here... elif sys.platform.startswith('linux'): # Linux-specific code here... + .. versionchanged:: 2.7.3 + Since lots of code check for ``sys.platform == 'linux2'``, and there is + no essential change between Linux 2.x and 3.x, ``sys.platform`` is always + set to ``'linux2'``, even on Linux 3.x. In Python 3.3 and later, the + value will always be set to ``'linux'``, so it is recommended to always + use the ``startswith`` idiom presented above. + For other systems, the values are: - ================ =========================== - System ``platform`` value - ================ =========================== - Linux ``'linux'`` - Windows ``'win32'`` - Windows/Cygwin ``'cygwin'`` - Mac OS X ``'darwin'`` - OS/2 ``'os2'`` - OS/2 EMX ``'os2emx'`` - ================ =========================== - - .. versionchanged:: 3.3 - On Linux, :attr:`sys.platform` doesn't contain the major version anymore. - It is always ``'linux'``, instead of ``'linux2'`` or ``'linux3'``. Since - older Python versions include the version number, it is recommended to - always use the ``startswith`` idiom presented above. + ===================== =========================== + System :data:`platform` value + ===================== =========================== + Linux (2.x *and* 3.x) ``'linux2'`` + Windows ``'win32'`` + Windows/Cygwin ``'cygwin'`` + Mac OS X ``'darwin'`` + OS/2 ``'os2'`` + OS/2 EMX ``'os2emx'`` + RiscOS ``'riscos'`` + AtheOS ``'atheos'`` + ===================== =========================== .. seealso:: - :attr:`os.name` has a coarser granularity. :func:`os.uname` gives system-dependent version information. The :mod:`platform` module provides detailed checks for the system's identity. - .. data:: prefix A string giving the site-specific directory prefix where the platform @@ -837,12 +781,7 @@ always available. library modules is installed in the directory :file:`{prefix}/lib/python{X.Y}` while the platform independent header files (all except :file:`pyconfig.h`) are stored in :file:`{prefix}/include/python{X.Y}`, where *X.Y* is the version - number of Python, for example ``3.2``. - - .. note:: If a :ref:`virtual environment <venv-def>` is in effect, this - value will be changed in ``site.py`` to point to the virtual - environment. The value for the Python installation will still be - available, via :data:`base_prefix`. + number of Python, for example ``2.7``. .. data:: ps1 @@ -860,6 +799,16 @@ always available. implement a dynamic prompt. +.. data:: py3kwarning + + Bool containing the status of the Python 3 warning flag. It's ``True`` + when Python is started with the -3 option. (This should be considered + read-only; setting it to a different value doesn't have an effect on + Python 3 warnings.) + + .. versionadded:: 2.6 + + .. function:: setcheckinterval(interval) Set the interpreter's "check interval". This integer value determines how often @@ -869,10 +818,19 @@ always available. performance for programs using threads. Setting it to a value ``<=`` 0 checks every virtual instruction, maximizing responsiveness as well as overhead. - .. deprecated:: 3.2 - This function doesn't have an effect anymore, as the internal logic for - thread switching and asynchronous tasks has been rewritten. Use - :func:`setswitchinterval` instead. + +.. function:: setdefaultencoding(name) + + Set the current default string encoding used by the Unicode implementation. If + *name* does not match any available encoding, :exc:`LookupError` is raised. + This function is only intended to be used by the :mod:`site` module + implementation and, where needed, by :mod:`sitecustomize`. Once used by the + :mod:`site` module, it is removed from the :mod:`sys` module's namespace. + + .. Note that :mod:`site` is not imported if the :option:`-S` option is passed + to the interpreter, in which case this function will remain available. + + .. versionadded:: 2.0 .. function:: setdlopenflags(n) @@ -881,11 +839,14 @@ always available. the interpreter loads extension modules. Among other things, this will enable a lazy resolving of symbols when importing a module, if called as ``sys.setdlopenflags(0)``. To share symbols across extension modules, call as - ``sys.setdlopenflags(os.RTLD_GLOBAL)``. Symbolic names for the flag modules - can be found in the :mod:`os` module (``RTLD_xxx`` constants, e.g. - :data:`os.RTLD_LAZY`). + ``sys.setdlopenflags(dl.RTLD_NOW | dl.RTLD_GLOBAL)``. Symbolic names for the + flag modules can be either found in the :mod:`dl` module, or in the :mod:`DLFCN` + module. If :mod:`DLFCN` is not available, it can be generated from + :file:`/usr/include/dlfcn.h` using the :program:`h2py` script. Availability: + Unix. + + .. versionadded:: 2.2 - Availability: Unix. .. function:: setprofile(profilefunc) @@ -911,24 +872,11 @@ always available. Python. The highest possible limit is platform-dependent. A user may need to set the - limit higher when they have a program that requires deep recursion and a platform + limit higher when she has a program that requires deep recursion and a platform that supports a higher limit. This should be done with care, because a too-high limit can lead to a crash. -.. function:: setswitchinterval(interval) - - Set the interpreter's thread switch interval (in seconds). This floating-point - value determines the ideal duration of the "timeslices" allocated to - concurrently running Python threads. Please note that the actual value - can be higher, especially if long-running internal functions or methods - are used. Also, which thread becomes scheduled at the end of the interval - is the operating system's decision. The interpreter doesn't have its - own scheduler. - - .. versionadded:: 3.2 - - .. function:: settrace(tracefunc) .. index:: @@ -1008,7 +956,10 @@ always available. available only if Python was compiled with ``--with-tsc``. To understand the output of this dump, read :file:`Python/ceval.c` in the Python sources. + .. versionadded:: 2.4 + .. impl-detail:: + This function is intimately bound to CPython implementation details and thus not likely to be implemented elsewhere. @@ -1017,44 +968,21 @@ always available. stdout stderr - :term:`File objects <file object>` used by the interpreter for standard - input, output and errors: - - * ``stdin`` is used for all interactive input (including calls to - :func:`input`); - * ``stdout`` is used for the output of :func:`print` and :term:`expression` - statements and for the prompts of :func:`input`; - * The interpreter's own prompts and its error messages go to ``stderr``. - - By default, these streams are regular text streams as returned by the - :func:`open` function. Their parameters are chosen as follows: - - * The character encoding is platform-dependent. Under Windows, if the stream - is interactive (that is, if its :meth:`isatty` method returns True), the - console codepage is used, otherwise the ANSI code page. Under other - platforms, the locale encoding is used (see :meth:`locale.getpreferredencoding`). - - Under all platforms though, you can override this value by setting the - :envvar:`PYTHONIOENCODING` environment variable. - - * When interactive, standard streams are line-buffered. Otherwise, they - are block-buffered like regular text files. You can override this - value with the :option:`-u` command-line option. - - To write or read binary data from/to the standard streams, use the - underlying binary :data:`~io.TextIOBase.buffer`. For example, to write - bytes to :data:`stdout`, use ``sys.stdout.buffer.write(b'abc')``. Using - :meth:`io.TextIOBase.detach`, streams can be made binary by default. This - function sets :data:`stdin` and :data:`stdout` to binary:: - - def make_streams_binary(): - sys.stdin = sys.stdin.detach() - sys.stdout = sys.stdout.detach() - - Note that the streams may be replaced with objects (like :class:`io.StringIO`) - that do not support the :attr:`~io.BufferedIOBase.buffer` attribute or the - :meth:`~io.BufferedIOBase.detach` method and can raise :exc:`AttributeError` - or :exc:`io.UnsupportedOperation`. + .. index:: + builtin: input + builtin: raw_input + + File objects corresponding to the interpreter's standard input, output and error + streams. ``stdin`` is used for all interpreter input except for scripts but + including calls to :func:`input` and :func:`raw_input`. ``stdout`` is used for + the output of :keyword:`print` and :term:`expression` statements and for the + prompts of :func:`input` and :func:`raw_input`. The interpreter's own prompts + and (almost all of) its error messages go to ``stderr``. ``stdout`` and + ``stderr`` needn't be built-in file objects: any object is acceptable as long + as it has a :meth:`write` method that takes a string argument. (Changing these + objects doesn't affect the standard I/O streams of processes executed by + :func:`os.popen`, :func:`os.system` or the :func:`exec\*` family of functions in + the :mod:`os` module.) .. data:: __stdin__ @@ -1071,42 +999,25 @@ always available. preferred way to do this is to explicitly save the previous stream before replacing it, and restore the saved object. - .. note:: - Under some conditions ``stdin``, ``stdout`` and ``stderr`` as well as the - original values ``__stdin__``, ``__stdout__`` and ``__stderr__`` can be - None. It is usually the case for Windows GUI apps that aren't connected - to a console and Python apps started with :program:`pythonw`. +.. data:: subversion -.. data:: thread_info + A triple (repo, branch, version) representing the Subversion information of the + Python interpreter. *repo* is the name of the repository, ``'CPython'``. + *branch* is a string of one of the forms ``'trunk'``, ``'branches/name'`` or + ``'tags/name'``. *version* is the output of ``svnversion``, if the interpreter + was built from a Subversion checkout; it contains the revision number (range) + and possibly a trailing 'M' if there were local modifications. If the tree was + exported (or svnversion was not available), it is the revision of + ``Include/patchlevel.h`` if the branch is a tag. Otherwise, it is ``None``. - A :term:`struct sequence` holding information about the thread - implementation. + .. versionadded:: 2.5 - .. tabularcolumns:: |l|p{0.7\linewidth}| - - +------------------+---------------------------------------------------------+ - | Attribute | Explanation | - +==================+=========================================================+ - | :const:`name` | Name of the thread implementation: | - | | | - | | * ``'nt'``: Windows threads | - | | * ``'os2'``: OS/2 threads | - | | * ``'pthread'``: POSIX threads | - | | * ``'solaris'``: Solaris threads | - +------------------+---------------------------------------------------------+ - | :const:`lock` | Name of the lock implementation: | - | | | - | | * ``'semaphore'``: a lock uses a semaphore | - | | * ``'mutex+cond'``: a lock uses a mutex | - | | and a condition variable | - | | * ``None`` if this information is unknown | - +------------------+---------------------------------------------------------+ - | :const:`version` | Name and version of the thread library. It is a string, | - | | or ``None`` if these informations are unknown. | - +------------------+---------------------------------------------------------+ - - .. versionadded:: 3.3 + .. note:: + Python is now `developed <http://docs.python.org/devguide/>`_ using + Mercurial. In recent Python 2.7 bugfix releases, :data:`subversion` + therefore contains placeholder information. It is removed in Python + 3.3. .. data:: tracebacklimit @@ -1131,6 +1042,8 @@ always available. The C API version for this interpreter. Programmers may find this useful when debugging version conflicts between Python and extension modules. + .. versionadded:: 2.3 + .. data:: version_info @@ -1142,8 +1055,10 @@ always available. so ``sys.version_info[0]`` is equivalent to ``sys.version_info.major`` and so on. - .. versionchanged:: 3.1 - Added named component attributes. + .. versionadded:: 2.0 + .. versionchanged:: 2.7 + Added named component attributes + .. data:: warnoptions @@ -1160,30 +1075,6 @@ always available. module for informational purposes; modifying this value has no effect on the registry keys used by Python. Availability: Windows. - -.. data:: _xoptions - - A dictionary of the various implementation-specific flags passed through - the :option:`-X` command-line option. Option names are either mapped to - their values, if given explicitly, or to :const:`True`. Example:: - - $ ./python -Xa=b -Xc - Python 3.2a3+ (py3k, Oct 16 2010, 20:14:50) - [GCC 4.4.3] on linux2 - Type "help", "copyright", "credits" or "license" for more information. - >>> import sys - >>> sys._xoptions - {'a': 'b', 'c': True} - - .. impl-detail:: - - This is a CPython-specific way of accessing options passed through - :option:`-X`. Other implementations may export them through other - means, or not at all. - - .. versionadded:: 3.2 - - .. rubric:: Citations .. [C99] ISO/IEC 9899:1999. "Programming languages -- C." A public draft of this standard is available at http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1256.pdf . |