mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-09-26 18:29:57 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 10

Revision pass: lots of edits, typo fixes, rearrangements

Browse source
This commit is contained in:
Andrew M. Kuchling 2010-05-12 00:38:44 +00:00
parent fd25594aa4
commit 2702491687
1 changed files with 212 additions and 191 deletions
Download patch file Download diff file Expand all files Collapse all files

403
Doc/whatsnew/2.7.rst
View file

@ -56,12 +56,7 @@ This article explains the new features in Python 2.7. The final
release of 2.7 is currently scheduled for July 2010; the detailed release of 2.7 is currently scheduled for July 2010; the detailed
schedule is described in :pep:`373`. schedule is described in :pep:`373`.
Python 2.7 is planned to be the last of the 2.x releases, so we worked Numeric handling has been improved in many ways, for both
on making it a good release for the long term. To help with porting
to Python 3, several new features from the Python 3.x series have been
included in 2.7.
Numeric handling has been improved in many ways, both for
floating-point numbers and for the :class:`Decimal` class. There are floating-point numbers and for the :class:`Decimal` class. There are
some useful additions to the standard library, such as a greatly some useful additions to the standard library, such as a greatly
enhanced :mod:`unittest` module, the :mod:`argparse` module for enhanced :mod:`unittest` module, the :mod:`argparse` module for
@ -69,6 +64,11 @@ parsing command-line options, convenient ordered-dictionary and
:class:`Counter` classes in the :mod:`collections` module, and many :class:`Counter` classes in the :mod:`collections` module, and many
other improvements. other improvements.
Python 2.7 is planned to be the last of the 2.x releases, so we worked
on making it a good release for the long term. To help with porting
to Python 3, several new features from the Python 3.x series have been
included in 2.7.
This article doesn't attempt to provide a complete specification of This article doesn't attempt to provide a complete specification of
the new features, but instead provides a convenient overview. For the new features, but instead provides a convenient overview. For
full details, you should refer to the documentation for Python 2.7 at full details, you should refer to the documentation for Python 2.7 at
@ -98,7 +98,7 @@ Two consequences of the long-term significance of 2.7 are:
releases beyond the typical two years. releases beyond the typical two years.
* A policy decision was made to silence warnings only of interest to * A policy decision was made to silence warnings only of interest to
developers by default. :exc:`DeprecationWarning` and its developers. :exc:`DeprecationWarning` and its
descendants are now ignored unless otherwise requested, preventing descendants are now ignored unless otherwise requested, preventing
users from seeing warnings triggered by an application. This change users from seeing warnings triggered by an application. This change
was also made in the branch that will become Python 3.2. (Discussed was also made in the branch that will become Python 3.2. (Discussed
@ -113,13 +113,13 @@ Two consequences of the long-term significance of 2.7 are:
applications who are not directly involved in the development of applications who are not directly involved in the development of
those applications. :exc:`DeprecationWarning` messages are those applications. :exc:`DeprecationWarning` messages are
irrelevant to such users, making them worry about an application irrelevant to such users, making them worry about an application
that's actually working correctly and burdening the developers of that's actually working correctly and burdening application developers
these applications with responding to these concerns. with responding to these concerns.
You can re-enable display of :exc:`DeprecationWarning` messages by You can re-enable display of :exc:`DeprecationWarning` messages by
running Python with the :option:`-Wdefault` (short form: running Python with the :option:`-Wdefault` (short form:
:option:`-Wd`) switch, or by setting the :envvar:`PYTHONWARNINGS` :option:`-Wd`) switch, or by setting the :envvar:`PYTHONWARNINGS`
environment variable to ``"default"`` or ``"d"``) before running environment variable to ``"default"`` (or ``"d"``) before running
Python. Python code can also re-enable them Python. Python code can also re-enable them
by calling ``warnings.simplefilter('default')``. by calling ``warnings.simplefilter('default')``.
@ -139,24 +139,26 @@ A partial list of 3.1 features that were backported to 2.7:
* Multiple context managers in a single :keyword:`with` statement. * Multiple context managers in a single :keyword:`with` statement.
* A new version of the :mod:`io` library, rewritten in C for performance. * A new version of the :mod:`io` library, rewritten in C for performance.
* The ordered-dictionary type described in :ref:`pep-0372`. * The ordered-dictionary type described in :ref:`pep-0372`.
* The new format specifier described in :ref:`pep-0378`. * The new ``","`` format specifier described in :ref:`pep-0378`.
* The :class:`memoryview` object. * The :class:`memoryview` object.
* A small subset of the :mod:`importlib` module `described below <#importlib-section>`__. * A small subset of the :mod:`importlib` module,
`described below <#importlib-section>`__.
* Float-to-string and string-to-float conversions now round their * Float-to-string and string-to-float conversions now round their
results more correctly. And :func:`repr` of a floating-point results more correctly, and :func:`repr` of a floating-point
number *x* returns a result that's guaranteed to round back to the number *x* returns a result that's guaranteed to round back to the
same number when converted back to a string. same number when converted back to a string.
* The :ctype:`PyCapsule` type, used to provide a C API for extension modules. * The :ctype:`PyCapsule` type, used to provide a C API for extension modules.
* The :cfunc:`PyLong_AsLongAndOverflow` C API function. * The :cfunc:`PyLong_AsLongAndOverflow` C API function.
One porting change: the :option:`-3` switch now automatically
enables the :option:`-Qwarn` switch that causes warnings
about using classic division with integers and long integers.
Other new Python3-mode warnings include: Other new Python3-mode warnings include:
* :func:`operator.isCallable` and :func:`operator.sequenceIncludes`, * :func:`operator.isCallable` and :func:`operator.sequenceIncludes`,
which are not supported in 3.x. which are not supported in 3.x, now trigger warnings.
* The :option:`-3` switch now automatically
enables the :option:`-Qwarn` switch that causes warnings
about using classic division with integers and long integers.
.. ======================================================================== .. ========================================================================
.. Large, PEP-level features and changes should be described here. .. Large, PEP-level features and changes should be described here.
@ -170,16 +172,16 @@ PEP 372: Adding an Ordered Dictionary to collections
Regular Python dictionaries iterate over key/value pairs in arbitrary order. Regular Python dictionaries iterate over key/value pairs in arbitrary order.
Over the years, a number of authors have written alternative implementations Over the years, a number of authors have written alternative implementations
that remember the order that the keys were originally inserted. Based on that remember the order that the keys were originally inserted. Based on
the experiences from those implementations, a new the experiences from those implementations, 2.7 introduces a new
:class:`~collections.OrderedDict` class has been introduced in the :class:`~collections.OrderedDict` class in the :mod:`collections` module.
:mod:`collections` module.
The :class:`~collections.OrderedDict` API is substantially the same as regular The :class:`~collections.OrderedDict` API provides the same interface as regular
dictionaries but will iterate over keys and values in a guaranteed order dictionaries but iterates over keys and values in a guaranteed order
depending on when a key was first inserted:: depending on when a key was first inserted::
>>> from collections import OrderedDict >>> from collections import OrderedDict
>>> d = OrderedDict([('first', 1), ('second', 2), >>> d = OrderedDict([('first', 1),
... ('second', 2),
... ('third', 3)]) ... ('third', 3)])
>>> d.items() >>> d.items()
[('first', 1), ('second', 2), ('third', 3)] [('first', 1), ('second', 2), ('third', 3)]
@ -216,9 +218,11 @@ oldest key is selected::
Comparing two ordered dictionaries checks both the keys and values, Comparing two ordered dictionaries checks both the keys and values,
and requires that the insertion order was the same:: and requires that the insertion order was the same::
>>> od1 = OrderedDict([('first', 1), ('second', 2), >>> od1 = OrderedDict([('first', 1),
... ('second', 2),
... ('third', 3)]) ... ('third', 3)])
>>> od2 = OrderedDict([('third', 3), ('first', 1), >>> od2 = OrderedDict([('third', 3),
... ('first', 1),
... ('second', 2)]) ... ('second', 2)])
>>> od1 == od2 >>> od1 == od2
False False
@ -239,9 +243,9 @@ remains O(1).
The standard library now supports use of ordered dictionaries in several The standard library now supports use of ordered dictionaries in several
modules. modules.
* The :mod:`ConfigParser` module uses them by default, letting * The :mod:`ConfigParser` module uses them by default, meaning that
configuration files be read, modified, and then written back in their original configuration files can now read, modified, and then written back
order. in their original order.
* The :meth:`~collections.somenamedtuple._asdict()` method for * The :meth:`~collections.somenamedtuple._asdict()` method for
:func:`collections.namedtuple` now returns an ordered dictionary with the :func:`collections.namedtuple` now returns an ordered dictionary with the
@ -265,7 +269,7 @@ PEP 378: Format Specifier for Thousands Separator
================================================= =================================================
To make program output more readable, it can be useful to add To make program output more readable, it can be useful to add
separators to large numbers and render them as separators to large numbers, rendering them as
18,446,744,073,709,551,616 instead of 18446744073709551616. 18,446,744,073,709,551,616 instead of 18446744073709551616.
The fully general solution for doing this is the :mod:`locale` module, The fully general solution for doing this is the :mod:`locale` module,
@ -301,13 +305,13 @@ PEP 389: The argparse Module for Parsing Command Lines
====================================================== ======================================================
The :mod:`argparse` module for parsing command-line arguments was The :mod:`argparse` module for parsing command-line arguments was
added, intended as a more powerful replacement for the added as a more powerful replacement for the
:mod:`optparse` module. :mod:`optparse` module.
This means Python now supports three different modules for parsing This means Python now supports three different modules for parsing
command-line arguments: :mod:`getopt`, :mod:`optparse`, and command-line arguments: :mod:`getopt`, :mod:`optparse`, and
:mod:`argparse`. The :mod:`getopt` module closely resembles the C :mod:`argparse`. The :mod:`getopt` module closely resembles the C
:cfunc:`getopt` function, so it remains useful if you're writing a library's :cfunc:`getopt` function, so it remains useful if you're writing a
Python prototype that will eventually be rewritten in C. Python prototype that will eventually be rewritten in C.
:mod:`optparse` becomes redundant, but there are no plans to remove it :mod:`optparse` becomes redundant, but there are no plans to remove it
because there are many scripts still using it, and there's no because there are many scripts still using it, and there's no
@ -359,23 +363,28 @@ are automatically added, and produce neatly formatted output::
-o FILE direct output to FILE instead of stdout -o FILE direct output to FILE instead of stdout
-C NUM display NUM lines of added context -C NUM display NUM lines of added context
Similarly to :mod:`optparse`, the command-line switches and arguments As with :mod:`optparse`, the command-line switches and arguments
are returned as an object with attributes named by the *dest* parameters:: are returned as an object with attributes named by the *dest* parameters::
-> ./python.exe argparse-example.py -v -> ./python.exe argparse-example.py -v
{'output': None, 'is_verbose': True, 'context': 0, 'inputs': []} {'output': None,
'is_verbose': True,
'context': 0,
'inputs': []}
-> ./python.exe argparse-example.py -v -o /tmp/output -C 4 file1 file2 -> ./python.exe argparse-example.py -v -o /tmp/output -C 4 file1 file2
{'output': '/tmp/output', 'is_verbose': True, 'context': 4, {'output': '/tmp/output',
'is_verbose': True,
'context': 4,
'inputs': ['file1', 'file2']} 'inputs': ['file1', 'file2']}
:mod:`argparse` has much fancier validation than :mod:`optparse`; you :mod:`argparse` has much fancier validation than :mod:`optparse`; you
can specify an exact number of arguments as an integer, 0 or more can specify an exact number of arguments as an integer, 0 or more
arguments by passing ``'*'``, 1 or more by passing ``'+'``, or an arguments by passing ``'*'``, 1 or more by passing ``'+'``, or an
optional argument with ``'?'``. A top-level parser can contain optional argument with ``'?'``. A top-level parser can contain
sub-parsers, so you can define subcommands that have different sets of sub-parsers to define subcommands that have different sets of
switches, as in ``svn commit``, ``svn checkout``, etc. You can switches, as in ``svn commit``, ``svn checkout``, etc. You can
specify an argument type as :class:`~argparse.FileType`, which will specify an argument's type as :class:`~argparse.FileType`, which will
automatically open files for you and understands that ``'-'`` means automatically open files for you and understands that ``'-'`` means
standard input or output. standard input or output.
@ -384,6 +393,8 @@ standard input or output.
`argparse module documentation <http://docs.python.org/dev/library/argparse.html>`__ `argparse module documentation <http://docs.python.org/dev/library/argparse.html>`__
`Upgrading optparse code to use argparse <http://docs.python.org/dev/library/argparse.html#upgrading-optparse-code>`__ `Upgrading optparse code to use argparse <http://docs.python.org/dev/library/argparse.html#upgrading-optparse-code>`__
Part of the Python documentation, describing how to convert
code that uses :mod:`optparse`.
:pep:`389` - argparse - New Command Line Parsing Module :pep:`389` - argparse - New Command Line Parsing Module
PEP written and implemented by Steven Bethard. PEP written and implemented by Steven Bethard.
@ -391,26 +402,25 @@ standard input or output.
PEP 391: Dictionary-Based Configuration For Logging PEP 391: Dictionary-Based Configuration For Logging
==================================================== ====================================================
.. not documented in library reference yet. .. XXX not documented in library reference yet; add link here once it's added.
The :mod:`logging` module is very flexible; an application can define The :mod:`logging` module is very flexible; applications can define
a tree of logging subsystems, and each logger in this tree can filter a tree of logging subsystems, and each logger in this tree can filter
out certain messages, format them differently, and direct messages to out certain messages, format them differently, and direct messages to
a varying number of handlers. a varying number of handlers.
All this flexibility can require a lot of configuration. You can All this flexibility can require a lot of configuration. You can
write Python statements to create objects and set their properties, write Python statements to create objects and set their properties,
but a complex set-up would require verbose but boring code. but a complex set-up requires verbose but boring code.
:mod:`logging` also supports a :func:`~logging.config.fileConfig` :mod:`logging` also supports a :func:`~logging.config.fileConfig`
function that parses a file, but the file format doesn't support function that parses a file, but the file format doesn't support
configuring filters, and it's messier to generate programmatically. configuring filters, and it's messier to generate programmatically.
Python 2.7 adds a :func:`~logging.config.dictConfig` function that Python 2.7 adds a :func:`~logging.config.dictConfig` function that
uses a dictionary, and there are many ways to produce a dictionary uses a dictionary to configure logging. There are many ways to
from different sources. You can construct one with code, of course. produce a dictionary from different sources: construct one with code;
Python's standard library now includes a JSON parser, so you could parse a file containing JSON; or use a YAML parsing library if one is
parse a file containing JSON, or you could use a YAML parsing library installed.
if one is installed.
The following example configures two loggers, the root logger and a The following example configures two loggers, the root logger and a
logger named "network". Messages sent to the root logger will be logger named "network". Messages sent to the root logger will be
@ -424,17 +434,18 @@ that will be rotated once the log reaches 1Mb.
import logging.config import logging.config
configdict = { configdict = {
'version': 1, # Must be 1 at present 'version': 1, # Configuration schema in use; must be 1 for now
'formatters': { 'formatters': {
'standard': { 'standard': {
'format': '%(asctime)s %(name)-15s %(levelname)-8s %(message)s'}}, 'format': ('%(asctime)s %(name)-15s '
'%(levelname)-8s %(message)s')}},
'handlers': {'netlog': {'backupCount': 10, 'handlers': {'netlog': {'backupCount': 10,
'class': 'logging.handlers.RotatingFileHandler', 'class': 'logging.handlers.RotatingFileHandler',
'filename': '/logs/network.log', 'filename': '/logs/network.log',
'formatter': 'standard', 'formatter': 'standard',
'level': 'INFO', 'level': 'INFO',
'maxBytes': 1024*1024}, 'maxBytes': 1024*1024},
'syslog': {'class': 'logging.handlers.SysLogHandler', 'syslog': {'class': 'logging.handlers.SysLogHandler',
'formatter': 'standard', 'formatter': 'standard',
'level': 'ERROR'}}, 'level': 'ERROR'}},
@ -497,7 +508,7 @@ instead of a fully materialized list.
It's not possible to change the return values of :meth:`keys`, It's not possible to change the return values of :meth:`keys`,
:meth:`values`, and :meth:`items` in Python 2.7 because too much code :meth:`values`, and :meth:`items` in Python 2.7 because too much code
would break. Instead the 3.x versions were added under the new names would break. Instead the 3.x versions were added under the new names
of :meth:`viewkeys`, :meth:`viewvalues`, and :meth:`viewitems`. :meth:`viewkeys`, :meth:`viewvalues`, and :meth:`viewitems`.
:: ::
@ -507,8 +518,9 @@ of :meth:`viewkeys`, :meth:`viewvalues`, and :meth:`viewitems`.
>>> d.viewkeys() >>> d.viewkeys()
dict_keys([0, 130, 10, 140, 20, 150, 30, ..., 250]) dict_keys([0, 130, 10, 140, 20, 150, 30, ..., 250])
Views can be iterated over, but they also behave like sets. The ``&`` Views can be iterated over, but the key and item views also behave
operator performs intersection, and ``|`` performs a union:: like sets. The ``&`` operator performs intersection, and ``|``
performs a union::
>>> d1 = dict((i*10, chr(65+i)) for i in range(26)) >>> d1 = dict((i*10, chr(65+i)) for i in range(26))
>>> d2 = dict((i**.5, i) for i in range(1000)) >>> d2 = dict((i**.5, i) for i in range(1000))
@ -566,13 +578,13 @@ memory content that matches the :class:`bytes` type's interface.
>>> m2 >>> m2
<memory at 0x37f080> <memory at 0x37f080>
The content of the view can be converted to a string of bytes or to The content of the view can be converted to a string of bytes or
a list of integers: a list of integers:
>>> m2.tobytes() >>> m2.tobytes()
'abcdefghijklmnopqrstuvwxyz' 'abcdefghijklmnopqrstuvwxyz'
>>> m2.tolist() >>> m2.tolist()
[97, 98, 99, 100, 101, 102, 103, 104, 105, 106, 107, 108, 109, 110, 111, 112, 113, 114, 115, 116, 117, 118, 119, 120, 121, 122] [97, 98, 99, 100, 101, 102, 103, ... 121, 122]
>>> >>>
:class:`memoryview` objects allow modifying the underlying object if :class:`memoryview` objects allow modifying the underlying object if
@ -657,8 +669,8 @@ Some smaller changes made to the core Python language are:
in many different places: :func:`str` on in many different places: :func:`str` on
floats and complex numbers; the :class:`float` and :class:`complex` floats and complex numbers; the :class:`float` and :class:`complex`
constructors; constructors;
numeric formatting; serialization and numeric formatting; serializing and
deserialization of floats and complex numbers using the deserializing floats and complex numbers using the
:mod:`marshal`, :mod:`pickle` :mod:`marshal`, :mod:`pickle`
and :mod:`json` modules; and :mod:`json` modules;
parsing of float and imaginary literals in Python code; parsing of float and imaginary literals in Python code;
@ -673,7 +685,7 @@ Some smaller changes made to the core Python language are:
.. maybe add an example? .. maybe add an example?
The rounding library responsible for this improvement works on The rounding library responsible for this improvement works on
Windows, and on Unix platforms using the gcc, icc, or suncc Windows and on Unix platforms using the gcc, icc, or suncc
compilers. There may be a small number of platforms where correct compilers. There may be a small number of platforms where correct
operation of this code cannot be guaranteed, so the code is not operation of this code cannot be guaranteed, so the code is not
used on such systems. You can find out which code is being used used on such systems. You can find out which code is being used
@ -683,6 +695,33 @@ Some smaller changes made to the core Python language are:
Implemented by Eric Smith and Mark Dickinson, using David Gay's Implemented by Eric Smith and Mark Dickinson, using David Gay's
:file:`dtoa.c` library; :issue:`7117`. :file:`dtoa.c` library; :issue:`7117`.
* Conversions from long integers and regular integers to floating
point now round differently, returning the floating-point number
closest to the number. This doesn't matter for small integers that
can be converted exactly, but for large numbers that will
unavoidably lose precision, Python 2.7 now approximates more
closely. For example, Python 2.6 computed the following::
>>> n = 295147905179352891391
>>> float(n)
2.9514790517935283e+20
>>> n - long(float(n))
65535L
Python 2.7's floating-point result is larger, but much closer to the
true value::
>>> n = 295147905179352891391
>>> float(n)
2.9514790517935289e+20
>>> n - long(float(n))
-1L
(Implemented by Mark Dickinson; :issue:`3166`.)
Integer division is also more accurate in its rounding behaviours. (Also
implemented by Mark Dickinson; :issue:`1811`.)
* The :meth:`str.format` method now supports automatic numbering of the replacement * The :meth:`str.format` method now supports automatic numbering of the replacement
fields. This makes using :meth:`str.format` more closely resemble using fields. This makes using :meth:`str.format` more closely resemble using
``%s`` formatting:: ``%s`` formatting::
@ -713,8 +752,8 @@ Some smaller changes made to the core Python language are:
A low-level change: the :meth:`object.__format__` method now triggers A low-level change: the :meth:`object.__format__` method now triggers
a :exc:`PendingDeprecationWarning` if it's passed a format string, a :exc:`PendingDeprecationWarning` if it's passed a format string,
because the :meth:`__format__` method for :class:`object` converts because the :meth:`__format__` method for :class:`object` converts
the object to a string representation and formats that. The method the object to a string representation and formats that. Previously
used to silently apply the format string to the string the method silently applied the format string to the string
representation, but that could hide mistakes in Python code. If representation, but that could hide mistakes in Python code. If
you're supplying formatting information such as an alignment or you're supplying formatting information such as an alignment or
precision, presumably you're expecting the formatting to be applied precision, presumably you're expecting the formatting to be applied
@ -737,33 +776,6 @@ Some smaller changes made to the core Python language are:
(Contributed by Fredrik Johansson and Victor Stinner; :issue:`3439`.) (Contributed by Fredrik Johansson and Victor Stinner; :issue:`3439`.)
* Conversions from long integers and regular integers to floating
point now round differently, returning the floating-point number
closest to the number. This doesn't matter for small integers that
can be converted exactly, but for large numbers that will
unavoidably lose precision, Python 2.7 now approximates more
closely. For example, Python 2.6 computed the following::
>>> n = 295147905179352891391
>>> float(n)
2.9514790517935283e+20
>>> n - long(float(n))
65535L
Python 2.7's floating-point result is larger, but much closer to the
true value::
>>> n = 295147905179352891391
>>> float(n)
2.9514790517935289e+20
>>> n - long(float(n))
-1L
(Implemented by Mark Dickinson; :issue:`3166`.)
Integer division is also more accurate in its rounding behaviours. (Also
implemented by Mark Dickinson; :issue:`1811`.)
* It's now possible for a subclass of the built-in :class:`unicode` type * It's now possible for a subclass of the built-in :class:`unicode` type
to override the :meth:`__unicode__` method. (Implemented by to override the :meth:`__unicode__` method. (Implemented by
Victor Stinner; :issue:`1583863`.) Victor Stinner; :issue:`1583863`.)
@ -796,7 +808,7 @@ Some smaller changes made to the core Python language are:
(fixed by Stefan Krah; :issue:`5677`). (fixed by Stefan Krah; :issue:`5677`).
* The Python tokenizer now translates line endings itself, so the * The Python tokenizer now translates line endings itself, so the
:func:`compile` built-in function can now accept code using any :func:`compile` built-in function now accepts code using any
line-ending convention. Additionally, it no longer requires that the line-ending convention. Additionally, it no longer requires that the
code end in a newline. code end in a newline.
@ -829,7 +841,7 @@ used with the :option:`-W` switch, separated by commas.
For example, the following setting will print warnings every time For example, the following setting will print warnings every time
they occur, but turn warnings from the :mod:`Cookie` module into an they occur, but turn warnings from the :mod:`Cookie` module into an
error. (The exact syntax for setting an environment variable varies error. (The exact syntax for setting an environment variable varies
across operating systems and shells, so it may be different for you.) across operating systems and shells.)
:: ::
@ -865,7 +877,7 @@ Several performance enhancements have been added:
any of them. This would previously take quadratic any of them. This would previously take quadratic
time for garbage collection, but now the number of full garbage collections time for garbage collection, but now the number of full garbage collections
is reduced as the number of objects on the heap grows. is reduced as the number of objects on the heap grows.
The new logic is to only perform a full garbage collection pass when The new logic only performs a full garbage collection pass when
the middle generation has been collected 10 times and when the the middle generation has been collected 10 times and when the
number of survivor objects from the middle generation exceeds 10% of number of survivor objects from the middle generation exceeds 10% of
the number of objects in the oldest generation. (Suggested by Martin the number of objects in the oldest generation. (Suggested by Martin
@ -975,10 +987,10 @@ changes, or look through the Subversion logs for all the details.
The new version features better Python 3.x compatibility, various bug fixes, The new version features better Python 3.x compatibility, various bug fixes,
and adds several new BerkeleyDB flags and methods. and adds several new BerkeleyDB flags and methods.
(Updated by Jesús Cea Avión; :issue:`8156`. The pybsddb (Updated by Jesús Cea Avión; :issue:`8156`. The pybsddb
changelog can be browsed at http://hg.jcea.es/pybsddb/file/tip/ChangeLog.) changelog can be read at http://hg.jcea.es/pybsddb/file/tip/ChangeLog.)
* The :mod:`bz2` module's :class:`~bz2.BZ2File` now supports the context * The :mod:`bz2` module's :class:`~bz2.BZ2File` now supports the context
management protocol, so you can write ``with bz2.BZ2File(...) as f: ...``. management protocol, so you can write ``with bz2.BZ2File(...) as f:``.
(Contributed by Hagen Fürstenau; :issue:`3860`.) (Contributed by Hagen Fürstenau; :issue:`3860`.)
* New class: the :class:`~collections.Counter` class in the :mod:`collections` * New class: the :class:`~collections.Counter` class in the :mod:`collections`
@ -1003,7 +1015,7 @@ changes, or look through the Subversion logs for all the details.
>>> c['z'] >>> c['z']
0 0
There are three additional :class:`~collections.Counter` methods: There are three additional :class:`~collections.Counter` methods.
:meth:`~collections.Counter.most_common` returns the N most common :meth:`~collections.Counter.most_common` returns the N most common
elements and their counts. :meth:`~collections.Counter.elements` elements and their counts. :meth:`~collections.Counter.elements`
returns an iterator over the contained elements, repeating each returns an iterator over the contained elements, repeating each
@ -1030,12 +1042,20 @@ changes, or look through the Subversion logs for all the details.
.. revision 79660 .. revision 79660
The new :class:`~collections.OrderedDict` class is described in the earlier New class: :class:`~collections.OrderedDict` is described in the earlier
section :ref:`pep-0372`. section :ref:`pep-0372`.
New method: The :class:`~collections.deque` data type now has a
:meth:`~collections.deque.count` method that returns the number of
contained elements equal to the supplied argument *x*, and a
:meth:`~collections.deque.reverse` method that reverses the elements
of the deque in-place. :class:`deque` also exposes its maximum
length as the read-only :attr:`~collections.deque.maxlen` attribute.
(Both features added by Raymond Hettinger.)
The :class:`~collections.namedtuple` class now has an optional *rename* parameter. The :class:`~collections.namedtuple` class now has an optional *rename* parameter.
If *rename* is true, field names that are invalid because they've If *rename* is true, field names that are invalid because they've
been repeated or that aren't legal Python identifiers will be been repeated or aren't legal Python identifiers will be
renamed to legal names that are derived from the field's renamed to legal names that are derived from the field's
position within the list of fields: position within the list of fields:
@ -1046,14 +1066,6 @@ changes, or look through the Subversion logs for all the details.
(Added by Raymond Hettinger; :issue:`1818`.) (Added by Raymond Hettinger; :issue:`1818`.)
The :class:`~collections.deque` data type now has a
:meth:`~collections.deque.count` method that returns the number of
contained elements equal to the supplied argument *x*, and a
:meth:`~collections.deque.reverse` method that reverses the elements
of the deque in-place. :class:`deque` also exposes its maximum
length as the read-only :attr:`~collections.deque.maxlen` attribute.
(Both features added by Raymond Hettinger.)
* Constructors for the parsing classes in the :mod:`ConfigParser` module now * Constructors for the parsing classes in the :mod:`ConfigParser` module now
take a *allow_no_value* parameter, defaulting to false; if true, take a *allow_no_value* parameter, defaulting to false; if true,
options without values will be allowed. For example:: options without values will be allowed. For example::
@ -1074,14 +1086,14 @@ changes, or look through the Subversion logs for all the details.
>>> print config.get('mysqld', 'unknown') >>> print config.get('mysqld', 'unknown')
Traceback (most recent call last): Traceback (most recent call last):
... ...
ConfigParser.NoOptionError: No option 'unknown' in section: 'mysqld' NoOptionError: No option 'unknown' in section: 'mysqld'
(Contributed by Mats Kindahl; :issue:`7005`.) (Contributed by Mats Kindahl; :issue:`7005`.)
* Deprecated function: :func:`contextlib.nested`, which allows * Deprecated function: :func:`contextlib.nested`, which allows
handling more than one context manager with a single :keyword:`with` handling more than one context manager with a single :keyword:`with`
statement, has been deprecated, because :keyword:`with` supports statement, has been deprecated, because the :keyword:`with` statement
multiple context managers syntactically now. now supports multiple context managers.
* The :mod:`copy` module's :func:`~copy.deepcopy` function will now * The :mod:`copy` module's :func:`~copy.deepcopy` function will now
correctly copy bound instance methods. (Implemented by correctly copy bound instance methods. (Implemented by
@ -1101,7 +1113,7 @@ changes, or look through the Subversion logs for all the details.
* New method: the :class:`~decimal.Decimal` class gained a * New method: the :class:`~decimal.Decimal` class gained a
:meth:`~decimal.Decimal.from_float` class method that performs an exact :meth:`~decimal.Decimal.from_float` class method that performs an exact
conversion of a floating-point number to a :class:`~decimal.Decimal`. conversion of a floating-point number to a :class:`~decimal.Decimal`.
Note that this is an **exact** conversion that strives for the This exact conversion strives for the
closest decimal approximation to the floating-point representation's value; closest decimal approximation to the floating-point representation's value;
the resulting decimal value will therefore still include the inaccuracy, the resulting decimal value will therefore still include the inaccuracy,
if any. if any.
@ -1119,19 +1131,19 @@ changes, or look through the Subversion logs for all the details.
:class:`Decimal`. :class:`Decimal`.
(Fixed by Mark Dickinson; :issue:`2531`.) (Fixed by Mark Dickinson; :issue:`2531`.)
Most of the methods of the :class:`~decimal.Context` class now accept integers
as well as :class:`~decimal.Decimal` instances; the only exceptions are the
:meth:`~decimal.Context.canonical` and :meth:`~decimal.Context.is_canonical`
methods. (Patch by Juan José Conti; :issue:`7633`.)
The constructor for :class:`~decimal.Decimal` now accepts The constructor for :class:`~decimal.Decimal` now accepts
floating-point numbers (added by Raymond Hettinger; :issue:`8257`) floating-point numbers (added by Raymond Hettinger; :issue:`8257`)
and non-European Unicode characters such as Arabic-Indic digits and non-European Unicode characters such as Arabic-Indic digits
(contributed by Mark Dickinson; :issue:`6595`). (contributed by Mark Dickinson; :issue:`6595`).
Most of the methods of the :class:`~decimal.Context` class now accept integers
as well as :class:`~decimal.Decimal` instances; the only exceptions are the
:meth:`~decimal.Context.canonical` and :meth:`~decimal.Context.is_canonical`
methods. (Patch by Juan José Conti; :issue:`7633`.)
When using :class:`~decimal.Decimal` instances with a string's When using :class:`~decimal.Decimal` instances with a string's
:meth:`~str.format` method, the default alignment was previously :meth:`~str.format` method, the default alignment was previously
left-alignment. This has been changed to right-alignment, which seems left-alignment. This has been changed to right-alignment, which is
more sensible for numeric types. (Changed by Mark Dickinson; :issue:`6857`.) more sensible for numeric types. (Changed by Mark Dickinson; :issue:`6857`.)
Comparisons involving a signaling NaN value (or ``sNAN``) now signal Comparisons involving a signaling NaN value (or ``sNAN``) now signal
@ -1156,17 +1168,18 @@ changes, or look through the Subversion logs for all the details.
rationals added in :issue:`5812`, and float/decimal in rationals added in :issue:`5812`, and float/decimal in
:issue:`8294`.) :issue:`8294`.)
An oversight was fixed, making the :class:`Fraction` match the other Ordering comparisons (``<``, ``<=``, ``>``, ``>=``) between
numeric types; ordering comparisons (``<``, ``<=``, ``>``, ``>=``) between
fractions and complex numbers now raise a :exc:`TypeError`. fractions and complex numbers now raise a :exc:`TypeError`.
This fixes an oversight, making the :class:`Fraction` match the other
numeric types.
.. revision 79455 .. revision 79455
* New class: a new :class:`~ftplib.FTP_TLS` class in * New class: :class:`~ftplib.FTP_TLS` in
the :mod:`ftplib` module provides secure FTP the :mod:`ftplib` module provides secure FTP
connections using TLS encapsulation of authentication as well as connections using TLS encapsulation of authentication as well as
subsequent control and data transfers. subsequent control and data transfers.
(Contributed by Giampaolo Rodola', :issue:`2054`.) (Contributed by Giampaolo Rodola; :issue:`2054`.)
The :meth:`~ftplib.FTP.storbinary` method for binary uploads can now restart The :meth:`~ftplib.FTP.storbinary` method for binary uploads can now restart
uploads thanks to an added *rest* parameter (patch by Pablo Mouzo; uploads thanks to an added *rest* parameter (patch by Pablo Mouzo;
@ -1192,7 +1205,7 @@ changes, or look through the Subversion logs for all the details.
otherwise. (Contributed by Antoine Pitrou; :issue:`4688`.) otherwise. (Contributed by Antoine Pitrou; :issue:`4688`.)
* The :mod:`gzip` module's :class:`~gzip.GzipFile` now supports the context * The :mod:`gzip` module's :class:`~gzip.GzipFile` now supports the context
management protocol, so you can write ``with gzip.GzipFile(...) as f: ...`` management protocol, so you can write ``with gzip.GzipFile(...) as f:``
(contributed by Hagen Fürstenau; :issue:`3860`), and it now implements (contributed by Hagen Fürstenau; :issue:`3860`), and it now implements
the :class:`io.BufferedIOBase` ABC, so you can wrap it with the :class:`io.BufferedIOBase` ABC, so you can wrap it with
:class:`io.BufferedReader` for faster processing :class:`io.BufferedReader` for faster processing
@ -1208,7 +1221,7 @@ changes, or look through the Subversion logs for all the details.
* New attribute: the :mod:`hashlib` module now has an :attr:`~hashlib.hashlib.algorithms` * New attribute: the :mod:`hashlib` module now has an :attr:`~hashlib.hashlib.algorithms`
attribute containing a tuple naming the supported algorithms. attribute containing a tuple naming the supported algorithms.
In Python 2.7, ``hashlib.algorithms`` contains In Python 2.7, ``hashlib.algorithms`` contains
``('md5', 'sha1', 'sha224', 'sha256', 'sha384', 'sha512')`` ``('md5', 'sha1', 'sha224', 'sha256', 'sha384', 'sha512')``.
(Contributed by Carl Chenet; :issue:`7418`.) (Contributed by Carl Chenet; :issue:`7418`.)
* The default :class:`~httplib.HTTPResponse` class used by the :mod:`httplib` module now * The default :class:`~httplib.HTTPResponse` class used by the :mod:`httplib` module now
@ -1221,7 +1234,7 @@ changes, or look through the Subversion logs for all the details.
(Contributed by Eldon Ziegler; :issue:`3972`.) (Contributed by Eldon Ziegler; :issue:`3972`.)
* The :mod:`ihooks` module now supports relative imports. Note that * The :mod:`ihooks` module now supports relative imports. Note that
:mod:`ihooks` is an older module used to support customizing imports, :mod:`ihooks` is an older module for customizing imports,
superseded by the :mod:`imputil` module added in Python 2.0. superseded by the :mod:`imputil` module added in Python 2.0.
(Relative import support added by Neil Schemenauer.) (Relative import support added by Neil Schemenauer.)
@ -1239,9 +1252,9 @@ changes, or look through the Subversion logs for all the details.
>>> def f(a, b=1, *pos, **named): >>> def f(a, b=1, *pos, **named):
... pass ... pass
>>> getcallargs(f, 1, 2, 3) >>> getcallargs(f, 1, 2, 3)
{'a': 1, 'named': {}, 'b': 2, 'pos': (3,)} {'a': 1, 'b': 2, 'pos': (3,), 'named': {}}
>>> getcallargs(f, a=2, x=4) >>> getcallargs(f, a=2, x=4)
{'a': 2, 'named': {'x': 4}, 'b': 1, 'pos': ()} {'a': 2, 'b': 1, 'pos': (), 'named': {'x': 4}}
>>> getcallargs(f) >>> getcallargs(f)
Traceback (most recent call last): Traceback (most recent call last):
... ...
@ -1292,8 +1305,8 @@ changes, or look through the Subversion logs for all the details.
floats or :class:`~decimal.Decimal` instances. (Implemented by Raymond floats or :class:`~decimal.Decimal` instances. (Implemented by Raymond
Hettinger; :issue:`5032`.) Hettinger; :issue:`5032`.)
:func:`itertools.combinations` and :func:`itertools.product` were :func:`itertools.combinations` and :func:`itertools.product`
previously raising :exc:`ValueError` for values of *r* larger than previously raised :exc:`ValueError` for values of *r* larger than
the input iterable. This was deemed a specification error, so they the input iterable. This was deemed a specification error, so they
now return an empty iterator. (Fixed by Raymond Hettinger; :issue:`4816`.) now return an empty iterator. (Fixed by Raymond Hettinger; :issue:`4816`.)
@ -1343,7 +1356,8 @@ changes, or look through the Subversion logs for all the details.
real, effective, and saved GIDs and UIDs; real, effective, and saved GIDs and UIDs;
:func:`~os.setresgid` and :func:`~os.setresuid`, which set :func:`~os.setresgid` and :func:`~os.setresuid`, which set
real, effective, and saved GIDs and UIDs to new values; real, effective, and saved GIDs and UIDs to new values;
:func:`~os.initgroups`. (GID/UID functions :func:`~os.initgroups`, which initialize the group access list
for the current process. (GID/UID functions
contributed by Travis H.; :issue:`6508`. Support for initgroups added contributed by Travis H.; :issue:`6508`. Support for initgroups added
by Jean-Paul Calderone; :issue:`7333`.) by Jean-Paul Calderone; :issue:`7333`.)
@ -1393,9 +1407,9 @@ changes, or look through the Subversion logs for all the details.
* New functions: in the :mod:`site` module, three new functions * New functions: in the :mod:`site` module, three new functions
return various site- and user-specific paths. return various site- and user-specific paths.
:func:`~site.getsitepackages` returns a list containing all :func:`~site.getsitepackages` returns a list containing all
global site-packages directories, and global site-packages directories,
:func:`~site.getusersitepackages` returns the path of the user's :func:`~site.getusersitepackages` returns the path of the user's
site-packages directory. site-packages directory, and
:func:`~site.getuserbase` returns the value of the :envvar:`USER_BASE` :func:`~site.getuserbase` returns the value of the :envvar:`USER_BASE`
environment variable, giving the path to a directory that can be used environment variable, giving the path to a directory that can be used
to store data. to store data.
@ -1461,7 +1475,7 @@ changes, or look through the Subversion logs for all the details.
Another change makes the extension load all of OpenSSL's ciphers and Another change makes the extension load all of OpenSSL's ciphers and
digest algorithms so that they're all available. Some SSL digest algorithms so that they're all available. Some SSL
certificates couldn't be verified, reporting an 'unknown algorithm' certificates couldn't be verified, reporting an "unknown algorithm"
error. (Reported by Beda Kosata, and fixed by Antoine Pitrou; error. (Reported by Beda Kosata, and fixed by Antoine Pitrou;
:issue:`8484`.) :issue:`8484`.)
@ -1531,7 +1545,7 @@ changes, or look through the Subversion logs for all the details.
:mod:`tarfile` now supports filtering the :class:`~tarfile.TarInfo` :mod:`tarfile` now supports filtering the :class:`~tarfile.TarInfo`
objects being added to a tar file. When you call :meth:`~tarfile.TarFile.add`, objects being added to a tar file. When you call :meth:`~tarfile.TarFile.add`,
instance, you may supply an optional *filter* argument you may supply an optional *filter* argument
that's a callable. The *filter* callable will be passed the that's a callable. The *filter* callable will be passed the
:class:`~tarfile.TarInfo` for every file being added, and can modify and return it. :class:`~tarfile.TarInfo` for every file being added, and can modify and return it.
If the callable returns ``None``, the file will be excluded from the If the callable returns ``None``, the file will be excluded from the
@ -1609,7 +1623,7 @@ changes, or look through the Subversion logs for all the details.
(Contributed by Kristján Valur Jónsson; :issue:`6267`.) (Contributed by Kristján Valur Jónsson; :issue:`6267`.)
* The :mod:`zipfile` module's :class:`~zipfile.ZipFile` now supports the context * The :mod:`zipfile` module's :class:`~zipfile.ZipFile` now supports the context
management protocol, so you can write ``with zipfile.ZipFile(...) as f: ...``. management protocol, so you can write ``with zipfile.ZipFile(...) as f:``.
(Contributed by Brian Curtin; :issue:`5511`.) (Contributed by Brian Curtin; :issue:`5511`.)
:mod:`zipfile` now also supports archiving empty directories and :mod:`zipfile` now also supports archiving empty directories and
@ -1661,9 +1675,9 @@ Here are some examples::
>>> anydbm >>> anydbm
<module 'anydbm' from '/p/python/Lib/anydbm.py'> <module 'anydbm' from '/p/python/Lib/anydbm.py'>
>>> # Relative import >>> # Relative import
>>> sysconfig = import_module('..sysconfig', 'distutils.command') >>> file_util = import_module('..file_util', 'distutils.command')
>>> sysconfig >>> file_util
<module 'distutils.sysconfig' from '/p/python/Lib/distutils/sysconfig.pyc'> <module 'distutils.file_util' from '/python/Lib/distutils/file_util.pyc'>
:mod:`importlib` was implemented by Brett Cannon and introduced in :mod:`importlib` was implemented by Brett Cannon and introduced in
Python 3.1. Python 3.1.
@ -1710,7 +1724,7 @@ set was originally called Tile, but was renamed to Ttk (for "themed Tk")
on being added to Tcl/Tck release 8.5. on being added to Tcl/Tck release 8.5.
To learn more, read the :mod:`ttk` module documentation. You may also To learn more, read the :mod:`ttk` module documentation. You may also
wish to read Tcl/Tk manual page describing the wish to read the Tcl/Tk manual page describing the
Ttk theme engine, available at Ttk theme engine, available at
http://www.tcl.tk/man/tcl8.5/TkCmd/ttk_intro.htm. Some http://www.tcl.tk/man/tcl8.5/TkCmd/ttk_intro.htm. Some
screenshots of the Python/Ttk code in use are at screenshots of the Python/Ttk code in use are at
@ -1751,17 +1765,17 @@ The :func:`main` function supports some other new options:
* :option:`-b` or :option:`--buffer` will buffer the standard output * :option:`-b` or :option:`--buffer` will buffer the standard output
and standard error streams during each test. If the test passes, and standard error streams during each test. If the test passes,
any resulting output will be discard; on failure, the buffered any resulting output will be discarded; on failure, the buffered
output will be displayed. output will be displayed.
* :option:`-c` or :option:`--catch` will cause the control-C interrupt * :option:`-c` or :option:`--catch` will cause the control-C interrupt
to be handled more gracefully. Instead of interrupting the test to be handled more gracefully. Instead of interrupting the test
process immediately, the currently running test will be completed process immediately, the currently running test will be completed
and then the resulting partial results will be reported. If you're and then the partial results up to the interruption will be reported.
impatient, a second press of control-C will cause an immediate If you're impatient, a second press of control-C will cause an immediate
interruption. interruption.
This control-C handler tries to avoid interfering when the code This control-C handler tries to avoid causing problems when the code
being tested or the tests being run have defined a signal handler of being tested or the tests being run have defined a signal handler of
their own, by noticing that a signal handler was already set and their own, by noticing that a signal handler was already set and
calling it. If this doesn't work for you, there's a calling it. If this doesn't work for you, there's a
@ -1773,12 +1787,12 @@ The :func:`main` function supports some other new options:
continuing to execute further tests. (Suggested by Cliff Dyer and continuing to execute further tests. (Suggested by Cliff Dyer and
implemented by Michael Foord; :issue:`8074`.) implemented by Michael Foord; :issue:`8074`.)
The progress messages now shows 'x' for expected failures The progress messages now show 'x' for expected failures
and 'u' for unexpected successes when run in verbose mode. and 'u' for unexpected successes when run in verbose mode.
(Contributed by Benjamin Peterson.) (Contributed by Benjamin Peterson.)
Test cases can raise the :exc:`~unittest.SkipTest` exception to skip a Test cases can raise the :exc:`~unittest.SkipTest` exception to skip a
test. (:issue:`1034053`.) test (:issue:`1034053`).
The error messages for :meth:`~unittest.TestCase.assertEqual`, The error messages for :meth:`~unittest.TestCase.assertEqual`,
:meth:`~unittest.TestCase.assertTrue`, and :meth:`~unittest.TestCase.assertFalse` :meth:`~unittest.TestCase.assertTrue`, and :meth:`~unittest.TestCase.assertFalse`
@ -1788,7 +1802,7 @@ True, both the standard error message and any additional message you
provide will be printed for failures. (Added by Michael Foord; :issue:`5663`.) provide will be printed for failures. (Added by Michael Foord; :issue:`5663`.)
The :meth:`~unittest.TestCase.assertRaises` method now The :meth:`~unittest.TestCase.assertRaises` method now
return a context handler when called without providing a callable returns a context handler when called without providing a callable
object to run. For example, you can write this:: object to run. For example, you can write this::
with self.assertRaises(KeyError): with self.assertRaises(KeyError):
@ -1808,7 +1822,7 @@ different module or class.
The methods :meth:`~unittest.TestCase.addCleanup` and The methods :meth:`~unittest.TestCase.addCleanup` and
:meth:`~unittest.TestCase.doCleanups` were added. :meth:`~unittest.TestCase.doCleanups` were added.
:meth:`~unittest.TestCase.addCleanup` allows you to add cleanup functions that :meth:`~unittest.TestCase.addCleanup` lets you add cleanup functions that
will be called unconditionally (after :meth:`~unittest.TestCase.setUp` if will be called unconditionally (after :meth:`~unittest.TestCase.setUp` if
:meth:`~unittest.TestCase.setUp` fails, otherwise after :meth:`~unittest.TestCase.tearDown`). This allows :meth:`~unittest.TestCase.setUp` fails, otherwise after :meth:`~unittest.TestCase.tearDown`). This allows
for much simpler resource allocation and deallocation during tests for much simpler resource allocation and deallocation during tests
@ -1887,13 +1901,13 @@ GvR worked on merging them into Python's version of :mod:`unittest`.
objects being compared are of the specified type. This function objects being compared are of the specified type. This function
should compare the two objects and raise an exception if they don't should compare the two objects and raise an exception if they don't
match; it's a good idea for the function to provide additional match; it's a good idea for the function to provide additional
information about why the two objects are matching, much as the new information about why the two objects aren't matching, much as the new
sequence comparison methods do. sequence comparison methods do.
:func:`unittest.main` now takes an optional ``exit`` argument. If :func:`unittest.main` now takes an optional ``exit`` argument. If
False, :func:`~unittest.main` doesn't call :func:`sys.exit`, allowing it to be False, :func:`~unittest.main` doesn't call :func:`sys.exit`, allowing
used from the interactive interpreter. (Contributed by J. Pablo :func:`main` to be used from the interactive interpreter.
Fernández; :issue:`3379`.) (Contributed by J. Pablo Fernández; :issue:`3379`.)
:class:`~unittest.TestResult` has new :meth:`~unittest.TestResult.startTestRun` and :class:`~unittest.TestResult` has new :meth:`~unittest.TestResult.startTestRun` and
:meth:`~unittest.TestResult.stopTestRun` methods that are called immediately before :meth:`~unittest.TestResult.stopTestRun` methods that are called immediately before
@ -1916,17 +1930,17 @@ Updated module: ElementTree 1.3
--------------------------------- ---------------------------------
The version of the ElementTree library included with Python was updated to The version of the ElementTree library included with Python was updated to
version 1.3. Some of the new features in ElementTree 1.3 are: version 1.3. Some of the new features are:
* The various parsing functions now take a *parser* keyword argument * The various parsing functions now take a *parser* keyword argument
that can be used to provide an :class:`XMLParser` instance that will giving an :class:`XMLParser` instance that will
be used. This makes it possible to override the file's internal encoding: be used. This makes it possible to override the file's internal encoding::
p = ET.XMLParser(encoding='utf-8') p = ET.XMLParser(encoding='utf-8')
t = ET.XML("""<root/>""", parser=p) t = ET.XML("""<root/>""", parser=p)
Errors in parsing XML now raise a :exc:`ParseError` exception. Errors in parsing XML now raise a :exc:`ParseError` exception, whose
Instances of :exc:`ParseError` have a :attr:`position` attribute instances have a :attr:`position` attribute
containing a (*line*, *column*) tuple giving the location of the problem. containing a (*line*, *column*) tuple giving the location of the problem.
* ElementTree's code for converting trees to a string has been * ElementTree's code for converting trees to a string has been
@ -1937,15 +1951,15 @@ version 1.3. Some of the new features in ElementTree 1.3 are:
elements as ``<empty></empty>`` instead of ``<empty/>``, and text elements as ``<empty></empty>`` instead of ``<empty/>``, and text
mode will skip over elements and only output the text chunks. If mode will skip over elements and only output the text chunks. If
you set the :attr:`tag` attribute of an element to ``None`` but you set the :attr:`tag` attribute of an element to ``None`` but
leaves its children in place, the element will be omitted when the leave its children in place, the element will be omitted when the
tree is written out, so you don't need to do more extensive rearrangement tree is written out, so you don't need to do more extensive rearrangement
to remove a single element. to remove a single element.
Namespace aspects have also been improved. All the ``xmlns:<whatever>`` Namespace handling has also been improved. All ``xmlns:<whatever>``
declarations are now put on the root element and not scattered throughout declarations are now output on the root element, not scattered throughout
the resulting output. You can set the default namespace for a tree the resulting XML. You can set the default namespace for a tree
by setting the :attr:`default_namespace` attribute and can by setting the :attr:`default_namespace` attribute and can
register new prefixes with :meth:`regsiter_namespace`. In XML mode, register new prefixes with :meth:`register_namespace`. In XML mode,
you can use the true/false *xml_declaration* parameter to suppress the you can use the true/false *xml_declaration* parameter to suppress the
XML declaration. XML declaration.
@ -1967,10 +1981,9 @@ version 1.3. Some of the new features in ElementTree 1.3 are:
* New :class:`Element` method: :meth:`iter` yields the children of the * New :class:`Element` method: :meth:`iter` yields the children of the
element as a generator. It's also possible to write ``for child in element as a generator. It's also possible to write ``for child in
elem: ...`` to loop over an element's children. The existing method elem:`` to loop over an element's children. The existing method
:meth:`getiterator` is now deprecated. :meth:`getchildren` is :meth:`getiterator` is now deprecated, as is :meth:`getchildren`
another similar method that constructs and returns a list of which constructs and returns a list of children.
children; it's also deprecated.
* New :class:`Element` method: :meth:`itertext` yields all chunks of * New :class:`Element` method: :meth:`itertext` yields all chunks of
text that are descendants of the element. For example:: text that are descendants of the element. For example::
@ -1982,13 +1995,13 @@ version 1.3. Some of the new features in ElementTree 1.3 are:
# Outputs ['\n ', '1', ' ', '2', ' ', '3', '\n'] # Outputs ['\n ', '1', ' ', '2', ' ', '3', '\n']
print list(t.itertext()) print list(t.itertext())
* Deprecated: using an element as a Boolean (i.e., ``if elem: ...``) * Deprecated: using an element as a Boolean (i.e., ``if elem:``) would
would return true if the element had any children, or false if return true if the element had any children, or false if there were
there were no children. This behaviour will eventually change or be removed no children. This behaviour is confusing -- ``None`` is false, but
because it's confusing (``None`` is false, but so is a childless element?), so is a childless element? -- so it will now trigger a
so it will now trigger a :exc:`FutureWarning`. In your code, :exc:`FutureWarning`. In your code, you should be explicit: write
you should be explicit: write ``len(elem) != 0`` if you're interested in ``len(elem) != 0`` if you're interested in the number of children,
the number of children, or ``elem is not None`` Instead, or ``elem is not None``.
Fredrik Lundh develops ElementTree and produced the 1.3 version; Fredrik Lundh develops ElementTree and produced the 1.3 version;
you can read his article describing 1.3 at you can read his article describing 1.3 at
@ -2009,9 +2022,9 @@ Changes to Python's build process and to the C API include:
<http://sourceware.org/gdb/current/onlinedocs/gdb/Python.html>`__. <http://sourceware.org/gdb/current/onlinedocs/gdb/Python.html>`__.
When you begin debugging an executable program P, GDB will look for When you begin debugging an executable program P, GDB will look for
a file named ``P-gdb.py`` and automatically read it. Dave Malcolm a file named ``P-gdb.py`` and automatically read it. Dave Malcolm
contributed a :file:`python-gdb.py` that adds a number of useful contributed a :file:`python-gdb.py` that adds a number of
commands when debugging Python itself. For example, there are commands useful when debugging Python itself. For example,
``py-up`` and ``py-down`` that go up or down one Python stack frame, ``py-up`` and ``py-down`` go up or down one Python stack frame,
which usually corresponds to several C stack frames. ``py-print`` which usually corresponds to several C stack frames. ``py-print``
prints the value of a Python variable, and ``py-bt`` prints the prints the value of a Python variable, and ``py-bt`` prints the
Python stack trace. (Added as a result of :issue:`8032`.) Python stack trace. (Added as a result of :issue:`8032`.)
@ -2028,7 +2041,7 @@ Changes to Python's build process and to the C API include:
* New function: :cfunc:`PyCode_NewEmpty` creates an empty code object; * New function: :cfunc:`PyCode_NewEmpty` creates an empty code object;
only the filename, function name, and first line number are required. only the filename, function name, and first line number are required.
This is useful to extension modules that are attempting to This is useful for extension modules that are attempting to
construct a more useful traceback stack. Previously such construct a more useful traceback stack. Previously such
extensions needed to call :cfunc:`PyCode_New`, which had many extensions needed to call :cfunc:`PyCode_New`, which had many
more arguments. (Added by Jeffrey Yasskin.) more arguments. (Added by Jeffrey Yasskin.)
@ -2036,7 +2049,7 @@ Changes to Python's build process and to the C API include:
* New function: :cfunc:`PyErr_NewExceptionWithDoc` creates a new * New function: :cfunc:`PyErr_NewExceptionWithDoc` creates a new
exception class, just as the existing :cfunc:`PyErr_NewException` does, exception class, just as the existing :cfunc:`PyErr_NewException` does,
but takes an extra ``char *`` argument containing the docstring for the but takes an extra ``char *`` argument containing the docstring for the
new exception class. (Added by the 'lekma' user on the Python bug tracker; new exception class. (Added by 'lekma' on the Python bug tracker;
:issue:`7033`.) :issue:`7033`.)
* New function: :cfunc:`PyFrame_GetLineNumber` takes a frame object * New function: :cfunc:`PyFrame_GetLineNumber` takes a frame object
@ -2078,11 +2091,11 @@ Changes to Python's build process and to the C API include:
* Removed function: :cmacro:`PyEval_CallObject` is now only available * Removed function: :cmacro:`PyEval_CallObject` is now only available
as a macro. A function version was being kept around to preserve as a macro. A function version was being kept around to preserve
ABI linking compatibility, but that was in 1997; it can certainly be ABI linking compatibility, but that was in 1997; it can certainly be
deleted. (Removed by Antoine Pitrou; :issue:`8276`.) deleted by now. (Removed by Antoine Pitrou; :issue:`8276`.)
* New format codes: the :cfunc:`PyFormat_FromString`, * New format codes: the :cfunc:`PyFormat_FromString`,
:cfunc:`PyFormat_FromStringV`, and :cfunc:`PyErr_Format` now :cfunc:`PyFormat_FromStringV`, and :cfunc:`PyErr_Format` functions now
accepts ``%lld`` and ``%llu`` format codes for displaying values of accept ``%lld`` and ``%llu`` format codes for displaying
C's :ctype:`long long` types. C's :ctype:`long long` types.
(Contributed by Mark Dickinson; :issue:`7228`.) (Contributed by Mark Dickinson; :issue:`7228`.)
@ -2096,7 +2109,7 @@ Changes to Python's build process and to the C API include:
ever release the lock, since the other threads weren't replicated, ever release the lock, since the other threads weren't replicated,
and the child process would no longer be able to perform imports. and the child process would no longer be able to perform imports.
Python 2.7 now acquires the import lock before performing an Python 2.7 acquires the import lock before performing an
:func:`os.fork`, and will also clean up any locks created using the :func:`os.fork`, and will also clean up any locks created using the
:mod:`threading` module. C extension modules that have internal :mod:`threading` module. C extension modules that have internal
locks, or that call :cfunc:`fork()` themselves, will not benefit locks, or that call :cfunc:`fork()` themselves, will not benefit
@ -2123,15 +2136,15 @@ Changes to Python's build process and to the C API include:
building the :mod:`pyexpat` module to use the system Expat library. building the :mod:`pyexpat` module to use the system Expat library.
(Contributed by Arfrever Frehtes Taifersar Arahesis; :issue:`7609`.) (Contributed by Arfrever Frehtes Taifersar Arahesis; :issue:`7609`.)
* New configure option: compiling Python with the * New configure option: the
:option:`--with-valgrind` option will now disable the pymalloc :option:`--with-valgrind` option will now disable the pymalloc
allocator, which is difficult for the Valgrind memory-error detector allocator, which is difficult for the Valgrind memory-error detector
to analyze correctly. to analyze correctly.
Valgrind will therefore be better at detecting memory leaks and Valgrind will therefore be better at detecting memory leaks and
overruns. (Contributed by James Henstridge; :issue:`2422`.) overruns. (Contributed by James Henstridge; :issue:`2422`.)
* New configure option: you can now supply no arguments to * New configure option: you can now supply an empty string to
:option:`--with-dbmliborder=` in order to build none of the various :option:`--with-dbmliborder=` in order to disable all of the various
DBM modules. (Added by Arfrever Frehtes Taifersar Arahesis; DBM modules. (Added by Arfrever Frehtes Taifersar Arahesis;
:issue:`6491`.) :issue:`6491`.)
@ -2158,15 +2171,15 @@ Capsules
------------------- -------------------
Python 3.1 adds a new C datatype, :ctype:`PyCapsule`, for providing a Python 3.1 adds a new C datatype, :ctype:`PyCapsule`, for providing a
C API to an extension module. A capsule is essentially the holder for C API to an extension module. A capsule is essentially the holder of
a C ``void *`` pointer, and is bound to a module attribute; for a C ``void *`` pointer, and is made available as a module attribute; for
example, the :mod:`socket` module's API is exposed as ``socket.CAPI``, example, the :mod:`socket` module's API is exposed as ``socket.CAPI``,
and :mod:`unicodedata` calls it ``ucnhash_CAPI``. Other extensions and :mod:`unicodedata` exposes ``ucnhash_CAPI``. Other extensions
can import the module, access its dictionary to get the capsule can import the module, access its dictionary to get the capsule
object, and then get the ``void *`` pointer, which will usually point object, and then get the ``void *`` pointer, which will usually point
to an array of pointers to the various API functions. to an array of pointers to the module's various API functions.
There is an existing data type that already does this, There is an existing data type already used for this,
:ctype:`PyCObject`, but it doesn't provide type safety. Evil code :ctype:`PyCObject`, but it doesn't provide type safety. Evil code
written in pure Python could cause a segmentation fault by taking a written in pure Python could cause a segmentation fault by taking a
:ctype:`PyCObject` from module A and somehow substituting it for the :ctype:`PyCObject` from module A and somehow substituting it for the
@ -2224,10 +2237,10 @@ Port-Specific Changes: Windows
* The :func:`os.kill` function now works on Windows. The signal value * The :func:`os.kill` function now works on Windows. The signal value
can be the constants :const:`CTRL_C_EVENT`, can be the constants :const:`CTRL_C_EVENT`,
:const:`CTRL_BREAK_EVENT`, or any integer. The Control-C and :const:`CTRL_BREAK_EVENT`, or any integer. The first two constants
Control-Break keystroke events can be sent to subprocesses; any will send Control-C and Control-Break keystroke events to
other value will use the :cfunc:`TerminateProcess` API. subprocesses; any other value will use the :cfunc:`TerminateProcess`
(Contributed by Miki Tebeka; :issue:`1220212`.) API. (Contributed by Miki Tebeka; :issue:`1220212`.)
* The :func:`os.listdir` function now correctly fails * The :func:`os.listdir` function now correctly fails
for an empty path. (Fixed by Hirokazu Yamamoto; :issue:`5913`.) for an empty path. (Fixed by Hirokazu Yamamoto; :issue:`5913`.)
@ -2259,7 +2272,7 @@ Other Changes and Fixes
* Two benchmark scripts, :file:`iobench` and :file:`ccbench`, were * Two benchmark scripts, :file:`iobench` and :file:`ccbench`, were
added to the :file:`Tools` directory. :file:`iobench` measures the added to the :file:`Tools` directory. :file:`iobench` measures the
speed of built-in file I/O objects (as returned by :func:`open`) speed of the built-in file I/O objects returned by :func:`open`
while performing various operations, and :file:`ccbench` is a while performing various operations, and :file:`ccbench` is a
concurrency benchmark that tries to measure computing throughput, concurrency benchmark that tries to measure computing throughput,
thread switching latency, and IO processing bandwidth when thread switching latency, and IO processing bandwidth when
@ -2354,6 +2367,14 @@ In the standard library:
identifier instead of the previous default value of ``'python'``. identifier instead of the previous default value of ``'python'``.
(Changed by Sean Reifschneider; :issue:`8451`.) (Changed by Sean Reifschneider; :issue:`8451`.)
* The :mod:`tarfile` module's default error handling has changed, to
no longer suppress fatal errors. The default error level was previously 0,
which meant that errors would only result in a message being written to the
debug log, but because the debug log is not activated by default,
these errors go unnoticed. The default error level is now 1,
which raises an exception if there's an error.
(Changed by Lars Gustäbel; :issue:`7357`.)
* The :mod:`urlparse` module's :func:`~urlparse.urlsplit` now handles * The :mod:`urlparse` module's :func:`~urlparse.urlsplit` now handles
unknown URL schemes in a fashion compliant with :rfc:`3986`: if the unknown URL schemes in a fashion compliant with :rfc:`3986`: if the
URL is of the form ``"<something>://..."``, the text before the URL is of the form ``"<something>://..."``, the text before the