summaryrefslogtreecommitdiffstats
path: root/Doc/whatsnew/3.7.rst
blob: a92ad9f1df40078415d9719f6852d854ada90310 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
****************************
  What's New In Python 3.7
****************************

:Release: |release|
:Date: |today|

.. Rules for maintenance:

   * Anyone can add text to this document.  Do not spend very much time
   on the wording of your changes, because your text will probably
   get rewritten to some degree.

   * The maintainer will go through Misc/NEWS periodically and add
   changes; it's therefore more important to add your changes to
   Misc/NEWS than to this file.

   * This is not a complete list of every single change; completeness
   is the purpose of Misc/NEWS.  Some changes I consider too small
   or esoteric to include.  If such a change is added to the text,
   I'll just remove it.  (This is another reason you shouldn't spend
   too much time on writing your addition.)

   * If you want to draw your new text to the attention of the
   maintainer, add 'XXX' to the beginning of the paragraph or
   section.

   * It's OK to just add a fragmentary note about a change.  For
   example: "XXX Describe the transmogrify() function added to the
   socket module."  The maintainer will research the change and
   write the necessary text.

   * You can comment out your additions if you like, but it's not
   necessary (especially when a final release is some months away).

   * Credit the author of a patch or bugfix.   Just the name is
   sufficient; the e-mail address isn't necessary.

   * It's helpful to add the bug/patch number as a comment:

   XXX Describe the transmogrify() function added to the socket
   module.
   (Contributed by P.Y. Developer in :issue:`12345`.)

   This saves the maintainer the effort of going through the Mercurial log
   when researching a change.

This article explains the new features in Python 3.7, compared to 3.6.

For full details, see the :ref:`changelog <changelog>`.

.. note::

   Prerelease users should be aware that this document is currently in draft
   form. It will be updated substantially as Python 3.7 moves towards release,
   so it's worth checking back even after reading earlier versions.


Summary -- Release highlights
=============================

.. This section singles out the most important changes in Python 3.7.
   Brevity is key.


.. PEP-sized items next.



New Features
============

.. _whatsnew37-pep538:

PEP 538: Legacy C Locale Coercion
---------------------------------

An ongoing challenge within the Python 3 series has been determining a sensible
default strategy for handling the "7-bit ASCII" text encoding assumption
currently implied by the use of the default C locale on non-Windows platforms.

:pep:`538` updates the default interpreter command line interface to
automatically coerce that locale to an available UTF-8 based locale as
described in the documentation of the new :envvar:`PYTHONCOERCECLOCALE`
environment variable. Automatically setting ``LC_CTYPE`` this way means that
both the core interpreter and locale-aware C extensions (such as
:mod:`readline`) will assume the use of UTF-8 as the default text encoding,
rather than ASCII.

The platform support definition in :pep:`11` has also been updated to limit
full text handling support to suitably configured non-ASCII based locales.

As part of this change, the default error handler for ``stdin`` and ``stdout``
is now ``surrogateescape`` (rather than ``strict``) when using any of the
defined coercion target locales (currently ``C.UTF-8``, ``C.utf8``, and
``UTF-8``). The default error handler for ``stderr`` continues to be
``backslashreplace``, regardless of locale.

