Index: Doc/whatsnew/3.2.rst =================================================================== --- Doc/whatsnew/3.2.rst (révision 87897) +++ Doc/whatsnew/3.2.rst (copie de travail) @@ -49,7 +49,7 @@ This article explains the new features in Python 3.2 as compared to 3.1. It focuses on a few highlights and gives a few examples. For full details, see the -:source:`Misc/NEWS ` file. +:source:`Misc/NEWS` file. .. seealso:: @@ -205,7 +205,7 @@ "root": {"level": "DEBUG", "handlers": ["console", "console_priority"]}} -If that dictionary is stored in a file called :file:`conf.json`, it can loaded +If that dictionary is stored in a file called :file:`conf.json`, it can be loaded and called with code like this:: >>> import logging.config @@ -281,7 +281,7 @@ ===================================== Python's scheme for caching bytecode in *.pyc* files did not work well in -environments with multiple python interpreters. If one interpreter encountered +environments with multiple Python interpreters. If one interpreter encountered a cached file created by another interpreter, it would recompile the source and overwrite the cached file, thus losing the benefits of caching. @@ -367,8 +367,8 @@ This informational PEP clarifies how bytes/text issues are to be handled by the WGSI protocol. The challenge is that string handling in Python 3 is most -conveniently handled with the :class:`str` type eventhough the HTTP protocol -is itself bytes oriented. +conveniently handled with the :class:`str` type even though the HTTP protocol +is itself bytes-oriented. The PEP differentiates so-called *native strings* that are used for request/response headers and metadata versus *byte strings* which are used for @@ -393,8 +393,8 @@ bytes to native strings using ``h.encode('utf-8').decode('latin-1')``. * Values yielded by an application or sent using the :meth:`write` method - must be byte strings. The :func:`start_response` function and environ - must use native strings. The two cannot be mixed. + must be byte strings. The :func:`start_response` function and environ + must use native strings. The two cannot be mixed. For server implementers writing CGI-to-WSGI pathways or other CGI-style protocols, the users must to be able access the environment using native strings @@ -428,7 +428,7 @@ (Suggested by Mark Dickinson and implemented by Eric Smith in :issue:`7094`.) * The interpreter can now be started with a quiet option, ``-q``, to suppress - the copyright and version information in an interactive mode. The option can + the copyright and version information in interactive mode. The option can be introspected using the :attr:`sys.flags` attribute:: $ python -q @@ -498,9 +498,9 @@ (See :issue:`4617`.) * The internal :c:type:`structsequence` tool now creates subclasses of tuple. - This means that C generated structures like those returned by :func:`os.stat`, - :func:`time.gmtime`, and :func:`sys.version_info` now work like a - :term:`named tuple` and are more interoperable with functions and methods that + This means that C-generated structures like those returned by :func:`os.stat`, + :func:`time.gmtime` and :func:`sys.version_info` now work like a + :term:`named tuple` and are more compatible with functions and methods that expect a tuple as an argument. The is a big step forward in making the C structures as flexible as their pure Python counterparts. @@ -530,19 +530,19 @@ produce various issues, especially under Windows. Here is an example of enabling the warning from the command line:: - $ ./python -q -Wdefault + $ python -q -Wdefault >>> f = open("foo", "wb") >>> del f __main__:1: ResourceWarning: unclosed file <_io.BufferedWriter name='foo'> (Added by Antoine Pitrou and Georg Brandl in :issue:`10093` and :issue:`477863`.) -* :class:`range` objects now support *index* and *count* methods. This is part +* :class:`range` objects now support *index* and *count* methods. This is part of an effort to make more objects fully implement the :class:`collections.Sequence` :term:`abstract base class`. As a result, the language will have a more uniform API. In addition, :class:`range` objects now support slicing and negative indices. This makes *range* more - interoperable with lists:: + compatible with lists:: >>> range(0, 100, 2).count(10) 1 @@ -553,10 +553,10 @@ >>> range(0, 100, 2)[0:5] range(0, 10, 2) - (Contributed by Daniel Stuzback in :issue:`9213` and by Alexander Belopolsky + (Contributed by Daniel Stutzbach in :issue:`9213` and by Alexander Belopolsky in :issue:`2690`.) -* The :func:`callable` builtin function from Py2.x was resurrected. It provides +* The :func:`callable` built-in function from Python 2.x was resurrected. It provides a concise, readable alternative to using an :term:`abstract base class` in an expression like ``isinstance(x, collections.Callable)``: @@ -586,14 +586,14 @@ Throughout the standard library, there has been more careful attention to encodings and text versus bytes issues. In particular, interactions with the operating system are now better able to pass non-ASCII data using the Windows -mcbs encoding, locale aware encodings, or UTF-8. +mcbs encoding, locale-aware encodings, or UTF-8. Another significant win is the addition of substantially better support for *SSL* connections and security certificates. -In addition, more functions and classes now have a :term:`context manager` to -support convenient and reliable resource clean-up using the -:keyword:`with`-statement. +In addition, more functions and classes now behave as :term:`context +manager`\s, to support convenient and reliable resource cleanup using the +:keyword:`with` statement. email ----- @@ -655,7 +655,7 @@ * :meth:`xml.etree.ElementTree.Element.iterfind` searches an element and subelements * :meth:`xml.etree.ElementTree.Element.itertext` creates a text iterator over - an element and its sub-elements + an element and its subelements * :meth:`xml.etree.ElementTree.TreeBuilder.end` closes the current element * :meth:`xml.etree.ElementTree.TreeBuilder.doctype` handles a doctype declaration @@ -714,7 +714,7 @@ * To help write classes with rich comparison methods, a new decorator :func:`functools.total_ordering` will use a existing equality and inequality - methods to fill-in the remaining methods. + methods to fill in the remaining methods. For example, supplying *__eq__* and *__lt__* will enable :func:`~functools.total_ordering` to fill-in *__le__*, *__gt__* and *__ge__*:: @@ -729,7 +729,7 @@ (other.lastname.lower(), other.firstname.lower())) With the *total_ordering* decorator, the remaining comparison methods - are filled-in automatically. + are filled in automatically. (Contributed by Raymond Hettinger.) @@ -823,7 +823,7 @@ * The :mod:`datetime` module has a new type :class:`~datetime.timezone` that implements the :class:`~datetime.tzinfo` interface by returning a fixed UTC - offset and timezone name. This makes it easier to create timezone aware + offset and timezone name. This makes it easier to create timezone-aware datetime objects: >>> datetime.now(timezone.utc) @@ -856,7 +856,7 @@ There is a new and slightly mind-blowing tool :class:`~contextlib.ContextDecorator` that is helpful for creating a -:term:`context manager` that does double-duty as a function decorator. +:term:`context manager` that does double duty as a function decorator. As a convenience, this new functionality is used by :func:`~contextlib.contextmanager` so that no extra effort is needed to support @@ -864,9 +864,9 @@ The basic idea is that both context managers and function decorators can be used for pre-action and post-action wrappers. Context managers wrap a group of -statements using the :keyword:`with`-statement, and function decorators wrap a +statements using the :keyword:`with` statement, and function decorators wrap a group of statements enclosed in a function. So, occasionally there is a need to -write a pre/post action wrapper that can be used in either role. +write a pre/post-action wrapper that can be used in either role. For example, it is sometimes useful to wrap functions or groups of statements with a logger that can track the time of entry and time of exit. Rather than @@ -897,16 +897,16 @@ Trying to fulfill two roles at once places some limitations on the technique. Context managers normally have the flexibility to return an argument usable by -the :keyword:`with`-statement, but there is no parallel for function decorators. +the :keyword:`with` statement, but there is no parallel for function decorators. -In the above example, there is not a clean way for the *track_entry_and_exit* -context manager to return a logging instance for use in the body of enclosed +In the above example, the *:func:`track_entry_and_exit* context manager does +not have a way to return a logging instance for use in the body of enclosed statements. (Contributed by Michael Foord in :issue:`9110`.) decimal and fractions ----------------------- +--------------------- Mark Dickinson crafted an elegant and efficient scheme for assuring that different numeric datatypes will have the same hash value whenever their actual @@ -979,7 +979,7 @@ ----- The :func:`os.popen` and :func:`subprocess.Popen` functions now support -the :keyword:`with`-statement` for auto-closing of the file descriptors. +the :keyword:`with` statement` for auto-closing of the file descriptors. gzip and zipfile ---------------- @@ -991,7 +991,7 @@ The :mod:`gzip` module also gains the :func:`~gzip.compress` and :func:`~gzip.decompress` functions for easier in-memory compression and -decompression. Keep in mind that text needs to be encoded in to :class:`bytes` +decompression. Keep in mind that text needs to be encoded to :class:`bytes` before compressing and decompressing: >>> s = 'Three shall be the number thou shalt count, ' @@ -1107,7 +1107,7 @@ ---- The :mod:`nntplib` module has a revamped implementation with better bytes and -unicode semantics as well as more practical APIs. These improvements break +text semantics as well as more practical APIs. These improvements break compatibility with the nntplib version in Python 3.1, which was partly dysfunctional in itself. @@ -1131,14 +1131,14 @@ methods, improved diagnostic messages for test failures, and better method names. -* The command-line call, ``python -m unittest`` can now accept file paths +* The command-line call ``python -m unittest`` can now accept file paths instead of module names for running specific tests (:issue:`10620`). The new test discovery can find tests within packages, locating any test importable from the top level directory. The top level directory can be specified with the `-t` option, a pattern for matching files with ``-p``, and a directory to start discovery with ``-s``:: - $ python -m unittest discover -s my_proj_dir -p '_test.py' + $ python -m unittest discover -s my_proj_dir -p _test.py (Contributed by Michael Foord.) @@ -1171,7 +1171,7 @@ (Contributed by Raymond Hettinger.) * A principal feature of the unittest module is an effort to produce meaningful - diagnostics when a test fails. When possible the failure is recorded along + diagnostics when a test fails. When possible, the failure is recorded along with a diff of the output. This is especially helpful for analyzing log files of failed test runs. However, since diffs can sometime be voluminous, there is a new :attr:`~unittest.TestCase.maxDiff` attribute which sets maximum length of @@ -1189,7 +1189,7 @@ (Contributed by Raymond Hettinger and implemented by Ezio Melotti.) -* To improve consistency, some of long-standing method aliases are being +* To improve consistency, some of the long-standing method aliases are being deprecated in favor of the preferred names: - replace :meth:`assert_` with :meth:`.assertTrue` @@ -1252,7 +1252,7 @@ cleanup of temporary directories: >>> with tempfile.TemporaryDirectory() as tmpdirname: -... print 'created temporary directory', tmpdirname +... print('created temporary directory', tmpdirname) (Contributed by Neil Schemenauer and Nick Coghlan; :issue:`5178`.) @@ -1282,7 +1282,7 @@ sysconfig --------- -The new :mod:`sysconfig` module makes it straight-forward to discover +The new :mod:`sysconfig` module makes it straightforward to discover installation paths and configuration variables which vary across platforms and installations. @@ -1292,7 +1292,7 @@ * :func:`~sysconfig.get_platform` returning values like *linux-i586* or *macosx-10.6-ppc*. * :func:`~sysconfig.get_python_version` returns a Python version string in - the form, "3.2". + the form "3.2". It also provides access to the paths and variables corresponding to one of seven named schemes used by :mod:`distutils`. Those include *posix_prefix*, @@ -1350,13 +1350,13 @@ * A :file:`.pdbrc` script file can contain ``continue`` and ``next`` commands that continue debugging. * The :class:`Pdb` class constructor now accepts a *nosigint* argument. -* new commands: ``l(list)``, ``ll(long list`` and ``source`` for +* New commands: ``l(list)``, ``ll(long list)`` and ``source`` for listing source code. -* new commands: ``display`` and ``undisplay`` for showing or hiding +* New commands: ``display`` and ``undisplay`` for showing or hiding the value of an expression if it has changed. -* new command: ``interact`` for starting an interactive interpreter containing +* New command: ``interact`` for starting an interactive interpreter containing the global and local names found in the current scope. -* breakpoints can be cleared by breakpoint number +* Breakpoints can be cleared by breakpoint number (Contributed by Georg Brandl, Antonio Cuni and Ilya Sandler.) @@ -1468,15 +1468,20 @@ (Contributed by Antoine Pitrou.) * Regular and recursive locks now accept an optional *timeout* argument to their - :meth:`acquire` method. (Contributed by Antoine Pitrou; :issue:`7316`.) + :meth:`acquire` method. + + (Contributed by Antoine Pitrou; :issue:`7316`.) * Similarly, :meth:`threading.Semaphore.acquire` also gained a *timeout* - argument. (Contributed by Torsten Landschoff; :issue:`850728`.) + argument. + + (Contributed by Torsten Landschoff; :issue:`850728`.) * Regular and recursive lock acquisitions can now be interrupted by signals on platforms using pthreads. This means that Python programs that deadlock while acquiring locks can be successfully killed by repeatedly sending SIGINT to the process (by pressing :kbd:`Ctrl+C` in most shells). + (Contributed by Reid Kleckner; :issue:`8844`.) @@ -1509,12 +1514,12 @@ :meth:`list.sort` and :func:`sorted` now runs faster and uses less memory when called with a :term:`key function`. Previously, every element of a list was wrapped with a temporary object that remembered the key value - associated with each element. Now, an array of keys and values are + associated with each element. Now, two arrays of keys and values are sorted in parallel. This save the memory consumed by the sort wrappers, - and it saves time lost during comparisons which were delegated by the + and it saves time lost during comparisons which where delegated by the sort wrappers. - (Patch by Daniel Stuzback in :issue:`9915`.) + (Patch by Daniel Stutzbach in :issue:`9915`.) * JSON decoding performance is improved and memory consumption is reduced whenever the same string is repeated for multiple keys. Also, JSON encoding @@ -1544,11 +1549,11 @@ (:issue:`6713` by Gawain Bolton, Mark Dickinson, and Victor Stinner.) There were several other minor optimizations. Set differencing now runs faster -when one operand is much larger than the other (Patch by Andress Bennetts in +when one operand is much larger than the other (patch by Andress Bennetts in :issue:`8685`). The :meth:`array.repeat` method has a faster implementation -(:issue:`1569291` by Alexander Belopolsky). The :class:`BaseHTTPRequestHandler` +(:issue:`1569291` by Alexander Belopolsky). The :class:`BaseHTTPRequestHandler` has more efficient buffering (:issue:`3709` by Andrew Schaaf). The -multi-argument form of :func:`operator.attrgetter` now function runs slightly +multi-argument form of :func:`operator.attrgetter` function now runs slightly faster (:issue:`10160` by Christos Georgiou). And :class:`ConfigParser` loads multi-line arguments a bit faster (:issue:`7113` by Łukasz Langa). @@ -1598,7 +1603,7 @@ ``'mbcs'``), and the ``'surrogateescape'`` error handler on all operating systems. -* Added the *cp720* Arabic DOS encoding (:issue:`1616979`). +Added the *cp720* Arabic DOS encoding (:issue:`1616979`). Documentation @@ -1611,8 +1616,8 @@ accompanied by tables of cheatsheet-style summaries to provide an overview and memory jog without having to read all of the docs. -In some cases, the pure python source code can be helpful adjunct to the docs, -so now some modules feature quick links to the latest version of the source +In some cases, the pure Python source code can be an helpful adjunct to the docs, +so some modules now feature quick links to the latest version of the source code. For example, the :mod:`functools` module documentation has a quick link at the top labeled :source:`functools Python source code `. @@ -1624,15 +1629,15 @@ No functionality was changed. This just provides an easier-to-read alternate implementation. (Contributed by Alexander Belopolsky.) -The unmaintained *Demo* directory has been removed. Some demos were integrated -into the documentation, some were moved to the *Tools/demo* directory, and -others were removed altogether. (Contributed by Georg Brandl.) +The unmaintained :file:`Demo` directory has been removed. Some demos were +integrated into the documentation, some were moved to the :file:`Tools/demo` +directory, and others were removed altogether. (Contributed by Georg Brandl.) IDLE ==== -* The format menu now has an option to clean-up source files by stripping +* The format menu now has an option to clean up source files by stripping trailing whitespace. (Contributed by Raymond Hettinger; :issue:`5150`.) @@ -1681,19 +1686,19 @@ :issue:`9778`.) * A new macro :c:macro:`Py_VA_COPY` copies the state of the variable argument - list. It is equivalent to C99 *va_copy* but available on all python platforms + list. It is equivalent to C99 *va_copy* but available on all Python platforms (:issue:`2443`). * A new C API function :c:func:`PySys_SetArgvEx` allows an embedded - interpreter to set sys.argv without also modifying :attr:`sys.path` + interpreter to set :data:`sys.argv` without also modifying :data:`sys.path` (:issue:`5753`). * :c:macro:`PyEval_CallObject` is now only available in macro form. The function declaration, which was kept for backwards compatibility reasons, is - now removed -- the macro was introduced in 1997 (:issue:`8276`). + now removed -- the macro was introduced in 1997 (:issue:`8276`). * The is a new function :c:func:`PyLong_AsLongLongAndOverflow` which - is analogous to :c:func:`PyLong_AsLongAndOverflow`. The both serve to + is analogous to :c:func:`PyLong_AsLongAndOverflow`. They both serve to convert Python :class:`int` into a native fixed-width type while providing detection of cases where the conversion won't fit (:issue:`7767`). @@ -1710,7 +1715,7 @@ gives improved memory leak detection when running under Valgrind, while taking advantage of pymalloc at other times (:issue:`2422`). -* Removed the "O?" format from the *PyArg_Parse* functions. The format is no +* Removed the ``O?`` format from the *PyArg_Parse* functions. The format is no longer used and it had never been documented (:issue:`8837`). There were a number of other small changes to the C-API. See the @@ -1760,7 +1765,7 @@ * :class:`bytearray` objects can no longer be used as filenames; instead, they should be converted to :class:`bytes`. -* PyArg_Parse*() functions: +* ``PyArg_Parse*()`` functions: * "t#" format has been removed: use "s#" or "s*" instead * "w" and "w#" formats has been removed: use "w*" instead @@ -1779,7 +1784,7 @@ ``random.seed(s, version=1)``. * The previously deprecated :func:`string.maketrans` function has been removed - in favor of the static methods, :meth:`bytes.maketrans` and + in favor of the static methods :meth:`bytes.maketrans` and :meth:`bytearray.maketrans`. This change solves the confusion around which types were supported by the :mod:`string` module. Now, :class:`str`, :class:`bytes`, and :class:`bytearray` each have their own **maketrans** and @@ -1805,16 +1810,16 @@ * :func:`struct.pack` now only allows bytes for the ``s`` string pack code. Formerly, it would accept text arguments and implicitly encode them to bytes using UTF-8. This was problematic because it made assumptions about the - correct encoding and because a variable length encoding can fail when writing + correct encoding and because a variable-length encoding can fail when writing to fixed length segment of a structure. Code such as ``struct.pack('<6sHHBBB', 'GIF87a', x, y)`` should be rewritten with to use bytes instead of text, ``struct.pack('<6sHHBBB', b'GIF87a', x, y)``. - (Discovered by David Beazley and fixed by Victor Stinner; :issue:`10783`. + (Discovered by David Beazley and fixed by Victor Stinner; :issue:`10783`.) * The :class:`xml.etree.ElementTree` class now raises an - :exc:`xml.etree.ElementTree.ParseError` when a parse fails. Previously it + :exc:`xml.etree.ElementTree.ParseError` when a parse fails. Previously it raised a :exc:`xml.parsers.expat.ExpatError`. * The new, longer :func:`str` value on floats may break doctests which rely on