From: Georg Brandl Date: Thu, 28 Mar 2013 12:35:18 +0000 (+0100) Subject: Backport rev. 3ae74b361f53 to 2.7 branch. X-Git-Tag: v2.7.5~132 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=75da35747eabe6f9e0d3158d4f367332155627d9;p=python Backport rev. 3ae74b361f53 to 2.7 branch. --- 75da35747eabe6f9e0d3158d4f367332155627d9 diff --cc Doc/c-api/unicode.rst index 73f6fe6008,abf353f728..fd4fe233f1 --- a/Doc/c-api/unicode.rst +++ b/Doc/c-api/unicode.rst @@@ -251,7 -435,12 +251,9 @@@ APIs .. % The descriptions for %zd and %zu are wrong, but the truth is complicated .. % because not all compilers support the %z width modifier -- we fake it .. % when necessary via interpolating PY_FORMAT_SIZE_T. - .. % Similar comments apply to the %ll width modifier and - .. % PY_FORMAT_LONG_LONG. + .. tabularcolumns:: |l|l|L| + +-------------------+---------------------+--------------------------------+ | Format Characters | Type | Comment | +===================+=====================+================================+ diff --cc Doc/distutils/apiref.rst index b37e02cb68,c323775cb4..f34a8eaa67 --- a/Doc/distutils/apiref.rst +++ b/Doc/distutils/apiref.rst @@@ -163,8 -167,10 +167,10 @@@ the full reference .. class:: Extension The Extension class describes a single C or C++extension module in a setup - script. It accepts the following keyword arguments in its constructor: + script. It accepts the following keyword arguments in its constructor + .. tabularcolumns:: |l|L|l| + +------------------------+--------------------------------+---------------------------+ | argument name | value | type | +========================+================================+===========================+ diff --cc Doc/faq/gui.rst index 50a30b034e,5827f28c3b..bb544202d9 --- a/Doc/faq/gui.rst +++ b/Doc/faq/gui.rst @@@ -4,8 -4,16 +4,10 @@@ Graphic User Interface FAQ ========================== - .. contents:: + .. only:: html + + .. contents:: -.. XXX need review for Python 3. - - -General GUI Questions -===================== - What platform-independent GUI toolkits exist for Python? ======================================================== diff --cc Doc/faq/windows.rst index 0abe2e98c4,651ba22683..7cc6033d70 --- a/Doc/faq/windows.rst +++ b/Doc/faq/windows.rst @@@ -6,8 -6,14 +6,10 @@@ Python on Windows FAQ ===================== - .. contents:: + .. only:: html + + .. contents:: -.. XXX need review for Python 3. - XXX need review for Windows Vista/Seven? - - How do I run a Python program under Windows? -------------------------------------------- diff --cc Doc/library/codecs.rst index 62bb5044ee,9e1a9c744a..ce850f6c06 --- a/Doc/library/codecs.rst +++ b/Doc/library/codecs.rst @@@ -1094,83 -1142,91 +1098,85 @@@ particular, the following variants typi | utf_8_sig | | all languages | +-----------------+--------------------------------+--------------------------------+ -.. XXX fix here, should be in above table - -.. tabularcolumns:: |l|p{0.3\linewidth}|p{0.3\linewidth}| - -+--------------------+---------+---------------------------+ -| Codec | Aliases | Purpose | -+====================+=========+===========================+ -| idna | | Implements :rfc:`3490`, | -| | | see also | -| | | :mod:`encodings.idna` | -+--------------------+---------+---------------------------+ -| mbcs | dbcs | Windows only: Encode | -| | | operand according to the | -| | | ANSI codepage (CP_ACP) | -+--------------------+---------+---------------------------+ -| palmos | | Encoding of PalmOS 3.5 | -+--------------------+---------+---------------------------+ -| punycode | | Implements :rfc:`3492` | -+--------------------+---------+---------------------------+ -| raw_unicode_escape | | Produce a string that is | -| | | suitable as raw Unicode | -| | | literal in Python source | -| | | code | -+--------------------+---------+---------------------------+ -| undefined | | Raise an exception for | -| | | all conversions. Can be | -| | | used as the system | -| | | encoding if no automatic | -| | | coercion between byte and | -| | | Unicode strings is | -| | | desired. | -+--------------------+---------+---------------------------+ -| unicode_escape | | Produce a string that is | -| | | suitable as Unicode | -| | | literal in Python source | -| | | code | -+--------------------+---------+---------------------------+ -| unicode_internal | | Return the internal | -| | | representation of the | -| | | operand | -| | | | -| | | .. deprecated:: 3.3 | -+--------------------+---------+---------------------------+ - -The following codecs provide bytes-to-bytes mappings. - -.. tabularcolumns:: |l|p{0.3\linewidth}|p{0.3\linewidth}| - -+--------------------+---------------------------+---------------------------+ -| Codec | Aliases | Purpose | -+====================+===========================+===========================+ -| base64_codec | base64, base-64 | Convert operand to MIME | -| | | base64 | -+--------------------+---------------------------+---------------------------+ -| bz2_codec | bz2 | Compress the operand | -| | | using bz2 | -+--------------------+---------------------------+---------------------------+ -| hex_codec | hex | Convert operand to | -| | | hexadecimal | -| | | representation, with two | -| | | digits per byte | -+--------------------+---------------------------+---------------------------+ -| quopri_codec | quopri, quoted-printable, | Convert operand to MIME | -| | quotedprintable | quoted printable | -+--------------------+---------------------------+---------------------------+ -| uu_codec | uu | Convert the operand using | -| | | uuencode | -+--------------------+---------------------------+---------------------------+ -| zlib_codec | zip, zlib | Compress the operand | -| | | using gzip | -+--------------------+---------------------------+---------------------------+ - -The following codecs provide string-to-string mappings. - -.. tabularcolumns:: |l|p{0.3\linewidth}|p{0.3\linewidth}| - -+--------------------+---------------------------+---------------------------+ -| Codec | Aliases | Purpose | -+====================+===========================+===========================+ -| rot_13 | rot13 | Returns the Caesar-cypher | -| | | encryption of the operand | -+--------------------+---------------------------+---------------------------+ - -.. versionadded:: 3.2 - bytes-to-bytes and string-to-string codecs. +A number of codecs are specific to Python, so their codec names have no meaning +outside Python. Some of them don't convert from Unicode strings to byte strings, +but instead use the property of the Python codecs machinery that any bijective +function with one argument can be considered as an encoding. + +For the codecs listed below, the result in the "encoding" direction is always a +byte string. The result of the "decoding" direction is listed as operand type in +the table. + ++.. tabularcolumns:: |l|p{0.3\linewidth}|l|p{0.3\linewidth}| ++ ++--------------------+---------------------------+----------------+---------------------------+ +| Codec | Aliases | Operand type | Purpose | ++====================+===========================+================+===========================+ +| base64_codec | base64, base-64 | byte string | Convert operand to MIME | +| | | | base64 | ++--------------------+---------------------------+----------------+---------------------------+ +| bz2_codec | bz2 | byte string | Compress the operand | +| | | | using bz2 | ++--------------------+---------------------------+----------------+---------------------------+ +| hex_codec | hex | byte string | Convert operand to | +| | | | hexadecimal | +| | | | representation, with two | +| | | | digits per byte | ++--------------------+---------------------------+----------------+---------------------------+ +| idna | | Unicode string | Implements :rfc:`3490`, | +| | | | see also | +| | | | :mod:`encodings.idna` | ++--------------------+---------------------------+----------------+---------------------------+ +| mbcs | dbcs | Unicode string | Windows only: Encode | +| | | | operand according to the | +| | | | ANSI codepage (CP_ACP) | ++--------------------+---------------------------+----------------+---------------------------+ +| palmos | | Unicode string | Encoding of PalmOS 3.5 | ++--------------------+---------------------------+----------------+---------------------------+ +| punycode | | Unicode string | Implements :rfc:`3492` | ++--------------------+---------------------------+----------------+---------------------------+ +| quopri_codec | quopri, quoted-printable, | byte string | Convert operand to MIME | +| | quotedprintable | | quoted printable | ++--------------------+---------------------------+----------------+---------------------------+ +| raw_unicode_escape | | Unicode string | Produce a string that is | +| | | | suitable as raw Unicode | +| | | | literal in Python source | +| | | | code | ++--------------------+---------------------------+----------------+---------------------------+ +| rot_13 | rot13 | Unicode string | Returns the Caesar-cypher | +| | | | encryption of the operand | ++--------------------+---------------------------+----------------+---------------------------+ +| string_escape | | byte string | Produce a string that is | +| | | | suitable as string | +| | | | literal in Python source | +| | | | code | ++--------------------+---------------------------+----------------+---------------------------+ +| undefined | | any | Raise an exception for | +| | | | all conversions. Can be | +| | | | used as the system | +| | | | encoding if no automatic | +| | | | :term:`coercion` between | +| | | | byte and Unicode strings | +| | | | is desired. | ++--------------------+---------------------------+----------------+---------------------------+ +| unicode_escape | | Unicode string | Produce a string that is | +| | | | suitable as Unicode | +| | | | literal in Python source | +| | | | code | ++--------------------+---------------------------+----------------+---------------------------+ +| unicode_internal | | Unicode string | Return the internal | +| | | | representation of the | +| | | | operand | ++--------------------+---------------------------+----------------+---------------------------+ +| uu_codec | uu | byte string | Convert the operand using | +| | | | uuencode | ++--------------------+---------------------------+----------------+---------------------------+ +| zlib_codec | zip, zlib | byte string | Compress the operand | +| | | | using gzip | ++--------------------+---------------------------+----------------+---------------------------+ + +.. versionadded:: 2.3 + The ``idna`` and ``punycode`` encodings. :mod:`encodings.idna` --- Internationalized Domain Names in Applications diff --cc Doc/library/subprocess.rst index 2c44b4921b,4212e0250a..d29fbecfa1 --- a/Doc/library/subprocess.rst +++ b/Doc/library/subprocess.rst @@@ -143,8 -167,10 +143,10 @@@ use cases, the underlying :class:`Popen ... shell=True) 'ls: non_existent_file: No such file or directory\n' - .. versionadded:: 3.1 + .. versionadded:: 2.7 + .. + .. warning:: Invoking the system shell with ``shell=True`` can be a security hazard diff --cc Doc/library/sys.rst index f5f8148bda,e7e853dd8e..6f8b8bb3a9 --- a/Doc/library/sys.rst +++ b/Doc/library/sys.rst @@@ -281,27 -282,33 +281,29 @@@ 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| + +---------------------+----------------+--------------------------------------------------+ | attribute | float.h macro | explanation | +=====================+================+==================================================+ @@@ -564,41 -597,59 +566,43 @@@ 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| + +-------------------------+----------------------------------------------+ | Attribute | Explanation | +=========================+==============================================+ diff --cc Doc/library/turtle.rst index e05305acb7,aea9450bec..c9bdfea7a8 --- a/Doc/library/turtle.rst +++ b/Doc/library/turtle.rst @@@ -2155,29 -2277,37 +2155,31 @@@ not from within the demo-viewer) Demo scripts ============ -There is a set of demo scripts in the :mod:`turtledemo` package. These -scripts can be run and viewed using the supplied demo viewer as follows:: - - python -m turtledemo +There is a set of demo scripts in the turtledemo directory located in the +:file:`Demo/turtle` directory in the source distribution. -Alternatively, you can run the demo scripts individually. For example, :: - - python -m turtledemo.bytedesign - -The :mod:`turtledemo` package directory contains: +It contains: - a set of 15 demo scripts demonstrating different features of the new module - :mod:`turtle`; -- a demo viewer :file:`__main__.py` which can be used to view the sourcecode + :mod:`turtle` +- a demo viewer :file:`turtleDemo.py` which can be used to view the sourcecode of the scripts and run them at the same time. 14 of the examples can be accessed via the Examples menu; all of them can also be run standalone. -- The example :mod:`turtledemo.two_canvases` demonstrates the simultaneous +- The example :file:`turtledemo_two_canvases.py` demonstrates the simultaneous use of two canvases with the turtle module. Therefore it only can be run standalone. -- There is a :file:`turtle.cfg` file in this directory, which serves as an +- There is a :file:`turtle.cfg` file in this directory, which also serves as an example for how to write and use such files. -The demo scripts are: +The demoscripts are: + .. tabularcolumns:: |l|L|L| + +----------------+------------------------------+-----------------------+ | Name | Description | Features | - +----------------+------------------------------+-----------------------+ + +================+==============================+=======================+ | bytedesign | complex classical | :func:`tracer`, delay,| -| | turtle graphics pattern | :func:`update` | +| | turtlegraphics pattern | :func:`update` | +----------------+------------------------------+-----------------------+ | chaos | graphs Verhulst dynamics, | world coordinates | | | shows that computer's | | diff --cc Doc/reference/datamodel.rst index d76dc9207b,e815690865..79114c1ec2 --- a/Doc/reference/datamodel.rst +++ b/Doc/reference/datamodel.rst @@@ -481,49 -448,60 +481,51 @@@ Callable type Special attributes: + .. tabularcolumns:: |l|L|l| + - +-------------------------+-------------------------------+-----------+ - | Attribute | Meaning | | - +=========================+===============================+===========+ - | :attr:`__doc__` | The function's documentation | Writable | - | | string, or ``None`` if | | - | | unavailable | | - +-------------------------+-------------------------------+-----------+ - | :attr:`__name__` | The function's name | Writable | - +-------------------------+-------------------------------+-----------+ - | :attr:`__qualname__` | The function's | Writable | - | | :term:`qualified name` | | - | | | | - | | .. versionadded:: 3.3 | | - +-------------------------+-------------------------------+-----------+ - | :attr:`__module__` | The name of the module the | Writable | - | | function was defined in, or | | - | | ``None`` if unavailable. | | - +-------------------------+-------------------------------+-----------+ - | :attr:`__defaults__` | A tuple containing default | Writable | - | | argument values for those | | - | | arguments that have defaults, | | - | | or ``None`` if no arguments | | - | | have a default value | | - +-------------------------+-------------------------------+-----------+ - | :attr:`__code__` | The code object representing | Writable | - | | the compiled function body. | | - +-------------------------+-------------------------------+-----------+ - | :attr:`__globals__` | A reference to the dictionary | Read-only | - | | that holds the function's | | - | | global variables --- the | | - | | global namespace of the | | - | | module in which the function | | - | | was defined. | | - +-------------------------+-------------------------------+-----------+ - | :attr:`__dict__` | The namespace supporting | Writable | - | | arbitrary function | | - | | attributes. | | - +-------------------------+-------------------------------+-----------+ - | :attr:`__closure__` | ``None`` or a tuple of cells | Read-only | - | | that contain bindings for the | | - | | function's free variables. | | - +-------------------------+-------------------------------+-----------+ - | :attr:`__annotations__` | A dict containing annotations | Writable | - | | of parameters. The keys of | | - | | the dict are the parameter | | - | | names, or ``'return'`` for | | - | | the return annotation, if | | - | | provided. | | - +-------------------------+-------------------------------+-----------+ - | :attr:`__kwdefaults__` | A dict containing defaults | Writable | - | | for keyword-only parameters. | | - +-------------------------+-------------------------------+-----------+ + +-----------------------+-------------------------------+-----------+ + | Attribute | Meaning | | + +=======================+===============================+===========+ + | :attr:`func_doc` | The function's documentation | Writable | + | | string, or ``None`` if | | + | | unavailable | | + +-----------------------+-------------------------------+-----------+ + | :attr:`__doc__` | Another way of spelling | Writable | + | | :attr:`func_doc` | | + +-----------------------+-------------------------------+-----------+ + | :attr:`func_name` | The function's name | Writable | + +-----------------------+-------------------------------+-----------+ + | :attr:`__name__` | Another way of spelling | Writable | + | | :attr:`func_name` | | + +-----------------------+-------------------------------+-----------+ + | :attr:`__module__` | The name of the module the | Writable | + | | function was defined in, or | | + | | ``None`` if unavailable. | | + +-----------------------+-------------------------------+-----------+ + | :attr:`func_defaults` | A tuple containing default | Writable | + | | argument values for those | | + | | arguments that have defaults, | | + | | or ``None`` if no arguments | | + | | have a default value | | + +-----------------------+-------------------------------+-----------+ + | :attr:`func_code` | The code object representing | Writable | + | | the compiled function body. | | + +-----------------------+-------------------------------+-----------+ + | :attr:`func_globals` | A reference to the dictionary | Read-only | + | | that holds the function's | | + | | global variables --- the | | + | | global namespace of the | | + | | module in which the function | | + | | was defined. | | + +-----------------------+-------------------------------+-----------+ + | :attr:`func_dict` | The namespace supporting | Writable | + | | arbitrary function | | + | | attributes. | | + +-----------------------+-------------------------------+-----------+ + | :attr:`func_closure` | ``None`` or a tuple of cells | Read-only | + | | that contain bindings for the | | + | | function's free variables. | | + +-----------------------+-------------------------------+-----------+ Most of the attributes labelled "Writable" check the type of the assigned value. diff --cc Doc/reference/expressions.rst index 812fb70ed2,c866f8493d..a11ee6e262 --- a/Doc/reference/expressions.rst +++ b/Doc/reference/expressions.rst @@@ -1370,8 -1335,8 +1370,8 @@@ groups from right to left) | :keyword:`not` ``x`` | Boolean NOT | +-----------------------------------------------+-------------------------------------+ | :keyword:`in`, :keyword:`not in`, | Comparisons, including membership | - | :keyword:`is`, :keyword:`is not`, ``<``, | tests and identity tests, | + | :keyword:`is`, :keyword:`is not`, ``<``, | tests and identity tests | -| ``<=``, ``>``, ``>=``, ``!=``, ``==`` | | +| ``<=``, ``>``, ``>=``, ``<>``, ``!=``, ``==`` | | +-----------------------------------------------+-------------------------------------+ | ``|`` | Bitwise OR | +-----------------------------------------------+-------------------------------------+