Locale coercion is silent by default, but to assist in debugging potentially
locale related integration problems, explicit warnings (emitted directly on
``stderr`` can be requested by setting ``PYTHONCOERCECLOCALE=warn``. This
setting will also cause the Python runtime to emit a warning if the legacy C
locale remains active when the core interpreter is initialized.

.. seealso::

    :pep:`538` -- Coercing the legacy C locale to a UTF-8 based locale
       PEP written and implemented by Nick Coghlan.


Other Language Changes
======================

* More than 255 arguments can now be passed to a function, and a function can
  now have more than 255 parameters. (Contributed by Serhiy Storchaka in
  :issue:`12844` and :issue:`18896`.)

* :meth:`bytes.fromhex` and :meth:`bytearray.fromhex` now ignore all ASCII
  whitespace, not only spaces. (Contributed by Robert Xiao in :issue:`28927`.)

* :exc:`ImportError` now displays module name and module ``__file__`` path when
  ``from ... import ...`` fails. (Contributed by Matthias Bussonnier in :issue:`29546`.)

* Circular imports involving absolute imports with binding a submodule to
  a name are now supported.
  (Contributed by Serhiy Storchaka in :issue:`30024`.)

* ``object.__format__(x, '')`` is now equivalent to ``str(x)`` rather than
  ``format(str(self), '')``.
  (Contributed by Serhiy Storchaka in :issue:`28974`.)


New Modules
===========

* None yet.


Improved Modules
================


binascii
--------

The :func:`~binascii.b2a_uu` function now accepts an optional *backtick*
keyword argument.  When it's true, zeros are represented by ``'`'``
instead of spaces.  (Contributed by Xiang Zhang in :issue:`30103`.)


calendar
--------

The class :class:`~calendar.HTMLCalendar` has new class attributes which ease
the customisation of the CSS classes in the produced HTML calendar.
(Contributed by Oz Tiram in :issue:`30095`.)

cgi
---

:func:`~cgi.parse_multipart` returns the same results as
:class:`~FieldStorage` : for non-file fields, the value associated to a key
is a list of strings, not bytes.
(Contributed by Pierre Quentel in :issue:`29979`.)

contextlib
----------

:func:`contextlib.asynccontextmanager` has been added. (Contributed by
Jelle Zijlstra in :issue:`29679`.)

dis
---

The :func:`~dis.dis` function now is able to
disassemble nested code objects (the code of comprehensions, generator
expressions and nested functions, and the code used for building nested
classes).  (Contributed by Serhiy Storchaka in :issue:`11822`.)

distutils
---------

README.rst is now included in the list of distutils standard READMEs and
therefore included in source distributions.
(Contributed by Ryan Gonzalez in :issue:`11913`.)

http.server
-----------

:class:`~http.server.SimpleHTTPRequestHandler` supports the HTTP
If-Modified-Since header. The server returns the 304 response status if the
target file was not modified after the time specified in the header.
(Contributed by Pierre Quentel in :issue:`29654`.)

Add the parameter ``directory`` to the :class:`~http.server.SimpleHTTPRequestHandler`
and the ``--directory`` to the command line of the module :mod:`~http.server`.
With this parameter, the server serves the specified directory, by default it uses the current working directory.
(Contributed by Stéphane Wirtel and Julien Palard in :issue:`28707`.)

locale
------

Added another argument *monetary* in :meth:`format_string` of :mod:`locale`.
If *monetary* is true, the conversion uses monetary thousands separator and
grouping strings. (Contributed by Garvit in :issue:`10379`.)

math
----

New :func:`~math.remainder` function, implementing the IEEE 754-style remainder
operation. (Contributed by Mark Dickinson in :issue:`29962`.)

os
--

Added support for :class:`bytes` paths in :func:`~os.fwalk`. (Contributed by
Serhiy Storchaka in :issue:`28682`.)

Added support for :ref:`file descriptors <path_fd>` in :func:`~os.scandir`
on Unix.  (Contributed by Serhiy Storchaka in :issue:`25996`.)

New function :func:`os.register_at_fork` allows registering Python callbacks
to be executed on a process fork.  (Contributed by Antoine Pitrou in
:issue:`16500`.)

unittest.mock
-------------

The :const:`~unittest.mock.sentinel` attributes now preserve their identity
when they are :mod:`copied <copy>` or :mod:`pickled <pickle>`. (Contributed by
Serhiy Storchaka in :issue:`20804`.)

xmlrpc.server
-------------

:meth:`register_function` of :class:`xmlrpc.server.SimpleXMLRPCDispatcher` and
its subclasses can be used as a decorator. (Contributed by Xiang Zhang in
:issue:`7769`.)

unicodedata
-----------

The internal :mod:`unicodedata` database has been upgraded to use `Unicode 10
<http://www.unicode.org/versions/Unicode10.0.0/>`_. (Contributed by Benjamin
Peterson.)

urllib.parse
------------

:func:`urllib.parse.quote` has been updated from RFC 2396 to RFC 3986,
adding `~` to the set of characters that is never quoted by default.
(Contributed by Christian Theune and Ratnadeep Debnath in :issue:`16285`.)

uu
--

