:pep:`398` - Python 3.3 Release Schedule

:pep:`405` - Python Virtual Environments
   PEP written by Carl Meyer; implementation by Carl Meyer and Vinay Sajip

from errno import ENOENT, EACCES, EPERM

try:
    with open("document.txt") as f:
        content = f.read()
except IOError as err:
    if err.errno == ENOENT:
        print("document.txt file is missing")
    elif err.errno in (EACCES, EPERM):
        print("You are not allowed to read document.txt")
    else:
        raise

try:
    with open("document.txt") as f:
        content = f.read()
except FileNotFoundError:
    print("document.txt file is missing")
except PermissionError:
    print("You are not allowed to read document.txt")

>>> def g(x):
...     yield from range(x, 0, -1)
...     yield from range(x)
...
>>> list(g(5))
[5, 4, 3, 2, 1, 0, 1, 2, 3, 4]

>>> def accumulate():
...     tally = 0
...     while 1:
...         next = yield
...         if next is None:
...             return tally
...         tally += next
...
>>> def gather_tallies(tallies):
...     while 1:
...         tally = yield from accumulate()
...         tallies.append(tally)
...
>>> tallies = []
>>> acc = gather_tallies(tallies)
>>> next(acc)  # Ensure the accumulator is ready to accept values
>>> for i in range(4):
...     acc.send(i)
...
>>> acc.send(None)  # Finish the first tally
>>> for i in range(5):
...     acc.send(i)
...
>>> acc.send(None)  # Finish the second tally
>>> tallies
[6, 10]

>>> class D:
...     def __init__(self, extra):
...         self._extra_attributes = extra
...     def __getattr__(self, attr):
...         try:
...             return self._extra_attributes[attr]
...         except KeyError:
...             raise AttributeError(attr) from None
...
>>> D({}).x
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "<stdin>", line 8, in __getattr__
AttributeError: x

>>> class C:
...     def __init__(self, extra):
...         self._extra_attributes = extra
...     def __getattr__(self, attr):
...         try:
...             return self._extra_attributes[attr]
...         except KeyError:
...             raise AttributeError(attr)
...
>>> C({}).x
Traceback (most recent call last):
  File "<stdin>", line 6, in __getattr__
KeyError: 'x'

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "<stdin>", line 8, in __getattr__
AttributeError: x

>>> try:
...     D({}).x
... except AttributeError as exc:
...     print(repr(exc.__context__))
...
KeyError('x',)

$ python -q -X faulthandler
>>> import ctypes
>>> ctypes.string_at(0)
Fatal Python error: Segmentation fault

Current thread 0x00007fb899f39700:
  File "/home/python/cpython/Lib/ctypes/__init__.py", line 486 in string_at
  File "<stdin>", line 1 in <module>
Segmentation fault

>>> import codecs
>>> encoder = codecs.getincrementalencoder('hz')('strict')
>>> b''.join(encoder.encode(x) for x in '\u52ff\u65bd\u65bc\u4eba\u3002 Bye.')
b'~{NpJ)l6HK!#~} Bye.'

* The :exc:`~decimal.FloatOperation` signal optionally enables stricter
  semantics for mixing floats and Decimals.

* If Python is compiled without threads, the C version automatically
  disables the expensive thread local context machinery. In this case,
  the variable :data:`~decimal.HAVE_THREADS` is set to ``False``.

API changes

The email package now has a :mod:`~email.policy` framework.  A
:class:`~email.policy.Policy` is an object with several methods and properties
that control how the email package behaves.  The primary policy for Python 3.3
is the :class:`~email.policy.Compat32` policy, which provides backward
compatibility with the email package in Python 3.2.  A ``policy`` can be
specified when an email message is parsed by a :mod:`~email.parser`, or when a
:class:`~email.message.Message` object is created, or when an email is
serialized using a :mod:`~email.generator`.  Unless overridden, a policy passed
to a ``parser`` is inherited by all the ``Message`` object and sub-objects
created by the ``parser``.  By default a ``generator`` will use the policy of
the ``Message`` object it is serializing.  The default policy is
:data:`~email.policy.compat32`.

The minimum set of controls implemented by all ``policy`` objects are:

    .. tabularcolumns:: |l|L|

    ===============     =======================================================
    max_line_length     The maximum length, excluding the linesep character(s),
                        individual lines may have when a ``Message`` is
                        serialized.  Defaults to 78.

    linesep             The character used to separate individual lines when a
                        ``Message`` is serialized.  Defaults to ``\n``.

    cte_type            ``7bit`` or ``8bit``.  ``8bit`` applies only to a
                        ``Bytes`` ``generator``, and means that non-ASCII may
                        be used where allowed by the protocol (or where it
                        exists in the original input).

    raise_on_defect     Causes a ``parser`` to raise error when defects are
                        encountered instead of adding them to the ``Message``
                        object's ``defects`` list.
    ===============     =======================================================

A new policy instance, with new settings, is created using the
:meth:`~email.policy.Policy.clone` method of policy objects.  ``clone`` takes
any of the above controls as keyword arguments.  Any control not specified in
the call retains its default value.  Thus you can create a policy that uses
``\r\n`` linesep characters like this::

    mypolicy = compat32.clone(linesep='\r\n')

Policies can be used to make the generation of messages in the format needed by
your application simpler.  Instead of having to remember to specify
``linesep='\r\n'`` in all the places you call a ``generator``, you can specify
it once, when you set the policy used by the ``parser`` or the ``Message``,
whichever your program uses to create ``Message`` objects.  On the other hand,
if you need to generate messages in multiple forms, you can still specify the
parameters in the appropriate ``generator`` call.  Or you can have custom
policy instances for your different cases, and pass those in when you create
the ``generator``.


Provisional Policy with New Header API

.. tabularcolumns:: |l|L|

===============     =======================================================
refold_source       Controls whether or not headers parsed by a
                    :mod:`~email.parser` are refolded by the
                    :mod:`~email.generator`.  It can be ``none``, ``long``,
                    or ``all``.  The default is ``long``, which means that
                    source headers with a line longer than
                    ``max_line_length`` get refolded.  ``none`` means no
                    line get refolded, and ``all`` means that all lines
                    get refolded.

header_factory      A callable that take a ``name`` and ``value`` and
                    produces a custom header object.
===============     =======================================================

>>> m = Message(policy=SMTP)
>>> m['To'] = 'Éric <[email protected]>'
>>> m['to']
'Éric <[email protected]>'
>>> m['to'].addresses
(Address(display_name='Éric', username='foo', domain='example.com'),)
>>> m['to'].addresses[0].username
'foo'
>>> m['to'].addresses[0].display_name
'Éric'
>>> m['Date'] = email.utils.localtime()
>>> m['Date'].datetime
datetime.datetime(2012, 5, 25, 21, 39, 24, 465484, tzinfo=datetime.timezone(datetime.timedelta(-1, 72000), 'EDT'))
>>> m['Date']
'Fri, 25 May 2012 21:44:27 -0400'
>>> print(m)
To: =?utf-8?q?=C3=89ric?= <[email protected]>
Date: Fri, 25 May 2012 21:44:27 -0400

