[Python-checkins] cpython (3.5): whatsnew/3.5: Add some examples
yury.selivanov
python-checkins at python.org
Sun Sep 13 05:46:52 CEST 2015
https://hg.python.org/cpython/rev/c471f57097fb
changeset: 97960:c471f57097fb
branch: 3.5
parent: 97958:d1748935d4d1
user: Yury Selivanov <yselivanov at sprymix.com>
date: Sat Sep 12 23:46:39 2015 -0400
summary:
whatsnew/3.5: Add some examples
Patch by Elvis Pranskevichus
files:
Doc/whatsnew/3.5.rst | 198 +++++++++++++++++++++++++++---
1 files changed, 177 insertions(+), 21 deletions(-)
diff --git a/Doc/whatsnew/3.5.rst b/Doc/whatsnew/3.5.rst
--- a/Doc/whatsnew/3.5.rst
+++ b/Doc/whatsnew/3.5.rst
@@ -358,7 +358,7 @@
PEP 461 - % formatting support for bytes and bytearray
------------------------------------------------------
-PEP 461 adds support for ``%``
+:pep:`461` adds support for ``%``
:ref:`interpolation operator <bytes-formatting>` to :class:`bytes`
and :class:`bytearray`.
@@ -447,15 +447,24 @@
:pep:`471` adds a new directory iteration function, :func:`os.scandir`,
to the standard library. Additionally, :func:`os.walk` is now
-implemented using ``os.scandir()``, which makes it 3 to 5 times faster
+implemented using ``scandir``, which makes it 3 to 5 times faster
on POSIX systems and 7 to 20 times faster on Windows systems. This is
largely achieved by greatly reducing the number of calls to :func:`os.stat`
required to walk a directory tree.
-Additionally, ``os.scandir()`` returns an iterator, as opposed to returning
+Additionally, ``scandir`` returns an iterator, as opposed to returning
a list of file names, which improves memory efficiency when iterating
over very large directories.
+The following example shows a simple use of :func:`os.scandir` to display all
+the files (excluding directories) in the given *path* that don't start with
+``'.'``. The :meth:`entry.is_file <os.DirEntry.is_file>` call will generally
+not make an additional system call::
+
+ for entry in os.scandir(path):
+ if not entry.name.startswith('.') and entry.is_file():
+ print(entry.name)
+
.. seealso::
:pep:`471` -- os.scandir() function -- a better and faster directory iterator
@@ -641,6 +650,27 @@
functions which tell whether two values are approximately equal or
"close" to each other. Whether or not two values are considered
close is determined according to given absolute and relative tolerances.
+Relative tolerance is the maximum allowed difference between ``isclose()``
+arguments, relative to the larger absolute value::
+
+ >>> import math
+ >>> a = 5.0
+ >>> b = 4.99998
+ >>> math.isclose(a, b, rel_tol=1e-5)
+ True
+ >>> math.isclose(a, b, rel_tol=1e-6)
+ False
+
+It is also possible to compare two values using absolute tolerance, which
+must be a non-negative value::
+
+ >>> import math
+ >>> a = 5.0
+ >>> b = 4.99998
+ >>> math.isclose(a, b, abs_tol=0.00003)
+ True
+ >>> math.isclose(a, b, abs_tol=0.00001)
+ False
.. seealso::
@@ -678,6 +708,13 @@
New Modules
===========
+typing
+------
+
+The new :mod:`typing` :term:`provisional <provisional api>` module
+provides standard definitions and tools for function type annotations.
+See :ref:`Type Hints <whatsnew-pep-484>` for more information.
+
.. _whatsnew-zipapp:
zipapp
@@ -854,8 +891,25 @@
------------
Config parsers can be customized by providing a dictionary of converters in the
-constructor. All converters defined in config parser (either by subclassing or
+constructor, or All converters defined in config parser (either by subclassing or
by providing in a constructor) will be available on all section proxies.
+
+Example::
+
+ >>> import configparser
+ >>> conv = {}
+ >>> conv['list'] = lambda v: [e.strip() for e in v.split() if e.strip()]
+ >>> cfg = configparser.ConfigParser(converters=conv)
+ >>> cfg.read_string("""
+ ... [s]
+ ... list = a b c d e f g
+ ... """)
+ >>> cfg.get('s', 'list')
+ 'a b c d e f g'
+ >>> cfg.getlist('s', 'list')
+ ['a', 'b', 'c', 'd', 'e', 'f', 'g']
+
+
(Contributed by Łukasz Langa in :issue:`18159`.)
@@ -865,8 +919,17 @@
The new :func:`~contextlib.redirect_stderr` context manager (similar to
:func:`~contextlib.redirect_stdout`) makes it easier for utility scripts to
handle inflexible APIs that write their output to :data:`sys.stderr` and
-don't provide any options to redirect it. (Contributed by Berker Peksag in
-:issue:`22389`.)
+don't provide any options to redirect it::
+
+ >>> import contextlib, io, logging
+ >>> f = io.StringIO()
+ >>> with contextlib.redirect_stderr(f):
+ ... logging.warning('warning')
+ ...
+ >>> f.getvalue()
+ 'WARNING:root:warning\n'
+
+(Contributed by Berker Peksag in :issue:`22389`.)
curses
@@ -1001,9 +1064,19 @@
-----
Element comparison in :func:`~heapq.merge` can now be customized by
-passing a :term:`key function` in a new optional *key* keyword argument.
-A new optional *reverse* keyword argument can be used to reverse element
-comparison. (Contributed by Raymond Hettinger in :issue:`13742`.)
+passing a :term:`key function` in a new optional *key* keyword argument,
+and a new optional *reverse* keyword argument can be used to reverse element
+comparison::
+
+ >>> import heapq
+ >>> a = ['9', '777', '55555']
+ >>> b = ['88', '6666']
+ >>> list(heapq.merge(a, b, key=len))
+ ['9', '88', '777', '6666', '55555']
+ >>> list(heapq.merge(reversed(a), reversed(b), key=len, reverse=True))
+ ['55555', '6666', '777', '88', '9']
+
+(Contributed by Raymond Hettinger in :issue:`13742`.)
http
@@ -1022,7 +1095,17 @@
remote server connection is closed unexpectedly. Additionally, if a
:exc:`ConnectionError` (of which ``RemoteDisconnected``
is a subclass) is raised, the client socket is now closed automatically,
-and will reconnect on the next request.
+and will reconnect on the next request::
+
+ import http.client
+ conn = http.client.HTTPConnection('www.python.org')
+ for retries in range(3):
+ try:
+ conn.request('GET', '/')
+ resp = conn.getresponse()
+ except http.client.RemoteDisconnected:
+ pass
+
(Contributed by Martin Panter in :issue:`3566`.)
@@ -1095,7 +1178,14 @@
A new
:meth:`BoundArguments.apply_defaults <inspect.BoundArguments.apply_defaults>`
-method provides a way to set default values for missing arguments.
+method provides a way to set default values for missing arguments::
+
+ >>> def foo(a, b='ham', *args): pass
+ >>> ba = inspect.signature(foo).bind('spam')
+ >>> ba.apply_defaults()
+ >>> ba.arguments
+ OrderedDict([('a', 'spam'), ('b', 'ham'), ('args', ())])
+
(Contributed by Yury Selivanov in :issue:`24190`.)
A new class method
@@ -1137,12 +1227,28 @@
Both :class:`~ipaddress.IPv4Network` and :class:`~ipaddress.IPv6Network` classes
now accept an ``(address, netmask)`` tuple argument, so as to easily construct
-network objects from existing addresses. (Contributed by Peter Moody
-and Antoine Pitrou in :issue:`16531`.)
+network objects from existing addresses::
+
+ >>> import ipaddress
+ >>> ipaddress.IPv4Network(('127.0.0.0', 8))
+ IPv4Network('127.0.0.0/8')
+ >>> ipaddress.IPv4Network(('127.0.0.0', '255.0.0.0'))
+ IPv4Network('127.0.0.0/8')
+
+(Contributed by Peter Moody and Antoine Pitrou in :issue:`16531`.)
A new :attr:`~ipaddress.IPv4Network.reverse_pointer>` attribute for
:class:`~ipaddress.IPv4Network` and :class:`~ipaddress.IPv6Network` classes
-returns the name of the reverse DNS PTR record.
+returns the name of the reverse DNS PTR record::
+
+ >>> import ipaddress
+ >>> addr = ipaddress.IPv4Address('127.0.0.1')
+ >>> addr.reverse_pointer
+ '1.0.0.127.in-addr.arpa'
+ >>> addr6 = ipaddress.IPv6Address('::1')
+ >>> addr6.reverse_pointer
+ '1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.ip6.arpa'
+
(Contributed by Leon Weber in :issue:`20480`.)
@@ -1173,7 +1279,18 @@
------
A new :func:`~locale.delocalize` function can be used to convert a string into
-a normalized number string, taking the ``LC_NUMERIC`` settings into account.
+a normalized number string, taking the ``LC_NUMERIC`` settings into account::
+
+ >>> import locale
+ >>> locale.setlocale(locale.LC_NUMERIC, 'de_DE.UTF-8')
+ 'de_DE.UTF-8'
+ >>> locale.delocalize('1.234,56')
+ '1234.56'
+ >>> locale.setlocale(locale.LC_NUMERIC, 'en_US.UTF-8')
+ 'en_US.UTF-8'
+ >>> locale.delocalize('1,234.56')
+ '1234.56'
+
(Contributed by Cédric Krier in :issue:`13918`.)
@@ -1223,9 +1340,9 @@
multiprocessing
---------------
-:func:`~multiprocessing.synchronized` objects now support the
-:term:`context manager` protocol. (Contributed by Charles-François Natali in
-:issue:`21565`.)
+:func:`sharedctypes.synchronized <multiprocessing.sharedctypes.synchronized>`
+objects now support the :term:`context manager` protocol.
+(Contributed by Charles-François Natali in :issue:`21565`.)
operator
@@ -1271,7 +1388,15 @@
There is a new :func:`os.path.commonpath` function returning the longest
common sub-path of each passed pathname. Unlike the
:func:`os.path.commonprefix` function, it always returns a valid
-path. (Contributed by Rafik Draoui and Serhiy Storchaka in :issue:`10395`.)
+path::
+
+ >>> os.path.commonprefix(['/usr/lib', '/usr/local/lib'])
+ '/usr/l'
+
+ >>> os.path.commonpath(['/usr/lib', '/usr/local/lib'])
+ '/usr'
+
+(Contributed by Rafik Draoui and Serhiy Storchaka in :issue:`10395`.)
pathlib
@@ -1324,7 +1449,15 @@
--
References and conditional references to groups with fixed length are now
-allowed in lookbehind assertions.
+allowed in lookbehind assertions::
+
+ >>> import re
+ >>> pat = re.compile(r'(a|b).(?<=\1)c')
+ >>> pat.match('aac')
+ <_sre.SRE_Match object; span=(0, 3), match='aac'>
+ >>> pat.match('bbc')
+ <_sre.SRE_Match object; span=(0, 3), match='bbc'>
+
(Contributed by Serhiy Storchaka in :issue:`9179`.)
The number of capturing groups in regular expression is no longer limited by
@@ -1338,7 +1471,16 @@
:attr:`~re.error.msg`, :attr:`~re.error.pattern`,
:attr:`~re.error.pos`, :attr:`~re.error.lineno`,
and :attr:`~re.error.colno` that provide better context
-information about the error.
+information about the error::
+
+ >>> re.compile("""
+ ... (?x)
+ ... .++
+ ... """)
+ Traceback (most recent call last):
+ ...
+ sre_constants.error: multiple repeat at position 16 (line 3, column 7)
+
(Contributed by Serhiy Storchaka in :issue:`22578`.)
@@ -1568,6 +1710,20 @@
compatibility with earlier Python versions.
(Contributed by Thomas Kluyver in :issue:`23342`.)
+Examples::
+
+ >>> subprocess.run(["ls", "-l"]) # doesn't capture output
+ CompletedProcess(args=['ls', '-l'], returncode=0)
+
+ >>> subprocess.run("exit 1", shell=True, check=True)
+ Traceback (most recent call last):
+ ...
+ subprocess.CalledProcessError: Command 'exit 1' returned non-zero exit status 1
+
+ >>> subprocess.run(["ls", "-l", "/dev/null"], stdout=subprocess.PIPE)
+ CompletedProcess(args=['ls', '-l', '/dev/null'], returncode=0,
+ stdout=b'crw-rw-rw- 1 root root 1, 3 Jan 23 16:23 /dev/null\n')
+
sys
---
--
Repository URL: https://hg.python.org/cpython
More information about the Python-checkins
mailing list