Function :func:`~uu.encode` now accepts an optional *backtick*
keyword argument.  When it's true, zeros are represented by ``'`'``
instead of spaces.  (Contributed by Xiang Zhang in :issue:`30103`.)


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

* Added two new opcodes: ``LOAD_METHOD`` and ``CALL_METHOD`` to avoid
  instantiation of bound method objects for method calls, which results
  in method calls being faster up to 20%. (Contributed by Yury Selivanov and
  INADA Naoki in :issue:`26110`.)

* Searching some unlucky Unicode characters (like Ukrainian capital "Є")
  in a string was to 25 times slower than searching other characters.
  Now it is slower only by 3 times in worst case.
  (Contributed by Serhiy Storchaka in :issue:`24821`.)

* Fast implementation from standard C library is now used for functions
  :func:`~math.tgamma`, :func:`~math.lgamma`, :func:`~math.erf` and
  :func:`~math.erfc` in the :mod:`math` module. (Contributed by Serhiy
  Storchaka in :issue:`26121`.)

* The :func:`os.fwalk` function has been sped up by 2 times.  This was done
  using the :func:`os.scandir` function.
  (Contributed by Serhiy Storchaka in :issue:`25996`.)

* Optimized case-insensitive matching and searching of :mod:`regular
  expressions <re>`.  Searching some patterns can now be up to 20 times faster.
  (Contributed by Serhiy Storchaka in :issue:`30285`.)

* :meth:`selectors.EpollSelector.modify`, :meth:`selectors.PollSelector.modify`
  and :meth:`selectors.DevpollSelector.modify` may be around 10% faster under
  heavy loads. (Contributed by Giampaolo Rodola' in :issue:`30014`)

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

* A full copy of libffi is no longer bundled for use when building the
  :mod:`_ctypes <ctypes>` module on non-OSX UNIX platforms.  An installed copy
  of libffi is now required when building ``_ctypes`` on such platforms.
  Contributed by Zachary Ware in :issue:`27979`.

* The fields :c:member:`name` and :c:member:`doc` of structures
  :c:type:`PyMemberDef`, :c:type:`PyGetSetDef`,
  :c:type:`PyStructSequence_Field`, :c:type:`PyStructSequence_Desc`,
  and :c:type:`wrapperbase` are now of type ``const char *`` rather of
  ``char *``.  (Contributed by Serhiy Storchaka in :issue:`28761`.)

* The result of :c:func:`PyUnicode_AsUTF8AndSize` and :c:func:`PyUnicode_AsUTF8`
  is now of type ``const char *`` rather of ``char *``. (Contributed by Serhiy
  Storchaka in :issue:`28769`.)

* Added functions :c:func:`PySlice_Unpack` and :c:func:`PySlice_AdjustIndices`.
  (Contributed by Serhiy Storchaka in :issue:`27867`.)

* :c:func:`PyOS_AfterFork` is deprecated in favour of the new functions
  :c:func:`PyOS_BeforeFork`, :c:func:`PyOS_AfterFork_Parent` and
  :c:func:`PyOS_AfterFork_Child`.  (Contributed by Antoine Pitrou in
  :issue:`16500`.)

* The Windows build process no longer depends on Subversion to pull in external
  sources, a Python script is used to download zipfiles from GitHub instead.
  If Python 3.6 is not found on the system (via ``py -3.6``), NuGet is used to
  download a copy of 32-bit Python for this purpose.  (Contributed by Zachary
  Ware in :issue:`30450`.)


Deprecated
==========

- Function :c:func:`PySlice_GetIndicesEx` is deprecated and replaced with
  a macro if ``Py_LIMITED_API`` is not set or set to the value between
  ``0x03050400`` and ``0x03060000`` (not including) or ``0x03060100`` or
  higher.  (Contributed by Serhiy Storchaka in :issue:`27867`.)

- Deprecated :meth:`format` from :mod:`locale`, use the :meth:`format_string`
  instead. (Contributed by Garvit in :issue:`10379`.)

- Methods
  :meth:`MetaPathFinder.find_module() <importlib.abc.MetaPathFinder.find_module>`
  (replaced by
  :meth:`MetaPathFinder.find_spec() <importlib.abc.MetaPathFinder.find_spec>`
  ) and
  :meth:`PathEntryFinder.find_loader() <importlib.abc.PathEntryFinder.find_loader>`
  (replaced by
  :meth:`PathEntryFinder.find_spec() <importlib.abc.PathEntryFinder.find_spec>`)
  both deprecated in Python 3.4 now emit :exc:`DeprecationWarning`. (Contributed
  by Matthias Bussonnier in :issue:`29576`)

- Using non-integer value for selecting a plural form in :mod:`gettext` is
  now deprecated.  It never correctly worked. (Contributed by Serhiy Storchaka
  in :issue:`28692`.)

- The :mod:`macpath` is now deprecated and will be removed in Python 3.8.


Changes in the C API
--------------------

- The type of results of :c:func:`PyThread_start_new_thread` and
  :c:func:`PyThread_get_thread_ident`, and the *id* parameter of
  :c:func:`PyThreadState_SetAsyncExc` changed from :c:type:`long` to
  :c:type:`unsigned long`.
  (Contributed by Serhiy Storchaka in :issue:`6532`.)

- :c:func:`PyUnicode_AsWideCharString` now raises a :exc:`ValueError` if the
  second argument is *NULL* and the :c:type:`wchar_t*` string contains null
  characters.  (Contributed by Serhiy Storchaka in :issue:`30708`.)


Windows Only
------------
- The python launcher, (py.exe), can accept 32 & 64 bit specifiers **without**
  having to specify a minor version as well. So ``py -3-32`` and ``py -3-64``
  become valid as well as ``py -3.7-32``, also the -*m*-64 and -*m.n*-64 forms
  are now accepted to force 64 bit python even if 32 bit would have otherwise
  been used. If the specified version is not available py.exe will error exit.
  (Contributed by Steve Barnes in :issue:`30291`.)

- The launcher can be run as "py -0" to produce a list of the installed pythons,
  *with default marked with an asterix*. Running "py -0p" will include the paths.
  If py is run with a version specifier that cannot be matched it will also print
  the *short form* list of available specifiers.
  (Contributed by Steve Barnes in :issue:`30362`.)

Removed
=======

API and Feature Removals
------------------------

* Unknown escapes consisting of ``'\'`` and an ASCII letter in replacement
  templates for :func:`re.sub` were deprecated in Python 3.5, and will now
  cause an error.

* Removed support of the *exclude* argument in :meth:`tarfile.TarFile.add`.
  It was deprecated in Python 2.7 and 3.2.  Use the *filter* argument instead.

* The ``splitunc()`` function in the :mod:`ntpath` module was deprecated in
  Python 3.1, and has now been removed.  Use the :func:`~os.path.splitdrive`
  function instead.

* Functions :func:`bool`, :func:`float`, :func:`list` and :func:`tuple` no
  longer take keyword arguments.  The first argument of :func:`int` can now
  be passed only as positional argument.

* Removed previously deprecated in Python 2.4 classes ``Plist``, ``Dict`` and
  ``_InternalDict`` in the :mod:`plistlib` module.  Dict values in the result
  of functions :func:`~plistlib.readPlist` and
  :func:`~plistlib.readPlistFromBytes` are now normal dicts.  You no longer
  can use attribute access to access items of these dictionaries.


Porting to Python 3.7
=====================

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


Changes in the Python API
-------------------------

* :meth:`pkgutil.walk_packages` now raises ValueError if *path* is a string.
  Previously an empty list was returned. (Contributed by Sanyam Khurana in
  :issue:`24744`.)

* A format string argument for :meth:`string.Formatter.format`
  is now :ref:`positional-only <positional-only_parameter>`.
  Passing it as a keyword argument was deprecated in Python 3.5. (Contributed
  by Serhiy Storchaka in :issue:`29193`.)

* Attributes :attr:`~http.cookies.Morsel.key`,
  :attr:`~http.cookies.Morsel.value` and
  :attr:`~http.cookies.Morsel.coded_value` of class
  :class:`http.cookies.Morsel` are now read-only.
  Assigning to them was deprecated in Python 3.5.
  Use the :meth:`~http.cookies.Morsel.set` method for setting them.
  (Contributed by Serhiy Storchaka in :issue:`29192`.)

* ``Module``, ``FunctionDef``, ``AsyncFunctionDef``, and
  ``ClassDef`` AST nodes now have a new ``docstring`` field.
  The first statement in their body is not considered as a docstring
  anymore.  ``co_firstlineno`` and ``co_lnotab`` of code object for class
  and module are affected by this change. (Contributed by INADA Naoki and
  Eugene Toder in :issue:`29463`.)

* The *mode* argument of :func:`os.makedirs` no longer affects the file
  permission bits of newly-created intermediate-level directories.
  To set their file permission bits you can set the umask before invoking
  ``makedirs()``.
  (Contributed by Serhiy Storchaka in :issue:`19930`.)

* The :attr:`struct.Struct.format` type is now :class:`str` instead of
  :class:`bytes`. (Contributed by Victor Stinner in :issue:`21071`.)

* Due to internal changes in :mod:`socket` you won't be able to
  :func:`socket.fromshare` a socket :func:`~socket.socket.share`-ed in older
  Python versions.

* ``repr`` for :class:`datetime.timedelta` has changed to include keyword arguments
  in the output. (Contributed by Utkarsh Upadhyay in :issue:`30302`.)


CPython bytecode changes
------------------------

* Added two new opcodes: :opcode:`LOAD_METHOD` and :opcode:`CALL_METHOD`.
  (Contributed by Yury Selivanov and INADA Naoki in :issue:`26110`.)