• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1****************************
2  What's New in Python 2.7
3****************************
4
5:Author: A.M. Kuchling (amk at amk.ca)
6
7..  hyperlink all the methods & functions.
8
9.. T_STRING_INPLACE not described in main docs
10
11.. $Id$
12   Rules for maintenance:
13
14   * Anyone can add text to this document.  Do not spend very much time
15   on the wording of your changes, because your text will probably
16   get rewritten to some degree.
17
18   * The maintainer will go through Misc/NEWS periodically and add
19   changes; it's therefore more important to add your changes to
20   Misc/NEWS than to this file.
21
22   * This is not a complete list of every single change; completeness
23   is the purpose of Misc/NEWS.  Some changes I consider too small
24   or esoteric to include.  If such a change is added to the text,
25   I'll just remove it.  (This is another reason you shouldn't spend
26   too much time on writing your addition.)
27
28   * If you want to draw your new text to the attention of the
29   maintainer, add 'XXX' to the beginning of the paragraph or
30   section.
31
32   * It's OK to just add a fragmentary note about a change.  For
33   example: "XXX Describe the transmogrify() function added to the
34   socket module."  The maintainer will research the change and
35   write the necessary text.
36
37   * You can comment out your additions if you like, but it's not
38   necessary (especially when a final release is some months away).
39
40   * Credit the author of a patch or bugfix.  Just the name is
41   sufficient; the e-mail address isn't necessary.
42
43   * It's helpful to add the bug/patch number in a parenthetical comment.
44
45   XXX Describe the transmogrify() function added to the socket
46   module.
47   (Contributed by P.Y. Developer; :issue:`12345`.)
48
49   This saves the maintainer some effort going through the SVN logs
50   when researching a change.
51
52This article explains the new features in Python 2.7.  Python 2.7 was released
53on July 3, 2010.
54
55Numeric handling has been improved in many ways, for both
56floating-point numbers and for the :class:`~decimal.Decimal` class.
57There are some useful additions to the standard library, such as a
58greatly enhanced :mod:`unittest` module, the :mod:`argparse` module
59for parsing command-line options, convenient :class:`~collections.OrderedDict`
60and :class:`~collections.Counter` classes in the :mod:`collections` module,
61and many other improvements.
62
63Python 2.7 is planned to be the last of the 2.x releases, so we worked
64on making it a good release for the long term.  To help with porting
65to Python 3, several new features from the Python 3.x series have been
66included in 2.7.
67
68This article doesn't attempt to provide a complete specification of
69the new features, but instead provides a convenient overview.  For
70full details, you should refer to the documentation for Python 2.7 at
71https://docs.python.org. If you want to understand the rationale for
72the design and implementation, refer to the PEP for a particular new
73feature or the issue on https://bugs.python.org in which a change was
74discussed.  Whenever possible, "What's New in Python" links to the
75bug/patch item for each change.
76
77.. _whatsnew27-python31:
78
79The Future for Python 2.x
80=========================
81
82Python 2.7 is the last major release in the 2.x series, as the Python
83maintainers have shifted the focus of their new feature development efforts
84to the Python 3.x series. This means that while Python 2 continues to
85receive bug fixes, and to be updated to build correctly on new hardware and
86versions of supported operated systems, there will be no new full feature
87releases for the language or standard library.
88
89However, while there is a large common subset between Python 2.7 and Python
903, and many of the changes involved in migrating to that common subset, or
91directly to Python 3, can be safely automated, some other changes (notably
92those associated with Unicode handling) may require careful consideration,
93and preferably robust automated regression test suites, to migrate
94effectively.
95
96This means that Python 2.7 will remain in place for a long time, providing a
97stable and supported base platform for production systems that have not yet
98been ported to Python 3. The full expected lifecycle of the Python 2.7
99series is detailed in :pep:`373`.
100
101Some key consequences of the long-term significance of 2.7 are:
102
103* As noted above, the 2.7 release has a much longer period of maintenance
104  when compared to earlier 2.x versions. Python 2.7 is currently expected to
105  remain supported by the core development team (receiving security updates
106  and other bug fixes) until at least 2020 (10 years after its initial
107  release, compared to the more typical support period of 18--24 months).
108
109* As the Python 2.7 standard library ages, making effective use of the
110  Python Package Index (either directly or via a redistributor) becomes
111  more important for Python 2 users. In addition to a wide variety of third
112  party packages for various tasks, the available packages include backports
113  of new modules and features from the Python 3 standard library that are
114  compatible with Python 2, as well as various tools and libraries that can
115  make it easier to migrate to Python 3. The `Python Packaging User Guide
116  <https://packaging.python.org>`__ provides guidance on downloading and
117  installing software from the Python Package Index.
118
119* While the preferred approach to enhancing Python 2 is now the publication
120  of new packages on the Python Package Index, this approach doesn't
121  necessarily work in all cases, especially those related to network
122  security. In exceptional cases that cannot be handled adequately by
123  publishing new or updated packages on PyPI, the Python Enhancement
124  Proposal process may be used to make the case for adding new features
125  directly to the Python 2 standard library. Any such additions, and the
126  maintenance releases where they were added, will be noted in the
127  :ref:`py27-maintenance-enhancements` section below.
128
129For projects wishing to migrate from Python 2 to Python 3, or for library
130and framework developers wishing to support users on both Python 2 and
131Python 3, there are a variety of tools and guides available to help decide
132on a suitable approach and manage some of the technical details involved.
133The recommended starting point is the :ref:`pyporting-howto` HOWTO guide.
134
135
136Changes to the Handling of Deprecation Warnings
137===============================================
138
139For Python 2.7, a policy decision was made to silence warnings only of
140interest to developers by default.  :exc:`DeprecationWarning` and its
141descendants are now ignored unless otherwise requested, preventing
142users from seeing warnings triggered by an application.  This change
143was also made in the branch that became Python 3.2. (Discussed
144on stdlib-sig and carried out in :issue:`7319`.)
145
146In previous releases, :exc:`DeprecationWarning` messages were
147enabled by default, providing Python developers with a clear
148indication of where their code may break in a future major version
149of Python.
150
151However, there are increasingly many users of Python-based
152applications who are not directly involved in the development of
153those applications.  :exc:`DeprecationWarning` messages are
154irrelevant to such users, making them worry about an application
155that's actually working correctly and burdening application developers
156with responding to these concerns.
157
158You can re-enable display of :exc:`DeprecationWarning` messages by
159running Python with the :option:`-Wdefault <-W>` (short form:
160:option:`-Wd <-W>`) switch, or by setting the :envvar:`PYTHONWARNINGS`
161environment variable to ``"default"`` (or ``"d"``) before running
162Python.  Python code can also re-enable them
163by calling ``warnings.simplefilter('default')``.
164
165The ``unittest`` module also automatically reenables deprecation warnings
166when running tests.
167
168
169Python 3.1 Features
170=======================
171
172Much as Python 2.6 incorporated features from Python 3.0,
173version 2.7 incorporates some of the new features
174in Python 3.1.  The 2.x series continues to provide tools
175for migrating to the 3.x series.
176
177A partial list of 3.1 features that were backported to 2.7:
178
179* The syntax for set literals (``{1,2,3}`` is a mutable set).
180* Dictionary and set comprehensions (``{i: i*2 for i in range(3)}``).
181* Multiple context managers in a single :keyword:`with` statement.
182* A new version of the :mod:`io` library, rewritten in C for performance.
183* The ordered-dictionary type described in :ref:`pep-0372`.
184* The new ``","`` format specifier described in :ref:`pep-0378`.
185* The :class:`memoryview` object.
186* A small subset of the :mod:`importlib` module,
187  `described below <#importlib-section>`__.
188* The :func:`repr` of a float ``x`` is shorter in many cases: it's now
189  based on the shortest decimal string that's guaranteed to round back
190  to ``x``.  As in previous versions of Python, it's guaranteed that
191  ``float(repr(x))`` recovers ``x``.
192* Float-to-string and string-to-float conversions are correctly rounded.
193  The :func:`round` function is also now correctly rounded.
194* The :c:type:`PyCapsule` type, used to provide a C API for extension modules.
195* The :c:func:`PyLong_AsLongAndOverflow` C API function.
196
197Other new Python3-mode warnings include:
198
199* :func:`operator.isCallable` and :func:`operator.sequenceIncludes`,
200  which are not supported in 3.x, now trigger warnings.
201* The :option:`!-3` switch now automatically
202  enables the :option:`!-Qwarn` switch that causes warnings
203  about using classic division with integers and long integers.
204
205
206
207.. ========================================================================
208.. Large, PEP-level features and changes should be described here.
209.. ========================================================================
210
211.. _pep-0372:
212
213PEP 372: Adding an Ordered Dictionary to collections
214====================================================
215
216Regular Python dictionaries iterate over key/value pairs in arbitrary order.
217Over the years, a number of authors have written alternative implementations
218that remember the order that the keys were originally inserted.  Based on
219the experiences from those implementations, 2.7 introduces a new
220:class:`~collections.OrderedDict` class in the :mod:`collections` module.
221
222The :class:`~collections.OrderedDict` API provides the same interface as regular
223dictionaries but iterates over keys and values in a guaranteed order
224depending on when a key was first inserted::
225
226    >>> from collections import OrderedDict
227    >>> d = OrderedDict([('first', 1),
228    ...                  ('second', 2),
229    ...                  ('third', 3)])
230    >>> d.items()
231    [('first', 1), ('second', 2), ('third', 3)]
232
233If a new entry overwrites an existing entry, the original insertion
234position is left unchanged::
235
236    >>> d['second'] = 4
237    >>> d.items()
238    [('first', 1), ('second', 4), ('third', 3)]
239
240Deleting an entry and reinserting it will move it to the end::
241
242    >>> del d['second']
243    >>> d['second'] = 5
244    >>> d.items()
245    [('first', 1), ('third', 3), ('second', 5)]
246
247The :meth:`~collections.OrderedDict.popitem` method has an optional *last*
248argument that defaults to ``True``.  If *last* is true, the most recently
249added key is returned and removed; if it's false, the
250oldest key is selected::
251
252    >>> od = OrderedDict([(x,0) for x in range(20)])
253    >>> od.popitem()
254    (19, 0)
255    >>> od.popitem()
256    (18, 0)
257    >>> od.popitem(last=False)
258    (0, 0)
259    >>> od.popitem(last=False)
260    (1, 0)
261
262Comparing two ordered dictionaries checks both the keys and values,
263and requires that the insertion order was the same::
264
265    >>> od1 = OrderedDict([('first', 1),
266    ...                    ('second', 2),
267    ...                    ('third', 3)])
268    >>> od2 = OrderedDict([('third', 3),
269    ...                    ('first', 1),
270    ...                    ('second', 2)])
271    >>> od1 == od2
272    False
273    >>> # Move 'third' key to the end
274    >>> del od2['third']; od2['third'] = 3
275    >>> od1 == od2
276    True
277
278Comparing an :class:`~collections.OrderedDict` with a regular dictionary
279ignores the insertion order and just compares the keys and values.
280
281How does the :class:`~collections.OrderedDict` work?  It maintains a
282doubly-linked list of keys, appending new keys to the list as they're inserted.
283A secondary dictionary maps keys to their corresponding list node, so
284deletion doesn't have to traverse the entire linked list and therefore
285remains O(1).
286
287The standard library now supports use of ordered dictionaries in several
288modules.
289
290* The :mod:`ConfigParser` module uses them by default, meaning that
291  configuration files can now be read, modified, and then written back
292  in their original order.
293
294* The :meth:`~collections.somenamedtuple._asdict()` method for
295  :func:`collections.namedtuple` now returns an ordered dictionary with the
296  values appearing in the same order as the underlying tuple indices.
297
298* The :mod:`json` module's :class:`~json.JSONDecoder` class
299  constructor was extended with an *object_pairs_hook* parameter to
300  allow :class:`OrderedDict` instances to be built by the decoder.
301  Support was also added for third-party tools like
302  `PyYAML <http://pyyaml.org/>`_.
303
304.. seealso::
305
306   :pep:`372` - Adding an ordered dictionary to collections
307     PEP written by Armin Ronacher and Raymond Hettinger;
308     implemented by Raymond Hettinger.
309
310.. _pep-0378:
311
312PEP 378: Format Specifier for Thousands Separator
313=================================================
314
315To make program output more readable, it can be useful to add
316separators to large numbers, rendering them as
31718,446,744,073,709,551,616 instead of 18446744073709551616.
318
319The fully general solution for doing this is the :mod:`locale` module,
320which can use different separators ("," in North America, "." in
321Europe) and different grouping sizes, but :mod:`locale` is complicated
322to use and unsuitable for multi-threaded applications where different
323threads are producing output for different locales.
324
325Therefore, a simple comma-grouping mechanism has been added to the
326mini-language used by the :meth:`str.format` method.  When
327formatting a floating-point number, simply include a comma between the
328width and the precision::
329
330   >>> '{:20,.2f}'.format(18446744073709551616.0)
331   '18,446,744,073,709,551,616.00'
332
333When formatting an integer, include the comma after the width:
334
335   >>> '{:20,d}'.format(18446744073709551616)
336   '18,446,744,073,709,551,616'
337
338This mechanism is not adaptable at all; commas are always used as the
339separator and the grouping is always into three-digit groups.  The
340comma-formatting mechanism isn't as general as the :mod:`locale`
341module, but it's easier to use.
342
343.. seealso::
344
345   :pep:`378` - Format Specifier for Thousands Separator
346     PEP written by Raymond Hettinger; implemented by Eric Smith.
347
348PEP 389: The argparse Module for Parsing Command Lines
349======================================================
350
351The :mod:`argparse` module for parsing command-line arguments was
352added as a more powerful replacement for the
353:mod:`optparse` module.
354
355This means Python now supports three different modules for parsing
356command-line arguments: :mod:`getopt`, :mod:`optparse`, and
357:mod:`argparse`.  The :mod:`getopt` module closely resembles the C
358library's :c:func:`getopt` function, so it remains useful if you're writing a
359Python prototype that will eventually be rewritten in C.
360:mod:`optparse` becomes redundant, but there are no plans to remove it
361because there are many scripts still using it, and there's no
362automated way to update these scripts.  (Making the :mod:`argparse`
363API consistent with :mod:`optparse`'s interface was discussed but
364rejected as too messy and difficult.)
365
366In short, if you're writing a new script and don't need to worry
367about compatibility with earlier versions of Python, use
368:mod:`argparse` instead of :mod:`optparse`.
369
370Here's an example::
371
372    import argparse
373
374    parser = argparse.ArgumentParser(description='Command-line example.')
375
376    # Add optional switches
377    parser.add_argument('-v', action='store_true', dest='is_verbose',
378                        help='produce verbose output')
379    parser.add_argument('-o', action='store', dest='output',
380                        metavar='FILE',
381                        help='direct output to FILE instead of stdout')
382    parser.add_argument('-C', action='store', type=int, dest='context',
383                        metavar='NUM', default=0,
384                        help='display NUM lines of added context')
385
386    # Allow any number of additional arguments.
387    parser.add_argument(nargs='*', action='store', dest='inputs',
388                        help='input filenames (default is stdin)')
389
390    args = parser.parse_args()
391    print args.__dict__
392
393Unless you override it, :option:`!-h` and :option:`!--help` switches
394are automatically added, and produce neatly formatted output::
395
396    -> ./python.exe argparse-example.py --help
397    usage: argparse-example.py [-h] [-v] [-o FILE] [-C NUM] [inputs [inputs ...]]
398
399    Command-line example.
400
401    positional arguments:
402      inputs      input filenames (default is stdin)
403
404    optional arguments:
405      -h, --help  show this help message and exit
406      -v          produce verbose output
407      -o FILE     direct output to FILE instead of stdout
408      -C NUM      display NUM lines of added context
409
410As with :mod:`optparse`, the command-line switches and arguments
411are returned as an object with attributes named by the *dest* parameters::
412
413    -> ./python.exe argparse-example.py -v
414    {'output': None,
415     'is_verbose': True,
416     'context': 0,
417     'inputs': []}
418
419    -> ./python.exe argparse-example.py -v -o /tmp/output -C 4 file1 file2
420    {'output': '/tmp/output',
421     'is_verbose': True,
422     'context': 4,
423     'inputs': ['file1', 'file2']}
424
425:mod:`argparse` has much fancier validation than :mod:`optparse`; you
426can specify an exact number of arguments as an integer, 0 or more
427arguments by passing ``'*'``, 1 or more by passing ``'+'``, or an
428optional argument with ``'?'``.  A top-level parser can contain
429sub-parsers to define subcommands that have different sets of
430switches, as in ``svn commit``, ``svn checkout``, etc.  You can
431specify an argument's type as :class:`~argparse.FileType`, which will
432automatically open files for you and understands that ``'-'`` means
433standard input or output.
434
435.. seealso::
436
437   :mod:`argparse` documentation
438     The documentation page of the argparse module.
439
440   :ref:`upgrading-optparse-code`
441     Part of the Python documentation, describing how to convert
442     code that uses :mod:`optparse`.
443
444   :pep:`389` - argparse - New Command Line Parsing Module
445     PEP written and implemented by Steven Bethard.
446
447PEP 391: Dictionary-Based Configuration For Logging
448====================================================
449
450The :mod:`logging` module is very flexible; applications can define
451a tree of logging subsystems, and each logger in this tree can filter
452out certain messages, format them differently, and direct messages to
453a varying number of handlers.
454
455All this flexibility can require a lot of configuration.  You can
456write Python statements to create objects and set their properties,
457but a complex set-up requires verbose but boring code.
458:mod:`logging` also supports a :func:`~logging.fileConfig`
459function that parses a file, but the file format doesn't support
460configuring filters, and it's messier to generate programmatically.
461
462Python 2.7 adds a :func:`~logging.dictConfig` function that
463uses a dictionary to configure logging.  There are many ways to
464produce a dictionary from different sources: construct one with code;
465parse a file containing JSON; or use a YAML parsing library if one is
466installed.  For more information see :ref:`logging-config-api`.
467
468The following example configures two loggers, the root logger and a
469logger named "network".  Messages sent to the root logger will be
470sent to the system log using the syslog protocol, and messages
471to the "network" logger will be written to a :file:`network.log` file
472that will be rotated once the log reaches 1MB.
473
474::
475
476    import logging
477    import logging.config
478
479    configdict = {
480     'version': 1,    # Configuration schema in use; must be 1 for now
481     'formatters': {
482         'standard': {
483             'format': ('%(asctime)s %(name)-15s '
484                        '%(levelname)-8s %(message)s')}},
485
486     'handlers': {'netlog': {'backupCount': 10,
487                         'class': 'logging.handlers.RotatingFileHandler',
488                         'filename': '/logs/network.log',
489                         'formatter': 'standard',
490                         'level': 'INFO',
491                         'maxBytes': 1000000},
492                  'syslog': {'class': 'logging.handlers.SysLogHandler',
493                             'formatter': 'standard',
494                             'level': 'ERROR'}},
495
496     # Specify all the subordinate loggers
497     'loggers': {
498                 'network': {
499                             'handlers': ['netlog']
500                 }
501     },
502     # Specify properties of the root logger
503     'root': {
504              'handlers': ['syslog']
505     },
506    }
507
508    # Set up configuration
509    logging.config.dictConfig(configdict)
510
511    # As an example, log two error messages
512    logger = logging.getLogger('/')
513    logger.error('Database not found')
514
515    netlogger = logging.getLogger('network')
516    netlogger.error('Connection failed')
517
518Three smaller enhancements to the :mod:`logging` module, all
519implemented by Vinay Sajip, are:
520
521.. rev79293
522
523* The :class:`~logging.handlers.SysLogHandler` class now supports
524  syslogging over TCP.  The constructor has a *socktype* parameter
525  giving the type of socket to use, either :const:`socket.SOCK_DGRAM`
526  for UDP or :const:`socket.SOCK_STREAM` for TCP.  The default
527  protocol remains UDP.
528
529* :class:`~logging.Logger` instances gained a :meth:`~logging.Logger.getChild`
530  method that retrieves a descendant logger using a relative path.
531  For example, once you retrieve a logger by doing ``log = getLogger('app')``,
532  calling ``log.getChild('network.listen')`` is equivalent to
533  ``getLogger('app.network.listen')``.
534
535* The :class:`~logging.LoggerAdapter` class gained an
536  :meth:`~logging.LoggerAdapter.isEnabledFor` method that takes a
537  *level* and returns whether the underlying logger would
538  process a message of that level of importance.
539
540.. XXX: Logger objects don't have a class declaration so the link don't work
541
542.. seealso::
543
544   :pep:`391` - Dictionary-Based Configuration For Logging
545     PEP written and implemented by Vinay Sajip.
546
547PEP 3106: Dictionary Views
548====================================================
549
550The dictionary methods :meth:`~dict.keys`, :meth:`~dict.values`, and
551:meth:`~dict.items` are different in Python 3.x.  They return an object
552called a :dfn:`view` instead of a fully materialized list.
553
554It's not possible to change the return values of :meth:`~dict.keys`,
555:meth:`~dict.values`, and :meth:`~dict.items` in Python 2.7 because
556too much code would break.  Instead the 3.x versions were added
557under the new names :meth:`~dict.viewkeys`, :meth:`~dict.viewvalues`,
558and :meth:`~dict.viewitems`.
559
560::
561
562    >>> d = dict((i*10, chr(65+i)) for i in range(26))
563    >>> d
564    {0: 'A', 130: 'N', 10: 'B', 140: 'O', 20: ..., 250: 'Z'}
565    >>> d.viewkeys()
566    dict_keys([0, 130, 10, 140, 20, 150, 30, ..., 250])
567
568Views can be iterated over, but the key and item views also behave
569like sets.  The ``&`` operator performs intersection, and ``|``
570performs a union::
571
572    >>> d1 = dict((i*10, chr(65+i)) for i in range(26))
573    >>> d2 = dict((i**.5, i) for i in range(1000))
574    >>> d1.viewkeys() & d2.viewkeys()
575    set([0.0, 10.0, 20.0, 30.0])
576    >>> d1.viewkeys() | range(0, 30)
577    set([0, 1, 130, 3, 4, 5, 6, ..., 120, 250])
578
579The view keeps track of the dictionary and its contents change as the
580dictionary is modified::
581
582    >>> vk = d.viewkeys()
583    >>> vk
584    dict_keys([0, 130, 10, ..., 250])
585    >>> d[260] = '&'
586    >>> vk
587    dict_keys([0, 130, 260, 10, ..., 250])
588
589However, note that you can't add or remove keys while you're iterating
590over the view::
591
592    >>> for k in vk:
593    ...     d[k*2] = k
594    ...
595    Traceback (most recent call last):
596      File "<stdin>", line 1, in <module>
597    RuntimeError: dictionary changed size during iteration
598
599You can use the view methods in Python 2.x code, and the 2to3
600converter will change them to the standard :meth:`~dict.keys`,
601:meth:`~dict.values`, and :meth:`~dict.items` methods.
602
603.. seealso::
604
605   :pep:`3106` - Revamping dict.keys(), .values() and .items()
606     PEP written by Guido van Rossum.
607     Backported to 2.7 by Alexandre Vassalotti; :issue:`1967`.
608
609
610PEP 3137: The memoryview Object
611====================================================
612
613The :class:`memoryview` object provides a view of another object's
614memory content that matches the :class:`bytes` type's interface.
615
616.. doctest::
617    :options: +SKIP
618
619    >>> import string
620    >>> m = memoryview(string.letters)
621    >>> m
622    <memory at 0x37f850>
623    >>> len(m)           # Returns length of underlying object
624    52
625    >>> m[0], m[25], m[26]   # Indexing returns one byte
626    ('a', 'z', 'A')
627    >>> m2 = m[0:26]         # Slicing returns another memoryview
628    >>> m2
629    <memory at 0x37f080>
630
631The content of the view can be converted to a string of bytes or
632a list of integers:
633
634.. doctest::
635    :options: +SKIP
636
637    >>> m2.tobytes()
638    'abcdefghijklmnopqrstuvwxyz'
639    >>> m2.tolist()
640    [97, 98, 99, 100, 101, 102, 103, ... 121, 122]
641    >>>
642
643:class:`memoryview` objects allow modifying the underlying object if
644it's a mutable object.
645
646.. doctest::
647    :options: +SKIP
648
649    >>> m2[0] = 75
650    Traceback (most recent call last):
651      File "<stdin>", line 1, in <module>
652    TypeError: cannot modify read-only memory
653    >>> b = bytearray(string.letters)  # Creating a mutable object
654    >>> b
655    bytearray(b'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ')
656    >>> mb = memoryview(b)
657    >>> mb[0] = '*'         # Assign to view, changing the bytearray.
658    >>> b[0:5]              # The bytearray has been changed.
659    bytearray(b'*bcde')
660    >>>
661
662.. seealso::
663
664   :pep:`3137` - Immutable Bytes and Mutable Buffer
665     PEP written by Guido van Rossum.
666     Implemented by Travis Oliphant, Antoine Pitrou and others.
667     Backported to 2.7 by Antoine Pitrou; :issue:`2396`.
668
669
670
671Other Language Changes
672======================
673
674Some smaller changes made to the core Python language are:
675
676* The syntax for set literals has been backported from Python 3.x.
677  Curly brackets are used to surround the contents of the resulting
678  mutable set; set literals are
679  distinguished from dictionaries by not containing colons and values.
680  ``{}`` continues to represent an empty dictionary; use
681  ``set()`` for an empty set.
682
683  .. doctest::
684    :options: +SKIP
685
686    >>> {1, 2, 3, 4, 5}
687    set([1, 2, 3, 4, 5])
688    >>> set() # empty set
689    set([])
690    >>> {}    # empty dict
691    {}
692
693  Backported by Alexandre Vassalotti; :issue:`2335`.
694
695* Dictionary and set comprehensions are another feature backported from
696  3.x, generalizing list/generator comprehensions to use
697  the literal syntax for sets and dictionaries.
698
699  .. doctest::
700    :options: +SKIP
701
702    >>> {x: x*x for x in range(6)}
703    {0: 0, 1: 1, 2: 4, 3: 9, 4: 16, 5: 25}
704    >>> {('a'*x) for x in range(6)}
705    set(['', 'a', 'aa', 'aaa', 'aaaa', 'aaaaa'])
706
707  Backported by Alexandre Vassalotti; :issue:`2333`.
708
709* The :keyword:`with` statement can now use multiple context managers
710  in one statement.  Context managers are processed from left to right
711  and each one is treated as beginning a new :keyword:`!with` statement.
712  This means that::
713
714   with A() as a, B() as b:
715       ... suite of statements ...
716
717  is equivalent to::
718
719   with A() as a:
720       with B() as b:
721           ... suite of statements ...
722
723  The :func:`contextlib.nested` function provides a very similar
724  function, so it's no longer necessary and has been deprecated.
725
726  (Proposed in https://codereview.appspot.com/53094; implemented by
727  Georg Brandl.)
728
729* Conversions between floating-point numbers and strings are
730  now correctly rounded on most platforms.  These conversions occur
731  in many different places: :func:`str` on
732  floats and complex numbers; the :class:`float` and :class:`complex`
733  constructors;
734  numeric formatting; serializing and
735  deserializing floats and complex numbers using the
736  :mod:`marshal`, :mod:`pickle`
737  and :mod:`json` modules;
738  parsing of float and imaginary literals in Python code;
739  and :class:`~decimal.Decimal`-to-float conversion.
740
741  Related to this, the :func:`repr` of a floating-point number *x*
742  now returns a result based on the shortest decimal string that's
743  guaranteed to round back to *x* under correct rounding (with
744  round-half-to-even rounding mode).  Previously it gave a string
745  based on rounding x to 17 decimal digits.
746
747  .. maybe add an example?
748
749  The rounding library responsible for this improvement works on
750  Windows and on Unix platforms using the gcc, icc, or suncc
751  compilers.  There may be a small number of platforms where correct
752  operation of this code cannot be guaranteed, so the code is not
753  used on such systems.  You can find out which code is being used
754  by checking :data:`sys.float_repr_style`,  which will be ``short``
755  if the new code is in use and ``legacy`` if it isn't.
756
757  Implemented by Eric Smith and Mark Dickinson, using David Gay's
758  :file:`dtoa.c` library; :issue:`7117`.
759
760* Conversions from long integers and regular integers to floating
761  point now round differently, returning the floating-point number
762  closest to the number.  This doesn't matter for small integers that
763  can be converted exactly, but for large numbers that will
764  unavoidably lose precision, Python 2.7 now approximates more
765  closely.  For example, Python 2.6 computed the following::
766
767    >>> n = 295147905179352891391
768    >>> float(n)
769    2.9514790517935283e+20
770    >>> n - long(float(n))
771    65535L
772
773  Python 2.7's floating-point result is larger, but much closer to the
774  true value::
775
776    >>> n = 295147905179352891391
777    >>> float(n)
778    2.9514790517935289e+20
779    >>> n - long(float(n))
780    -1L
781
782  (Implemented by Mark Dickinson; :issue:`3166`.)
783
784  Integer division is also more accurate in its rounding behaviours.  (Also
785  implemented by Mark Dickinson; :issue:`1811`.)
786
787* Implicit coercion for complex numbers has been removed; the interpreter
788  will no longer ever attempt to call a :meth:`__coerce__` method on complex
789  objects.  (Removed by Meador Inge and Mark Dickinson; :issue:`5211`.)
790
791* The :meth:`str.format` method now supports automatic numbering of the replacement
792  fields.  This makes using :meth:`str.format` more closely resemble using
793  ``%s`` formatting::
794
795    >>> '{}:{}:{}'.format(2009, 04, 'Sunday')
796    '2009:4:Sunday'
797    >>> '{}:{}:{day}'.format(2009, 4, day='Sunday')
798    '2009:4:Sunday'
799
800  The auto-numbering takes the fields from left to right, so the first ``{...}``
801  specifier will use the first argument to :meth:`str.format`, the next
802  specifier will use the next argument, and so on.  You can't mix auto-numbering
803  and explicit numbering -- either number all of your specifier fields or none
804  of them -- but you can mix auto-numbering and named fields, as in the second
805  example above.  (Contributed by Eric Smith; :issue:`5237`.)
806
807  Complex numbers now correctly support usage with :func:`format`,
808  and default to being right-aligned.
809  Specifying a precision or comma-separation applies to both the real
810  and imaginary parts of the number, but a specified field width and
811  alignment is applied to the whole of the resulting ``1.5+3j``
812  output.  (Contributed by Eric Smith; :issue:`1588` and :issue:`7988`.)
813
814  The 'F' format code now always formats its output using uppercase characters,
815  so it will now produce 'INF' and 'NAN'.
816  (Contributed by Eric Smith; :issue:`3382`.)
817
818  A low-level change: the :meth:`object.__format__` method now triggers
819  a :exc:`PendingDeprecationWarning` if it's passed a format string,
820  because the :meth:`__format__` method for :class:`object` converts
821  the object to a string representation and formats that.  Previously
822  the method silently applied the format string to the string
823  representation, but that could hide mistakes in Python code.  If
824  you're supplying formatting information such as an alignment or
825  precision, presumably you're expecting the formatting to be applied
826  in some object-specific way.  (Fixed by Eric Smith; :issue:`7994`.)
827
828* The :func:`int` and :func:`long` types gained a ``bit_length``
829  method that returns the number of bits necessary to represent
830  its argument in binary::
831
832      >>> n = 37
833      >>> bin(n)
834      '0b100101'
835      >>> n.bit_length()
836      6
837      >>> n = 2**123-1
838      >>> n.bit_length()
839      123
840      >>> (n+1).bit_length()
841      124
842
843  (Contributed by Fredrik Johansson and Victor Stinner; :issue:`3439`.)
844
845* The :keyword:`import` statement will no longer try an absolute import
846  if a relative import (e.g. ``from .os import sep``) fails.  This
847  fixes a bug, but could possibly break certain :keyword:`!import`
848  statements that were only working by accident.  (Fixed by Meador Inge;
849  :issue:`7902`.)
850
851* It's now possible for a subclass of the built-in :class:`unicode` type
852  to override the :meth:`__unicode__` method.  (Implemented by
853  Victor Stinner; :issue:`1583863`.)
854
855* The :class:`bytearray` type's :meth:`~bytearray.translate` method now accepts
856  ``None`` as its first argument.  (Fixed by Georg Brandl;
857  :issue:`4759`.)
858
859  .. XXX bytearray doesn't seem to be documented
860
861* When using ``@classmethod`` and ``@staticmethod`` to wrap
862  methods as class or static methods, the wrapper object now
863  exposes the wrapped function as their :attr:`__func__` attribute.
864  (Contributed by Amaury Forgeot d'Arc, after a suggestion by
865  George Sakkis; :issue:`5982`.)
866
867* When a restricted set of attributes were set using ``__slots__``,
868  deleting an unset attribute would not raise :exc:`AttributeError`
869  as you would expect.  Fixed by Benjamin Peterson; :issue:`7604`.)
870
871* Two new encodings are now supported: "cp720", used primarily for
872  Arabic text; and "cp858", a variant of CP 850 that adds the euro
873  symbol.  (CP720 contributed by Alexander Belchenko and Amaury
874  Forgeot d'Arc in :issue:`1616979`; CP858 contributed by Tim Hatch in
875  :issue:`8016`.)
876
877* The :class:`file` object will now set the :attr:`filename` attribute
878  on the :exc:`IOError` exception when trying to open a directory
879  on POSIX platforms (noted by Jan Kaliszewski; :issue:`4764`), and
880  now explicitly checks for and forbids writing to read-only file objects
881  instead of trusting the C library to catch and report the error
882  (fixed by Stefan Krah; :issue:`5677`).
883
884* The Python tokenizer now translates line endings itself, so the
885  :func:`compile` built-in function now accepts code using any
886  line-ending convention.  Additionally, it no longer requires that the
887  code end in a newline.
888
889* Extra parentheses in function definitions are illegal in Python 3.x,
890  meaning that you get a syntax error from ``def f((x)): pass``.  In
891  Python3-warning mode, Python 2.7 will now warn about this odd usage.
892  (Noted by James Lingard; :issue:`7362`.)
893
894* It's now possible to create weak references to old-style class
895  objects.  New-style classes were always weak-referenceable.  (Fixed
896  by Antoine Pitrou; :issue:`8268`.)
897
898* When a module object is garbage-collected, the module's dictionary is
899  now only cleared if no one else is holding a reference to the
900  dictionary (:issue:`7140`).
901
902.. ======================================================================
903
904.. _new-27-interpreter:
905
906Interpreter Changes
907-------------------------------
908
909A new environment variable, :envvar:`PYTHONWARNINGS`,
910allows controlling warnings.  It should be set to a string
911containing warning settings, equivalent to those
912used with the :option:`-W` switch, separated by commas.
913(Contributed by Brian Curtin; :issue:`7301`.)
914
915For example, the following setting will print warnings every time
916they occur, but turn warnings from the :mod:`Cookie` module into an
917error.  (The exact syntax for setting an environment variable varies
918across operating systems and shells.)
919
920::
921
922  export PYTHONWARNINGS=all,error:::Cookie:0
923
924.. ======================================================================
925
926
927Optimizations
928-------------
929
930Several performance enhancements have been added:
931
932* A new opcode was added to perform the initial setup for
933  :keyword:`with` statements, looking up the :meth:`__enter__` and
934  :meth:`__exit__` methods.  (Contributed by Benjamin Peterson.)
935
936* The garbage collector now performs better for one common usage
937  pattern: when many objects are being allocated without deallocating
938  any of them.  This would previously take quadratic
939  time for garbage collection, but now the number of full garbage collections
940  is reduced as the number of objects on the heap grows.
941  The new logic only performs a full garbage collection pass when
942  the middle generation has been collected 10 times and when the
943  number of survivor objects from the middle generation exceeds 10% of
944  the number of objects in the oldest generation.  (Suggested by Martin
945  von Löwis and implemented by Antoine Pitrou; :issue:`4074`.)
946
947* The garbage collector tries to avoid tracking simple containers
948  which can't be part of a cycle. In Python 2.7, this is now true for
949  tuples and dicts containing atomic types (such as ints, strings,
950  etc.). Transitively, a dict containing tuples of atomic types won't
951  be tracked either. This helps reduce the cost of each
952  garbage collection by decreasing the number of objects to be
953  considered and traversed by the collector.
954  (Contributed by Antoine Pitrou; :issue:`4688`.)
955
956* Long integers are now stored internally either in base ``2**15`` or in base
957  ``2**30``, the base being determined at build time.  Previously, they
958  were always stored in base ``2**15``.  Using base ``2**30`` gives
959  significant performance improvements on 64-bit machines, but
960  benchmark results on 32-bit machines have been mixed.  Therefore,
961  the default is to use base ``2**30`` on 64-bit machines and base ``2**15``
962  on 32-bit machines; on Unix, there's a new configure option
963  :option:`!--enable-big-digits` that can be used to override this default.
964
965  Apart from the performance improvements this change should be
966  invisible to end users, with one exception: for testing and
967  debugging purposes there's a new structseq :data:`sys.long_info` that
968  provides information about the internal format, giving the number of
969  bits per digit and the size in bytes of the C type used to store
970  each digit::
971
972     >>> import sys
973     >>> sys.long_info
974     sys.long_info(bits_per_digit=30, sizeof_digit=4)
975
976  (Contributed by Mark Dickinson; :issue:`4258`.)
977
978  Another set of changes made long objects a few bytes smaller: 2 bytes
979  smaller on 32-bit systems and 6 bytes on 64-bit.
980  (Contributed by Mark Dickinson; :issue:`5260`.)
981
982* The division algorithm for long integers has been made faster
983  by tightening the inner loop, doing shifts instead of multiplications,
984  and fixing an unnecessary extra iteration.
985  Various benchmarks show speedups of between 50% and 150% for long
986  integer divisions and modulo operations.
987  (Contributed by Mark Dickinson; :issue:`5512`.)
988  Bitwise operations are also significantly faster (initial patch by
989  Gregory Smith; :issue:`1087418`).
990
991* The implementation of ``%`` checks for the left-side operand being
992  a Python string and special-cases it; this results in a 1--3%
993  performance increase for applications that frequently use ``%``
994  with strings, such as templating libraries.
995  (Implemented by Collin Winter; :issue:`5176`.)
996
997* List comprehensions with an ``if`` condition are compiled into
998  faster bytecode.  (Patch by Antoine Pitrou, back-ported to 2.7
999  by Jeffrey Yasskin; :issue:`4715`.)
1000
1001* Converting an integer or long integer to a decimal string was made
1002  faster by special-casing base 10 instead of using a generalized
1003  conversion function that supports arbitrary bases.
1004  (Patch by Gawain Bolton; :issue:`6713`.)
1005
1006* The :meth:`split`, :meth:`replace`, :meth:`rindex`,
1007  :meth:`rpartition`, and :meth:`rsplit` methods of string-like types
1008  (strings, Unicode strings, and :class:`bytearray` objects) now use a
1009  fast reverse-search algorithm instead of a character-by-character
1010  scan.  This is sometimes faster by a factor of 10.  (Added by
1011  Florent Xicluna; :issue:`7462` and :issue:`7622`.)
1012
1013* The :mod:`pickle` and :mod:`cPickle` modules now automatically
1014  intern the strings used for attribute names, reducing memory usage
1015  of the objects resulting from unpickling.  (Contributed by Jake
1016  McGuire; :issue:`5084`.)
1017
1018* The :mod:`cPickle` module now special-cases dictionaries,
1019  nearly halving the time required to pickle them.
1020  (Contributed by Collin Winter; :issue:`5670`.)
1021
1022.. ======================================================================
1023
1024New and Improved Modules
1025========================
1026
1027As in every release, Python's standard library received a number of
1028enhancements and bug fixes.  Here's a partial list of the most notable
1029changes, sorted alphabetically by module name. Consult the
1030:file:`Misc/NEWS` file in the source tree for a more complete list of
1031changes, or look through the Subversion logs for all the details.
1032
1033* The :mod:`bdb` module's base debugging class :class:`~bdb.Bdb`
1034  gained a feature for skipping modules.  The constructor
1035  now takes an iterable containing glob-style patterns such as
1036  ``django.*``; the debugger will not step into stack frames
1037  from a module that matches one of these patterns.
1038  (Contributed by Maru Newby after a suggestion by
1039  Senthil Kumaran; :issue:`5142`.)
1040
1041* The :mod:`binascii` module now supports the buffer API, so it can be
1042  used with :class:`memoryview` instances and other similar buffer objects.
1043  (Backported from 3.x by Florent Xicluna; :issue:`7703`.)
1044
1045* Updated module: the :mod:`bsddb` module has been updated from 4.7.2devel9
1046  to version 4.8.4 of
1047  `the pybsddb package <https://www.jcea.es/programacion/pybsddb.htm>`__.
1048  The new version features better Python 3.x compatibility, various bug fixes,
1049  and adds several new BerkeleyDB flags and methods.
1050  (Updated by Jesús Cea Avión; :issue:`8156`.  The pybsddb
1051  changelog can be read at http://hg.jcea.es/pybsddb/file/tip/ChangeLog.)
1052
1053* The :mod:`bz2` module's :class:`~bz2.BZ2File` now supports the context
1054  management protocol, so you can write ``with bz2.BZ2File(...) as f:``.
1055  (Contributed by Hagen Fürstenau; :issue:`3860`.)
1056
1057* New class: the :class:`~collections.Counter` class in the :mod:`collections`
1058  module is useful for tallying data.  :class:`~collections.Counter` instances
1059  behave mostly like dictionaries but return zero for missing keys instead of
1060  raising a :exc:`KeyError`:
1061
1062  .. doctest::
1063     :options: +NORMALIZE_WHITESPACE
1064
1065     >>> from collections import Counter
1066     >>> c = Counter()
1067     >>> for letter in 'here is a sample of english text':
1068     ...   c[letter] += 1
1069     ...
1070     >>> c # doctest: +SKIP
1071     Counter({' ': 6, 'e': 5, 's': 3, 'a': 2, 'i': 2, 'h': 2,
1072     'l': 2, 't': 2, 'g': 1, 'f': 1, 'm': 1, 'o': 1, 'n': 1,
1073     'p': 1, 'r': 1, 'x': 1})
1074     >>> c['e']
1075     5
1076     >>> c['z']
1077     0
1078
1079  There are three additional :class:`~collections.Counter` methods.
1080  :meth:`~collections.Counter.most_common` returns the N most common
1081  elements and their counts.  :meth:`~collections.Counter.elements`
1082  returns an iterator over the contained elements, repeating each
1083  element as many times as its count.
1084  :meth:`~collections.Counter.subtract` takes an iterable and
1085  subtracts one for each element instead of adding; if the argument is
1086  a dictionary or another :class:`Counter`, the counts are
1087  subtracted. ::
1088
1089    >>> c.most_common(5)
1090    [(' ', 6), ('e', 5), ('s', 3), ('a', 2), ('i', 2)]
1091    >>> c.elements() ->
1092       'a', 'a', ' ', ' ', ' ', ' ', ' ', ' ',
1093       'e', 'e', 'e', 'e', 'e', 'g', 'f', 'i', 'i',
1094       'h', 'h', 'm', 'l', 'l', 'o', 'n', 'p', 's',
1095       's', 's', 'r', 't', 't', 'x'
1096    >>> c['e']
1097    5
1098    >>> c.subtract('very heavy on the letter e')
1099    >>> c['e']    # Count is now lower
1100    -1
1101
1102  Contributed by Raymond Hettinger; :issue:`1696199`.
1103
1104  .. revision 79660
1105
1106  New class: :class:`~collections.OrderedDict` is described in the earlier
1107  section :ref:`pep-0372`.
1108
1109  New method: The :class:`~collections.deque` data type now has a
1110  :meth:`~collections.deque.count` method that returns the number of
1111  contained elements equal to the supplied argument *x*, and a
1112  :meth:`~collections.deque.reverse` method that reverses the elements
1113  of the deque in-place.  :class:`~collections.deque` also exposes its maximum
1114  length as the read-only :attr:`~collections.deque.maxlen` attribute.
1115  (Both features added by Raymond Hettinger.)
1116
1117  The :class:`~collections.namedtuple` class now has an optional *rename* parameter.
1118  If *rename* is true, field names that are invalid because they've
1119  been repeated or aren't legal Python identifiers will be
1120  renamed to legal names that are derived from the field's
1121  position within the list of fields:
1122
1123     >>> from collections import namedtuple
1124     >>> T = namedtuple('T', ['field1', '$illegal', 'for', 'field2'], rename=True)
1125     >>> T._fields
1126     ('field1', '_1', '_2', 'field2')
1127
1128  (Added by Raymond Hettinger; :issue:`1818`.)
1129
1130  Finally, the :class:`~collections.Mapping` abstract base class now
1131  returns :const:`NotImplemented` if a mapping is compared to
1132  another type that isn't a :class:`Mapping`.
1133  (Fixed by Daniel Stutzbach; :issue:`8729`.)
1134
1135* Constructors for the parsing classes in the :mod:`ConfigParser` module now
1136  take an *allow_no_value* parameter, defaulting to false; if true,
1137  options without values will be allowed.  For example::
1138
1139    >>> import ConfigParser, StringIO
1140    >>> sample_config = """
1141    ... [mysqld]
1142    ... user = mysql
1143    ... pid-file = /var/run/mysqld/mysqld.pid
1144    ... skip-bdb
1145    ... """
1146    >>> config = ConfigParser.RawConfigParser(allow_no_value=True)
1147    >>> config.readfp(StringIO.StringIO(sample_config))
1148    >>> config.get('mysqld', 'user')
1149    'mysql'
1150    >>> print config.get('mysqld', 'skip-bdb')
1151    None
1152    >>> print config.get('mysqld', 'unknown')
1153    Traceback (most recent call last):
1154      ...
1155    NoOptionError: No option 'unknown' in section: 'mysqld'
1156
1157  (Contributed by Mats Kindahl; :issue:`7005`.)
1158
1159* Deprecated function: :func:`contextlib.nested`, which allows
1160  handling more than one context manager with a single :keyword:`with`
1161  statement, has been deprecated, because the :keyword:`!with` statement
1162  now supports multiple context managers.
1163
1164* The :mod:`cookielib` module now ignores cookies that have an invalid
1165  version field, one that doesn't contain an integer value.  (Fixed by
1166  John J. Lee; :issue:`3924`.)
1167
1168* The :mod:`copy` module's :func:`~copy.deepcopy` function will now
1169  correctly copy bound instance methods.  (Implemented by
1170  Robert Collins; :issue:`1515`.)
1171
1172* The :mod:`ctypes` module now always converts ``None`` to a C ``NULL``
1173  pointer for arguments declared as pointers.  (Changed by Thomas
1174  Heller; :issue:`4606`.)  The underlying `libffi library
1175  <https://sourceware.org/libffi/>`__ has been updated to version
1176  3.0.9, containing various fixes for different platforms.  (Updated
1177  by Matthias Klose; :issue:`8142`.)
1178
1179* New method: the :mod:`datetime` module's :class:`~datetime.timedelta` class
1180  gained a :meth:`~datetime.timedelta.total_seconds` method that returns the
1181  number of seconds in the duration.  (Contributed by Brian Quinlan; :issue:`5788`.)
1182
1183* New method: the :class:`~decimal.Decimal` class gained a
1184  :meth:`~decimal.Decimal.from_float` class method that performs an exact
1185  conversion of a floating-point number to a :class:`~decimal.Decimal`.
1186  This exact conversion strives for the
1187  closest decimal approximation to the floating-point representation's value;
1188  the resulting decimal value will therefore still include the inaccuracy,
1189  if any.
1190  For example, ``Decimal.from_float(0.1)`` returns
1191  ``Decimal('0.1000000000000000055511151231257827021181583404541015625')``.
1192  (Implemented by Raymond Hettinger; :issue:`4796`.)
1193
1194  Comparing instances of :class:`~decimal.Decimal` with floating-point
1195  numbers now produces sensible results based on the numeric values
1196  of the operands.  Previously such comparisons would fall back to
1197  Python's default rules for comparing objects, which produced arbitrary
1198  results based on their type.  Note that you still cannot combine
1199  :class:`Decimal` and floating-point in other operations such as addition,
1200  since you should be explicitly choosing how to convert between float and
1201  :class:`~decimal.Decimal`.  (Fixed by Mark Dickinson; :issue:`2531`.)
1202
1203  The constructor for :class:`~decimal.Decimal` now accepts
1204  floating-point numbers (added by Raymond Hettinger; :issue:`8257`)
1205  and non-European Unicode characters such as Arabic-Indic digits
1206  (contributed by Mark Dickinson; :issue:`6595`).
1207
1208  Most of the methods of the :class:`~decimal.Context` class now accept integers
1209  as well as :class:`~decimal.Decimal` instances; the only exceptions are the
1210  :meth:`~decimal.Context.canonical` and :meth:`~decimal.Context.is_canonical`
1211  methods.  (Patch by Juan José Conti; :issue:`7633`.)
1212
1213  When using :class:`~decimal.Decimal` instances with a string's
1214  :meth:`~str.format` method, the default alignment was previously
1215  left-alignment.  This has been changed to right-alignment, which is
1216  more sensible for numeric types.  (Changed by Mark Dickinson; :issue:`6857`.)
1217
1218  Comparisons involving a signaling NaN value (or ``sNAN``) now signal
1219  :const:`InvalidOperation` instead of silently returning a true or
1220  false value depending on the comparison operator.  Quiet NaN values
1221  (or ``NaN``) are now hashable.  (Fixed by Mark Dickinson;
1222  :issue:`7279`.)
1223
1224* The :mod:`difflib` module now produces output that is more
1225  compatible with modern :command:`diff`/:command:`patch` tools
1226  through one small change, using a tab character instead of spaces as
1227  a separator in the header giving the filename.  (Fixed by Anatoly
1228  Techtonik; :issue:`7585`.)
1229
1230* The Distutils ``sdist`` command now always regenerates the
1231  :file:`MANIFEST` file, since even if the :file:`MANIFEST.in` or
1232  :file:`setup.py` files haven't been modified, the user might have
1233  created some new files that should be included.
1234  (Fixed by Tarek Ziadé; :issue:`8688`.)
1235
1236* The :mod:`doctest` module's :const:`IGNORE_EXCEPTION_DETAIL` flag
1237  will now ignore the name of the module containing the exception
1238  being tested.  (Patch by Lennart Regebro; :issue:`7490`.)
1239
1240* The :mod:`email` module's :class:`~email.message.Message` class will
1241  now accept a Unicode-valued payload, automatically converting the
1242  payload to the encoding specified by :attr:`output_charset`.
1243  (Added by R. David Murray; :issue:`1368247`.)
1244
1245* The :class:`~fractions.Fraction` class now accepts a single float or
1246  :class:`~decimal.Decimal` instance, or two rational numbers, as
1247  arguments to its constructor.  (Implemented by Mark Dickinson;
1248  rationals added in :issue:`5812`, and float/decimal in
1249  :issue:`8294`.)
1250
1251  Ordering comparisons (``<``, ``<=``, ``>``, ``>=``) between
1252  fractions and complex numbers now raise a :exc:`TypeError`.
1253  This fixes an oversight, making the :class:`~fractions.Fraction`
1254  match the other numeric types.
1255
1256  .. revision 79455
1257
1258* New class: :class:`~ftplib.FTP_TLS` in
1259  the :mod:`ftplib` module provides secure FTP
1260  connections using TLS encapsulation of authentication as well as
1261  subsequent control and data transfers.
1262  (Contributed by Giampaolo Rodola; :issue:`2054`.)
1263
1264  The :meth:`~ftplib.FTP.storbinary` method for binary uploads can now restart
1265  uploads thanks to an added *rest* parameter (patch by Pablo Mouzo;
1266  :issue:`6845`.)
1267
1268* New class decorator: :func:`~functools.total_ordering` in the :mod:`functools`
1269  module takes a class that defines an :meth:`__eq__` method and one of
1270  :meth:`__lt__`, :meth:`__le__`, :meth:`__gt__`, or :meth:`__ge__`,
1271  and generates the missing comparison methods.  Since the
1272  :meth:`__cmp__` method is being deprecated in Python 3.x,
1273  this decorator makes it easier to define ordered classes.
1274  (Added by Raymond Hettinger; :issue:`5479`.)
1275
1276  New function: :func:`~functools.cmp_to_key` will take an old-style comparison
1277  function that expects two arguments and return a new callable that
1278  can be used as the *key* parameter to functions such as
1279  :func:`sorted`, :func:`min` and :func:`max`, etc.  The primary
1280  intended use is to help with making code compatible with Python 3.x.
1281  (Added by Raymond Hettinger.)
1282
1283* New function: the :mod:`gc` module's :func:`~gc.is_tracked` returns
1284  true if a given instance is tracked by the garbage collector, false
1285  otherwise. (Contributed by Antoine Pitrou; :issue:`4688`.)
1286
1287* The :mod:`gzip` module's :class:`~gzip.GzipFile` now supports the context
1288  management protocol, so you can write ``with gzip.GzipFile(...) as f:``
1289  (contributed by Hagen Fürstenau; :issue:`3860`), and it now implements
1290  the :class:`io.BufferedIOBase` ABC, so you can wrap it with
1291  :class:`io.BufferedReader` for faster processing
1292  (contributed by Nir Aides; :issue:`7471`).
1293  It's also now possible to override the modification time
1294  recorded in a gzipped file by providing an optional timestamp to
1295  the constructor.  (Contributed by Jacques Frechet; :issue:`4272`.)
1296
1297  Files in gzip format can be padded with trailing zero bytes; the
1298  :mod:`gzip` module will now consume these trailing bytes.  (Fixed by
1299  Tadek Pietraszek and Brian Curtin; :issue:`2846`.)
1300
1301* New attribute: the :mod:`hashlib` module now has an :attr:`~hashlib.hashlib.algorithms`
1302  attribute containing a tuple naming the supported algorithms.
1303  In Python 2.7, ``hashlib.algorithms`` contains
1304  ``('md5', 'sha1', 'sha224', 'sha256', 'sha384', 'sha512')``.
1305  (Contributed by Carl Chenet; :issue:`7418`.)
1306
1307* The default :class:`~httplib.HTTPResponse` class used by the :mod:`httplib` module now
1308  supports buffering, resulting in much faster reading of HTTP responses.
1309  (Contributed by Kristján Valur Jónsson; :issue:`4879`.)
1310
1311  The :class:`~httplib.HTTPConnection` and :class:`~httplib.HTTPSConnection` classes
1312  now support a *source_address* parameter, a ``(host, port)`` 2-tuple
1313  giving the source address that will be used for the connection.
1314  (Contributed by Eldon Ziegler; :issue:`3972`.)
1315
1316* The :mod:`ihooks` module now supports relative imports.  Note that
1317  :mod:`ihooks` is an older module for customizing imports,
1318  superseded by the :mod:`imputil` module added in Python 2.0.
1319  (Relative import support added by Neil Schemenauer.)
1320
1321  .. revision 75423
1322
1323* The :mod:`imaplib` module now supports IPv6 addresses.
1324  (Contributed by Derek Morr; :issue:`1655`.)
1325
1326* New function: the :mod:`inspect` module's :func:`~inspect.getcallargs`
1327  takes a callable and its positional and keyword arguments,
1328  and figures out which of the callable's parameters will receive each argument,
1329  returning a dictionary mapping argument names to their values.  For example::
1330
1331    >>> from inspect import getcallargs
1332    >>> def f(a, b=1, *pos, **named):
1333    ...     pass
1334    >>> getcallargs(f, 1, 2, 3)
1335    {'a': 1, 'b': 2, 'pos': (3,), 'named': {}}
1336    >>> getcallargs(f, a=2, x=4)
1337    {'a': 2, 'b': 1, 'pos': (), 'named': {'x': 4}}
1338    >>> getcallargs(f)
1339    Traceback (most recent call last):
1340    ...
1341    TypeError: f() takes at least 1 argument (0 given)
1342
1343  Contributed by George Sakkis; :issue:`3135`.
1344
1345* Updated module: The :mod:`io` library has been upgraded to the version shipped with
1346  Python 3.1.  For 3.1, the I/O library was entirely rewritten in C
1347  and is 2 to 20 times faster depending on the task being performed.  The
1348  original Python version was renamed to the :mod:`_pyio` module.
1349
1350  One minor resulting change: the :class:`io.TextIOBase` class now
1351  has an :attr:`errors` attribute giving the error setting
1352  used for encoding and decoding errors (one of ``'strict'``, ``'replace'``,
1353  ``'ignore'``).
1354
1355  The :class:`io.FileIO` class now raises an :exc:`OSError` when passed
1356  an invalid file descriptor.  (Implemented by Benjamin Peterson;
1357  :issue:`4991`.)  The :meth:`~io.IOBase.truncate` method now preserves the
1358  file position; previously it would change the file position to the
1359  end of the new file.  (Fixed by Pascal Chambon; :issue:`6939`.)
1360
1361* New function: ``itertools.compress(data, selectors)`` takes two
1362  iterators.  Elements of *data* are returned if the corresponding
1363  value in *selectors* is true::
1364
1365    itertools.compress('ABCDEF', [1,0,1,0,1,1]) =>
1366      A, C, E, F
1367
1368  .. maybe here is better to use >>> list(itertools.compress(...)) instead
1369
1370  New function: ``itertools.combinations_with_replacement(iter, r)``
1371  returns all the possible *r*-length combinations of elements from the
1372  iterable *iter*.  Unlike :func:`~itertools.combinations`, individual elements
1373  can be repeated in the generated combinations::
1374
1375    itertools.combinations_with_replacement('abc', 2) =>
1376      ('a', 'a'), ('a', 'b'), ('a', 'c'),
1377      ('b', 'b'), ('b', 'c'), ('c', 'c')
1378
1379  Note that elements are treated as unique depending on their position
1380  in the input, not their actual values.
1381
1382  The :func:`itertools.count` function now has a *step* argument that
1383  allows incrementing by values other than 1.  :func:`~itertools.count` also
1384  now allows keyword arguments, and using non-integer values such as
1385  floats or :class:`~decimal.Decimal` instances.  (Implemented by Raymond
1386  Hettinger; :issue:`5032`.)
1387
1388  :func:`itertools.combinations` and :func:`itertools.product`
1389  previously raised :exc:`ValueError` for values of *r* larger than
1390  the input iterable.  This was deemed a specification error, so they
1391  now return an empty iterator.  (Fixed by Raymond Hettinger; :issue:`4816`.)
1392
1393* Updated module: The :mod:`json` module was upgraded to version 2.0.9 of the
1394  simplejson package, which includes a C extension that makes
1395  encoding and decoding faster.
1396  (Contributed by Bob Ippolito; :issue:`4136`.)
1397
1398  To support the new :class:`collections.OrderedDict` type, :func:`json.load`
1399  now has an optional *object_pairs_hook* parameter that will be called
1400  with any object literal that decodes to a list of pairs.
1401  (Contributed by Raymond Hettinger; :issue:`5381`.)
1402
1403* The :mod:`mailbox` module's :class:`~mailbox.Maildir` class now records the
1404  timestamp on the directories it reads, and only re-reads them if the
1405  modification time has subsequently changed.  This improves
1406  performance by avoiding unneeded directory scans.  (Fixed by
1407  A.M. Kuchling and Antoine Pitrou; :issue:`1607951`, :issue:`6896`.)
1408
1409* New functions: the :mod:`math` module gained
1410  :func:`~math.erf` and :func:`~math.erfc` for the error function and the complementary error function,
1411  :func:`~math.expm1` which computes ``e**x - 1`` with more precision than
1412  using :func:`~math.exp` and subtracting 1,
1413  :func:`~math.gamma` for the Gamma function, and
1414  :func:`~math.lgamma` for the natural log of the Gamma function.
1415  (Contributed by Mark Dickinson and nirinA raseliarison; :issue:`3366`.)
1416
1417* The :mod:`multiprocessing` module's :class:`Manager*` classes
1418  can now be passed a callable that will be called whenever
1419  a subprocess is started, along with a set of arguments that will be
1420  passed to the callable.
1421  (Contributed by lekma; :issue:`5585`.)
1422
1423  The :class:`~multiprocessing.Pool` class, which controls a pool of worker processes,
1424  now has an optional *maxtasksperchild* parameter.  Worker processes
1425  will perform the specified number of tasks and then exit, causing the
1426  :class:`~multiprocessing.Pool` to start a new worker.  This is useful if tasks may leak
1427  memory or other resources, or if some tasks will cause the worker to
1428  become very large.
1429  (Contributed by Charles Cazabon; :issue:`6963`.)
1430
1431* The :mod:`nntplib` module now supports IPv6 addresses.
1432  (Contributed by Derek Morr; :issue:`1664`.)
1433
1434* New functions: the :mod:`os` module wraps the following POSIX system
1435  calls: :func:`~os.getresgid` and :func:`~os.getresuid`, which return the
1436  real, effective, and saved GIDs and UIDs;
1437  :func:`~os.setresgid` and :func:`~os.setresuid`, which set
1438  real, effective, and saved GIDs and UIDs to new values;
1439  :func:`~os.initgroups`, which initialize the group access list
1440  for the current process.  (GID/UID functions
1441  contributed by Travis H.; :issue:`6508`.  Support for initgroups added
1442  by Jean-Paul Calderone; :issue:`7333`.)
1443
1444  The :func:`os.fork` function now re-initializes the import lock in
1445  the child process; this fixes problems on Solaris when :func:`~os.fork`
1446  is called from a thread.  (Fixed by Zsolt Cserna; :issue:`7242`.)
1447
1448* In the :mod:`os.path` module, the :func:`~os.path.normpath` and
1449  :func:`~os.path.abspath` functions now preserve Unicode; if their input path
1450  is a Unicode string, the return value is also a Unicode string.
1451  (:meth:`~os.path.normpath` fixed by Matt Giuca in :issue:`5827`;
1452  :meth:`~os.path.abspath` fixed by Ezio Melotti in :issue:`3426`.)
1453
1454* The :mod:`pydoc` module now has help for the various symbols that Python
1455  uses.  You can now do ``help('<<')`` or ``help('@')``, for example.
1456  (Contributed by David Laban; :issue:`4739`.)
1457
1458* The :mod:`re` module's :func:`~re.split`, :func:`~re.sub`, and :func:`~re.subn`
1459  now accept an optional *flags* argument, for consistency with the
1460  other functions in the module.  (Added by Gregory P. Smith.)
1461
1462* New function: :func:`~runpy.run_path` in the :mod:`runpy` module
1463  will execute the code at a provided *path* argument.  *path* can be
1464  the path of a Python source file (:file:`example.py`), a compiled
1465  bytecode file (:file:`example.pyc`), a directory
1466  (:file:`./package/`), or a zip archive (:file:`example.zip`).  If a
1467  directory or zip path is provided, it will be added to the front of
1468  ``sys.path`` and the module :mod:`__main__` will be imported.  It's
1469  expected that the directory or zip contains a :file:`__main__.py`;
1470  if it doesn't, some other :file:`__main__.py` might be imported from
1471  a location later in ``sys.path``.  This makes more of the machinery
1472  of :mod:`runpy` available to scripts that want to mimic the way
1473  Python's command line processes an explicit path name.
1474  (Added by Nick Coghlan; :issue:`6816`.)
1475
1476* New function: in the :mod:`shutil` module, :func:`~shutil.make_archive`
1477  takes a filename, archive type (zip or tar-format), and a directory
1478  path, and creates an archive containing the directory's contents.
1479  (Added by Tarek Ziadé.)
1480
1481  :mod:`shutil`'s :func:`~shutil.copyfile` and :func:`~shutil.copytree`
1482  functions now raise a :exc:`~shutil.SpecialFileError` exception when
1483  asked to copy a named pipe.  Previously the code would treat
1484  named pipes like a regular file by opening them for reading, and
1485  this would block indefinitely.  (Fixed by Antoine Pitrou; :issue:`3002`.)
1486
1487* The :mod:`signal` module no longer re-installs the signal handler
1488  unless this is truly necessary, which fixes a bug that could make it
1489  impossible to catch the EINTR signal robustly.  (Fixed by
1490  Charles-Francois Natali; :issue:`8354`.)
1491
1492* New functions: in the :mod:`site` module, three new functions
1493  return various site- and user-specific paths.
1494  :func:`~site.getsitepackages` returns a list containing all
1495  global site-packages directories,
1496  :func:`~site.getusersitepackages` returns the path of the user's
1497  site-packages directory, and
1498  :func:`~site.getuserbase` returns the value of the :envvar:`USER_BASE`
1499  environment variable, giving the path to a directory that can be used
1500  to store data.
1501  (Contributed by Tarek Ziadé; :issue:`6693`.)
1502
1503  The :mod:`site` module now reports exceptions occurring
1504  when the :mod:`sitecustomize` module is imported, and will no longer
1505  catch and swallow the :exc:`KeyboardInterrupt` exception.  (Fixed by
1506  Victor Stinner; :issue:`3137`.)
1507
1508* The :func:`~socket.create_connection` function
1509  gained a *source_address* parameter, a ``(host, port)`` 2-tuple
1510  giving the source address that will be used for the connection.
1511  (Contributed by Eldon Ziegler; :issue:`3972`.)
1512
1513  The :meth:`~socket.socket.recv_into` and :meth:`~socket.socket.recvfrom_into`
1514  methods will now write into objects that support the buffer API, most usefully
1515  the :class:`bytearray` and :class:`memoryview` objects.  (Implemented by
1516  Antoine Pitrou; :issue:`8104`.)
1517
1518* The :mod:`SocketServer` module's :class:`~SocketServer.TCPServer` class now
1519  supports socket timeouts and disabling the Nagle algorithm.
1520  The :attr:`~SocketServer.TCPServer.disable_nagle_algorithm` class attribute
1521  defaults to ``False``; if overridden to be true,
1522  new request connections will have the TCP_NODELAY option set to
1523  prevent buffering many small sends into a single TCP packet.
1524  The :attr:`~SocketServer.BaseServer.timeout` class attribute can hold
1525  a timeout in seconds that will be applied to the request socket; if
1526  no request is received within that time, :meth:`~SocketServer.BaseServer.handle_timeout`
1527  will be called and :meth:`~SocketServer.BaseServer.handle_request` will return.
1528  (Contributed by Kristján Valur Jónsson; :issue:`6192` and :issue:`6267`.)
1529
1530* Updated module: the :mod:`sqlite3` module has been updated to
1531  version 2.6.0 of the `pysqlite package <https://github.com/ghaering/pysqlite>`__. Version 2.6.0 includes a number of bugfixes, and adds
1532  the ability to load SQLite extensions from shared libraries.
1533  Call the ``enable_load_extension(True)`` method to enable extensions,
1534  and then call :meth:`~sqlite3.Connection.load_extension` to load a particular shared library.
1535  (Updated by Gerhard Häring.)
1536
1537* The :mod:`ssl` module's :class:`~ssl.SSLSocket` objects now support the
1538  buffer API, which fixed a test suite failure (fix by Antoine Pitrou;
1539  :issue:`7133`) and automatically set
1540  OpenSSL's :c:macro:`SSL_MODE_AUTO_RETRY`, which will prevent an error
1541  code being returned from :meth:`recv` operations that trigger an SSL
1542  renegotiation (fix by Antoine Pitrou; :issue:`8222`).
1543
1544  The :func:`ssl.wrap_socket` constructor function now takes a
1545  *ciphers* argument that's a string listing the encryption algorithms
1546  to be allowed; the format of the string is described
1547  `in the OpenSSL documentation
1548  <https://www.openssl.org/docs/manmaster/man1/ciphers.html#CIPHER-LIST-FORMAT>`__.
1549  (Added by Antoine Pitrou; :issue:`8322`.)
1550
1551  Another change makes the extension load all of OpenSSL's ciphers and
1552  digest algorithms so that they're all available.  Some SSL
1553  certificates couldn't be verified, reporting an "unknown algorithm"
1554  error.  (Reported by Beda Kosata, and fixed by Antoine Pitrou;
1555  :issue:`8484`.)
1556
1557  The version of OpenSSL being used is now available as the module
1558  attributes :data:`ssl.OPENSSL_VERSION` (a string),
1559  :data:`ssl.OPENSSL_VERSION_INFO` (a 5-tuple), and
1560  :data:`ssl.OPENSSL_VERSION_NUMBER` (an integer).  (Added by Antoine
1561  Pitrou; :issue:`8321`.)
1562
1563* The :mod:`struct` module will no longer silently ignore overflow
1564  errors when a value is too large for a particular integer format
1565  code (one of ``bBhHiIlLqQ``); it now always raises a
1566  :exc:`struct.error` exception.  (Changed by Mark Dickinson;
1567  :issue:`1523`.)  The :func:`~struct.pack` function will also
1568  attempt to use :meth:`__index__` to convert and pack non-integers
1569  before trying the :meth:`__int__` method or reporting an error.
1570  (Changed by Mark Dickinson; :issue:`8300`.)
1571
1572* New function: the :mod:`subprocess` module's
1573  :func:`~subprocess.check_output` runs a command with a specified set of arguments
1574  and returns the command's output as a string when the command runs without
1575  error, or raises a :exc:`~subprocess.CalledProcessError` exception otherwise.
1576
1577  ::
1578
1579    >>> subprocess.check_output(['df', '-h', '.'])
1580    'Filesystem     Size   Used  Avail Capacity  Mounted on\n
1581    /dev/disk0s2    52G    49G   3.0G    94%    /\n'
1582
1583    >>> subprocess.check_output(['df', '-h', '/bogus'])
1584      ...
1585    subprocess.CalledProcessError: Command '['df', '-h', '/bogus']' returned non-zero exit status 1
1586
1587  (Contributed by Gregory P. Smith.)
1588
1589  The :mod:`subprocess` module will now retry its internal system calls
1590  on receiving an :const:`EINTR` signal.  (Reported by several people; final
1591  patch by Gregory P. Smith in :issue:`1068268`.)
1592
1593* New function: :func:`~symtable.Symbol.is_declared_global` in the :mod:`symtable` module
1594  returns true for variables that are explicitly declared to be global,
1595  false for ones that are implicitly global.
1596  (Contributed by Jeremy Hylton.)
1597
1598* The :mod:`syslog` module will now use the value of ``sys.argv[0]`` as the
1599  identifier instead of the previous default value of ``'python'``.
1600  (Changed by Sean Reifschneider; :issue:`8451`.)
1601
1602* The ``sys.version_info`` value is now a named tuple, with attributes
1603  named :attr:`major`, :attr:`minor`, :attr:`micro`,
1604  :attr:`releaselevel`, and :attr:`serial`.  (Contributed by Ross
1605  Light; :issue:`4285`.)
1606
1607  :func:`sys.getwindowsversion` also returns a named tuple,
1608  with attributes named :attr:`major`, :attr:`minor`, :attr:`build`,
1609  :attr:`platform`, :attr:`service_pack`, :attr:`service_pack_major`,
1610  :attr:`service_pack_minor`, :attr:`suite_mask`, and
1611  :attr:`product_type`.  (Contributed by Brian Curtin; :issue:`7766`.)
1612
1613* The :mod:`tarfile` module's default error handling has changed, to
1614  no longer suppress fatal errors.  The default error level was previously 0,
1615  which meant that errors would only result in a message being written to the
1616  debug log, but because the debug log is not activated by default,
1617  these errors go unnoticed.  The default error level is now 1,
1618  which raises an exception if there's an error.
1619  (Changed by Lars Gustäbel; :issue:`7357`.)
1620
1621  :mod:`tarfile` now supports filtering the :class:`~tarfile.TarInfo`
1622  objects being added to a tar file.  When you call :meth:`~tarfile.TarFile.add`,
1623  you may supply an optional *filter* argument
1624  that's a callable.  The *filter* callable will be passed the
1625  :class:`~tarfile.TarInfo` for every file being added, and can modify and return it.
1626  If the callable returns ``None``, the file will be excluded from the
1627  resulting archive.  This is more powerful than the existing
1628  *exclude* argument, which has therefore been deprecated.
1629  (Added by Lars Gustäbel; :issue:`6856`.)
1630  The :class:`~tarfile.TarFile` class also now supports the context management protocol.
1631  (Added by Lars Gustäbel; :issue:`7232`.)
1632
1633* The :meth:`~threading.Event.wait` method of the :class:`threading.Event` class
1634  now returns the internal flag on exit.  This means the method will usually
1635  return true because :meth:`~threading.Event.wait` is supposed to block until the
1636  internal flag becomes true.  The return value will only be false if
1637  a timeout was provided and the operation timed out.
1638  (Contributed by Tim Lesher; :issue:`1674032`.)
1639
1640* The Unicode database provided by the :mod:`unicodedata` module is
1641  now used internally to determine which characters are numeric,
1642  whitespace, or represent line breaks.  The database also
1643  includes information from the :file:`Unihan.txt` data file (patch
1644  by Anders Chrigström and Amaury Forgeot d'Arc; :issue:`1571184`)
1645  and has been updated to version 5.2.0 (updated by
1646  Florent Xicluna; :issue:`8024`).
1647
1648* The :mod:`urlparse` module's :func:`~urlparse.urlsplit` now handles
1649  unknown URL schemes in a fashion compliant with :rfc:`3986`: if the
1650  URL is of the form ``"<something>://..."``, the text before the
1651  ``://`` is treated as the scheme, even if it's a made-up scheme that
1652  the module doesn't know about.  This change may break code that
1653  worked around the old behaviour.  For example, Python 2.6.4 or 2.5
1654  will return the following:
1655
1656  .. doctest::
1657    :options: +SKIP
1658
1659    >>> import urlparse
1660    >>> urlparse.urlsplit('invented://host/filename?query')
1661    ('invented', '', '//host/filename?query', '', '')
1662
1663  Python 2.7 (and Python 2.6.5) will return:
1664
1665  .. doctest::
1666    :options: +SKIP
1667
1668    >>> import urlparse
1669    >>> urlparse.urlsplit('invented://host/filename?query')
1670    ('invented', 'host', '/filename?query', '', '')
1671
1672  (Python 2.7 actually produces slightly different output, since it
1673  returns a named tuple instead of a standard tuple.)
1674
1675  The :mod:`urlparse` module also supports IPv6 literal addresses as defined by
1676  :rfc:`2732` (contributed by Senthil Kumaran; :issue:`2987`).
1677
1678  .. doctest::
1679    :options: +SKIP
1680
1681    >>> urlparse.urlparse('http://[1080::8:800:200C:417A]/foo')
1682    ParseResult(scheme='http', netloc='[1080::8:800:200C:417A]',
1683                path='/foo', params='', query='', fragment='')
1684
1685* New class: the :class:`~weakref.WeakSet` class in the :mod:`weakref`
1686  module is a set that only holds weak references to its elements; elements
1687  will be removed once there are no references pointing to them.
1688  (Originally implemented in Python 3.x by Raymond Hettinger, and backported
1689  to 2.7 by Michael Foord.)
1690
1691* The ElementTree library, :mod:`xml.etree`, no longer escapes
1692  ampersands and angle brackets when outputting an XML processing
1693  instruction (which looks like ``<?xml-stylesheet href="#style1"?>``)
1694  or comment (which looks like ``<!-- comment -->``).
1695  (Patch by Neil Muller; :issue:`2746`.)
1696
1697* The XML-RPC client and server, provided by the :mod:`xmlrpclib` and
1698  :mod:`SimpleXMLRPCServer` modules, have improved performance by
1699  supporting HTTP/1.1 keep-alive and by optionally using gzip encoding
1700  to compress the XML being exchanged.  The gzip compression is
1701  controlled by the :attr:`encode_threshold` attribute of
1702  :class:`SimpleXMLRPCRequestHandler`, which contains a size in bytes;
1703  responses larger than this will be compressed.
1704  (Contributed by Kristján Valur Jónsson; :issue:`6267`.)
1705
1706* The :mod:`zipfile` module's :class:`~zipfile.ZipFile` now supports the context
1707  management protocol, so you can write ``with zipfile.ZipFile(...) as f:``.
1708  (Contributed by Brian Curtin; :issue:`5511`.)
1709
1710  :mod:`zipfile` now also supports archiving empty directories and
1711  extracts them correctly.  (Fixed by Kuba Wieczorek; :issue:`4710`.)
1712  Reading files out of an archive is faster, and interleaving
1713  :meth:`~zipfile.ZipFile.read` and :meth:`~zipfile.ZipFile.readline` now works correctly.
1714  (Contributed by Nir Aides; :issue:`7610`.)
1715
1716  The :func:`~zipfile.is_zipfile` function now
1717  accepts a file object, in addition to the path names accepted in earlier
1718  versions.  (Contributed by Gabriel Genellina; :issue:`4756`.)
1719
1720  The :meth:`~zipfile.ZipFile.writestr` method now has an optional *compress_type* parameter
1721  that lets you override the default compression method specified in the
1722  :class:`~zipfile.ZipFile` constructor.  (Contributed by Ronald Oussoren;
1723  :issue:`6003`.)
1724
1725
1726.. ======================================================================
1727.. whole new modules get described in subsections here
1728
1729
1730.. _importlib-section:
1731
1732New module: importlib
1733------------------------------
1734
1735Python 3.1 includes the :mod:`importlib` package, a re-implementation
1736of the logic underlying Python's :keyword:`import` statement.
1737:mod:`importlib` is useful for implementors of Python interpreters and
1738to users who wish to write new importers that can participate in the
1739import process.  Python 2.7 doesn't contain the complete
1740:mod:`importlib` package, but instead has a tiny subset that contains
1741a single function, :func:`~importlib.import_module`.
1742
1743``import_module(name, package=None)`` imports a module.  *name* is
1744a string containing the module or package's name.  It's possible to do
1745relative imports by providing a string that begins with a ``.``
1746character, such as ``..utils.errors``.  For relative imports, the
1747*package* argument must be provided and is the name of the package that
1748will be used as the anchor for
1749the relative import.  :func:`~importlib.import_module` both inserts the imported
1750module into ``sys.modules`` and returns the module object.
1751
1752Here are some examples::
1753
1754    >>> from importlib import import_module
1755    >>> anydbm = import_module('anydbm')  # Standard absolute import
1756    >>> anydbm
1757    <module 'anydbm' from '/p/python/Lib/anydbm.py'>
1758    >>> # Relative import
1759    >>> file_util = import_module('..file_util', 'distutils.command')
1760    >>> file_util
1761    <module 'distutils.file_util' from '/python/Lib/distutils/file_util.pyc'>
1762
1763:mod:`importlib` was implemented by Brett Cannon and introduced in
1764Python 3.1.
1765
1766
1767New module: sysconfig
1768---------------------------------
1769
1770The :mod:`sysconfig` module has been pulled out of the Distutils
1771package, becoming a new top-level module in its own right.
1772:mod:`sysconfig` provides functions for getting information about
1773Python's build process: compiler switches, installation paths, the
1774platform name, and whether Python is running from its source
1775directory.
1776
1777Some of the functions in the module are:
1778
1779* :func:`~sysconfig.get_config_var` returns variables from Python's
1780  Makefile and the :file:`pyconfig.h` file.
1781* :func:`~sysconfig.get_config_vars` returns a dictionary containing
1782  all of the configuration variables.
1783* :func:`~sysconfig.get_path` returns the configured path for
1784  a particular type of module: the standard library,
1785  site-specific modules, platform-specific modules, etc.
1786* :func:`~sysconfig.is_python_build` returns true if you're running a
1787  binary from a Python source tree, and false otherwise.
1788
1789Consult the :mod:`sysconfig` documentation for more details and for
1790a complete list of functions.
1791
1792The Distutils package and :mod:`sysconfig` are now maintained by Tarek
1793Ziadé, who has also started a Distutils2 package (source repository at
1794https://hg.python.org/distutils2/) for developing a next-generation
1795version of Distutils.
1796
1797
1798ttk: Themed Widgets for Tk
1799--------------------------
1800
1801Tcl/Tk 8.5 includes a set of themed widgets that re-implement basic Tk
1802widgets but have a more customizable appearance and can therefore more
1803closely resemble the native platform's widgets.  This widget
1804set was originally called Tile, but was renamed to Ttk (for "themed Tk")
1805on being added to Tcl/Tck release 8.5.
1806
1807To learn more, read the :mod:`ttk` module documentation.  You may also
1808wish to read the Tcl/Tk manual page describing the
1809Ttk theme engine, available at
1810https://www.tcl.tk/man/tcl8.5/TkCmd/ttk_intro.htm. Some
1811screenshots of the Python/Ttk code in use are at
1812https://code.google.com/archive/p/python-ttk/wikis/Screenshots.wiki.
1813
1814The :mod:`ttk` module was written by Guilherme Polo and added in
1815:issue:`2983`.  An alternate version called ``Tile.py``, written by
1816Martin Franklin and maintained by Kevin Walzer, was proposed for
1817inclusion in :issue:`2618`, but the authors argued that Guilherme
1818Polo's work was more comprehensive.
1819
1820
1821.. _unittest-section:
1822
1823Updated module: unittest
1824---------------------------------
1825
1826The :mod:`unittest` module was greatly enhanced; many
1827new features were added.  Most of these features were implemented
1828by Michael Foord, unless otherwise noted.  The enhanced version of
1829the module is downloadable separately for use with Python versions 2.4 to 2.6,
1830packaged as the :mod:`unittest2` package, from
1831https://pypi.org/project/unittest2.
1832
1833When used from the command line, the module can automatically discover
1834tests.  It's not as fancy as `py.test <http://pytest.org>`__ or
1835`nose <https://nose.readthedocs.io/>`__, but provides a
1836simple way to run tests kept within a set of package directories.  For example,
1837the following command will search the :file:`test/` subdirectory for
1838any importable test files named ``test*.py``::
1839
1840   python -m unittest discover -s test
1841
1842Consult the :mod:`unittest` module documentation for more details.
1843(Developed in :issue:`6001`.)
1844
1845The :func:`~unittest.main` function supports some other new options:
1846
1847* :option:`-b <unittest -b>` or :option:`!--buffer` will buffer the standard output
1848  and standard error streams during each test.  If the test passes,
1849  any resulting output will be discarded; on failure, the buffered
1850  output will be displayed.
1851
1852* :option:`-c <unittest -c>` or :option:`!--catch` will cause the control-C interrupt
1853  to be handled more gracefully.  Instead of interrupting the test
1854  process immediately, the currently running test will be completed
1855  and then the partial results up to the interruption will be reported.
1856  If you're impatient, a second press of control-C will cause an immediate
1857  interruption.
1858
1859  This control-C handler tries to avoid causing problems when the code
1860  being tested or the tests being run have defined a signal handler of
1861  their own, by noticing that a signal handler was already set and
1862  calling it.  If this doesn't work for you, there's a
1863  :func:`~unittest.removeHandler` decorator that can be used to mark tests that
1864  should have the control-C handling disabled.
1865
1866* :option:`-f <unittest -f>` or :option:`!--failfast` makes
1867  test execution stop immediately when a test fails instead of
1868  continuing to execute further tests.  (Suggested by Cliff Dyer and
1869  implemented by Michael Foord; :issue:`8074`.)
1870
1871The progress messages now show 'x' for expected failures
1872and 'u' for unexpected successes when run in verbose mode.
1873(Contributed by Benjamin Peterson.)
1874
1875Test cases can raise the :exc:`~unittest.SkipTest` exception to skip a
1876test (:issue:`1034053`).
1877
1878The error messages for :meth:`~unittest.TestCase.assertEqual`,
1879:meth:`~unittest.TestCase.assertTrue`, and :meth:`~unittest.TestCase.assertFalse`
1880failures now provide more information.  If you set the
1881:attr:`~unittest.TestCase.longMessage` attribute of your :class:`~unittest.TestCase` classes to
1882true, both the standard error message and any additional message you
1883provide will be printed for failures.  (Added by Michael Foord; :issue:`5663`.)
1884
1885The :meth:`~unittest.TestCase.assertRaises` method now
1886returns a context handler when called without providing a callable
1887object to run.  For example, you can write this::
1888
1889  with self.assertRaises(KeyError):
1890      {}['foo']
1891
1892(Implemented by Antoine Pitrou; :issue:`4444`.)
1893
1894.. rev 78774
1895
1896Module- and class-level setup and teardown fixtures are now supported.
1897Modules can contain :func:`~unittest.setUpModule` and :func:`~unittest.tearDownModule`
1898functions.  Classes can have :meth:`~unittest.TestCase.setUpClass` and
1899:meth:`~unittest.TestCase.tearDownClass` methods that must be defined as class methods
1900(using ``@classmethod`` or equivalent).  These functions and
1901methods are invoked when the test runner switches to a test case in a
1902different module or class.
1903
1904The methods :meth:`~unittest.TestCase.addCleanup` and
1905:meth:`~unittest.TestCase.doCleanups` were added.
1906:meth:`~unittest.TestCase.addCleanup` lets you add cleanup functions that
1907will be called unconditionally (after :meth:`~unittest.TestCase.setUp` if
1908:meth:`~unittest.TestCase.setUp` fails, otherwise after :meth:`~unittest.TestCase.tearDown`). This allows
1909for much simpler resource allocation and deallocation during tests
1910(:issue:`5679`).
1911
1912A number of new methods were added that provide more specialized
1913tests.  Many of these methods were written by Google engineers
1914for use in their test suites; Gregory P. Smith, Michael Foord, and
1915GvR worked on merging them into Python's version of :mod:`unittest`.
1916
1917* :meth:`~unittest.TestCase.assertIsNone` and :meth:`~unittest.TestCase.assertIsNotNone` take one
1918  expression and verify that the result is or is not ``None``.
1919
1920* :meth:`~unittest.TestCase.assertIs` and :meth:`~unittest.TestCase.assertIsNot`
1921  take two values and check whether the two values evaluate to the same object or not.
1922  (Added by Michael Foord; :issue:`2578`.)
1923
1924* :meth:`~unittest.TestCase.assertIsInstance` and
1925  :meth:`~unittest.TestCase.assertNotIsInstance` check whether
1926  the resulting object is an instance of a particular class, or of
1927  one of a tuple of classes.  (Added by Georg Brandl; :issue:`7031`.)
1928
1929* :meth:`~unittest.TestCase.assertGreater`, :meth:`~unittest.TestCase.assertGreaterEqual`,
1930  :meth:`~unittest.TestCase.assertLess`, and :meth:`~unittest.TestCase.assertLessEqual` compare
1931  two quantities.
1932
1933* :meth:`~unittest.TestCase.assertMultiLineEqual` compares two strings, and if they're
1934  not equal, displays a helpful comparison that highlights the
1935  differences in the two strings.  This comparison is now used by
1936  default when Unicode strings are compared with :meth:`~unittest.TestCase.assertEqual`.
1937
1938* :meth:`~unittest.TestCase.assertRegexpMatches` and
1939  :meth:`~unittest.TestCase.assertNotRegexpMatches` checks whether the
1940  first argument is a string matching or not matching the regular
1941  expression provided as the second argument (:issue:`8038`).
1942
1943* :meth:`~unittest.TestCase.assertRaisesRegexp` checks whether a particular exception
1944  is raised, and then also checks that the string representation of
1945  the exception matches the provided regular expression.
1946
1947* :meth:`~unittest.TestCase.assertIn` and :meth:`~unittest.TestCase.assertNotIn`
1948  tests whether *first* is or is not in  *second*.
1949
1950* :meth:`~unittest.TestCase.assertItemsEqual` tests whether two provided sequences
1951  contain the same elements.
1952
1953* :meth:`~unittest.TestCase.assertSetEqual` compares whether two sets are equal, and
1954  only reports the differences between the sets in case of error.
1955
1956* Similarly, :meth:`~unittest.TestCase.assertListEqual` and :meth:`~unittest.TestCase.assertTupleEqual`
1957  compare the specified types and explain any differences without necessarily
1958  printing their full values; these methods are now used by default
1959  when comparing lists and tuples using :meth:`~unittest.TestCase.assertEqual`.
1960  More generally, :meth:`~unittest.TestCase.assertSequenceEqual` compares two sequences
1961  and can optionally check whether both sequences are of a
1962  particular type.
1963
1964* :meth:`~unittest.TestCase.assertDictEqual` compares two dictionaries and reports the
1965  differences; it's now used by default when you compare two dictionaries
1966  using :meth:`~unittest.TestCase.assertEqual`.  :meth:`~unittest.TestCase.assertDictContainsSubset` checks whether
1967  all of the key/value pairs in *first* are found in *second*.
1968
1969* :meth:`~unittest.TestCase.assertAlmostEqual` and :meth:`~unittest.TestCase.assertNotAlmostEqual` test
1970  whether *first* and *second* are approximately equal.  This method
1971  can either round their difference to an optionally-specified number
1972  of *places* (the default is 7) and compare it to zero, or require
1973  the difference to be smaller than a supplied *delta* value.
1974
1975* :meth:`~unittest.TestLoader.loadTestsFromName` properly honors the
1976  :attr:`~unittest.TestLoader.suiteClass` attribute of
1977  the :class:`~unittest.TestLoader`. (Fixed by Mark Roddy; :issue:`6866`.)
1978
1979* A new hook lets you extend the :meth:`~unittest.TestCase.assertEqual` method to handle
1980  new data types.  The :meth:`~unittest.TestCase.addTypeEqualityFunc` method takes a type
1981  object and a function. The function will be used when both of the
1982  objects being compared are of the specified type.  This function
1983  should compare the two objects and raise an exception if they don't
1984  match; it's a good idea for the function to provide additional
1985  information about why the two objects aren't matching, much as the new
1986  sequence comparison methods do.
1987
1988:func:`unittest.main` now takes an optional ``exit`` argument.  If
1989false, :func:`~unittest.main` doesn't call :func:`sys.exit`, allowing
1990:func:`~unittest.main` to be used from the interactive interpreter.
1991(Contributed by J. Pablo Fernández; :issue:`3379`.)
1992
1993:class:`~unittest.TestResult` has new :meth:`~unittest.TestResult.startTestRun` and
1994:meth:`~unittest.TestResult.stopTestRun` methods that are called immediately before
1995and after a test run.  (Contributed by Robert Collins; :issue:`5728`.)
1996
1997With all these changes, the :file:`unittest.py` was becoming awkwardly
1998large, so the module was turned into a package and the code split into
1999several files (by Benjamin Peterson).  This doesn't affect how the
2000module is imported or used.
2001
2002.. seealso::
2003
2004  http://www.voidspace.org.uk/python/articles/unittest2.shtml
2005    Describes the new features, how to use them, and the
2006    rationale for various design decisions.  (By Michael Foord.)
2007
2008.. _elementtree-section:
2009
2010Updated module: ElementTree 1.3
2011---------------------------------
2012
2013The version of the ElementTree library included with Python was updated to
2014version 1.3.  Some of the new features are:
2015
2016* The various parsing functions now take a *parser* keyword argument
2017  giving an :class:`~xml.etree.ElementTree.XMLParser` instance that will
2018  be used.  This makes it possible to override the file's internal encoding::
2019
2020    p = ET.XMLParser(encoding='utf-8')
2021    t = ET.XML("""<root/>""", parser=p)
2022
2023  Errors in parsing XML now raise a :exc:`ParseError` exception, whose
2024  instances have a :attr:`position` attribute
2025  containing a (*line*, *column*) tuple giving the location of the problem.
2026
2027* ElementTree's code for converting trees to a string has been
2028  significantly reworked, making it roughly twice as fast in many
2029  cases.  The :meth:`ElementTree.write() <xml.etree.ElementTree.ElementTree.write>`
2030  and :meth:`Element.write` methods now have a *method* parameter that can be
2031  "xml" (the default), "html", or "text".  HTML mode will output empty
2032  elements as ``<empty></empty>`` instead of ``<empty/>``, and text
2033  mode will skip over elements and only output the text chunks.  If
2034  you set the :attr:`tag` attribute of an element to ``None`` but
2035  leave its children in place, the element will be omitted when the
2036  tree is written out, so you don't need to do more extensive rearrangement
2037  to remove a single element.
2038
2039  Namespace handling has also been improved.  All ``xmlns:<whatever>``
2040  declarations are now output on the root element, not scattered throughout
2041  the resulting XML.  You can set the default namespace for a tree
2042  by setting the :attr:`default_namespace` attribute and can
2043  register new prefixes with :meth:`~xml.etree.ElementTree.register_namespace`.  In XML mode,
2044  you can use the true/false *xml_declaration* parameter to suppress the
2045  XML declaration.
2046
2047* New :class:`~xml.etree.ElementTree.Element` method:
2048  :meth:`~xml.etree.ElementTree.Element.extend` appends the items from a
2049  sequence to the element's children.  Elements themselves behave like
2050  sequences, so it's easy to move children from one element to
2051  another::
2052
2053    from xml.etree import ElementTree as ET
2054
2055    t = ET.XML("""<list>
2056      <item>1</item> <item>2</item>  <item>3</item>
2057    </list>""")
2058    new = ET.XML('<root/>')
2059    new.extend(t)
2060
2061    # Outputs <root><item>1</item>...</root>
2062    print ET.tostring(new)
2063
2064* New :class:`Element` method:
2065  :meth:`~xml.etree.ElementTree.Element.iter` yields the children of the
2066  element as a generator.  It's also possible to write ``for child in
2067  elem:`` to loop over an element's children.  The existing method
2068  :meth:`getiterator` is now deprecated, as is :meth:`getchildren`
2069  which constructs and returns a list of children.
2070
2071* New :class:`Element` method:
2072  :meth:`~xml.etree.ElementTree.Element.itertext` yields all chunks of
2073  text that are descendants of the element.  For example::
2074
2075    t = ET.XML("""<list>
2076      <item>1</item> <item>2</item>  <item>3</item>
2077    </list>""")
2078
2079    # Outputs ['\n  ', '1', ' ', '2', '  ', '3', '\n']
2080    print list(t.itertext())
2081
2082* Deprecated: using an element as a Boolean (i.e., ``if elem:``) would
2083  return true if the element had any children, or false if there were
2084  no children.  This behaviour is confusing -- ``None`` is false, but
2085  so is a childless element? -- so it will now trigger a
2086  :exc:`FutureWarning`.  In your code, you should be explicit: write
2087  ``len(elem) != 0`` if you're interested in the number of children,
2088  or ``elem is not None``.
2089
2090Fredrik Lundh develops ElementTree and produced the 1.3 version;
2091you can read his article describing 1.3 at
2092http://effbot.org/zone/elementtree-13-intro.htm.
2093Florent Xicluna updated the version included with
2094Python, after discussions on python-dev and in :issue:`6472`.)
2095
2096.. ======================================================================
2097
2098
2099Build and C API Changes
2100=======================
2101
2102Changes to Python's build process and to the C API include:
2103
2104* The latest release of the GNU Debugger, GDB 7, can be `scripted
2105  using Python
2106  <https://sourceware.org/gdb/current/onlinedocs/gdb/Python.html>`__.
2107  When you begin debugging an executable program P, GDB will look for
2108  a file named ``P-gdb.py`` and automatically read it.  Dave Malcolm
2109  contributed a :file:`python-gdb.py` that adds a number of
2110  commands useful when debugging Python itself.  For example,
2111  ``py-up`` and ``py-down`` go up or down one Python stack frame,
2112  which usually corresponds to several C stack frames.  ``py-print``
2113  prints the value of a Python variable, and ``py-bt`` prints the
2114  Python stack trace.  (Added as a result of :issue:`8032`.)
2115
2116* If you use the :file:`.gdbinit` file provided with Python,
2117  the "pyo" macro in the 2.7 version now works correctly when the thread being
2118  debugged doesn't hold the GIL; the macro now acquires it before printing.
2119  (Contributed by Victor Stinner; :issue:`3632`.)
2120
2121* :c:func:`Py_AddPendingCall` is now thread-safe, letting any
2122  worker thread submit notifications to the main Python thread.  This
2123  is particularly useful for asynchronous IO operations.
2124  (Contributed by Kristján Valur Jónsson; :issue:`4293`.)
2125
2126* New function: :c:func:`PyCode_NewEmpty` creates an empty code object;
2127  only the filename, function name, and first line number are required.
2128  This is useful for extension modules that are attempting to
2129  construct a more useful traceback stack.  Previously such
2130  extensions needed to call :c:func:`PyCode_New`, which had many
2131  more arguments.  (Added by Jeffrey Yasskin.)
2132
2133* New function: :c:func:`PyErr_NewExceptionWithDoc` creates a new
2134  exception class, just as the existing :c:func:`PyErr_NewException` does,
2135  but takes an extra ``char *`` argument containing the docstring for the
2136  new exception class.  (Added by 'lekma' on the Python bug tracker;
2137  :issue:`7033`.)
2138
2139* New function: :c:func:`PyFrame_GetLineNumber` takes a frame object
2140  and returns the line number that the frame is currently executing.
2141  Previously code would need to get the index of the bytecode
2142  instruction currently executing, and then look up the line number
2143  corresponding to that address.  (Added by Jeffrey Yasskin.)
2144
2145* New functions: :c:func:`PyLong_AsLongAndOverflow` and
2146  :c:func:`PyLong_AsLongLongAndOverflow`  approximates a Python long
2147  integer as a C :c:type:`long` or :c:type:`long long`.
2148  If the number is too large to fit into
2149  the output type, an *overflow* flag is set and returned to the caller.
2150  (Contributed by Case Van Horsen; :issue:`7528` and :issue:`7767`.)
2151
2152* New function: stemming from the rewrite of string-to-float conversion,
2153  a new :c:func:`PyOS_string_to_double` function was added.  The old
2154  :c:func:`PyOS_ascii_strtod` and :c:func:`PyOS_ascii_atof` functions
2155  are now deprecated.
2156
2157* New function: :c:func:`PySys_SetArgvEx` sets the value of
2158  ``sys.argv`` and can optionally update ``sys.path`` to include the
2159  directory containing the script named by ``sys.argv[0]`` depending
2160  on the value of an *updatepath* parameter.
2161
2162  This function was added to close a security hole for applications
2163  that embed Python.  The old function, :c:func:`PySys_SetArgv`, would
2164  always update ``sys.path``, and sometimes it would add the current
2165  directory.  This meant that, if you ran an application embedding
2166  Python in a directory controlled by someone else, attackers could
2167  put a Trojan-horse module in the directory (say, a file named
2168  :file:`os.py`) that your application would then import and run.
2169
2170  If you maintain a C/C++ application that embeds Python, check
2171  whether you're calling :c:func:`PySys_SetArgv` and carefully consider
2172  whether the application should be using :c:func:`PySys_SetArgvEx`
2173  with *updatepath* set to false.
2174
2175  Security issue reported as `CVE-2008-5983
2176  <https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2008-5983>`_;
2177  discussed in :issue:`5753`, and fixed by Antoine Pitrou.
2178
2179* New macros: the Python header files now define the following macros:
2180  :c:macro:`Py_ISALNUM`,
2181  :c:macro:`Py_ISALPHA`,
2182  :c:macro:`Py_ISDIGIT`,
2183  :c:macro:`Py_ISLOWER`,
2184  :c:macro:`Py_ISSPACE`,
2185  :c:macro:`Py_ISUPPER`,
2186  :c:macro:`Py_ISXDIGIT`,
2187  :c:macro:`Py_TOLOWER`, and :c:macro:`Py_TOUPPER`.
2188  All of these functions are analogous to the C
2189  standard macros for classifying characters, but ignore the current
2190  locale setting, because in
2191  several places Python needs to analyze characters in a
2192  locale-independent way.  (Added by Eric Smith;
2193  :issue:`5793`.)
2194
2195  .. XXX these macros don't seem to be described in the c-api docs.
2196
2197* Removed function: :c:macro:`PyEval_CallObject` is now only available
2198  as a macro.  A function version was being kept around to preserve
2199  ABI linking compatibility, but that was in 1997; it can certainly be
2200  deleted by now.  (Removed by Antoine Pitrou; :issue:`8276`.)
2201
2202* New format codes: the :c:func:`PyFormat_FromString`,
2203  :c:func:`PyFormat_FromStringV`, and :c:func:`PyErr_Format` functions now
2204  accept ``%lld`` and ``%llu`` format codes for displaying
2205  C's :c:type:`long long` types.
2206  (Contributed by Mark Dickinson; :issue:`7228`.)
2207
2208* The complicated interaction between threads and process forking has
2209  been changed.  Previously, the child process created by
2210  :func:`os.fork` might fail because the child is created with only a
2211  single thread running, the thread performing the :func:`os.fork`.
2212  If other threads were holding a lock, such as Python's import lock,
2213  when the fork was performed, the lock would still be marked as
2214  "held" in the new process.  But in the child process nothing would
2215  ever release the lock, since the other threads weren't replicated,
2216  and the child process would no longer be able to perform imports.
2217
2218  Python 2.7 acquires the import lock before performing an
2219  :func:`os.fork`, and will also clean up any locks created using the
2220  :mod:`threading` module.  C extension modules that have internal
2221  locks, or that call :c:func:`fork()` themselves, will not benefit
2222  from this clean-up.
2223
2224  (Fixed by Thomas Wouters; :issue:`1590864`.)
2225
2226* The :c:func:`Py_Finalize` function now calls the internal
2227  :func:`threading._shutdown` function; this prevents some exceptions from
2228  being raised when an interpreter shuts down.
2229  (Patch by Adam Olsen; :issue:`1722344`.)
2230
2231* When using the :c:type:`PyMemberDef` structure to define attributes
2232  of a type, Python will no longer let you try to delete or set a
2233  :const:`T_STRING_INPLACE` attribute.
2234
2235  .. rev 79644
2236
2237* Global symbols defined by the :mod:`ctypes` module are now prefixed
2238  with ``Py``, or with ``_ctypes``.  (Implemented by Thomas
2239  Heller; :issue:`3102`.)
2240
2241* New configure option: the :option:`!--with-system-expat` switch allows
2242  building the :mod:`pyexpat` module to use the system Expat library.
2243  (Contributed by Arfrever Frehtes Taifersar Arahesis; :issue:`7609`.)
2244
2245* New configure option: the
2246  :option:`!--with-valgrind` option will now disable the pymalloc
2247  allocator, which is difficult for the Valgrind memory-error detector
2248  to analyze correctly.
2249  Valgrind will therefore be better at detecting memory leaks and
2250  overruns. (Contributed by James Henstridge; :issue:`2422`.)
2251
2252* New configure option: you can now supply an empty string to
2253  :option:`!--with-dbmliborder=` in order to disable all of the various
2254  DBM modules.  (Added by Arfrever Frehtes Taifersar Arahesis;
2255  :issue:`6491`.)
2256
2257* The :program:`configure` script now checks for floating-point rounding bugs
2258  on certain 32-bit Intel chips and defines a :c:macro:`X87_DOUBLE_ROUNDING`
2259  preprocessor definition.  No code currently uses this definition,
2260  but it's available if anyone wishes to use it.
2261  (Added by Mark Dickinson; :issue:`2937`.)
2262
2263  :program:`configure` also now sets a :envvar:`LDCXXSHARED` Makefile
2264  variable for supporting C++ linking.  (Contributed by Arfrever
2265  Frehtes Taifersar Arahesis; :issue:`1222585`.)
2266
2267* The build process now creates the necessary files for pkg-config
2268  support.  (Contributed by Clinton Roy; :issue:`3585`.)
2269
2270* The build process now supports Subversion 1.7.  (Contributed by
2271  Arfrever Frehtes Taifersar Arahesis; :issue:`6094`.)
2272
2273
2274.. _whatsnew27-capsules:
2275
2276Capsules
2277-------------------
2278
2279Python 3.1 adds a new C datatype, :c:type:`PyCapsule`, for providing a
2280C API to an extension module.  A capsule is essentially the holder of
2281a C ``void *`` pointer, and is made available as a module attribute; for
2282example, the :mod:`socket` module's API is exposed as ``socket.CAPI``,
2283and :mod:`unicodedata` exposes ``ucnhash_CAPI``.  Other extensions
2284can import the module, access its dictionary to get the capsule
2285object, and then get the ``void *`` pointer, which will usually point
2286to an array of pointers to the module's various API functions.
2287
2288There is an existing data type already used for this,
2289:c:type:`PyCObject`, but it doesn't provide type safety.  Evil code
2290written in pure Python could cause a segmentation fault by taking a
2291:c:type:`PyCObject` from module A and somehow substituting it for the
2292:c:type:`PyCObject` in module B.   Capsules know their own name,
2293and getting the pointer requires providing the name:
2294
2295.. code-block:: c
2296
2297   void *vtable;
2298
2299   if (!PyCapsule_IsValid(capsule, "mymodule.CAPI") {
2300           PyErr_SetString(PyExc_ValueError, "argument type invalid");
2301           return NULL;
2302   }
2303
2304   vtable = PyCapsule_GetPointer(capsule, "mymodule.CAPI");
2305
2306You are assured that ``vtable`` points to whatever you're expecting.
2307If a different capsule was passed in, :c:func:`PyCapsule_IsValid` would
2308detect the mismatched name and return false.  Refer to
2309:ref:`using-capsules` for more information on using these objects.
2310
2311Python 2.7 now uses capsules internally to provide various
2312extension-module APIs, but the :c:func:`PyCObject_AsVoidPtr` was
2313modified to handle capsules, preserving compile-time compatibility
2314with the :c:type:`CObject` interface.  Use of
2315:c:func:`PyCObject_AsVoidPtr` will signal a
2316:exc:`PendingDeprecationWarning`, which is silent by default.
2317
2318Implemented in Python 3.1 and backported to 2.7 by Larry Hastings;
2319discussed in :issue:`5630`.
2320
2321
2322.. ======================================================================
2323
2324Port-Specific Changes: Windows
2325-----------------------------------
2326
2327* The :mod:`msvcrt` module now contains some constants from
2328  the :file:`crtassem.h` header file:
2329  :data:`CRT_ASSEMBLY_VERSION`,
2330  :data:`VC_ASSEMBLY_PUBLICKEYTOKEN`,
2331  and :data:`LIBRARIES_ASSEMBLY_NAME_PREFIX`.
2332  (Contributed by David Cournapeau; :issue:`4365`.)
2333
2334* The :mod:`_winreg` module for accessing the registry now implements
2335  the :func:`~_winreg.CreateKeyEx` and :func:`~_winreg.DeleteKeyEx`
2336  functions, extended versions of previously-supported functions that
2337  take several extra arguments.  The :func:`~_winreg.DisableReflectionKey`,
2338  :func:`~_winreg.EnableReflectionKey`, and :func:`~_winreg.QueryReflectionKey`
2339  were also tested and documented.
2340  (Implemented by Brian Curtin: :issue:`7347`.)
2341
2342* The new :c:func:`_beginthreadex` API is used to start threads, and
2343  the native thread-local storage functions are now used.
2344  (Contributed by Kristján Valur Jónsson; :issue:`3582`.)
2345
2346* The :func:`os.kill` function now works on Windows.  The signal value
2347  can be the constants :const:`CTRL_C_EVENT`,
2348  :const:`CTRL_BREAK_EVENT`, or any integer.  The first two constants
2349  will send :kbd:`Control-C` and :kbd:`Control-Break` keystroke events to
2350  subprocesses; any other value will use the :c:func:`TerminateProcess`
2351  API.  (Contributed by Miki Tebeka; :issue:`1220212`.)
2352
2353* The :func:`os.listdir` function now correctly fails
2354  for an empty path.  (Fixed by Hirokazu Yamamoto; :issue:`5913`.)
2355
2356* The :mod:`mimelib` module will now read the MIME database from
2357  the Windows registry when initializing.
2358  (Patch by Gabriel Genellina; :issue:`4969`.)
2359
2360.. ======================================================================
2361
2362Port-Specific Changes: Mac OS X
2363-----------------------------------
2364
2365* The path ``/Library/Python/2.7/site-packages`` is now appended to
2366  ``sys.path``, in order to share added packages between the system
2367  installation and a user-installed copy of the same version.
2368  (Changed by Ronald Oussoren; :issue:`4865`.)
2369
2370   .. versionchanged:: 2.7.13
2371
2372     As of 2.7.13, this change was removed.
2373     ``/Library/Python/2.7/site-packages``, the site-packages directory
2374     used by the Apple-supplied system Python 2.7 is no longer appended to
2375     ``sys.path`` for user-installed Pythons such as from the python.org
2376     installers.  As of macOS 10.12, Apple changed how the system
2377     site-packages directory is configured, which could cause installation
2378     of pip components, like setuptools, to fail.  Packages installed for
2379     the system Python will no longer be shared with user-installed
2380     Pythons. (:issue:`28440`)
2381
2382Port-Specific Changes: FreeBSD
2383-----------------------------------
2384
2385* FreeBSD 7.1's :const:`SO_SETFIB` constant, used with
2386  :func:`~socket.getsockopt`/:func:`~socket.setsockopt` to select an
2387  alternate routing table, is now available in the :mod:`socket`
2388  module.  (Added by Kyle VanderBeek; :issue:`8235`.)
2389
2390Other Changes and Fixes
2391=======================
2392
2393* Two benchmark scripts, :file:`iobench` and :file:`ccbench`, were
2394  added to the :file:`Tools` directory.  :file:`iobench` measures the
2395  speed of the built-in file I/O objects returned by :func:`open`
2396  while performing various operations, and :file:`ccbench` is a
2397  concurrency benchmark that tries to measure computing throughput,
2398  thread switching latency, and IO processing bandwidth when
2399  performing several tasks using a varying number of threads.
2400
2401* The :file:`Tools/i18n/msgfmt.py` script now understands plural
2402  forms in :file:`.po` files.  (Fixed by Martin von Löwis;
2403  :issue:`5464`.)
2404
2405* When importing a module from a :file:`.pyc` or :file:`.pyo` file
2406  with an existing :file:`.py` counterpart, the :attr:`co_filename`
2407  attributes of the resulting code objects are overwritten when the
2408  original filename is obsolete.  This can happen if the file has been
2409  renamed, moved, or is accessed through different paths.  (Patch by
2410  Ziga Seilnacht and Jean-Paul Calderone; :issue:`1180193`.)
2411
2412* The :file:`regrtest.py` script now takes a :option:`!--randseed=`
2413  switch that takes an integer that will be used as the random seed
2414  for the :option:`!-r` option that executes tests in random order.
2415  The :option:`!-r` option also reports the seed that was used
2416  (Added by Collin Winter.)
2417
2418* Another :file:`regrtest.py` switch is :option:`!-j`, which
2419  takes an integer specifying how many tests run in parallel. This
2420  allows reducing the total runtime on multi-core machines.
2421  This option is compatible with several other options, including the
2422  :option:`!-R` switch which is known to produce long runtimes.
2423  (Added by Antoine Pitrou, :issue:`6152`.)  This can also be used
2424  with a new :option:`!-F` switch that runs selected tests in a loop
2425  until they fail.  (Added by Antoine Pitrou; :issue:`7312`.)
2426
2427* When executed as a script, the :file:`py_compile.py` module now
2428  accepts ``'-'`` as an argument, which will read standard input for
2429  the list of filenames to be compiled.  (Contributed by Piotr
2430  Ożarowski; :issue:`8233`.)
2431
2432.. ======================================================================
2433
2434Porting to Python 2.7
2435=====================
2436
2437This section lists previously described changes and other bugfixes
2438that may require changes to your code:
2439
2440* The :func:`range` function processes its arguments more
2441  consistently; it will now call :meth:`__int__` on non-float,
2442  non-integer arguments that are supplied to it.  (Fixed by Alexander
2443  Belopolsky; :issue:`1533`.)
2444
2445* The string :meth:`format` method changed the default precision used
2446  for floating-point and complex numbers from 6 decimal
2447  places to 12, which matches the precision used by :func:`str`.
2448  (Changed by Eric Smith; :issue:`5920`.)
2449
2450* Because of an optimization for the :keyword:`with` statement, the special
2451  methods :meth:`__enter__` and :meth:`__exit__` must belong to the object's
2452  type, and cannot be directly attached to the object's instance.  This
2453  affects new-style classes (derived from :class:`object`) and C extension
2454  types.  (:issue:`6101`.)
2455
2456* Due to a bug in Python 2.6, the *exc_value* parameter to
2457  :meth:`__exit__` methods was often the string representation of the
2458  exception, not an instance.  This was fixed in 2.7, so *exc_value*
2459  will be an instance as expected.  (Fixed by Florent Xicluna;
2460  :issue:`7853`.)
2461
2462* When a restricted set of attributes were set using ``__slots__``,
2463  deleting an unset attribute would not raise :exc:`AttributeError`
2464  as you would expect.  Fixed by Benjamin Peterson; :issue:`7604`.)
2465
2466In the standard library:
2467
2468* Operations with :class:`~datetime.datetime` instances that resulted in a year
2469  falling outside the supported range didn't always raise
2470  :exc:`OverflowError`.  Such errors are now checked more carefully
2471  and will now raise the exception. (Reported by Mark Leander, patch
2472  by Anand B. Pillai and Alexander Belopolsky; :issue:`7150`.)
2473
2474* When using :class:`~decimal.Decimal` instances with a string's
2475  :meth:`format` method, the default alignment was previously
2476  left-alignment.  This has been changed to right-alignment, which might
2477  change the output of your programs.
2478  (Changed by Mark Dickinson; :issue:`6857`.)
2479
2480  Comparisons involving a signaling NaN value (or ``sNAN``) now signal
2481  :const:`~decimal.InvalidOperation` instead of silently returning a true or
2482  false value depending on the comparison operator.  Quiet NaN values
2483  (or ``NaN``) are now hashable.  (Fixed by Mark Dickinson;
2484  :issue:`7279`.)
2485
2486* The ElementTree library, :mod:`xml.etree`, no longer escapes
2487  ampersands and angle brackets when outputting an XML processing
2488  instruction (which looks like `<?xml-stylesheet href="#style1"?>`)
2489  or comment (which looks like `<!-- comment -->`).
2490  (Patch by Neil Muller; :issue:`2746`.)
2491
2492* The :meth:`~StringIO.StringIO.readline` method of :class:`~StringIO.StringIO` objects now does
2493  nothing when a negative length is requested, as other file-like
2494  objects do.  (:issue:`7348`).
2495
2496* The :mod:`syslog` module will now use the value of ``sys.argv[0]`` as the
2497  identifier instead of the previous default value of ``'python'``.
2498  (Changed by Sean Reifschneider; :issue:`8451`.)
2499
2500* The :mod:`tarfile` module's default error handling has changed, to
2501  no longer suppress fatal errors.  The default error level was previously 0,
2502  which meant that errors would only result in a message being written to the
2503  debug log, but because the debug log is not activated by default,
2504  these errors go unnoticed.  The default error level is now 1,
2505  which raises an exception if there's an error.
2506  (Changed by Lars Gustäbel; :issue:`7357`.)
2507
2508* The :mod:`urlparse` module's :func:`~urlparse.urlsplit` now handles
2509  unknown URL schemes in a fashion compliant with :rfc:`3986`: if the
2510  URL is of the form ``"<something>://..."``, the text before the
2511  ``://`` is treated as the scheme, even if it's a made-up scheme that
2512  the module doesn't know about.  This change may break code that
2513  worked around the old behaviour.  For example, Python 2.6.4 or 2.5
2514  will return the following:
2515
2516  .. doctest::
2517    :options: +SKIP
2518
2519    >>> import urlparse
2520    >>> urlparse.urlsplit('invented://host/filename?query')
2521    ('invented', '', '//host/filename?query', '', '')
2522
2523  Python 2.7 (and Python 2.6.5) will return:
2524
2525  .. doctest::
2526    :options: +SKIP
2527
2528    >>> import urlparse
2529    >>> urlparse.urlsplit('invented://host/filename?query')
2530    ('invented', 'host', '/filename?query', '', '')
2531
2532  (Python 2.7 actually produces slightly different output, since it
2533  returns a named tuple instead of a standard tuple.)
2534
2535For C extensions:
2536
2537* C extensions that use integer format codes with the ``PyArg_Parse*``
2538  family of functions will now raise a :exc:`TypeError` exception
2539  instead of triggering a :exc:`DeprecationWarning` (:issue:`5080`).
2540
2541* Use the new :c:func:`PyOS_string_to_double` function instead of the old
2542  :c:func:`PyOS_ascii_strtod` and :c:func:`PyOS_ascii_atof` functions,
2543  which are now deprecated.
2544
2545For applications that embed Python:
2546
2547* The :c:func:`PySys_SetArgvEx` function was added, letting
2548  applications close a security hole when the existing
2549  :c:func:`PySys_SetArgv` function was used.  Check whether you're
2550  calling :c:func:`PySys_SetArgv` and carefully consider whether the
2551  application should be using :c:func:`PySys_SetArgvEx` with
2552  *updatepath* set to false.
2553
2554.. ======================================================================
2555
2556
2557.. _py27-maintenance-enhancements:
2558
2559New Features Added to Python 2.7 Maintenance Releases
2560=====================================================
2561
2562New features may be added to Python 2.7 maintenance releases when the
2563situation genuinely calls for it. Any such additions must go through
2564the Python Enhancement Proposal process, and make a compelling case for why
2565they can't be adequately addressed by either adding the new feature solely to
2566Python 3, or else by publishing it on the Python Package Index.
2567
2568In addition to the specific proposals listed below, there is a general
2569exemption allowing new ``-3`` warnings to be added in any Python 2.7
2570maintenance release.
2571
2572
2573Two new environment variables for debug mode
2574--------------------------------------------
2575
2576In debug mode, the ``[xxx refs]`` statistic is not written by default, the
2577:envvar:`PYTHONSHOWREFCOUNT` environment variable now must also be set.
2578(Contributed by Victor Stinner; :issue:`31733`.)
2579
2580When Python is compiled with ``COUNT_ALLOC`` defined, allocation counts are no
2581longer dumped by default anymore: the :envvar:`PYTHONSHOWALLOCCOUNT` environment
2582variable must now also be set. Moreover, allocation counts are now dumped into
2583stderr, rather than stdout. (Contributed by Victor Stinner; :issue:`31692`.)
2584
2585.. versionadded:: 2.7.15
2586
2587
2588PEP 434: IDLE Enhancement Exception for All Branches
2589----------------------------------------------------
2590
2591:pep:`434` describes a general exemption for changes made to the IDLE
2592development environment shipped along with Python. This exemption makes it
2593possible for the IDLE developers to provide a more consistent user
2594experience across all supported versions of Python 2 and 3.
2595
2596For details of any IDLE changes, refer to the NEWS file for the specific
2597release.
2598
2599
2600PEP 466: Network Security Enhancements for Python 2.7
2601-----------------------------------------------------
2602
2603:pep:`466` describes a number of network security enhancement proposals
2604that have been approved for inclusion in Python 2.7 maintenance releases,
2605with the first of those changes appearing in the Python 2.7.7 release.
2606
2607:pep:`466` related features added in Python 2.7.7:
2608
2609* :func:`hmac.compare_digest` was backported from Python 3 to make a timing
2610  attack resistant comparison operation available to Python 2 applications.
2611  (Contributed by Alex Gaynor; :issue:`21306`.)
2612
2613* OpenSSL 1.0.1g was upgraded in the official Windows installers published on
2614  python.org. (Contributed by Zachary Ware; :issue:`21462`.)
2615
2616:pep:`466` related features added in Python 2.7.8:
2617
2618* :func:`hashlib.pbkdf2_hmac` was backported from Python 3 to make a hashing
2619  algorithm suitable for secure password storage broadly available to Python
2620  2 applications. (Contributed by Alex Gaynor; :issue:`21304`.)
2621
2622* OpenSSL 1.0.1h was upgraded for the official Windows installers published on
2623  python.org. (contributed by Zachary Ware in :issue:`21671` for CVE-2014-0224)
2624
2625:pep:`466` related features added in Python 2.7.9:
2626
2627* Most of Python 3.4's :mod:`ssl` module was backported. This means :mod:`ssl`
2628  now supports Server Name Indication, TLS1.x settings, access to the platform
2629  certificate store, the :class:`~ssl.SSLContext` class, and other
2630  features. (Contributed by Alex Gaynor and David Reid; :issue:`21308`.)
2631
2632  Refer to the "Version added: 2.7.9" notes in the module documentation for
2633  specific details.
2634
2635* :func:`os.urandom` was changed to cache a file descriptor to ``/dev/urandom``
2636  instead of reopening ``/dev/urandom`` on every call. (Contributed by Alex
2637  Gaynor; :issue:`21305`.)
2638
2639* :data:`hashlib.algorithms_guaranteed` and
2640  :data:`hashlib.algorithms_available` were backported from Python 3 to make
2641  it easier for Python 2 applications to select the strongest available hash
2642  algorithm. (Contributed by Alex Gaynor in :issue:`21307`)
2643
2644
2645PEP 477: Backport ensurepip (PEP 453) to Python 2.7
2646---------------------------------------------------
2647
2648:pep:`477` approves the inclusion of the :pep:`453` ensurepip module and the
2649improved documentation that was enabled by it in the Python 2.7 maintenance
2650releases, appearing first in the Python 2.7.9 release.
2651
2652
2653Bootstrapping pip By Default
2654~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2655
2656The new :mod:`ensurepip` module (defined in :pep:`453`) provides a standard
2657cross-platform mechanism to bootstrap the pip installer into Python
2658installations. The version of ``pip`` included with Python 2.7.9 is ``pip``
26591.5.6, and future 2.7.x maintenance releases will update the bundled version to
2660the latest version of ``pip`` that is available at the time of creating the
2661release candidate.
2662
2663By default, the commands ``pip``, ``pipX`` and ``pipX.Y`` will be installed on
2664all platforms (where X.Y stands for the version of the Python installation),
2665along with the ``pip`` Python package and its dependencies.
2666
2667For CPython :ref:`source builds on POSIX systems <building-python-on-unix>`,
2668the ``make install`` and ``make altinstall`` commands do not bootstrap ``pip``
2669by default.  This behaviour can be controlled through configure options, and
2670overridden through Makefile options.
2671
2672On Windows and Mac OS X, the CPython installers now default to installing
2673``pip`` along with CPython itself (users may opt out of installing it
2674during the installation process). Window users will need to opt in to the
2675automatic ``PATH`` modifications to have ``pip`` available from the command
2676line by default, otherwise it can still be accessed through the Python
2677launcher for Windows as ``py -m pip``.
2678
2679As `discussed in the PEP`__, platform packagers may choose not to install
2680these commands by default, as long as, when invoked, they provide clear and
2681simple directions on how to install them on that platform (usually using
2682the system package manager).
2683
2684__ https://www.python.org/dev/peps/pep-0477/#disabling-ensurepip-by-downstream-distributors
2685
2686
2687Documentation Changes
2688~~~~~~~~~~~~~~~~~~~~~
2689
2690As part of this change, the :ref:`installing-index` and
2691:ref:`distributing-index` sections of the documentation have been
2692completely redesigned as short getting started and FAQ documents. Most
2693packaging documentation has now been moved out to the Python Packaging
2694Authority maintained `Python Packaging User Guide
2695<http://packaging.python.org>`__ and the documentation of the individual
2696projects.
2697
2698However, as this migration is currently still incomplete, the legacy
2699versions of those guides remaining available as :ref:`install-index`
2700and :ref:`distutils-index`.
2701
2702.. seealso::
2703
2704   :pep:`453` -- Explicit bootstrapping of pip in Python installations
2705      PEP written by Donald Stufft and Nick Coghlan, implemented by
2706      Donald Stufft, Nick Coghlan, Martin von Löwis and Ned Deily.
2707
2708PEP 476: Enabling certificate verification by default for stdlib http clients
2709-----------------------------------------------------------------------------
2710
2711:pep:`476` updated :mod:`httplib` and modules which use it, such as
2712:mod:`urllib2` and :mod:`xmlrpclib`, to now verify that the server
2713presents a certificate which is signed by a Certificate Authority in the
2714platform trust store and whose hostname matches the hostname being requested
2715by default, significantly improving security for many applications. This
2716change was made in the Python 2.7.9 release.
2717
2718For applications which require the old previous behavior, they can pass an
2719alternate context::
2720
2721    import urllib2
2722    import ssl
2723
2724    # This disables all verification
2725    context = ssl._create_unverified_context()
2726
2727    # This allows using a specific certificate for the host, which doesn't need
2728    # to be in the trust store
2729    context = ssl.create_default_context(cafile="/path/to/file.crt")
2730
2731    urllib2.urlopen("https://invalid-cert", context=context)
2732
2733
2734PEP 493: HTTPS verification migration tools for Python 2.7
2735----------------------------------------------------------
2736
2737:pep:`493` provides additional migration tools to support a more incremental
2738infrastructure upgrade process for environments containing applications and
2739services relying on the historically permissive processing of server
2740certificates when establishing client HTTPS connections.  These additions were
2741made in the Python 2.7.12 release.
2742
2743These tools are intended for use in cases where affected applications and
2744services can't be modified to explicitly pass a more permissive SSL context
2745when establishing the connection.
2746
2747For applications and services which can't be modified at all, the new
2748``PYTHONHTTPSVERIFY`` environment variable may be set to ``0`` to revert an
2749entire Python process back to the default permissive behaviour of Python 2.7.8
2750and earlier.
2751
2752For cases where the connection establishment code can't be modified, but the
2753overall application can be, the new :func:`ssl._https_verify_certificates`
2754function can be used to adjust the default behaviour at runtime.
2755
2756
2757New ``make regen-all`` build target
2758-----------------------------------
2759
2760To simplify cross-compilation, and to ensure that CPython can reliably be
2761compiled without requiring an existing version of Python to already be
2762available, the autotools-based build system no longer attempts to implicitly
2763recompile generated files based on file modification times.
2764
2765Instead, a new ``make regen-all`` command has been added to force regeneration
2766of these files when desired (e.g. after an initial version of Python has
2767already been built based on the pregenerated versions).
2768
2769More selective regeneration targets are also defined - see
2770:source:`Makefile.pre.in` for details.
2771
2772(Contributed by Victor Stinner in :issue:`23404`.)
2773
2774.. versionadded:: 2.7.14
2775
2776
2777Removal of ``make touch`` build target
2778--------------------------------------
2779
2780The ``make touch`` build target previously used to request implicit regeneration
2781of generated files by updating their modification times has been removed.
2782
2783It has been replaced by the new ``make regen-all`` target.
2784
2785(Contributed by Victor Stinner in :issue:`23404`.)
2786
2787.. versionchanged:: 2.7.14
2788
2789.. ======================================================================
2790
2791.. _acks27:
2792
2793Acknowledgements
2794================
2795
2796The author would like to thank the following people for offering
2797suggestions, corrections and assistance with various drafts of this
2798article: Nick Coghlan, Philip Jenvey, Ryan Lovett, R. David Murray,
2799Hugh Secker-Walker.
2800