>>> m['cc'] = [Group('pals', [Address('Bob', 'bob', 'example.com'),
...                           Address('Sally', 'sally', 'example.com')]),
...            Address('Bonzo', addr_spec='[email protected]')]
>>> print(m)
To: =?utf-8?q?=C3=89ric?= <[email protected]>
Date: Fri, 25 May 2012 21:44:27 -0400
cc: pals: Bob <[email protected]>, Sally <[email protected]>;, Bonzo <[email protected]>

>>> m2 = message_from_string(str(m))
>>> m2['to']
'Éric <[email protected]>'

>>> m2['cc'].addresses
(Address(display_name='Bob', username='bob', domain='example.com'), Address(display_name='Sally', username='sally', domain='example.com'), Address(display_name='Bonzo', username='bonz', domain='laugh.com'))
>>> m2['cc'].groups
(Group(display_name='pals', addresses=(Address(display_name='Bob', username='bob', domain='example.com'), Address(display_name='Sally', username='sally', domain='example.com')), Group(display_name=None, addresses=(Address(display_name='Bonzo', username='bonz', domain='laugh.com'),))

New :class:`~email.parser.BytesHeaderParser`, added to the :mod:`~email.parser`
module to complement :class:`~email.parser.HeaderParser` and complete the Bytes
API.

New utility functions:

   * :func:`~email.utils.format_datetime`: given a :class:`~datetime.datetime`,
     produce a string formatted for use in an email header.

   * :func:`~email.utils.parsedate_to_datetime`: given a date string from
     an email header, convert it into an aware :class:`~datetime.datetime`,
     or a naive :class:`~datetime.datetime` if the offset is ``-0000``.

   * :func:`~email.utils.localtime`: With no argument, returns the
     current local time as an aware :class:`~datetime.datetime` using the local
     :class:`~datetime.timezone`.  Given an aware :class:`~datetime.datetime`,
     converts it into an aware :class:`~datetime.datetime` using the
     local :class:`~datetime.timezone`.


ftplib
------

* :class:`ftplib.FTP` now accepts a ``source_address`` keyword argument to
  specify the ``(host, port)`` to use as the source address in the bind call
  when creating the outgoing socket.  (Contributed by Giampaolo Rodolà
  in :issue:`8594`.)

* The :class:`~ftplib.FTP_TLS` class now provides a new
  :func:`~ftplib.FTP_TLS.ccc` function to revert control channel back to
  plaintext.  This can be useful to take advantage of firewalls that know how
  to handle NAT with non-secure FTP without opening fixed ports.  (Contributed
  by Giampaolo Rodolà in :issue:`12139`.)

* Added :meth:`ftplib.FTP.mlsd` method which provides a parsable directory
  listing format and deprecates :meth:`ftplib.FTP.nlst` and
  :meth:`ftplib.FTP.dir`.  (Contributed by Giampaolo Rodolà in :issue:`11072`.)


functools
---------

The :func:`functools.lru_cache` decorator now accepts a ``typed`` keyword
argument (that defaults to ``False`` to ensure that it caches values of
different types that compare equal in separate cache slots.  (Contributed
by Raymond Hettinger in :issue:`13227`.)


gc
--

It is now possible to register callbacks invoked by the garbage collector
before and after collection using the new :data:`~gc.callbacks` list.


hmac
----

A new :func:`~hmac.compare_digest` function has been added to prevent side
channel attacks on digests through timing analysis.  (Contributed by Nick
Coghlan and Christian Heimes in :issue:`15061`.)


http
----

:class:`http.server.BaseHTTPRequestHandler` now buffers the headers and writes
them all at once when :meth:`~http.server.BaseHTTPRequestHandler.end_headers` is
called.  A new method :meth:`~http.server.BaseHTTPRequestHandler.flush_headers`
can be used to directly manage when the accumulated headers are sent.
(Contributed by Andrew Schaaf in :issue:`3709`.)

:class:`http.server` now produces valid ``HTML 4.01 strict`` output.
(Contributed by Ezio Melotti in :issue:`13295`.)

:class:`http.client.HTTPResponse` now has a
:meth:`~http.client.HTTPResponse.readinto` method, which means it can be used
as an :class:`io.RawIOBase` class.  (Contributed by John Kuhn in
:issue:`13464`.)


html
----

:class:`html.parser.HTMLParser` is now able to parse broken markup without
raising errors, therefore the *strict* argument of the constructor and the
:exc:`~html.parser.HTMLParseError` exception are now deprecated.
The ability to parse broken markup is the result of a number of bug fixes that
are also available on the latest bug fix releases of Python 2.7/3.2.
(Contributed by Ezio Melotti in :issue:`15114`, and :issue:`14538`,
:issue:`13993`, :issue:`13960`, :issue:`13358`, :issue:`1745761`,
:issue:`755670`, :issue:`13357`, :issue:`12629`, :issue:`1200313`,
:issue:`670664`, :issue:`13273`, :issue:`12888`, :issue:`7311`.)

A new :data:`~html.entities.html5` dictionary that maps HTML5 named character
references to the equivalent Unicode character(s) (e.g. ``html5['gt;'] ==
'>'``) has been added to the :mod:`html.entities` module.  The dictionary is
now also used by :class:`~html.parser.HTMLParser`.  (Contributed by Ezio
Melotti in :issue:`11113` and :issue:`15156`.)


imaplib
-------

The :class:`~imaplib.IMAP4_SSL` constructor now accepts an SSLContext
parameter to control parameters of the secure channel.

(Contributed by Sijin Joseph in :issue:`8808`.)


inspect
-------

A new :func:`~inspect.getclosurevars` function has been added. This function
reports the current binding of all names referenced from the function body and
where those names were resolved, making it easier to verify correct internal
state when testing code that relies on stateful closures.

(Contributed by Meador Inge and Nick Coghlan in :issue:`13062`.)

A new :func:`~inspect.getgeneratorlocals` function has been added. This
function reports the current binding of local variables in the generator's
stack frame, making it easier to verify correct internal state when testing
generators.

(Contributed by Meador Inge in :issue:`15153`.)

io
--

The :func:`~io.open` function has a new ``'x'`` mode that can be used to
exclusively create a new file, and raise a :exc:`FileExistsError` if the file
already exists. It is based on the C11 'x' mode to fopen().

(Contributed by David Townshend in :issue:`12760`.)

The constructor of the :class:`~io.TextIOWrapper` class has a new
*write_through* optional argument. If *write_through* is ``True``, calls to
:meth:`~io.TextIOWrapper.write` are guaranteed not to be buffered: any data
written on the :class:`~io.TextIOWrapper` object is immediately handled to its
underlying binary buffer.


itertools
---------

:func:`~itertools.accumulate` now takes an optional ``func`` argument for
providing a user-supplied binary function.


logging
-------

The :func:`~logging.basicConfig` function now supports an optional ``handlers``
argument taking an iterable of handlers to be added to the root logger.

A class level attribute :attr:`~logging.handlers.SysLogHandler.append_nul` has
been added to :class:`~logging.handlers.SysLogHandler` to allow control of the
appending of the ``NUL`` (``\000``) byte to syslog records, since for some
daemons it is required while for others it is passed through to the log.



math
----

The :mod:`math` module has a new function, :func:`~math.log2`,  which returns
the base-2 logarithm of *x*.

(Written by Mark Dickinson in :issue:`11888`.)


mmap
----

The :meth:`~mmap.mmap.read` method is now more compatible with other file-like
objects: if the argument is omitted or specified as ``None``, it returns the
bytes from the current file position to the end of the mapping.  (Contributed
by Petri Lehtinen in :issue:`12021`.)


multiprocessing
---------------

The new :func:`multiprocessing.connection.wait` function allows polling
multiple objects (such as connections, sockets and pipes) with a timeout.
(Contributed by Richard Oudkerk in :issue:`12328`.)

:class:`multiprocessing.Connection` objects can now be transferred over
multiprocessing connections.
(Contributed by Richard Oudkerk in :issue:`4892`.)

:class:`multiprocessing.Process` now accepts a ``daemon`` keyword argument
to override the default behavior of inheriting the ``daemon`` flag from
the parent process (:issue:`6064`).

New attribute :data:`multiprocessing.Process.sentinel` allows a
program to wait on multiple :class:`~multiprocessing.Process` objects at one
time using the appropriate OS primitives (for example, :mod:`select` on
posix systems).

New methods :meth:`multiprocessing.pool.Pool.starmap` and
:meth:`~multiprocessing.pool.Pool.starmap_async` provide
:func:`itertools.starmap` equivalents to the existing
:meth:`multiprocessing.pool.Pool.map` and
:meth:`~multiprocessing.pool.Pool.map_async` functions.  (Contributed by Hynek
Schlawack in :issue:`12708`.)


nntplib
-------

The :class:`nntplib.NNTP` class now supports the context management protocol to
unconditionally consume :exc:`socket.error` exceptions and to close the NNTP
connection when done::

  >>> from nntplib import NNTP
  >>> with NNTP('news.gmane.org') as n:
  ...     n.group('gmane.comp.python.committers')
  ...
  ('211 1755 1 1755 gmane.comp.python.committers', 1755, 1, 1755, 'gmane.comp.python.committers')
  >>>

(Contributed by Giampaolo Rodolà in :issue:`9795`.)


os
--

* The :mod:`os` module has a new :func:`~os.pipe2` function that makes it
  possible to create a pipe with :data:`~os.O_CLOEXEC` or
  :data:`~os.O_NONBLOCK` flags set atomically. This is especially useful to
  avoid race conditions in multi-threaded programs.

* The :mod:`os` module has a new :func:`~os.sendfile` function which provides
  an efficient "zero-copy" way for copying data from one file (or socket)
  descriptor to another. The phrase "zero-copy" refers to the fact that all of
  the copying of data between the two descriptors is done entirely by the
  kernel, with no copying of data into userspace buffers. :func:`~os.sendfile`
  can be used to efficiently copy data from a file on disk to a network socket,
  e.g. for downloading a file.

  (Patch submitted by Ross Lagerwall and Giampaolo Rodolà in :issue:`10882`.)

* To avoid race conditions like symlink attacks and issues with temporary
  files and directories, it is more reliable (and also faster) to manipulate
  file descriptors instead of file names. Python 3.3 enhances existing functions
  and introduces new functions to work on file descriptors (:issue:`4761`,
  :issue:`10755` and :issue:`14626`).

  - The :mod:`os` module has a new :func:`~os.fwalk` function similar to
    :func:`~os.walk` except that it also yields file descriptors referring to the
    directories visited. This is especially useful to avoid symlink races.

  - The following functions get new optional *dir_fd* (:ref:`paths relative to
    directory descriptors <dir_fd>`) and/or *follow_symlinks* (:ref:`not
    following symlinks <follow_symlinks>`):
    :func:`~os.access`, :func:`~os.chflags`, :func:`~os.chmod`, :func:`~os.chown`,
    :func:`~os.link`, :func:`~os.lstat`, :func:`~os.mkdir`, :func:`~os.mkfifo`,
    :func:`~os.mknod`, :func:`~os.open`, :func:`~os.readlink`, :func:`~os.remove`,
    :func:`~os.rename`, :func:`~os.replace`, :func:`~os.rmdir`, :func:`~os.stat`,
    :func:`~os.symlink`, :func:`~os.unlink`, :func:`~os.utime`.  Platform
    support for using these parameters can be checked via the sets
    :data:`os.supports_dir_fd` and :data:`os.supports_follows_symlinks`.

  - The following functions now support a file descriptor for their path argument:
    :func:`~os.chdir`, :func:`~os.chmod`, :func:`~os.chown`,
    :func:`~os.execve`, :func:`~os.listdir`, :func:`~os.pathconf`, :func:`~os.path.exists`,
    :func:`~os.stat`, :func:`~os.statvfs`, :func:`~os.utime`.  Platform support
    for this can be checked via the :data:`os.supports_fd` set.

* :func:`~os.access` accepts an ``effective_ids`` keyword argument to turn on
  using the effective uid/gid rather than the real uid/gid in the access check.
  Platform support for this can be checked via the
  :data:`~os.supports_effective_ids` set.

* The :mod:`os` module has two new functions: :func:`~os.getpriority` and
  :func:`~os.setpriority`. They can be used to get or set process
  niceness/priority in a fashion similar to :func:`os.nice` but extended to all
  processes instead of just the current one.

  (Patch submitted by Giampaolo Rodolà in :issue:`10784`.)

* The new :func:`os.replace` function allows cross-platform renaming of a
  file with overwriting the destination.  With :func:`os.rename`, an existing
  destination file is overwritten under POSIX, but raises an error under
  Windows.
  (Contributed by Antoine Pitrou in :issue:`8828`.)

* The stat family of functions (:func:`~os.stat`, :func:`~os.fstat`,
  and :func:`~os.lstat`) now support reading a file's timestamps
  with nanosecond precision.  Symmetrically, :func:`~os.utime`
  can now write file timestamps with nanosecond precision.  (Contributed by
  Larry Hastings in :issue:`14127`.)

* The new :func:`os.get_terminal_size` function queries the size of the
  terminal attached to a file descriptor. See also
  :func:`shutil.get_terminal_size`.
  (Contributed by Zbigniew Jędrzejewski-Szmek in :issue:`13609`.)

.. XXX sort out this mess after beta1

* New functions to support Linux extended attributes (:issue:`12720`):
  :func:`~os.getxattr`, :func:`~os.listxattr`, :func:`~os.removexattr`,
  :func:`~os.setxattr`.

* New interface to the scheduler. These functions
  control how a process is allocated CPU time by the operating system. New
  functions:
  :func:`~os.sched_get_priority_max`, :func:`~os.sched_get_priority_min`,
  :func:`~os.sched_getaffinity`, :func:`~os.sched_getparam`,
  :func:`~os.sched_getscheduler`, :func:`~os.sched_rr_get_interval`,
  :func:`~os.sched_setaffinity`, :func:`~os.sched_setparam`,
  :func:`~os.sched_setscheduler`, :func:`~os.sched_yield`,

* New functions to control the file system:

  * :func:`~os.posix_fadvise`: Announces an intention to access data in a
    specific pattern thus allowing the kernel to make optimizations.
  * :func:`~os.posix_fallocate`: Ensures that enough disk space is allocated
    for a file.
  * :func:`~os.sync`: Force write of everything to disk.

* Additional new  posix functions:

  * :func:`~os.lockf`: Apply, test or remove a POSIX lock on an open file descriptor.
  * :func:`~os.pread`: Read from a file descriptor at an offset, the file
    offset remains unchanged.
  * :func:`~os.pwrite`: Write to a file descriptor from an offset, leaving
    the file offset unchanged.
  * :func:`~os.readv`: Read from a file descriptor into a number of writable buffers.
  * :func:`~os.truncate`: Truncate the file corresponding to *path*, so that
    it is at most *length* bytes in size.
  * :func:`~os.waitid`: Wait for the completion of one or more child processes.
  * :func:`~os.writev`: Write the contents of *buffers* to a file descriptor,
    where *buffers* is an arbitrary sequence of buffers.
  * :func:`~os.getgrouplist` (:issue:`9344`): Return list of group ids that
    specified user belongs to.

* :func:`~os.times` and :func:`~os.uname`: Return type changed from a tuple to
  a tuple-like object with named attributes.

* Some platforms now support additional constants for the :func:`~os.lseek`
  function, such as ``os.SEEK_HOLE`` and ``os.SEEK_DATA``.

* New constants :data:`~os.RTLD_LAZY`, :data:`~os.RTLD_NOW`,
  :data:`~os.RTLD_GLOBAL`, :data:`~os.RTLD_LOCAL`, :data:`~os.RTLD_NODELETE`,
  :data:`~os.RTLD_NOLOAD`, and :data:`~os.RTLD_DEEPBIND` are available on
  platforms that support them.   These are for use with the
  :func:`sys.setdlopenflags` function, and supersede the similar constants
  defined in :mod:`ctypes` and :mod:`DLFCN`.  (Contributed by Victor Stinner
  in :issue:`13226`.)

* :func:`os.symlink` now accepts (and ignores) the ``target_is_directory``
  keyword argument on non-Windows platforms, to ease cross-platform support.


pdb
---

Tab-completion is now available not only for command names, but also their
arguments.  For example, for the ``break`` command, function and file names
are completed.

(Contributed by Georg Brandl in :issue:`14210`)


pickle
------

:class:`pickle.Pickler` objects now have an optional
:attr:`~pickle.Pickler.dispatch_table` attribute allowing per-pickler
reduction functions to be set.

(Contributed by Richard Oudkerk in :issue:`14166`.)


pydoc
-----

The Tk GUI and the :func:`~pydoc.serve` function have been removed from the
:mod:`pydoc` module: ``pydoc -g`` and :func:`~pydoc.serve` have been deprecated
in Python 3.2.


re
--

:class:`str` regular expressions now support ``\u`` and ``\U`` escapes.

(Contributed by Serhiy Storchaka in :issue:`3665`.)


sched
-----

* :meth:`~sched.scheduler.run` now accepts a *blocking* parameter which when
  set to false makes the method execute the scheduled events due to expire
  soonest (if any) and then return immediately.
  This is useful in case you want to use the :class:`~sched.scheduler` in
  non-blocking applications.  (Contributed by Giampaolo Rodolà in :issue:`13449`.)

* :class:`~sched.scheduler` class can now be safely used in multi-threaded
  environments.  (Contributed by Josiah Carlson and Giampaolo Rodolà in
  :issue:`8684`.)

* *timefunc* and *delayfunct* parameters of :class:`~sched.scheduler` class
  constructor are now optional and defaults to :func:`time.time` and
  :func:`time.sleep` respectively.  (Contributed by Chris Clark in
  :issue:`13245`.)

* :meth:`~sched.scheduler.enter` and :meth:`~sched.scheduler.enterabs`
  *argument* parameter is now optional.  (Contributed by Chris Clark in
  :issue:`13245`.)

* :meth:`~sched.scheduler.enter` and :meth:`~sched.scheduler.enterabs`
  now accept a *kwargs* parameter.  (Contributed by Chris Clark in
  :issue:`13245`.)


select
------

Solaris and derivative platforms have a new class :class:`select.devpoll`
for high performance asynchronous sockets via :file:`/dev/poll`.
(Contributed by Jesús Cea Avión in :issue:`6397`.)


shlex
-----

The previously undocumented helper function ``quote`` from the
:mod:`pipes` modules has been moved to the :mod:`shlex` module and
documented.  :func:`~shlex.quote` properly escapes all characters in a string
that might be otherwise given special meaning by the shell.


shutil
------

* New functions:

  * :func:`~shutil.disk_usage`: provides total, used and free disk space
    statistics.  (Contributed by Giampaolo Rodolà in :issue:`12442`.)
  * :func:`~shutil.chown`: allows one to change user and/or group of the given
    path also specifying the user/group names and not only their numeric
    ids.  (Contributed by Sandro Tosi in :issue:`12191`.)
  * :func:`shutil.get_terminal_size`: returns the size of the terminal window
    to which the interpreter is attached.  (Contributed by Zbigniew
    Jędrzejewski-Szmek in :issue:`13609`.)

* :func:`~shutil.copy2` and :func:`~shutil.copystat` now preserve file
  timestamps with nanosecond precision on platforms that support it.
  They also preserve file "extended attributes" on Linux.  (Contributed
  by Larry Hastings in :issue:`14127` and  :issue:`15238`.)

* Several functions now take an optional ``symlinks`` argument: when that
  parameter is true, symlinks aren't dereferenced and the operation instead
  acts on the symlink itself (or creates one, if relevant).
  (Contributed by Hynek Schlawack in :issue:`12715`.)

* When copying files to a different file system, :func:`~shutil.move` now
  handles symlinks the way the posix ``mv`` command does, recreating the
  symlink rather than copying the target file contents.  (Contributed by
  Jonathan Niehof in :issue:`9993`.)  :func:`~shutil.move` now also returns
  the ``dst`` argument as its result.

* :func:`~shutil.rmtree` is now resistant to symlink attacks on platforms
  which support the new ``dir_fd`` parameter in :func:`os.open` and
  :func:`os.unlink`.  (Contributed by Martin von Löwis and Hynek Schlawack
  in :issue:`4489`.)


signal
------

* The :mod:`signal` module has new functions:

  * :func:`~signal.pthread_sigmask`: fetch and/or change the signal mask of the
    calling thread (Contributed by Jean-Paul Calderone in :issue:`8407`);
  * :func:`~signal.pthread_kill`: send a signal to a thread;
  * :func:`~signal.sigpending`: examine pending functions;
  * :func:`~signal.sigwait`: wait a signal;
  * :func:`~signal.sigwaitinfo`: wait for a signal, returning detailed
    information about it;
  * :func:`~signal.sigtimedwait`: like :func:`~signal.sigwaitinfo` but with a
    timeout.

* The signal handler writes the signal number as a single byte instead of
  a nul byte into the wakeup file descriptor. So it is possible to wait more
  than one signal and know which signals were raised.

* :func:`signal.signal` and :func:`signal.siginterrupt` raise an OSError,
  instead of a RuntimeError: OSError has an errno attribute.


smtpd
-----

The :mod:`smtpd` module now supports :rfc:`5321` (extended SMTP) and :rfc:`1870`
(size extension).  Per the standard, these extensions are enabled if and only
if the client initiates the session with an ``EHLO`` command.

(Initial ``ELHO`` support by Alberto Trevino.  Size extension by Juhana
Jauhiainen.  Substantial additional work on the patch contributed by Michele
Orrù and Dan Boswell.  :issue:`8739`)


smtplib
-------

The :class:`~smtplib.SMTP`, :class:`~smtplib.SMTP_SSL`, and
:class:`~smtplib.LMTP` classes now accept a ``source_address`` keyword argument
to specify the ``(host, port)`` to use as the source address in the bind call
when creating the outgoing socket.  (Contributed by Paulo Scardine in
:issue:`11281`.)

:class:`~smtplib.SMTP` now supports the context management protocol, allowing an
``SMTP`` instance to be used in a ``with`` statement.  (Contributed
by Giampaolo Rodolà in :issue:`11289`.)

The :class:`~smtplib.SMTP_SSL` constructor and the :meth:`~smtplib.SMTP.starttls`
method now accept an SSLContext parameter to control parameters of the secure
channel.  (Contributed by Kasun Herath in :issue:`8809`.)


socket
------

* The :class:`~socket.socket` class now exposes additional methods to process
  ancillary data when supported by the underlying platform:

  * :func:`~socket.socket.sendmsg`
  * :func:`~socket.socket.recvmsg`
  * :func:`~socket.socket.recvmsg_into`

  (Contributed by David Watson in :issue:`6560`, based on an earlier patch by
  Heiko Wundram)

* The :class:`~socket.socket` class now supports the PF_CAN protocol family
  (https://en.wikipedia.org/wiki/Socketcan), on Linux
  (https://lwn.net/Articles/253425).

  (Contributed by Matthias Fuchs, updated by Tiago Gonçalves in :issue:`10141`.)

* The :class:`~socket.socket` class now supports the PF_RDS protocol family
  (https://en.wikipedia.org/wiki/Reliable_Datagram_Sockets and
  https://oss.oracle.com/projects/rds/).

* The :class:`~socket.socket` class now supports the ``PF_SYSTEM`` protocol
  family on OS X.  (Contributed by Michael Goderbauer in :issue:`13777`.)

* New function :func:`~socket.sethostname` allows the hostname to be set
  on unix systems if the calling process has sufficient privileges.
  (Contributed by Ross Lagerwall in :issue:`10866`.)


socketserver
------------

:class:`~socketserver.BaseServer` now has an overridable method
:meth:`~socketserver.BaseServer.service_actions` that is called by the
:meth:`~socketserver.BaseServer.serve_forever` method in the service loop.
:class:`~socketserver.ForkingMixIn` now uses this to clean up zombie
child processes.  (Contributed by Justin Warkentin in :issue:`11109`.)


sqlite3
-------

New :class:`sqlite3.Connection` method
:meth:`~sqlite3.Connection.set_trace_callback` can be used to capture a trace of
all sql commands processed by sqlite.  (Contributed by Torsten Landschoff
in :issue:`11688`.)


ssl
---

* The :mod:`ssl` module has two new random generation functions:

  * :func:`~ssl.RAND_bytes`: generate cryptographically strong
    pseudo-random bytes.
  * :func:`~ssl.RAND_pseudo_bytes`: generate pseudo-random bytes.

  (Contributed by Victor Stinner in :issue:`12049`.)

* The :mod:`ssl` module now exposes a finer-grained exception hierarchy
  in order to make it easier to inspect the various kinds of errors.
  (Contributed by Antoine Pitrou in :issue:`11183`.)

* :meth:`~ssl.SSLContext.load_cert_chain` now accepts a *password* argument
  to be used if the private key is encrypted.
  (Contributed by Adam Simpkins in :issue:`12803`.)

* Diffie-Hellman key exchange, both regular and Elliptic Curve-based, is
  now supported through the :meth:`~ssl.SSLContext.load_dh_params` and
  :meth:`~ssl.SSLContext.set_ecdh_curve` methods.
  (Contributed by Antoine Pitrou in :issue:`13626` and :issue:`13627`.)

* SSL sockets have a new :meth:`~ssl.SSLSocket.get_channel_binding` method
  allowing the implementation of certain authentication mechanisms such as
  SCRAM-SHA-1-PLUS.  (Contributed by Jacek Konieczny in :issue:`12551`.)

* You can query the SSL compression algorithm used by an SSL socket, thanks
  to its new :meth:`~ssl.SSLSocket.compression` method.  The new attribute
  :attr:`~ssl.OP_NO_COMPRESSION` can be used to disable compression.
  (Contributed by Antoine Pitrou in :issue:`13634`.)

* Support has been added for the Next Protocol Negotiation extension using
  the :meth:`ssl.SSLContext.set_npn_protocols` method.
  (Contributed by Colin Marc in :issue:`14204`.)

* SSL errors can now be introspected more easily thanks to
  :attr:`~ssl.SSLError.library` and :attr:`~ssl.SSLError.reason` attributes.
  (Contributed by Antoine Pitrou in :issue:`14837`.)

* The :func:`~ssl.get_server_certificate` function now supports IPv6.
  (Contributed by Charles-François Natali in :issue:`11811`.)

* New attribute :attr:`~ssl.OP_CIPHER_SERVER_PREFERENCE` allows setting
  SSLv3 server sockets to use the server's cipher ordering preference rather
  than the client's (:issue:`13635`).


stat
----

The undocumented tarfile.filemode function has been moved to
:func:`stat.filemode`. It can be used to convert a file's mode to a string of
the form '-rwxrwxrwx'.

(Contributed by Giampaolo Rodolà in :issue:`14807`.)


struct
------

The :mod:`struct` module now supports ``ssize_t`` and ``size_t`` via the
new codes ``n`` and ``N``, respectively.  (Contributed by Antoine Pitrou
in :issue:`3163`.)


subprocess
----------

Command strings can now be bytes objects on posix platforms.  (Contributed by
Victor Stinner in :issue:`8513`.)

A new constant :data:`~subprocess.DEVNULL` allows suppressing output in a
platform-independent fashion.  (Contributed by Ross Lagerwall in
:issue:`5870`.)


sys
---

The :mod:`sys` module has a new :data:`~sys.thread_info` :term:`struct
sequence` holding information about the thread implementation
(:issue:`11223`).


tarfile
-------

:mod:`tarfile` now supports ``lzma`` encoding via the :mod:`lzma` module.
(Contributed by Lars Gustäbel in :issue:`5689`.)


tempfile
--------

:class:`tempfile.SpooledTemporaryFile`\'s
:meth:`~tempfile.SpooledTemporaryFile.truncate` method now accepts
a ``size`` parameter.  (Contributed by Ryan Kelly in :issue:`9957`.)


textwrap
--------

The :mod:`textwrap` module has a new :func:`~textwrap.indent` that makes
it straightforward to add a common prefix to selected lines in a block
of text  (:issue:`13857`).


threading
---------

:class:`threading.Condition`, :class:`threading.Semaphore`,
:class:`threading.BoundedSemaphore`, :class:`threading.Event`, and
:class:`threading.Timer`, all of which used to be factory functions returning a
class instance, are now classes and may be subclassed.  (Contributed by Éric
Araujo in :issue:`10968`.)

The :class:`threading.Thread` constructor now accepts a ``daemon`` keyword
argument to override the default behavior of inheriting the ``daemon`` flag
value from the parent thread (:issue:`6064`).

The formerly private function ``_thread.get_ident`` is now available as the
public function :func:`threading.get_ident`.  This eliminates several cases of
direct access to the ``_thread`` module in the stdlib.  Third party code that
used ``_thread.get_ident`` should likewise be changed to use the new public
interface.


time
----

The :pep:`418` added new functions to the :mod:`time` module:

* :func:`~time.get_clock_info`: Get information on a clock.
* :func:`~time.monotonic`: Monotonic clock (cannot go backward), not affected
  by system clock updates.
* :func:`~time.perf_counter`: Performance counter with the highest available
  resolution to measure a short duration.
* :func:`~time.process_time`: Sum of the system and user CPU time of the
  current process.

Other new functions:

* :func:`~time.clock_getres`, :func:`~time.clock_gettime` and
  :func:`~time.clock_settime` functions with ``CLOCK_xxx`` constants.
  (Contributed by Victor Stinner in :issue:`10278`.)

To improve cross platform consistency, :func:`~time.sleep` now raises a
:exc:`ValueError` when passed a negative sleep value.  Previously this was an
error on posix, but produced an infinite sleep on Windows.


types
-----

Add a new :class:`types.MappingProxyType` class: Read-only proxy of a mapping.
(:issue:`14386`)


The new functions :func:`types.new_class` and :func:`types.prepare_class` provide support
for PEP 3115 compliant dynamic type creation. (:issue:`14588`)


unittest
--------

:meth:`.assertRaises`, :meth:`.assertRaisesRegex`, :meth:`.assertWarns`, and
:meth:`.assertWarnsRegex` now accept a keyword argument *msg* when used as
context managers.  (Contributed by Ezio Melotti and Winston Ewert in
:issue:`10775`.)

:meth:`unittest.TestCase.run` now returns the :class:`~unittest.TestResult`
object.


urllib
------

The :class:`~urllib.request.Request` class, now accepts a *method* argument
used by :meth:`~urllib.request.Request.get_method` to determine what HTTP method
should be used.  For example, this will send a ``'HEAD'`` request::

   >>> urlopen(Request('https://www.python.org', method='HEAD'))

(:issue:`1673007`)


webbrowser
----------

The :mod:`webbrowser` module supports more "browsers": Google Chrome (named
:program:`chrome`, :program:`chromium`, :program:`chrome-browser` or
:program:`chromium-browser` depending on the version and operating system),
and the generic launchers :program:`xdg-open`, from the FreeDesktop.org
project, and :program:`gvfs-open`, which is the default URI handler for GNOME
3.  (The former contributed by Arnaud Calmettes in :issue:`13620`, the latter
by Matthias Klose in :issue:`14493`.)


xml.etree.ElementTree
---------------------

The :mod:`xml.etree.ElementTree` module now imports its C accelerator by
default; there is no longer a need to explicitly import
:mod:`xml.etree.cElementTree` (this module stays for backwards compatibility,
but is now deprecated).  In addition,  the ``iter`` family of methods of
:class:`~xml.etree.ElementTree.Element` has been optimized (rewritten in C).
The module's documentation has also been greatly improved with added examples
and a more detailed reference.


zlib
----

New attribute :attr:`zlib.Decompress.eof` makes it possible to distinguish
between a properly-formed compressed stream and an incomplete or truncated one.
(Contributed by Nadeem Vawda in :issue:`12646`.)

New attribute :attr:`zlib.ZLIB_RUNTIME_VERSION` reports the version string of
the underlying ``zlib`` library that is loaded at runtime.  (Contributed by
Torsten Landschoff in :issue:`12306`.)


Optimizations
=============

Major performance enhancements have been added:

* Thanks to :pep:`393`, some operations on Unicode strings have been optimized:

  * the memory footprint is divided by 2 to 4 depending on the text
  * encode an ASCII string to UTF-8 doesn't need to encode characters anymore,
    the UTF-8 representation is shared with the ASCII representation
  * the UTF-8 encoder has been optimized
  * repeating a single ASCII letter and getting a substring of an ASCII string
    is 4 times faster

* UTF-8 is now 2x to 4x faster.  UTF-16 encoding is now up to 10x faster.

  (Contributed by Serhiy Storchaka, :issue:`14624`, :issue:`14738` and
  :issue:`15026`.)


Build and C API Changes
=======================

Changes to Python's build process and to the C API include:

* New :pep:`3118` related function:

  * :c:func:`PyMemoryView_FromMemory`

* :pep:`393` added new Unicode types, macros and functions:

  * High-level API:

    * :c:func:`PyUnicode_CopyCharacters`
    * :c:func:`PyUnicode_FindChar`
    * :c:func:`PyUnicode_GetLength`, :c:macro:`PyUnicode_GET_LENGTH`
    * :c:func:`PyUnicode_New`
    * :c:func:`PyUnicode_Substring`
    * :c:func:`PyUnicode_ReadChar`, :c:func:`PyUnicode_WriteChar`

  * Low-level API:

    * :c:type:`Py_UCS1`, :c:type:`Py_UCS2`, :c:type:`Py_UCS4` types
    * :c:type:`PyASCIIObject` and :c:type:`PyCompactUnicodeObject` structures
    * :c:macro:`PyUnicode_READY`
    * :c:func:`PyUnicode_FromKindAndData`
    * :c:func:`PyUnicode_AsUCS4`, :c:func:`PyUnicode_AsUCS4Copy`
    * :c:macro:`PyUnicode_DATA`, :c:macro:`PyUnicode_1BYTE_DATA`,
      :c:macro:`PyUnicode_2BYTE_DATA`, :c:macro:`PyUnicode_4BYTE_DATA`
    * :c:macro:`PyUnicode_KIND` with :c:type:`PyUnicode_Kind` enum:
      :c:data:`PyUnicode_WCHAR_KIND`, :c:data:`PyUnicode_1BYTE_KIND`,
      :c:data:`PyUnicode_2BYTE_KIND`, :c:data:`PyUnicode_4BYTE_KIND`
    * :c:macro:`PyUnicode_READ`, :c:macro:`PyUnicode_READ_CHAR`, :c:macro:`PyUnicode_WRITE`
    * :c:macro:`PyUnicode_MAX_CHAR_VALUE`

* :c:macro:`PyArg_ParseTuple` now accepts a :class:`bytearray` for the ``c``
  format (:issue:`12380`).



Deprecated
==========

Unsupported Operating Systems
-----------------------------

OS/2 and VMS are no longer supported due to the lack of a maintainer.

Windows 2000 and Windows platforms which set ``COMSPEC`` to ``command.com``
are no longer supported due to maintenance burden.

OSF support, which was deprecated in 3.2, has been completely removed.


Deprecated Python modules, functions and methods
------------------------------------------------

* Passing a non-empty string to ``object.__format__()`` is deprecated, and
  will produce a :exc:`TypeError` in Python 3.4 (:issue:`9856`).
* The ``unicode_internal`` codec has been deprecated because of the
  :pep:`393`, use UTF-8, UTF-16 (``utf-16-le`` or ``utf-16-be``), or UTF-32
  (``utf-32-le`` or ``utf-32-be``)
* :meth:`ftplib.FTP.nlst` and :meth:`ftplib.FTP.dir`: use
  :meth:`ftplib.FTP.mlsd`
* :func:`platform.popen`: use the :mod:`subprocess` module. Check especially
  the :ref:`subprocess-replacements` section (:issue:`11377`).
* :issue:`13374`: The Windows bytes API has been deprecated in the :mod:`os`
  module. Use Unicode filenames, instead of bytes filenames, to not depend on
  the ANSI code page anymore and to support any filename.
* :issue:`13988`: The :mod:`xml.etree.cElementTree` module is deprecated.  The
  accelerator is used automatically whenever available.
* The behaviour of :func:`time.clock` depends on the platform: use the new
  :func:`time.perf_counter` or :func:`time.process_time` function instead,
  depending on your requirements, to have a well defined behaviour.
* The :func:`os.stat_float_times` function is deprecated.
* :mod:`abc` module:

  * :class:`abc.abstractproperty` has been deprecated, use :class:`property`
    with :func:`abc.abstractmethod` instead.
  * :class:`abc.abstractclassmethod` has been deprecated, use
    :class:`classmethod` with :func:`abc.abstractmethod` instead.
  * :class:`abc.abstractstaticmethod` has been deprecated, use
    :class:`staticmethod` with :func:`abc.abstractmethod` instead.

* :mod:`importlib` package:

  * :meth:`importlib.abc.SourceLoader.path_mtime` is now deprecated in favour of
    :meth:`importlib.abc.SourceLoader.path_stats` as bytecode files now store
    both the modification time and size of the source file the bytecode file was
    compiled from.





Deprecated functions and types of the C API
-------------------------------------------

The :c:type:`Py_UNICODE` has been deprecated by :pep:`393` and will be
removed in Python 4. All functions using this type are deprecated:

Unicode functions and methods using :c:type:`Py_UNICODE` and
:c:type:`Py_UNICODE*` types:

* :c:macro:`PyUnicode_FromUnicode`: use :c:func:`PyUnicode_FromWideChar` or
  :c:func:`PyUnicode_FromKindAndData`
* :c:macro:`PyUnicode_AS_UNICODE`, :c:func:`PyUnicode_AsUnicode`,
  :c:func:`PyUnicode_AsUnicodeAndSize`: use :c:func:`PyUnicode_AsWideCharString`
* :c:macro:`PyUnicode_AS_DATA`: use :c:macro:`PyUnicode_DATA` with
  :c:macro:`PyUnicode_READ` and :c:macro:`PyUnicode_WRITE`
* :c:macro:`PyUnicode_GET_SIZE`, :c:func:`PyUnicode_GetSize`: use
  :c:macro:`PyUnicode_GET_LENGTH` or :c:func:`PyUnicode_GetLength`
* :c:macro:`PyUnicode_GET_DATA_SIZE`: use
  ``PyUnicode_GET_LENGTH(str) * PyUnicode_KIND(str)`` (only work on ready
  strings)
* :c:func:`PyUnicode_AsUnicodeCopy`: use :c:func:`PyUnicode_AsUCS4Copy` or
  :c:func:`PyUnicode_AsWideCharString`
* :c:func:`PyUnicode_GetMax`


Functions and macros manipulating Py_UNICODE* strings:

* :c:macro:`Py_UNICODE_strlen`: use :c:func:`PyUnicode_GetLength` or
  :c:macro:`PyUnicode_GET_LENGTH`
* :c:macro:`Py_UNICODE_strcat`: use :c:func:`PyUnicode_CopyCharacters` or
  :c:func:`PyUnicode_FromFormat`
* :c:macro:`Py_UNICODE_strcpy`, :c:macro:`Py_UNICODE_strncpy`,
  :c:macro:`Py_UNICODE_COPY`: use :c:func:`PyUnicode_CopyCharacters` or
  :c:func:`PyUnicode_Substring`
* :c:macro:`Py_UNICODE_strcmp`: use :c:func:`PyUnicode_Compare`
* :c:macro:`Py_UNICODE_strncmp`: use :c:func:`PyUnicode_Tailmatch`
* :c:macro:`Py_UNICODE_strchr`, :c:macro:`Py_UNICODE_strrchr`: use
  :c:func:`PyUnicode_FindChar`
* :c:macro:`Py_UNICODE_FILL`: use :c:func:`PyUnicode_Fill`
* :c:macro:`Py_UNICODE_MATCH`

Encoders:

* :c:func:`PyUnicode_Encode`: use :c:func:`PyUnicode_AsEncodedObject`
* :c:func:`PyUnicode_EncodeUTF7`
* :c:func:`PyUnicode_EncodeUTF8`: use :c:func:`PyUnicode_AsUTF8` or
  :c:func:`PyUnicode_AsUTF8String`
* :c:func:`PyUnicode_EncodeUTF32`
* :c:func:`PyUnicode_EncodeUTF16`
* :c:func:`PyUnicode_EncodeUnicodeEscape:` use
  :c:func:`PyUnicode_AsUnicodeEscapeString`
* :c:func:`PyUnicode_EncodeRawUnicodeEscape:` use
  :c:func:`PyUnicode_AsRawUnicodeEscapeString`
* :c:func:`PyUnicode_EncodeLatin1`: use :c:func:`PyUnicode_AsLatin1String`
* :c:func:`PyUnicode_EncodeASCII`: use :c:func:`PyUnicode_AsASCIIString`
* :c:func:`PyUnicode_EncodeCharmap`
* :c:func:`PyUnicode_TranslateCharmap`
* :c:func:`PyUnicode_EncodeMBCS`: use :c:func:`PyUnicode_AsMBCSString` or
  :c:func:`PyUnicode_EncodeCodePage` (with ``CP_ACP`` code_page)
* :c:func:`PyUnicode_EncodeDecimal`,
  :c:func:`PyUnicode_TransformDecimalToASCII`


Deprecated features
-------------------

The :mod:`array` module's ``'u'`` format code is now deprecated and will be
removed in Python 4 together with the rest of the (:c:type:`Py_UNICODE`) API.


Porting to Python 3.3
=====================

This section lists previously described changes and other bugfixes
that may require changes to your code.

.. _portingpythoncode:

Porting Python code
-------------------

* Hash randomization is enabled by default. Set the :envvar:`PYTHONHASHSEED`
  environment variable to ``0`` to disable hash randomization. See also the
  :meth:`object.__hash__` method.

* :issue:`12326`: On Linux, sys.platform doesn't contain the major version
  anymore. It is now always 'linux', instead of 'linux2' or 'linux3' depending
  on the Linux version used to build Python. Replace sys.platform == 'linux2'
  with sys.platform.startswith('linux'), or directly sys.platform == 'linux' if
  you don't need to support older Python versions.

* :issue:`13847`, :issue:`14180`: :mod:`time` and :mod:`datetime`:
  :exc:`OverflowError` is now raised instead of :exc:`ValueError` if a
  timestamp is out of range. :exc:`OSError` is now raised if C functions
  :c:func:`gmtime` or :c:func:`localtime` failed.

* The default finders used by import now utilize a cache of what is contained
  within a specific directory. If you create a Python source file or sourceless
  bytecode file, make sure to call :func:`importlib.invalidate_caches` to clear
  out the cache for the finders to notice the new file.

* :exc:`ImportError` now uses the full name of the module that was attempted to
  be imported. Doctests that check ImportErrors' message will need to be
  updated to use the full name of the module instead of just the tail of the
  name.

* The *index* argument to :func:`__import__` now defaults to 0 instead of -1
  and no longer support negative values. It was an oversight when :pep:`328` was
  implemented that the default value remained -1. If you need to continue to
  perform a relative import followed by an absolute import, then perform the
  relative import using an index of 1, followed by another import using an
  index of 0. It is preferred, though, that you use
  :func:`importlib.import_module` rather than call :func:`__import__` directly.

* :func:`__import__` no longer allows one to use an index value other than 0
  for top-level modules. E.g. ``__import__('sys', level=1)`` is now an error.

* Because :attr:`sys.meta_path` and :attr:`sys.path_hooks` now have finders on
  them by default, you will most likely want to use :meth:`list.insert` instead
  of :meth:`list.append` to add to those lists.

* Because ``None`` is now inserted into :attr:`sys.path_importer_cache`, if you
  are clearing out entries in the dictionary of paths that do not have a
  finder, you will need to remove keys paired with values of ``None`` **and**
  :class:`imp.NullImporter` to be backwards-compatible. This will lead to extra
  overhead on older versions of Python that re-insert ``None`` into
  :attr:`sys.path_importer_cache` where it represents the use of implicit
  finders, but semantically it should not change anything.

* :class:`importlib.abc.Finder` no longer specifies a `find_module()` abstract
  method that must be implemented. If you were relying on subclasses to
  implement that method, make sure to check for the method's existence first.
  You will probably want to check for `find_loader()` first, though, in the
  case of working with :term:`path entry finders <path entry finder>`.

* :mod:`pkgutil` has been converted to use :mod:`importlib` internally. This
  eliminates many edge cases where the old behaviour of the PEP 302 import
  emulation failed to match the behaviour of the real import system. The
  import emulation itself is still present, but is now deprecated. The
  :func:`pkgutil.iter_importers` and :func:`pkgutil.walk_packages` functions
  special case the standard import hooks so they are still supported even
  though they do not provide the non-standard ``iter_modules()`` method.

* A longstanding RFC-compliance bug (:issue:`1079`) in the parsing done by
  :func:`email.header.decode_header` has been fixed.  Code that uses the
  standard idiom to convert encoded headers into unicode
  (``str(make_header(decode_header(h))``) will see no change, but code that
  looks at the individual tuples returned by decode_header will see that
  whitespace that precedes or follows ``ASCII`` sections is now included in the
  ``ASCII`` section.  Code that builds headers using ``make_header`` should
  also continue to work without change, since ``make_header`` continues to add
  whitespace between ``ASCII`` and non-``ASCII`` sections if it is not already
  present in the input strings.

* :func:`email.utils.formataddr` now does the correct content transfer
  encoding when passed non-``ASCII`` display names.  Any code that depended on
  the previous buggy behavior that preserved the non-``ASCII`` unicode in the
  formatted output string will need to be changed (:issue:`1690608`).

* :meth:`poplib.POP3.quit` may now raise protocol errors like all other
  ``poplib`` methods.  Code that assumes ``quit`` does not raise
  :exc:`poplib.error_proto` errors may need to be changed if errors on ``quit``
  are encountered by a particular application (:issue:`11291`).

* The ``strict`` argument to :class:`email.parser.Parser`, deprecated since
  Python 2.4, has finally been removed.

* The deprecated method ``unittest.TestCase.assertSameElements`` has been
  removed.

* The deprecated variable ``time.accept2dyear`` has been removed.

* The deprecated ``Context._clamp`` attribute has been removed from the
  :mod:`decimal` module.  It was previously replaced by the public attribute
  :attr:`~decimal.Context.clamp`.  (See :issue:`8540`.)

* The undocumented internal helper class ``SSLFakeFile`` has been removed
  from :mod:`smtplib`, since its functionality has long been provided directly
  by :meth:`socket.socket.makefile`.

* Passing a negative value to :func:`time.sleep` on Windows now raises an
  error instead of sleeping forever.  It has always raised an error on posix.

* The ``ast.__version__`` constant has been removed.  If you need to
  make decisions affected by the AST version, use :attr:`sys.version_info`
  to make the decision.

* Code that used to work around the fact that the :mod:`threading` module used
  factory functions by subclassing the private classes will need to change to
  subclass the now-public classes.

* The undocumented debugging machinery in the threading module has been
  removed, simplifying the code.  This should have no effect on production
  code, but is mentioned here in case any application debug frameworks were
  interacting with it (:issue:`13550`).


Porting C code
--------------

* In the course of changes to the buffer API the undocumented
  :c:member:`~Py_buffer.smalltable` member of the
  :c:type:`Py_buffer` structure has been removed and the
  layout of the :c:type:`PyMemoryViewObject` has changed.

  All extensions relying on the relevant parts in ``memoryobject.h``
  or ``object.h`` must be rebuilt.

* Due to :ref:`PEP 393 <pep-393>`, the :c:type:`Py_UNICODE` type and all
  functions using this type are deprecated (but will stay available for
  at least five years).  If you were using low-level Unicode APIs to
  construct and access unicode objects and you want to benefit of the
  memory footprint reduction provided by PEP 393, you have to convert
  your code to the new :doc:`Unicode API <../c-api/unicode>`.

  However, if you only have been using high-level functions such as
  :c:func:`PyUnicode_Concat()`, :c:func:`PyUnicode_Join` or
  :c:func:`PyUnicode_FromFormat()`, your code will automatically take
  advantage of the new unicode representations.

* :c:func:`PyImport_GetMagicNumber` now returns ``-1`` upon failure.

* As a negative value for the *level* argument to :func:`__import__` is no
  longer valid, the same now holds for :c:func:`PyImport_ImportModuleLevel`.
  This also means that the value of *level* used by
  :c:func:`PyImport_ImportModuleEx` is now ``0`` instead of ``-1``.


Building C extensions
---------------------

* The range of possible file names for C extensions has been narrowed.
  Very rarely used spellings have been suppressed: under POSIX, files
  named ``xxxmodule.so``, ``xxxmodule.abi3.so`` and
  ``xxxmodule.cpython-*.so`` are no longer recognized as implementing
  the ``xxx`` module.  If you had been generating such files, you have
  to switch to the other spellings (i.e., remove the ``module`` string
  from the file names).

  (implemented in :issue:`14040`.)


Command Line Switch Changes
---------------------------

* The -Q command-line flag and related artifacts have been removed.  Code
  checking sys.flags.division_warning will need updating.

  (:issue:`10998`, contributed by Éric Araujo.)

* When :program:`python` is started with :option:`-S`, ``import site``
  will no longer add site-specific paths to the module search paths.  In
  previous versions, it did.

  (:issue:`11591`, contributed by Carl Meyer with editions by Éric Araujo.)