Stowage/cpython
2
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2026-04-29 23:30:56 +00:00
Code Issues Projects Releases Packages Wiki Activity

Merge branch 'master' into feature/34632-importlib-metadata

Browse source
This commit is contained in:
Jason R. Coombs 2019-05-08 11:34:20 -04:00
commit 175603f3aa
706 changed files with 23101 additions and 14313 deletions
Download patch file Download diff file Expand all files Collapse all files

16
Doc/Makefile
View file

@ -48,11 +48,19 @@ build:
@if [ -f ../Misc/NEWS ] ; then \
echo "Using existing Misc/NEWS file"; \
cp ../Misc/NEWS build/NEWS; \
elif [ -d ../Misc/NEWS.d ]; then \
echo "Building NEWS from Misc/NEWS.d with blurb"; \
$(BLURB) merge -f build/NEWS; \
elif $(BLURB) help >/dev/null 2>&1 && $(SPHINXBUILD) --version >/dev/null 2>&1; then \
if [ -d ../Misc/NEWS.d ]; then \
echo "Building NEWS from Misc/NEWS.d with blurb"; \
$(BLURB) merge -f build/NEWS; \
else \
echo "Neither Misc/NEWS.d nor Misc/NEWS found; cannot build docs"; \
exit 1; \
fi \
else \
echo "Neither Misc/NEWS.d nor Misc/NEWS found; cannot build docs"; \
echo ""; \
echo "Missing the required blurb or sphinx-build tools."; \
echo "Please run 'make venv' to install local copies."; \
echo ""; \
exit 1; \
fi
$(SPHINXBUILD) $(ALLSPHINXOPTS)

10
Doc/bugs.rst
View file

@ -25,7 +25,15 @@ docs@python.org (behavioral bugs can be sent to python-list@python.org).
though it may take a while to be processed.
.. seealso::
`Documentation bugs`_ on the Python issue tracker
`Documentation bugs`_
A list of documentation bugs that have been submitted to the Python issue tracker.
`Issue Tracking <https://devguide.python.org/tracker/>`_
Overview of the process involved in reporting an improvement on the tracker.
`Helping with Documentation <https://devguide.python.org/docquality/#helping-with-documentation>`_
Comprehensive guide for individuals that are interested in contributing to Python documentation.
.. _using-the-tracker:

16
Doc/c-api/datetime.rst
View file

@ -98,6 +98,22 @@ Macros to create objects:
minute, second and microsecond.
.. c:function:: PyObject* PyDateTime_FromDateAndTimeAndFold(int year, int month, int day, int hour, int minute, int second, int usecond, int fold)
Return a :class:`datetime.datetime` object with the specified year, month, day, hour,
minute, second, microsecond and fold.
.. versionadded:: 3.6
.. c:function:: PyObject* PyTime_FromTimeAndFold(int hour, int minute, int second, int usecond, int fold)
Return a :class:`datetime.time` object with the specified hour, minute, second,
microsecond and fold.
.. versionadded:: 3.6
.. c:function:: PyObject* PyTime_FromTime(int hour, int minute, int second, int usecond)
Return a :class:`datetime.time` object with the specified hour, minute, second and

4
Doc/c-api/exceptions.rst
View file

@ -53,8 +53,8 @@ Printing and clearing
.. c:function:: void PyErr_PrintEx(int set_sys_last_vars)
Print a standard traceback to ``sys.stderr`` and clear the error indicator.
**Unless** the error is a ``SystemExit``. In that case the no traceback
is printed and Python process will exit with the error code specified by
**Unless** the error is a ``SystemExit``, in that case no traceback is
printed and the Python process will exit with the error code specified by
the ``SystemExit`` instance.
Call this function **only** when the error indicator is set. Otherwise it

42
Doc/c-api/init.rst
View file

@ -37,6 +37,7 @@ The following functions can be safely called before Python is initialized:
* Informative functions:
* :c:func:`Py_IsInitialized`
* :c:func:`PyMem_GetAllocator`
* :c:func:`PyObject_GetArenaAllocator`
* :c:func:`Py_GetBuildInfo`
@ -855,6 +856,12 @@ code, or when embedding the Python interpreter:
created, the current thread must not have acquired it, otherwise deadlock
ensues.
.. note::
Calling this function from a thread when the runtime is finalizing
will terminate the thread, even if the thread was not created by Python.
You can use :c:func:`_Py_IsFinalizing` or :func:`sys.is_finalizing` to
check if the interpreter is in process of being finalized before calling
this function to avoid unwanted termination.
.. c:function:: PyThreadState* PyThreadState_Get()
@ -902,6 +909,12 @@ with sub-interpreters:
When the function returns, the current thread will hold the GIL and be able
to call arbitrary Python code. Failure is a fatal error.
.. note::
Calling this function from a thread when the runtime is finalizing
will terminate the thread, even if the thread was not created by Python.
You can use :c:func:`_Py_IsFinalizing` or :func:`sys.is_finalizing` to
check if the interpreter is in process of being finalized before calling
this function to avoid unwanted termination.
.. c:function:: void PyGILState_Release(PyGILState_STATE)
@ -1067,6 +1080,18 @@ All of the following functions must be called after :c:func:`Py_Initialize`.
*tstate*, which should not be *NULL*. The lock must have been created earlier.
If this thread already has the lock, deadlock ensues.
.. note::
Calling this function from a thread when the runtime is finalizing
will terminate the thread, even if the thread was not created by Python.
You can use :c:func:`_Py_IsFinalizing` or :func:`sys.is_finalizing` to
check if the interpreter is in process of being finalized before calling
this function to avoid unwanted termination.
.. versionchanged:: 3.8
Updated to be consistent with :c:func:`PyEval_RestoreThread`,
:c:func:`Py_END_ALLOW_THREADS`, and :c:func:`PyGILState_Ensure`,
and terminate the current thread if called while the interpreter is finalizing.
:c:func:`PyEval_RestoreThread` is a higher-level function which is always
available (even when threads have not been initialized).
@ -1093,6 +1118,18 @@ All of the following functions must be called after :c:func:`Py_Initialize`.
:c:func:`PyEval_RestoreThread` or :c:func:`PyEval_AcquireThread`
instead.
.. note::
Calling this function from a thread when the runtime is finalizing
will terminate the thread, even if the thread was not created by Python.
You can use :c:func:`_Py_IsFinalizing` or :func:`sys.is_finalizing` to
check if the interpreter is in process of being finalized before calling
this function to avoid unwanted termination.
.. versionchanged:: 3.8
Updated to be consistent with :c:func:`PyEval_RestoreThread`,
:c:func:`Py_END_ALLOW_THREADS`, and :c:func:`PyGILState_Ensure`,
and terminate the current thread if called while the interpreter is finalizing.
.. c:function:: void PyEval_ReleaseLock()
@ -1394,6 +1431,11 @@ These functions are only intended to be used by advanced debugging tools.
Return the interpreter state object at the head of the list of all such objects.
.. c:function:: PyInterpreterState* PyInterpreterState_Main()
Return the main interpreter state object.
.. c:function:: PyInterpreterState* PyInterpreterState_Next(PyInterpreterState *interp)
Return the next interpreter state object after *interp* from the list of all

6
Doc/c-api/intro.rst
View file

@ -48,7 +48,8 @@ Include Files
All function, type and macro definitions needed to use the Python/C API are
included in your code by the following line::
#include "Python.h"
#define PY_SSIZE_T_CLEAN
#include <Python.h>
This implies inclusion of the following standard headers: ``<stdio.h>``,
``<string.h>``, ``<errno.h>``, ``<limits.h>``, ``<assert.h>`` and ``<stdlib.h>``
@ -60,6 +61,9 @@ This implies inclusion of the following standard headers: ``<stdio.h>``,
headers on some systems, you *must* include :file:`Python.h` before any standard
headers are included.
It is recommended to always define ``PY_SSIZE_T_CLEAN`` before including
``Python.h``. See :ref:`arg-parsing` for a description of this macro.
All user visible names defined by Python.h (except those defined by the included
standard headers) have one of the prefixes ``Py`` or ``_Py``. Names beginning
with ``_Py`` are for internal use by the Python implementation and should not be

11
Doc/c-api/memory.rst
View file

@ -440,8 +440,9 @@ Customize Memory Allocators
Setup hooks to detect bugs in the Python memory allocator functions.
Newly allocated memory is filled with the byte ``0xCB``, freed memory is
filled with the byte ``0xDB``.
Newly allocated memory is filled with the byte ``0xCD`` (``CLEANBYTE``),
freed memory is filled with the byte ``0xDD`` (``DEADBYTE``). Memory blocks
are surrounded by "forbidden bytes" (``FORBIDDENBYTE``: byte ``0xFD``).
Runtime checks:
@ -471,6 +472,12 @@ Customize Memory Allocators
if the GIL is held when functions of :c:data:`PYMEM_DOMAIN_OBJ` and
:c:data:`PYMEM_DOMAIN_MEM` domains are called.
.. versionchanged:: 3.8.0
Byte patterns ``0xCB`` (``CLEANBYTE``), ``0xDB`` (``DEADBYTE``) and
``0xFB`` (``FORBIDDENBYTE``) have been replaced with ``0xCD``, ``0xDD``
and ``0xFD`` to use the same values than Windows CRT debug ``malloc()``
and ``free()``.
.. _pymalloc:

4
Doc/c-api/typeobj.rst
View file

@ -2052,7 +2052,7 @@ Sequence Object Structures
signature. It should modify its first operand, and return it. This slot
may be left to *NULL*, in this case :c:func:`!PySequence_InPlaceConcat`
will fall back to :c:func:`PySequence_Concat`. It is also used by the
augmented assignment ``+=``, after trying numeric inplace addition
augmented assignment ``+=``, after trying numeric in-place addition
via the :c:member:`~PyNumberMethods.nb_inplace_add` slot.
.. c:member:: ssizeargfunc PySequenceMethods.sq_inplace_repeat
@ -2061,7 +2061,7 @@ Sequence Object Structures
signature. It should modify its first operand, and return it. This slot
may be left to *NULL*, in this case :c:func:`!PySequence_InPlaceRepeat`
will fall back to :c:func:`PySequence_Repeat`. It is also used by the
augmented assignment ``*=``, after trying numeric inplace multiplication
augmented assignment ``*=``, after trying numeric in-place multiplication
via the :c:member:`~PyNumberMethods.nb_inplace_multiply` slot.

4
Doc/c-api/veryhigh.rst
View file

@ -109,6 +109,10 @@ the same library that the Python runtime is using.
(:func:`sys.getfilesystemencoding`). If *closeit* is true, the file is
closed before PyRun_SimpleFileExFlags returns.
.. note::
On Windows, *fp* should be opened as binary mode (e.g. ``fopen(filename, "rb")``.
Otherwise, Python may not handle script file with LF line ending correctly.
.. c:function:: int PyRun_InteractiveOne(FILE *fp, const char *filename)

5
Doc/distutils/apiref.rst
View file

@ -277,6 +277,11 @@ the full reference.
| | simply skip the extension. | |
+------------------------+--------------------------------+---------------------------+
.. versionchanged:: 3.8
On Unix, C extensions are no longer linked to libpython except on
Android.
.. class:: Distribution

2
Doc/distutils/setupscript.rst
View file

@ -523,7 +523,7 @@ following way::
setup(...,
data_files=[('bitmaps', ['bm/b1.gif', 'bm/b2.gif']),
('config', ['cfg/data.cfg']),
('config', ['cfg/data.cfg'])],
)
Each (*directory*, *files*) pair in the sequence specifies the installation

4
Doc/extending/building.rst
View file

@ -145,7 +145,7 @@ that distutils gets the invocations right.
Distributing your extension modules
===================================
When an extension has been successfully build, there are three ways to use it.
When an extension has been successfully built, there are three ways to use it.
End-users will typically want to install the module, they do so by running ::
@ -158,7 +158,7 @@ Module maintainers should produce source packages; to do so, they run ::
In some cases, additional files need to be included in a source distribution;
this is done through a :file:`MANIFEST.in` file; see :ref:`manifest` for details.
If the source distribution has been build successfully, maintainers can also
If the source distribution has been built successfully, maintainers can also
create binary distributions. Depending on the platform, one of the following
commands can be used to do so. ::

1
Doc/extending/embedding.rst
View file

@ -53,6 +53,7 @@ interface. This interface is intended to execute a Python script without needing
to interact with the application directly. This can for example be used to
perform some operation on a file. ::
#define PY_SSIZE_T_CLEAN
#include <Python.h>
int

11
Doc/extending/extending.rst
View file

@ -55,8 +55,9 @@ called ``spam``, the C file containing its implementation is called
:file:`spammodule.c`; if the module name is very long, like ``spammify``, the
module name can be just :file:`spammify.c`.)
The first line of our file can be::
The first two lines of our file can be::
#define PY_SSIZE_T_CLEAN
#include <Python.h>
which pulls in the Python API (you can add a comment describing the purpose of
@ -68,6 +69,9 @@ the module and a copyright notice if you like).
headers on some systems, you *must* include :file:`Python.h` before any standard
headers are included.
It is recommended to always define ``PY_SSIZE_T_CLEAN`` before including
``Python.h``. See :ref:`parsetuple` for a description of this macro.
All user-visible symbols defined by :file:`Python.h` have a prefix of ``Py`` or
``PY``, except those defined in standard header files. For convenience, and
since they are used extensively by the Python interpreter, ``"Python.h"``
@ -729,7 +733,8 @@ it returns false and raises an appropriate exception.
Here is an example module which uses keywords, based on an example by Geoff
Philbrick (philbrick@hks.com)::
#include "Python.h"
#define PY_SSIZE_T_CLEAN /* Make "s#" use Py_ssize_t rather than int. */
#include <Python.h>
static PyObject *
keywdarg_parrot(PyObject *self, PyObject *args, PyObject *keywds)
@ -1228,7 +1233,7 @@ The function :c:func:`spam_system` is modified in a trivial way::
In the beginning of the module, right after the line ::
#include "Python.h"
#include <Python.h>
two more lines must be added::

1
Doc/extending/newtypes_tutorial.rst
View file

@ -92,6 +92,7 @@ The second bit is the definition of the type object. ::
.tp_doc = "Custom objects",
.tp_basicsize = sizeof(CustomObject),
.tp_itemsize = 0,
.tp_flags = Py_TPFLAGS_DEFAULT,
.tp_new = PyType_GenericNew,
};

2
Doc/faq/extending.rst
View file

@ -280,6 +280,7 @@ solution then is to call :c:func:`PyParser_ParseString` and test for ``e.error``
equal to ``E_EOF``, which means the input is incomplete. Here's a sample code
fragment, untested, inspired by code from Alex Farber::
#define PY_SSIZE_T_CLEAN
#include <Python.h>
#include <node.h>
#include <errcode.h>
@ -318,6 +319,7 @@ complete example using the GNU readline library (you may want to ignore
#include <stdio.h>
#include <readline.h>
#define PY_SSIZE_T_CLEAN
#include <Python.h>
#include <object.h>
#include <compile.h>

12
Doc/faq/general.rst
View file

@ -306,14 +306,10 @@ guaranteed that interfaces will remain the same throughout a series of bugfix
releases.
The latest stable releases can always be found on the `Python download page
<https://www.python.org/downloads/>`_. There are two production-ready version
of Python: 2.x and 3.x, but the recommended one at this times is Python 3.x.
Although Python 2.x is still widely used, `it will not be
maintained after January 1, 2020 <https://www.python.org/dev/peps/pep-0373/>`_.
Python 2.x was known for having more third-party libraries available, however,
by the time of this writing, most of the widely used libraries support Python 3.x,
and some are even dropping the Python 2.x support.
<https://www.python.org/downloads/>`_. There are two production-ready versions
of Python: 2.x and 3.x. The recommended version is 3.x, which is supported by
most widely used libraries. Although 2.x is still widely used, `it will not
be maintained after January 1, 2020 <https://www.python.org/dev/peps/pep-0373/>`_.
How many people are using Python?
---------------------------------

3
Doc/faq/programming.rst
View file

@ -16,6 +16,9 @@ Is there a source code level debugger with breakpoints, single-stepping, etc.?
Yes.
Several debuggers for Python are described below, and the built-in function
:func:`breakpoint` allows you to drop into any of them.
The pdb module is a simple but adequate console-mode debugger for Python. It is
part of the standard Python library, and is :mod:`documented in the Library
Reference Manual <pdb>`. You can also write your own debugger by using the code

7
Doc/glossary.rst
View file

@ -663,6 +663,11 @@ Glossary
:term:`finder`. See :pep:`302` for details and
:class:`importlib.abc.Loader` for an :term:`abstract base class`.
magic method
.. index:: pair: magic; method
An informal synonym for :term:`special method`.
mapping
A container object that supports arbitrary key lookups and implements the
methods specified in the :class:`~collections.abc.Mapping` or
@ -1004,6 +1009,8 @@ Glossary
(subscript) notation uses :class:`slice` objects internally.
special method
.. index:: pair: special; method
A method that is called implicitly by Python to execute a certain
operation on a type, such as addition. Such methods have names starting
and ending with double underscores. Special methods are documented in

7
Doc/howto/regex.rst
View file

@ -942,6 +942,13 @@ given numbers, so you can retrieve information about a group in two ways::
>>> m.group(1)
'Lots'
Additionally, you can retrieve named groups as a dictionary with
:meth:`~re.Match.groupdict`::
>>> m = re.match(r'(?P<first>\w+) (?P<last>\w+)', 'Jane Doe')
>>> m.groupdict()
{'first': 'Jane', 'last': 'Doe'}
Named groups are handy because they let you use easily-remembered names, instead
of having to remember numbers. Here's an example RE from the :mod:`imaplib`
module::

1
Doc/includes/custom.c
View file

@ -1,3 +1,4 @@
#define PY_SSIZE_T_CLEAN
#include <Python.h>
typedef struct {

1
Doc/includes/custom2.c
View file

@ -1,3 +1,4 @@
#define PY_SSIZE_T_CLEAN
#include <Python.h>
#include "structmember.h"

1
Doc/includes/custom3.c
View file

@ -1,3 +1,4 @@
#define PY_SSIZE_T_CLEAN
#include <Python.h>
#include "structmember.h"

1
Doc/includes/custom4.c
View file

@ -1,3 +1,4 @@
#define PY_SSIZE_T_CLEAN
#include <Python.h>
#include "structmember.h"

1
Doc/includes/run-func.c
View file

@ -1,3 +1,4 @@
#define PY_SSIZE_T_CLEAN
#include <Python.h>
int

1
Doc/includes/sublist.c
View file

@ -1,3 +1,4 @@
#define PY_SSIZE_T_CLEAN
#include <Python.h>
typedef struct {

34
Doc/library/asyncio-eventloop.rst
View file

@ -281,9 +281,9 @@ clocks to track time.
the event loop's internal monotonic clock.
.. note::
Timeouts (relative *delay* or absolute *when*) should not
exceed one day.
.. versionchanged:: 3.8
In Python 3.7 and earlier timeouts (relative *delay* or absolute *when*)
should not exceed one day. This has been fixed in Python 3.8.
.. seealso::
@ -397,9 +397,27 @@ Opening network connections
If given, these should all be integers from the corresponding
:mod:`socket` module constants.
* *happy_eyeballs_delay*, if given, enables Happy Eyeballs for this
connection. It should
be a floating-point number representing the amount of time in seconds
to wait for a connection attempt to complete, before starting the next
attempt in parallel. This is the "Connection Attempt Delay" as defined
in :rfc:`8305`. A sensible default value recommended by the RFC is ``0.25``
(250 milliseconds).
* *interleave* controls address reordering when a host name resolves to
multiple IP addresses.
If ``0`` or unspecified, no reordering is done, and addresses are
tried in the order returned by :meth:`getaddrinfo`. If a positive integer
is specified, the addresses are interleaved by address family, and the
given integer is interpreted as "First Address Family Count" as defined
in :rfc:`8305`. The default is ``0`` if *happy_eyeballs_delay* is not
specified, and ``1`` if it is.
* *sock*, if given, should be an existing, already connected
:class:`socket.socket` object to be used by the transport.
If *sock* is given, none of *host*, *port*, *family*, *proto*, *flags*
If *sock* is given, none of *host*, *port*, *family*, *proto*, *flags*,
*happy_eyeballs_delay*, *interleave*
and *local_addr* should be specified.
* *local_addr*, if given, is a ``(local_host, local_port)`` tuple used
@ -410,6 +428,10 @@ Opening network connections
to wait for the TLS handshake to complete before aborting the connection.
``60.0`` seconds if ``None`` (default).
.. versionadded:: 3.8
The *happy_eyeballs_delay* and *interleave* parameters.
.. versionadded:: 3.7
The *ssl_handshake_timeout* parameter.
@ -1601,7 +1623,7 @@ using the :meth:`loop.add_signal_handler` method::
import os
import signal
def ask_exit(signame):
def ask_exit(signame, loop):
print("got signal %s: exit" % signame)
loop.stop()
@ -1611,7 +1633,7 @@ using the :meth:`loop.add_signal_handler` method::
for signame in {'SIGINT', 'SIGTERM'}:
loop.add_signal_handler(
getattr(signal, signame),
functools.partial(ask_exit, signame))
functools.partial(ask_exit, signame, loop))
await asyncio.sleep(3600)

2
Doc/library/asyncio-subprocess.rst
View file

@ -56,7 +56,7 @@ See also the `Examples`_ subsection.
Creating Subprocesses
=====================
.. coroutinefunction:: create_subprocess_exec(\*args, stdin=None, \
.. coroutinefunction:: create_subprocess_exec(program, \*args, stdin=None, \
stdout=None, stderr=None, loop=None, \
limit=None, \*\*kwds)

2
Doc/library/asyncio-sync.rst
View file

@ -17,7 +17,7 @@ those of the :mod:`threading` module with two important caveats:
argument; use the :func:`asyncio.wait_for` function to perform
operations with timeouts.
asyncio has the following basic sychronization primitives:
asyncio has the following basic synchronization primitives:
* :class:`Lock`
* :class:`Event`

2
Doc/library/codecs.rst
View file

@ -638,7 +638,7 @@ define in order to be compatible with the Python codec registry.
.. method:: setstate(state)
Set the state of the encoder to *state*. *state* must be a decoder state
Set the state of the decoder to *state*. *state* must be a decoder state
returned by :meth:`getstate`.

6
Doc/library/configparser.rst
View file

@ -721,6 +721,12 @@ be overridden by subclasses or by attribute assignment.
>>> list(custom['Section2'].keys())
['AnotherKey']
.. note::
The optionxform function transforms option names to a canonical form.
This should be an idempotent function: if the name is already in
canonical form, it should be returned unchanged.
.. attribute:: ConfigParser.SECTCRE
A compiled regular expression used to parse section headers. The default

2
Doc/library/crypt.rst
View file

@ -30,6 +30,8 @@ the :manpage:`crypt(3)` routine in the running system. Therefore, any
extensions available on the current implementation will also be available on
this module.
.. availability:: Unix. Not available on VxWorks.
Hashing Methods
---------------

17
Doc/library/ctypes.rst
View file

@ -1322,14 +1322,14 @@ There are several ways to load shared libraries into the Python process. One
way is to instantiate one of the following classes:
.. class:: CDLL(name, mode=DEFAULT_MODE, handle=None, use_errno=False, use_last_error=False)
.. class:: CDLL(name, mode=DEFAULT_MODE, handle=None, use_errno=False, use_last_error=False, winmode=0)
Instances of this class represent loaded shared libraries. Functions in these
libraries use the standard C calling convention, and are assumed to return
:c:type:`int`.
.. class:: OleDLL(name, mode=DEFAULT_MODE, handle=None, use_errno=False, use_last_error=False)
.. class:: OleDLL(name, mode=DEFAULT_MODE, handle=None, use_errno=False, use_last_error=False, winmode=0)
Windows only: Instances of this class represent loaded shared libraries,
functions in these libraries use the ``stdcall`` calling convention, and are
@ -1342,7 +1342,7 @@ way is to instantiate one of the following classes:
:exc:`WindowsError` used to be raised.
.. class:: WinDLL(name, mode=DEFAULT_MODE, handle=None, use_errno=False, use_last_error=False)
.. class:: WinDLL(name, mode=DEFAULT_MODE, handle=None, use_errno=False, use_last_error=False, winmode=0)
Windows only: Instances of this class represent loaded shared libraries,
functions in these libraries use the ``stdcall`` calling convention, and are
@ -1394,6 +1394,17 @@ the Windows error code which is managed by the :func:`GetLastError` and
:func:`ctypes.set_last_error` are used to request and change the ctypes private
copy of the windows error code.
The *winmode* parameter is used on Windows to specify how the library is loaded
(since *mode* is ignored). It takes any value that is valid for the Win32 API
``LoadLibraryEx`` flags parameter. When omitted, the default is to use the flags
that result in the most secure DLL load to avoiding issues such as DLL
hijacking. Passing the full path to the DLL is the safest way to ensure the
correct library and dependencies are loaded.
.. versionchanged:: 3.8
Added *winmode* parameter.
.. data:: RTLD_GLOBAL
:noindex:

17
Doc/library/datetime.rst
View file

@ -458,6 +458,13 @@ Other constructors, all class methods:
.. versionadded:: 3.7
.. classmethod:: date.fromisocalendar(year, week, day)
Return a :class:`date` corresponding to the ISO calendar date specified by
year, week and day. This is the inverse of the function :meth:`date.isocalendar`.
.. versionadded:: 3.8
Class attributes:
@ -854,6 +861,16 @@ Other constructors, all class methods:
.. versionadded:: 3.7
.. classmethod:: datetime.fromisocalendar(year, week, day)
Return a :class:`datetime` corresponding to the ISO calendar date specified
by year, week and day. The non-date components of the datetime are populated
with their normal default values. This is the inverse of the function
:meth:`datetime.isocalendar`.
.. versionadded:: 3.8
.. classmethod:: datetime.strptime(date_string, format)
Return a :class:`.datetime` corresponding to *date_string*, parsed according to

2
Doc/library/email.encoders.rst
View file

@ -19,7 +19,7 @@ need to encode the payloads for transport through compliant mail servers. This
is especially true for :mimetype:`image/\*` and :mimetype:`text/\*` type messages
containing binary data.
The :mod:`email` package provides some convenient encodings in its
The :mod:`email` package provides some convenient encoders in its
:mod:`encoders` module. These encoders are actually used by the
:class:`~email.mime.audio.MIMEAudio` and :class:`~email.mime.image.MIMEImage`
class constructors to provide default encodings. All encoder functions take

2
Doc/library/email.generator.rst
View file

@ -188,7 +188,7 @@ to be using :class:`BytesGenerator`, and not :class:`Generator`.
(This is required because strings cannot represent non-ASCII bytes.)
Convert any bytes with the high bit set as needed using an
ASCII-compatible :mailheader:`Content-Transfer-Encoding`. That is,
transform parts with non-ASCII :mailheader:`Cotnent-Transfer-Encoding`
transform parts with non-ASCII :mailheader:`Content-Transfer-Encoding`
(:mailheader:`Content-Transfer-Encoding: 8bit`) to an ASCII compatible
:mailheader:`Content-Transfer-Encoding`, and encode RFC-invalid non-ASCII
bytes in headers using the MIME ``unknown-8bit`` character set, thus

9
Doc/library/exceptions.rst
View file

@ -691,8 +691,13 @@ The following exceptions are used as warning categories; see the
.. exception:: PendingDeprecationWarning
Base class for warnings about features which will be deprecated in the
future.
Base class for warnings about features which are obsolete and
expected to be deprecated in the future, but are not deprecated
at the moment.
This class is rarely used as emitting a warning about a possible
upcoming deprecation is unusual, and :exc:`DeprecationWarning`
is preferred for already active deprecations.
.. exception:: SyntaxWarning

25
Doc/library/functions.rst
View file

@ -211,19 +211,18 @@ are always available. They are listed here in alphabetical order.
@classmethod
def f(cls, arg1, arg2, ...): ...
The ``@classmethod`` form is a function :term:`decorator` -- see the description
of function definitions in :ref:`function` for details.
The ``@classmethod`` form is a function :term:`decorator` -- see
:ref:`function` for details.
It can be called either on the class (such as ``C.f()``) or on an instance (such
A class method can be called either on the class (such as ``C.f()``) or on an instance (such
as ``C().f()``). The instance is ignored except for its class. If a class
method is called for a derived class, the derived class object is passed as the
implied first argument.
Class methods are different than C++ or Java static methods. If you want those,
see :func:`staticmethod` in this section.
see :func:`staticmethod`.
For more information on class methods, consult the documentation on the standard
type hierarchy in :ref:`types`.
For more information on class methods, see :ref:`types`.
.. function:: compile(source, filename, mode, flags=0, dont_inherit=False, optimize=-1)
@ -844,7 +843,8 @@ are always available. They are listed here in alphabetical order.
Update and return a dictionary representing the current local symbol table.
Free variables are returned by :func:`locals` when it is called in function
blocks, but not in class blocks.
blocks, but not in class blocks. Note that at the module level, :func:`locals`
and :func:`globals` are the same dictionary.
.. note::
The contents of this dictionary should not be modified; changes may not
@ -1452,11 +1452,11 @@ are always available. They are listed here in alphabetical order.
@staticmethod
def f(arg1, arg2, ...): ...
The ``@staticmethod`` form is a function :term:`decorator` -- see the
description of function definitions in :ref:`function` for details.
The ``@staticmethod`` form is a function :term:`decorator` -- see
:ref:`function` for details.
It can be called either on the class (such as ``C.f()``) or on an instance (such
as ``C().f()``). The instance is ignored except for its class.
A static method can be called either on the class (such as ``C.f()``) or on an instance (such
as ``C().f()``).
Static methods in Python are similar to those found in Java or C++. Also see
:func:`classmethod` for a variant that is useful for creating alternate class
@ -1471,8 +1471,7 @@ are always available. They are listed here in alphabetical order.
class C:
builtin_open = staticmethod(open)
For more information on static methods, consult the documentation on the
standard type hierarchy in :ref:`types`.
For more information on static methods, see :ref:`types`.
.. index::

3
Doc/library/functools.rst
View file

@ -474,6 +474,9 @@ The :mod:`functools` module defines the following functions:
The same pattern can be used for other similar decorators: ``staticmethod``,
``abstractmethod``, and others.
.. versionadded:: 3.8
.. function:: update_wrapper(wrapper, wrapped, assigned=WRAPPER_ASSIGNMENTS, updated=WRAPPER_UPDATES)
Update a *wrapper* function to look like the *wrapped* function. The optional

16
Doc/library/http.cookies.rst
View file

@ -55,8 +55,9 @@ in Cookie name (as :attr:`~Morsel.key`).
.. class:: SimpleCookie([input])
This class derives from :class:`BaseCookie` and overrides :meth:`value_decode`
and :meth:`value_encode` to be the identity and :func:`str` respectively.
and :meth:`value_encode`. SimpleCookie supports strings as cookie values.
When setting the value, SimpleCookie calls the builtin :func:`str()` to convert
the value to a string. Values received from HTTP are kept as strings.
.. seealso::
@ -76,15 +77,16 @@ Cookie Objects
.. method:: BaseCookie.value_decode(val)
Return a decoded value from a string representation. Return value can be any
type. This method does nothing in :class:`BaseCookie` --- it exists so it can be
overridden.
Return a tuple ``(real_value, coded_value)`` from a string representation.
``real_value`` can be any type. This method does no decoding in
:class:`BaseCookie` --- it exists so it can be overridden.
.. method:: BaseCookie.value_encode(val)
Return an encoded value. *val* can be any type, but return value must be a
string. This method does nothing in :class:`BaseCookie` --- it exists so it can
Return a tuple ``(real_value, coded_value)``. *val* can be any type, but
``coded_value`` will always be converted to a string.
This method does no encoding in :class:`BaseCookie` --- it exists so it can
be overridden.
In general, it should be the case that :meth:`value_encode` and

28
Doc/library/idle.rst
View file

@ -356,8 +356,8 @@ Shell and Output windows also have the following.
Go to file/line
Same as in Debug menu.
The Shell window also has an output squeezing facility explained in the
the *Python Shell window* subsection below.
The Shell window also has an output squeezing facility explained in the *Python
Shell window* subsection below.
Squeeze
If the cursor is over an output line, squeeze all the output between
@ -716,21 +716,17 @@ In contrast, some system text windows only keep the last n lines of output.
A Windows console, for instance, keeps a user-settable 1 to 9999 lines,
with 300 the default.
A Tk Text widget, and hence IDLE's Shell, displays characters (codepoints)
in the the BMP (Basic Multilingual Plane) subset of Unicode.
Which characters are displayed with a proper glyph and which with a
replacement box depends on the operating system and installed fonts.
Tab characters cause the following text to begin after
the next tab stop. (They occur every 8 'characters').
Newline characters cause following text to appear on a new line.
Other control characters are ignored or displayed as a space, box, or
something else, depending on the operating system and font.
(Moving the text cursor through such output with arrow keys may exhibit
some surprising spacing behavior.)
A Tk Text widget, and hence IDLE's Shell, displays characters (codepoints) in
the BMP (Basic Multilingual Plane) subset of Unicode. Which characters are
displayed with a proper glyph and which with a replacement box depends on the
operating system and installed fonts. Tab characters cause the following text
to begin after the next tab stop. (They occur every 8 'characters'). Newline
characters cause following text to appear on a new line. Other control
characters are ignored or displayed as a space, box, or something else,
depending on the operating system and font. (Moving the text cursor through
such output with arrow keys may exhibit some surprising spacing behavior.) ::
.. code-block:: none
>>> s = 'a\tb\a<\x02><\r>\bc\nd'
>>> s = 'a\tb\a<\x02><\r>\bc\nd' # Enter 22 chars.
>>> len(s)
14
>>> s # Display repr(s)

3
Doc/library/imaplib.rst
View file

@ -327,6 +327,9 @@ An :class:`IMAP4` instance has the following methods:
Shutdown connection to server. Returns server ``BYE`` response.
.. versionchanged:: 3.8
The method no longer ignores silently arbitrary exceptions.
.. method:: IMAP4.lsub(directory='""', pattern='*')

5
Doc/library/inspect.rst
View file

@ -948,6 +948,11 @@ Classes and functions
APIs. This function is retained primarily for use in code that needs to
maintain compatibility with the Python 2 ``inspect`` module API.
.. deprecated:: 3.8
Use :func:`signature` and
:ref:`Signature Object <inspect-signature-object>`, which provide a
better introspecting API for callables.
.. versionchanged:: 3.4
This function is now based on :func:`signature`, but still ignores
``__wrapped__`` attributes and includes the already bound first

20
Doc/library/io.rst
View file

@ -226,7 +226,7 @@ I/O Base Classes
implementations represent a file that cannot be read, written or
seeked.
Even though :class:`IOBase` does not declare :meth:`read`, :meth:`readinto`,
Even though :class:`IOBase` does not declare :meth:`read`
or :meth:`write` because their signatures will vary, implementations and
clients should consider those methods part of the interface. Also,
implementations may raise a :exc:`ValueError` (or :exc:`UnsupportedOperation`)
@ -234,9 +234,7 @@ I/O Base Classes
The basic type used for binary data read from or written to a file is
:class:`bytes`. Other :term:`bytes-like objects <bytes-like object>` are
accepted as method arguments too. In some cases, such as
:meth:`~RawIOBase.readinto`, a writable object such as :class:`bytearray`
is required. Text I/O classes work with :class:`str` data.
accepted as method arguments too. Text I/O classes work with :class:`str` data.
Note that calling any method (even inquiries) on a closed stream is
undefined. Implementations may raise :exc:`ValueError` in this case.
@ -405,7 +403,8 @@ I/O Base Classes
Read bytes into a pre-allocated, writable
:term:`bytes-like object` *b*, and return the
number of bytes read. If the object is in non-blocking mode and no bytes
number of bytes read. For example, *b* might be a :class:`bytearray`.
If the object is in non-blocking mode and no bytes
are available, ``None`` is returned.
.. method:: write(b)
@ -495,6 +494,7 @@ I/O Base Classes
Read bytes into a pre-allocated, writable
:term:`bytes-like object` *b* and return the number of bytes read.
For example, *b* might be a :class:`bytearray`.
Like :meth:`read`, multiple reads may be issued to the underlying raw
stream, unless the latter is interactive.
@ -719,15 +719,15 @@ than raw I/O does.
.. class:: BufferedRandom(raw, buffer_size=DEFAULT_BUFFER_SIZE)
A buffered interface to random access streams. It inherits
:class:`BufferedReader` and :class:`BufferedWriter`, and further supports
:meth:`seek` and :meth:`tell` functionality.
:class:`BufferedReader` and :class:`BufferedWriter`.
The constructor creates a reader and writer for a seekable raw stream, given
in the first argument. If the *buffer_size* is omitted it defaults to
:data:`DEFAULT_BUFFER_SIZE`.
:class:`BufferedRandom` is capable of anything :class:`BufferedReader` or
:class:`BufferedWriter` can do.
:class:`BufferedWriter` can do. In addition, :meth:`seek` and :meth:`tell`
are guaranteed to be implemented.
.. class:: BufferedRWPair(reader, writer, buffer_size=DEFAULT_BUFFER_SIZE)
@ -757,8 +757,7 @@ Text I/O
.. class:: TextIOBase
Base class for text streams. This class provides a character and line based
interface to stream I/O. There is no :meth:`readinto` method because
Python's character strings are immutable. It inherits :class:`IOBase`.
interface to stream I/O. It inherits :class:`IOBase`.
There is no public constructor.
:class:`TextIOBase` provides or overrides these data attributes and
@ -1048,4 +1047,3 @@ The above implicitly extends to text files, since the :func:`open()` function
will wrap a buffered object inside a :class:`TextIOWrapper`. This includes
standard streams and therefore affects the built-in function :func:`print()` as
well.

2
Doc/library/itertools.rst
View file

@ -827,7 +827,7 @@ which incur interpreter overhead.
"List unique elements, preserving order. Remember only the element just seen."
# unique_justseen('AAAABBBCCDAABBB') --> A B C D A B
# unique_justseen('ABBCcAD', str.lower) --> A B C A D
return map(next, map(itemgetter(1), groupby(iterable, key)))
return map(next, map(operator.itemgetter(1), groupby(iterable, key)))
def iter_except(func, exception, first=None):
""" Call a function repeatedly until an exception is raised.

7
Doc/library/json.rst
View file

@ -265,18 +265,21 @@ Basic Usage
*fp* can now be a :term:`binary file`. The input encoding should be
UTF-8, UTF-16 or UTF-32.
.. function:: loads(s, *, encoding=None, cls=None, object_hook=None, parse_float=None, parse_int=None, parse_constant=None, object_pairs_hook=None, **kw)
.. function:: loads(s, *, cls=None, object_hook=None, parse_float=None, parse_int=None, parse_constant=None, object_pairs_hook=None, **kw)
Deserialize *s* (a :class:`str`, :class:`bytes` or :class:`bytearray`
instance containing a JSON document) to a Python object using this
:ref:`conversion table <json-to-py-table>`.
The other arguments have the same meaning as in :func:`load`, except
*encoding* which is ignored and deprecated.
*encoding* which is ignored and deprecated since Python 3.1.
If the data being deserialized is not a valid JSON document, a
:exc:`JSONDecodeError` will be raised.
.. deprecated-removed:: 3.1 3.9
*encoding* keyword argument.
.. versionchanged:: 3.6
*s* can now be of type :class:`bytes` or :class:`bytearray`. The
input encoding should be UTF-8, UTF-16 or UTF-32.

4
Doc/library/logging.rst
View file

@ -1215,6 +1215,10 @@ functions.
closing all handlers. This should be called at application exit and no
further use of the logging system should be made after this call.
When the logging module is imported, it registers this function as an exit
handler (see :mod:`atexit`), so normally there's no need to do that
manually.
.. function:: setLoggerClass(klass)

7
Doc/library/multiprocessing.shared_memory.rst
View file

@ -176,6 +176,7 @@ same ``numpy.ndarray`` from two distinct Python shells:
.. class:: SharedMemoryManager([address[, authkey]])
:module: multiprocessing.managers
A subclass of :class:`~multiprocessing.managers.BaseManager` which can be
used for the management of shared memory blocks across processes.
@ -218,8 +219,8 @@ The following example demonstrates the basic mechanisms of a
.. doctest::
:options: +SKIP
>>> from multiprocessing import shared_memory
>>> smm = shared_memory.SharedMemoryManager()
>>> from multiprocessing.managers import SharedMemoryManager
>>> smm = SharedMemoryManager()
>>> smm.start() # Start the process that manages the shared memory blocks
>>> sl = smm.ShareableList(range(4))
>>> sl
@ -238,7 +239,7 @@ needed:
.. doctest::
:options: +SKIP
>>> with shared_memory.SharedMemoryManager() as smm:
>>> with SharedMemoryManager() as smm:
... sl = smm.ShareableList(range(2000))
... # Divide the work among two processes, storing partial results in sl
... p1 = Process(target=do_work, args=(sl, 0, 1000))

6
Doc/library/operator.rst
View file

@ -440,8 +440,8 @@ Python syntax and the functions in the :mod:`operator` module.
| Ordering | ``a > b`` | ``gt(a, b)`` |
+-----------------------+-------------------------+---------------------------------------+
Inplace Operators
-----------------
In-place Operators
------------------
Many operations have an "in-place" version. Listed below are functions
providing a more primitive access to in-place operators than the usual syntax
@ -464,7 +464,7 @@ value is computed, but not assigned back to the input variable:
>>> a
'hello'
For mutable targets such as lists and dictionaries, the inplace method
For mutable targets such as lists and dictionaries, the in-place method
will perform the update, so no subsequent assignment is necessary:
>>> s = ['h', 'e', 'l', 'l', 'o']

181
Doc/library/os.rst
View file

@ -1453,16 +1453,19 @@ features:
.. _path_fd:
* **specifying a file descriptor:**
For some functions, the *path* argument can be not only a string giving a path
name, but also a file descriptor. The function will then operate on the file
referred to by the descriptor. (For POSIX systems, Python will call the
``f...`` version of the function.)
Normally the *path* argument provided to functions in the :mod:`os` module
must be a string specifying a file path. However, some functions now
alternatively accept an open file descriptor for their *path* argument.
The function will then operate on the file referred to by the descriptor.
(For POSIX systems, Python will call the variant of the function prefixed
with ``f`` (e.g. call ``fchdir`` instead of ``chdir``).)
You can check whether or not *path* can be specified as a file descriptor on
your platform using :data:`os.supports_fd`. If it is unavailable, using it
will raise a :exc:`NotImplementedError`.
You can check whether or not *path* can be specified as a file descriptor
for a particular function on your platform using :data:`os.supports_fd`.
If this functionality is unavailable, using it will raise a
:exc:`NotImplementedError`.
If the function also supports *dir_fd* or *follow_symlinks* arguments, it is
If the function also supports *dir_fd* or *follow_symlinks* arguments, it's
an error to specify one of those when supplying *path* as a file descriptor.
.. _dir_fd:
@ -1471,23 +1474,24 @@ features:
should be a file descriptor referring to a directory, and the path to operate
on should be relative; path will then be relative to that directory. If the
path is absolute, *dir_fd* is ignored. (For POSIX systems, Python will call
the ``...at`` or ``f...at`` version of the function.)
the variant of the function with an ``at`` suffix and possibly prefixed with
``f`` (e.g. call ``faccessat`` instead of ``access``).
You can check whether or not *dir_fd* is supported on your platform using
:data:`os.supports_dir_fd`. If it is unavailable, using it will raise a
:exc:`NotImplementedError`.
You can check whether or not *dir_fd* is supported for a particular function
on your platform using :data:`os.supports_dir_fd`. If it's unavailable,
using it will raise a :exc:`NotImplementedError`.
.. _follow_symlinks:
* **not following symlinks:** If *follow_symlinks* is
``False``, and the last element of the path to operate on is a symbolic link,
the function will operate on the symbolic link itself instead of the file the
link points to. (For POSIX systems, Python will call the ``l...`` version of
the function.)
the function will operate on the symbolic link itself rather than the file
pointed to by the link. (For POSIX systems, Python will call the ``l...``
variant of the function.)
You can check whether or not *follow_symlinks* is supported on your platform
using :data:`os.supports_follow_symlinks`. If it is unavailable, using it
will raise a :exc:`NotImplementedError`.
You can check whether or not *follow_symlinks* is supported for a particular
function on your platform using :data:`os.supports_follow_symlinks`.
If it's unavailable, using it will raise a :exc:`NotImplementedError`.
@ -1662,7 +1666,7 @@ features:
.. availability:: Unix.
.. versionadded:: 3.3
Added support for specifying an open file descriptor for *path*,
Added support for specifying *path* as an open file descriptor,
and the *dir_fd* and *follow_symlinks* arguments.
.. versionchanged:: 3.6
@ -1781,7 +1785,7 @@ features:
The *path* parameter became optional.
.. versionadded:: 3.3
Added support for specifying an open file descriptor for *path*.
Added support for specifying *path* as an open file descriptor.
.. versionchanged:: 3.6
Accepts a :term:`path-like object`.
@ -2593,7 +2597,7 @@ features:
The :const:`ST_RDONLY` and :const:`ST_NOSUID` constants were added.
.. versionadded:: 3.3
Added support for specifying an open file descriptor for *path*.
Added support for specifying *path* as an open file descriptor.
.. versionchanged:: 3.4
The :const:`ST_NODEV`, :const:`ST_NOEXEC`, :const:`ST_SYNCHRONOUS`,
@ -2610,59 +2614,61 @@ features:
.. data:: supports_dir_fd
A :class:`~collections.abc.Set` object indicating which functions in the
:mod:`os` module permit use of their *dir_fd* parameter. Different platforms
provide different functionality, and an option that might work on one might
be unsupported on another. For consistency's sakes, functions that support
*dir_fd* always allow specifying the parameter, but will raise an exception
if the functionality is not actually available.
A :class:`set` object indicating which functions in the :mod:`os`
module accept an open file descriptor for their *dir_fd* parameter.
Different platforms provide different features, and the underlying
functionality Python uses to implement the *dir_fd* parameter is not
available on all platforms Python supports. For consistency's sake,
functions that may support *dir_fd* always allow specifying the
parameter, but will throw an exception if the functionality is used
when it's not locally available. (Specifying ``None`` for *dir_fd*
is always supported on all platforms.)
To check whether a particular function permits use of its *dir_fd*
parameter, use the ``in`` operator on ``supports_dir_fd``. As an example,
this expression determines whether the *dir_fd* parameter of :func:`os.stat`
is locally available::
To check whether a particular function accepts an open file descriptor
for its *dir_fd* parameter, use the ``in`` operator on ``supports_dir_fd``.
As an example, this expression evaluates to ``True`` if :func:`os.stat`
accepts open file descriptors for *dir_fd* on the local platform::
os.stat in os.supports_dir_fd
Currently *dir_fd* parameters only work on Unix platforms; none of them work
on Windows.
Currently *dir_fd* parameters only work on Unix platforms;
none of them work on Windows.
.. versionadded:: 3.3
.. data:: supports_effective_ids
A :class:`~collections.abc.Set` object indicating which functions in the
:mod:`os` module permit use of the *effective_ids* parameter for
:func:`os.access`. If the local platform supports it, the collection will
contain :func:`os.access`, otherwise it will be empty.
A :class:`set` object indicating whether :func:`os.access` permits
specifying ``True`` for its *effective_ids* parameter on the local platform.
(Specifying ``False`` for *effective_ids* is always supported on all
platforms.) If the local platform supports it, the collection will contain
:func:`os.access`; otherwise it will be empty.
To check whether you can use the *effective_ids* parameter for
:func:`os.access`, use the ``in`` operator on ``supports_effective_ids``,
like so::
This expression evaluates to ``True`` if :func:`os.access` supports
``effective_ids=True`` on the local platform::
os.access in os.supports_effective_ids
Currently *effective_ids* only works on Unix platforms; it does not work on
Windows.
Currently *effective_ids* is only supported on Unix platforms;
it does not work on Windows.
.. versionadded:: 3.3
.. data:: supports_fd
A :class:`~collections.abc.Set` object indicating which functions in the
A :class:`set` object indicating which functions in the
:mod:`os` module permit specifying their *path* parameter as an open file
descriptor. Different platforms provide different functionality, and an
option that might work on one might be unsupported on another. For
consistency's sakes, functions that support *fd* always allow specifying
the parameter, but will raise an exception if the functionality is not
actually available.
descriptor on the local platform. Different platforms provide different
features, and the underlying functionality Python uses to accept open file
descriptors as *path* arguments is not available on all platforms Python
supports.
To check whether a particular function permits specifying an open file
To determine whether a particular function permits specifying an open file
descriptor for its *path* parameter, use the ``in`` operator on
``supports_fd``. As an example, this expression determines whether
:func:`os.chdir` accepts open file descriptors when called on your local
``supports_fd``. As an example, this expression evaluates to ``True`` if
:func:`os.chdir` accepts open file descriptors for *path* on your local
platform::
os.chdir in os.supports_fd
@ -2672,17 +2678,21 @@ features:
.. data:: supports_follow_symlinks
A :class:`~collections.abc.Set` object indicating which functions in the
:mod:`os` module permit use of their *follow_symlinks* parameter. Different
platforms provide different functionality, and an option that might work on
one might be unsupported on another. For consistency's sakes, functions that
support *follow_symlinks* always allow specifying the parameter, but will
raise an exception if the functionality is not actually available.
A :class:`set` object indicating which functions in the :mod:`os` module
accept ``False`` for their *follow_symlinks* parameter on the local platform.
Different platforms provide different features, and the underlying
functionality Python uses to implement *follow_symlinks* is not available
on all platforms Python supports. For consistency's sake, functions that
may support *follow_symlinks* always allow specifying the parameter, but
will throw an exception if the functionality is used when it's not locally
available. (Specifying ``True`` for *follow_symlinks* is always supported
on all platforms.)
To check whether a particular function permits use of its *follow_symlinks*
parameter, use the ``in`` operator on ``supports_follow_symlinks``. As an
example, this expression determines whether the *follow_symlinks* parameter
of :func:`os.stat` is locally available::
To check whether a particular function accepts ``False`` for its
*follow_symlinks* parameter, use the ``in`` operator on
``supports_follow_symlinks``. As an example, this expression evaluates
to ``True`` if you may specify ``follow_symlinks=False`` when calling
:func:`os.stat` on the local platform::
os.stat in os.supports_follow_symlinks
@ -2699,19 +2709,15 @@ features:
as a directory if *target_is_directory* is ``True`` or a file symlink (the
default) otherwise. On non-Windows platforms, *target_is_directory* is ignored.
Symbolic link support was introduced in Windows 6.0 (Vista). :func:`symlink`
will raise a :exc:`NotImplementedError` on Windows versions earlier than 6.0.
This function can support :ref:`paths relative to directory descriptors
<dir_fd>`.
.. note::
On Windows, the *SeCreateSymbolicLinkPrivilege* is required in order to
successfully create symlinks. This privilege is not typically granted to
regular users but is available to accounts which can escalate privileges
to the administrator level. Either obtaining the privilege or running your
application as an administrator are ways to successfully create symlinks.
On newer versions of Windows 10, unprivileged accounts can create symlinks
if Developer Mode is enabled. When Developer Mode is not available/enabled,
the *SeCreateSymbolicLinkPrivilege* privilege is required, or the process
must be run as an administrator.
:exc:`OSError` is raised when the function is called by an unprivileged
@ -2729,6 +2735,9 @@ features:
.. versionchanged:: 3.6
Accepts a :term:`path-like object` for *src* and *dst*.
.. versionchanged:: 3.8
Added support for unelevated symlinks on Windows with Developer Mode.
.. function:: sync()
@ -2802,7 +2811,7 @@ features:
following symlinks <follow_symlinks>`.
.. versionadded:: 3.3
Added support for specifying an open file descriptor for *path*,
Added support for specifying *path* as an open file descriptor,
and the *dir_fd*, *follow_symlinks*, and *ns* parameters.
.. versionchanged:: 3.6
@ -3079,6 +3088,36 @@ to be ignored.
:func:`signal.signal`.
.. function:: add_dll_directory(path)
Add a path to the DLL search path.
This search path is used when resolving dependencies for imported
extension modules (the module itself is resolved through sys.path),
and also by :mod:`ctypes`.
Remove the directory by calling **close()** on the returned object
or using it in a :keyword:`with` statement.
See the `Microsoft documentation
<https://msdn.microsoft.com/44228cf2-6306-466c-8f16-f513cd3ba8b5>`_
for more information about how DLLs are loaded.
.. availability:: Windows.
.. versionadded:: 3.8
Previous versions of CPython would resolve DLLs using the default
behavior for the current process. This led to inconsistencies,
such as only sometimes searching :envvar:`PATH` or the current
working directory, and OS functions such as ``AddDllDirectory``
having no effect.
In 3.8, the two primary ways DLLs are loaded now explicitly
override the process-wide behavior to ensure consistency. See the
:ref:`porting notes <bpo-36085-whatsnew>` for information on
updating libraries.
.. function:: execl(path, arg0, arg1, ...)
execle(path, arg0, arg1, ..., env)
execlp(file, arg0, arg1, ...)
@ -3133,7 +3172,7 @@ to be ignored.
.. availability:: Unix, Windows.
.. versionadded:: 3.3
Added support for specifying an open file descriptor for *path*
Added support for specifying *path* as an open file descriptor
for :func:`execve`.
.. versionchanged:: 3.6

7
Doc/library/pathlib.rst
View file

@ -1054,6 +1054,13 @@ call fails (for example because the path doesn't exist).
use :func:`Path.rmdir` instead.
.. method:: Path.link_to(target)
Create a hard link pointing to a path named *target*.
.. versionchanged:: 3.8
.. method:: Path.write_bytes(data)
Open the file pointed to in bytes mode, write *data* to it, and close the

15
Doc/library/platform.rst
View file

@ -216,6 +216,21 @@ Windows Platform
later (support for this was added in Python 2.6). It obviously
only runs on Win32 compatible platforms.
.. function:: win32_edition()
Returns a string representing the current Windows edition. Possible
values include but are not limited to ``'Enterprise'``, ``'IoTUAP'``,
``'ServerStandard'``, and ``'nanoserver'``.
.. versionadded:: 3.8
.. function:: win32_is_iot()
Returns True if the windows edition returned by win32_edition is recognized
as an IoT edition.
.. versionadded:: 3.8
Mac OS Platform
---------------

2
Doc/library/pyclbr.rst
View file

@ -44,7 +44,7 @@ modules.
.. versionadded:: 3.7
Descriptors for nested definitions. They are accessed through the
new children attibute. Each has a new parent attribute.
new children attribute. Each has a new parent attribute.
The descriptors returned by these functions are instances of
Function and Class classes. Users are not expected to create instances

5
Doc/library/queue.rst
View file

@ -150,6 +150,11 @@ provide the public methods described below.
Otherwise (*block* is false), return an item if one is immediately available,
else raise the :exc:`Empty` exception (*timeout* is ignored in that case).
Prior to 3.0 on POSIX systems, and for all versions on Windows, if
*block* is true and *timeout* is ``None``, this operation goes into
an uninterruptible wait on an underlying lock. This means that no exceptions
can occur, and in particular a SIGINT will not trigger a :exc:`KeyboardInterrupt`.
.. method:: Queue.get_nowait()

5
Doc/library/random.rst
View file

@ -310,6 +310,11 @@ be found in any statistics text.
Alternative Generator
---------------------
.. class:: Random([seed])
Class that implements the default pseudo-random number generator used by the
:mod:`random` module.
.. class:: SystemRandom([seed])
Class that uses the :func:`os.urandom` function for generating random numbers

1
Doc/library/re.rst
View file

@ -908,6 +908,7 @@ form.
Unknown escapes in *repl* consisting of ``'\'`` and an ASCII letter
now are errors.
.. versionchanged:: 3.7
Empty matches for the pattern are replaced when adjacent to a previous
non-empty match.

2
Doc/library/resource.rst
View file

@ -76,6 +76,8 @@ this module for those platforms.
``setrlimit`` may also raise :exc:`error` if the underlying system call
fails.
VxWorks only supports setting :data:`RLIMIT_NOFILE`.
.. function:: prlimit(pid, resource[, limits])
Combines :func:`setrlimit` and :func:`getrlimit` in one function and

6
Doc/library/shutil.rst
View file

@ -559,6 +559,10 @@ provided. They rely on the :mod:`zipfile` and :mod:`tarfile` modules.
The *verbose* argument is unused and deprecated.
.. versionchanged:: 3.8
The modern pax (POSIX.1-2001) format is now used instead of
the legacy GNU format for archives created with ``format="tar"``.
.. function:: get_archive_formats()
@ -568,7 +572,7 @@ provided. They rely on the :mod:`zipfile` and :mod:`tarfile` modules.
By default :mod:`shutil` provides these formats:
- *zip*: ZIP file (if the :mod:`zlib` module is available).
- *tar*: uncompressed tar file.
- *tar*: Uncompressed tar file. Uses POSIX.1-2001 pax format for new archives.
- *gztar*: gzip'ed tar-file (if the :mod:`zlib` module is available).
- *bztar*: bzip2'ed tar-file (if the :mod:`bz2` module is available).
- *xztar*: xz'ed tar-file (if the :mod:`lzma` module is available).

3
Doc/library/signal.rst
View file

@ -16,7 +16,8 @@ The :func:`signal.signal` function allows defining custom handlers to be
executed when a signal is received. A small number of default handlers are
installed: :const:`SIGPIPE` is ignored (so write errors on pipes and sockets
can be reported as ordinary Python exceptions) and :const:`SIGINT` is
translated into a :exc:`KeyboardInterrupt` exception.
translated into a :exc:`KeyboardInterrupt` exception if the parent process
has not changed it.
A handler for a particular signal, once set, remains installed until it is
explicitly reset (Python emulates the BSD style interface regardless of the

6
Doc/library/site.rst
View file

@ -45,9 +45,9 @@ sys.prefix and sys.exec_prefix are set to that directory and
it is also checked for site-packages (sys.base_prefix and
sys.base_exec_prefix will always be the "real" prefixes of the Python
installation). If "pyvenv.cfg" (a bootstrap configuration file) contains
the key "include-system-site-packages" set to anything other than "false"
(case-insensitive), the system-level prefixes will still also be
searched for site-packages; otherwise they won't.
the key "include-system-site-packages" set to anything other than "true"
(case-insensitive), the system-level prefixes will not be
searched for site-packages; otherwise they will.
.. index::
single: # (hash); comment

47
Doc/library/socket.rst
View file

@ -595,6 +595,50 @@ The following functions all create :ref:`socket objects <socket-objects>`.
.. versionchanged:: 3.2
*source_address* was added.
.. function:: create_server(address, *, family=AF_INET, backlog=None, reuse_port=False, dualstack_ipv6=False)
Convenience function which creates a TCP socket bound to *address* (a 2-tuple
``(host, port)``) and return the socket object.
*family* should be either :data:`AF_INET` or :data:`AF_INET6`.
*backlog* is the queue size passed to :meth:`socket.listen`; when ``0``
a default reasonable value is chosen.
*reuse_port* dictates whether to set the :data:`SO_REUSEPORT` socket option.
If *dualstack_ipv6* is true and the platform supports it the socket will
be able to accept both IPv4 and IPv6 connections, else it will raise
:exc:`ValueError`. Most POSIX platforms and Windows are supposed to support
this functionality.
When this functionality is enabled the address returned by
:meth:`socket.getpeername` when an IPv4 connection occurs will be an IPv6
address represented as an IPv4-mapped IPv6 address.
If *dualstack_ipv6* is false it will explicitly disable this functionality
on platforms that enable it by default (e.g. Linux).
This parameter can be used in conjunction with :func:`has_dualstack_ipv6`:
::
import socket
addr = ("", 8080) # all interfaces, port 8080
if socket.has_dualstack_ipv6():
s = socket.create_server(addr, family=socket.AF_INET6, dualstack_ipv6=True)
else:
s = socket.create_server(addr)
.. note::
On POSIX platforms the :data:`SO_REUSEADDR` socket option is set in order to
immediately reuse previous sockets which were bound on the same *address*
and remained in TIME_WAIT state.
.. versionadded:: 3.8
.. function:: has_dualstack_ipv6()
Return ``True`` if the platform supports creating a TCP socket which can
handle both IPv4 and IPv6 connections.
.. versionadded:: 3.8
.. function:: fromfd(fd, family, type, proto=0)
@ -752,6 +796,8 @@ The :mod:`socket` module also offers various network-related services:
For IPv6 addresses, ``%scope`` is appended to the host part if *sockaddr*
contains meaningful *scopeid*. Usually this happens for multicast addresses.
For more information about *flags* you can consult :manpage:`getnameinfo(3)`.
.. function:: getprotobyname(protocolname)
Translate an Internet protocol name (for example, ``'icmp'``) to a constant
@ -1778,7 +1824,6 @@ sends traffic to the first one connected successfully. ::
data = s.recv(1024)
print('Received', repr(data))
The next example shows how to write a very simple network sniffer with raw
sockets on Windows. The example requires administrator privileges to modify
the interface::

6
Doc/library/ssl.rst
View file

@ -665,7 +665,7 @@ Constants
.. data:: PROTOCOL_SSLv23
Alias for data:`PROTOCOL_TLS`.
Alias for :data:`PROTOCOL_TLS`.
.. deprecated:: 3.6
@ -1821,7 +1821,7 @@ to speed up repeated connections from the same clients.
.. attribute:: SSLContext.sslsocket_class
The return type of :meth:`SSLContext.wrap_sockets`, defaults to
The return type of :meth:`SSLContext.wrap_socket`, defaults to
:class:`SSLSocket`. The attribute can be overridden on instance of class
in order to return a custom subclass of :class:`SSLSocket`.
@ -1831,7 +1831,7 @@ to speed up repeated connections from the same clients.
server_hostname=None, session=None)
Wrap the BIO objects *incoming* and *outgoing* and return an instance of
attr:`SSLContext.sslobject_class` (default :class:`SSLObject`). The SSL
:attr:`SSLContext.sslobject_class` (default :class:`SSLObject`). The SSL
routines will read input data from the incoming BIO and write data to the
outgoing BIO.

75
Doc/library/statistics.rst
View file

@ -40,6 +40,7 @@ or sample.
======================= ===============================================================
:func:`mean` Arithmetic mean ("average") of data.
:func:`fmean` Fast, floating point arithmetic mean.
:func:`geometric_mean` Geometric mean of data.
:func:`harmonic_mean` Harmonic mean of data.
:func:`median` Median (middle value) of data.
:func:`median_low` Low median of data.
@ -47,6 +48,7 @@ or sample.
:func:`median_grouped` Median, or 50th percentile, of grouped data.
:func:`mode` Single mode (most common value) of discrete or nominal data.
:func:`multimode` List of modes (most common values) of discrete or nomimal data.
:func:`quantiles` Divide data into intervals with equal probability.
======================= ===============================================================
Measures of spread
@ -130,6 +132,24 @@ However, for reading convenience, most of the examples show sorted sequences.
.. versionadded:: 3.8
.. function:: geometric_mean(data)
Convert *data* to floats and compute the geometric mean.
Raises a :exc:`StatisticsError` if the input dataset is empty,
if it contains a zero, or if it contains a negative value.
No special efforts are made to achieve exact results.
(However, this may change in the future.)
.. doctest::
>>> round(geometric_mean([54, 24, 36]), 9)
36.0
.. versionadded:: 3.8
.. function:: harmonic_mean(data)
Return the harmonic mean of *data*, a sequence or iterator of
@ -480,6 +500,53 @@ However, for reading convenience, most of the examples show sorted sequences.
:func:`pvariance` function as the *mu* parameter to get the variance of a
sample.
.. function:: quantiles(dist, *, n=4, method='exclusive')
Divide *dist* into *n* continuous intervals with equal probability.
Returns a list of ``n - 1`` cut points separating the intervals.
Set *n* to 4 for quartiles (the default). Set *n* to 10 for deciles. Set
*n* to 100 for percentiles which gives the 99 cuts points that separate
*dist* in to 100 equal sized groups. Raises :exc:`StatisticsError` if *n*
is not least 1.
The *dist* can be any iterable containing sample data or it can be an
instance of a class that defines an :meth:`~inv_cdf` method.
Raises :exc:`StatisticsError` if there are not at least two data points.
For sample data, the cut points are linearly interpolated from the
two nearest data points. For example, if a cut point falls one-third
of the distance between two sample values, ``100`` and ``112``, the
cut-point will evaluate to ``104``. Other selection methods may be
offered in the future (for example choose ``100`` as the nearest
value or compute ``106`` as the midpoint). This might matter if
there are too few samples for a given number of cut points.
If *method* is set to *inclusive*, *dist* is treated as population data.
The minimum value is treated as the 0th percentile and the maximum
value is treated as the 100th percentile. If *dist* is an instance of
a class that defines an :meth:`~inv_cdf` method, setting *method*
has no effect.
.. doctest::
# Decile cut points for empirically sampled data
>>> data = [105, 129, 87, 86, 111, 111, 89, 81, 108, 92, 110,
... 100, 75, 105, 103, 109, 76, 119, 99, 91, 103, 129,
... 106, 101, 84, 111, 74, 87, 86, 103, 103, 106, 86,
... 111, 75, 87, 102, 121, 111, 88, 89, 101, 106, 95,
... 103, 107, 101, 81, 109, 104]
>>> [round(q, 1) for q in quantiles(data, n=10)]
[81.0, 86.2, 89.0, 99.4, 102.5, 103.6, 106.0, 109.8, 111.0]
>>> # Quartile cut points for the standard normal distibution
>>> Z = NormalDist()
>>> [round(q, 4) for q in quantiles(Z, n=4)]
[-0.6745, 0.0, 0.6745]
.. versionadded:: 3.8
Exceptions
----------
@ -540,7 +607,7 @@ of applications in statistics.
:exc:`StatisticsError` because it takes at least one point to estimate
a central value and at least two points to estimate dispersion.
.. method:: NormalDist.samples(n, seed=None)
.. method:: NormalDist.samples(n, *, seed=None)
Generates *n* random samples for a given mean and standard deviation.
Returns a :class:`list` of :class:`float` values.
@ -587,7 +654,7 @@ of applications in statistics.
<http://www.iceaaonline.com/ready/wp-content/uploads/2014/06/MM-9-Presentation-Meet-the-Overlapping-Coefficient-A-Measure-for-Elevator-Speeches.pdf>`_
between two normal distributions, giving a measure of agreement.
Returns a value between 0.0 and 1.0 giving `the overlapping area for
two probability density functions
the two probability density functions
<https://www.rasch.org/rmt/rmt101r.htm>`_.
Instances of :class:`NormalDist` support addition, subtraction,
@ -630,8 +697,8 @@ of applications in statistics.
For example, given `historical data for SAT exams
<https://blog.prepscholar.com/sat-standard-deviation>`_ showing that scores
are normally distributed with a mean of 1060 and a standard deviation of 192,
determine the percentage of students with scores between 1100 and 1200, after
rounding to the nearest whole number:
determine the percentage of students with test scores between 1100 and
1200, after rounding to the nearest whole number:
.. doctest::

16
Doc/library/stdtypes.rst
View file

@ -1509,6 +1509,10 @@ expression support in the :mod:`re` module).
Return a copy of the string with its first character capitalized and the
rest lowercased.
.. versionchanged:: 3.8
The first character is now put into titlecase rather than uppercase.
This means that characters like digraphs will only have their first
letter capitalized, instead of the full character.
.. method:: str.casefold()
@ -2052,8 +2056,7 @@ expression support in the :mod:`re` module).
>>> import re
>>> def titlecase(s):
... return re.sub(r"[A-Za-z]+('[A-Za-z]+)?",
... lambda mo: mo.group(0)[0].upper() +
... mo.group(0)[1:].lower(),
... lambda mo: mo.group(0).capitalize(),
... s)
...
>>> titlecase("they're bill's friends.")
@ -2696,8 +2699,8 @@ arbitrary binary data.
containing the part before the separator, the separator itself or its
bytearray copy, and the part after the separator.
If the separator is not found, return a 3-tuple
containing a copy of the original sequence, followed by two empty bytes or
bytearray objects.
containing two empty bytes or bytearray objects, followed by a copy of the
original sequence.
The separator to search for may be any :term:`bytes-like object`.
@ -4251,7 +4254,10 @@ pairs within braces, for example: ``{'jack': 4098, 'sjoerd': 4127}`` or ``{4098:
Create a new dictionary with keys from *iterable* and values set to *value*.
:meth:`fromkeys` is a class method that returns a new dictionary. *value*
defaults to ``None``.
defaults to ``None``. All of the values refer to just a single instance,
so it generally doesn't make sense for *value* to be a mutable object
such as an empty list. To get distinct values, use a :ref:`dict
comprehension <dict>` instead.
.. method:: get(key[, default])

7
Doc/library/subprocess.rst
View file

@ -567,6 +567,13 @@ functions.
Popen destructor now emits a :exc:`ResourceWarning` warning if the child
process is still running.
.. versionchanged:: 3.8
Popen can use :func:`os.posix_spawn` in some cases for better
performance. On Windows Subsystem for Linux and QEMU User Emulation,
Popen constructor using :func:`os.posix_spawn` no longer raise an
exception on errors like missing program, but the child process fails
with a non-zero :attr:`~Popen.returncode`.
Exceptions
^^^^^^^^^^

17
Doc/library/sys.rst
View file

@ -30,6 +30,12 @@ always available.
To loop over the standard input, or the list of files given on the
command line, see the :mod:`fileinput` module.
.. note::
On Unix, command line arguments are passed by bytes from OS. Python decodes
them with filesystem encoding and "surrogateescape" error handler.
When you need original bytes, you can get it by
``[os.fsencode(arg) for arg in sys.argv]``.
.. data:: base_exec_prefix
@ -1008,7 +1014,7 @@ always available.
This string contains a platform identifier that can be used to append
platform-specific components to :data:`sys.path`, for instance.
For Unix systems, except on Linux, this is the lowercased OS name as
For Unix systems, except on Linux and AIX, this is the lowercased OS name as
returned by ``uname -s`` with the first part of the version as returned by
``uname -r`` appended, e.g. ``'sunos5'`` or ``'freebsd8'``, *at the time
when Python was built*. Unless you want to test for a specific system
@ -1018,12 +1024,15 @@ always available.
# FreeBSD-specific code here...
elif sys.platform.startswith('linux'):
# Linux-specific code here...
elif sys.platform.startswith('aix'):
# AIX-specific code here...
For other systems, the values are:
================ ===========================
System ``platform`` value
================ ===========================
AIX ``'aix'``
Linux ``'linux'``
Windows ``'win32'``
Windows/Cygwin ``'cygwin'``
@ -1036,6 +1045,12 @@ always available.
older Python versions include the version number, it is recommended to
always use the ``startswith`` idiom presented above.
.. versionchanged:: 3.8
On AIX, :attr:`sys.platform` doesn't contain the major version anymore.
It is always ``'aix'``, instead of ``'aix5'`` or ``'aix7'``. Since
older Python versions include the version number, it is recommended to
always use the ``startswith`` idiom presented above.
.. seealso::
:attr:`os.name` has a coarser granularity. :func:`os.uname` gives

23
Doc/library/tarfile.rst
View file

@ -231,9 +231,9 @@ details.
The default format for creating archives. This is currently :const:`PAX_FORMAT`.
.. versionchanged:: 3.8
The default format for new archives was changed to
:const:`PAX_FORMAT` from :const:`GNU_FORMAT`.
.. versionchanged:: 3.8
The default format for new archives was changed to
:const:`PAX_FORMAT` from :const:`GNU_FORMAT`.
.. seealso::
@ -813,8 +813,8 @@ Supported tar formats
There are three tar formats that can be created with the :mod:`tarfile` module:
* The POSIX.1-1988 ustar format (:const:`USTAR_FORMAT`). It supports filenames
up to a length of at best 256 characters and linknames up to 100 characters. The
maximum file size is 8 GiB. This is an old and limited but widely
up to a length of at best 256 characters and linknames up to 100 characters.
The maximum file size is 8 GiB. This is an old and limited but widely
supported format.
* The GNU tar format (:const:`GNU_FORMAT`). It supports long filenames and
@ -826,14 +826,15 @@ There are three tar formats that can be created with the :mod:`tarfile` module:
format with virtually no limits. It supports long filenames and linknames, large
files and stores pathnames in a portable way. Modern tar implementations,
including GNU tar, bsdtar/libarchive and star, fully support extended *pax*
features; some older or unmaintained libraries may not, but should treat
features; some old or unmaintained libraries may not, but should treat
*pax* archives as if they were in the universally-supported *ustar* format.
It is the current default format for new archives.
The *pax* format is an extension to the existing *ustar* format. It uses extra
headers for information that cannot be stored otherwise. There are two flavours
of pax headers: Extended headers only affect the subsequent file header, global
headers are valid for the complete archive and affect all following files. All
the data in a pax header is encoded in *UTF-8* for portability reasons.
It extends the existing *ustar* format with extra headers for information
that cannot be stored otherwise. There are two flavours of pax headers:
Extended headers only affect the subsequent file header, global
headers are valid for the complete archive and affect all following files.
All the data in a pax header is encoded in *UTF-8* for portability reasons.
There are some more variants of the tar format which can be read, but not
created:

2
Doc/library/threading.rst
View file

@ -250,7 +250,7 @@ since it is impossible to detect the termination of alien threads.
You may override this method in a subclass. The standard :meth:`run`
method invokes the callable object passed to the object's constructor as
the *target* argument, if any, with sequential and keyword arguments taken
the *target* argument, if any, with positional and keyword arguments taken
from the *args* and *kwargs* arguments, respectively.
.. method:: join(timeout=None)

2
Doc/library/time.rst
View file

@ -153,6 +153,8 @@ Functions
:c:func:`QueryPerformanceCounter`. The resolution is typically better than one
microsecond.
.. availability:: Windows, Unix. Not available on VxWorks.
.. deprecated:: 3.3
The behaviour of this function depends on the platform: use
:func:`perf_counter` or :func:`process_time` instead, depending on your

18
Doc/library/typing.rst
View file

@ -951,6 +951,24 @@ The module defines the following classes, functions and decorators:
This wraps the decorator with something that wraps the decorated
function in :func:`no_type_check`.
.. decorator:: type_check_only
Decorator to mark a class or function to be unavailable at runtime.
This decorator is itself not available at runtime. It is mainly
intended to mark classes that are defined in type stub files if
an implementation returns an instance of a private class::
@type_check_only
class Response: # private or not available at runtime
code: int
def get_header(self, name: str) -> str: ...
def fetch_response() -> Response: ...
Note that returning instances of private classes is not recommended.
It is usually preferable to make such classes public.
.. data:: Any
Special type indicating an unconstrained type.

12
Doc/library/unittest.rst
View file

@ -1000,7 +1000,7 @@ Test cases
int('XYZ')
.. versionadded:: 3.1
under the name ``assertRaisesRegexp``.
Added under the name ``assertRaisesRegexp``.
.. versionchanged:: 3.2
Renamed to :meth:`assertRaisesRegex`.
@ -1145,7 +1145,7 @@ Test cases
+---------------------------------------+--------------------------------+--------------+
| :meth:`assertCountEqual(a, b) | *a* and *b* have the same | 3.2 |
| <TestCase.assertCountEqual>` | elements in the same number, | |
| | regardless of their order | |
| | regardless of their order. | |
+---------------------------------------+--------------------------------+--------------+
@ -1193,7 +1193,7 @@ Test cases
expression suitable for use by :func:`re.search`.
.. versionadded:: 3.1
under the name ``assertRegexpMatches``.
Added under the name ``assertRegexpMatches``.
.. versionchanged:: 3.2
The method ``assertRegexpMatches()`` has been renamed to
:meth:`.assertRegex`.
@ -1516,14 +1516,14 @@ along with their deprecated aliases:
============================== ====================== =======================
.. deprecated:: 3.1
the fail* aliases listed in the second column.
The fail* aliases listed in the second column have been deprecated.
.. deprecated:: 3.2
the assert* aliases listed in the third column.
The assert* aliases listed in the third column have been deprecated.
.. deprecated:: 3.2
``assertRegexpMatches`` and ``assertRaisesRegexp`` have been renamed to
:meth:`.assertRegex` and :meth:`.assertRaisesRegex`.
.. deprecated:: 3.5
the ``assertNotRegexpMatches`` name in favor of :meth:`.assertNotRegex`.
The ``assertNotRegexpMatches`` name is deprecated in favor of :meth:`.assertNotRegex`.
.. _testsuite-objects:

5
Doc/library/urllib.request.rst
View file

@ -192,8 +192,8 @@ The following classes are provided:
*data* must be an object specifying additional data to send to the
server, or ``None`` if no such data is needed. Currently HTTP
requests are the only ones that use *data*. The supported object
types include bytes, file-like objects, and iterables. If no
``Content-Length`` nor ``Transfer-Encoding`` header field
types include bytes, file-like objects, and iterables of bytes-like objects.
If no ``Content-Length`` nor ``Transfer-Encoding`` header field
has been provided, :class:`HTTPHandler` will set these headers according
to the type of *data*. ``Content-Length`` will be used to send
bytes objects, while ``Transfer-Encoding: chunked`` as specified in
@ -1435,6 +1435,7 @@ some point in the future.
The *data* argument has the same meaning as the *data* argument of
:func:`urlopen`.
This method always quotes *fullurl* using :func:`~urllib.parse.quote`.
.. method:: open_unknown(fullurl, data=None)

7
Doc/library/venv.rst
View file

@ -234,14 +234,19 @@ creation according to their needs, the :class:`EnvBuilder` class.
There is also a module-level convenience function:
.. function:: create(env_dir, system_site_packages=False, clear=False, \
symlinks=False, with_pip=False)
symlinks=False, with_pip=False, prompt=None)
Create an :class:`EnvBuilder` with the given keyword arguments, and call its
:meth:`~EnvBuilder.create` method with the *env_dir* argument.
.. versionadded:: 3.3
.. versionchanged:: 3.4
Added the ``with_pip`` parameter
.. versionchanged:: 3.6
Added the ``prompt`` parameter
An example of extending ``EnvBuilder``
--------------------------------------

10
Doc/library/warnings.rst
View file

@ -109,11 +109,11 @@ The following warnings category classes are currently defined:
+----------------------------------+-----------------------------------------------+
.. versionchanged:: 3.7
Previously :exc:`DeprecationWarning` and :exc:`FutureWarning` were
distinguished based on whether a feature was being removed entirely or
changing its behaviour. They are now distinguished based on their
intended audience and the way they're handled by the default warnings
filters.
Previously :exc:`DeprecationWarning` and :exc:`FutureWarning` were
distinguished based on whether a feature was being removed entirely or
changing its behaviour. They are now distinguished based on their
intended audience and the way they're handled by the default warnings
filters.
.. _warning-filter:

17
Doc/library/weakref.rst
View file

@ -139,6 +139,10 @@ Extension types can easily be made to support weak references; see
prevent their use as dictionary keys. *callback* is the same as the parameter
of the same name to the :func:`ref` function.
.. versionchanged:: 3.8
Extended the operator support on proxy objects to include the matrix
multiplication operators ``@`` and ``@=``.
.. function:: getweakrefcount(object)
@ -489,11 +493,14 @@ Unless you set the :attr:`~finalize.atexit` attribute to
:const:`False`, a finalizer will be called when the program exits if it
is still alive. For instance
>>> obj = Object()
>>> weakref.finalize(obj, print, "obj dead or exiting") #doctest:+ELLIPSIS
<finalize object at ...; for 'Object' at ...>
>>> exit() #doctest:+SKIP
obj dead or exiting
.. doctest::
:options: +SKIP
>>> obj = Object()
>>> weakref.finalize(obj, print, "obj dead or exiting")
<finalize object at ...; for 'Object' at ...>
>>> exit()
obj dead or exiting
Comparing finalizers with :meth:`__del__` methods

8
Doc/library/wsgiref.rst
View file

@ -767,7 +767,7 @@ This is a working "Hello World" WSGI application::
# use a function (note that you're not limited to a function, you can
# use a class for example). The first argument passed to the function
# is a dictionary containing CGI-style environment variables and the
# second variable is the callable object (see PEP 333).
# second variable is the callable object.
def hello_world_app(environ, start_response):
status = '200 OK' # HTTP Status
headers = [('Content-type', 'text/plain; charset=utf-8')] # HTTP Headers
@ -781,3 +781,9 @@ This is a working "Hello World" WSGI application::
# Serve until process is killed
httpd.serve_forever()
Example of a WSGI application serving the current directory, accept optional
directory and port number (default: 8000) on the command line:
.. literalinclude:: ../../Tools/scripts/serve.py

14
Doc/library/xml.dom.minidom.rst
View file

@ -238,22 +238,8 @@ The following interfaces have no implementation in :mod:`xml.dom.minidom`:
* :class:`DOMTimeStamp`
* :class:`DocumentType`
* :class:`DOMImplementation`
* :class:`CharacterData`
* :class:`CDATASection`
* :class:`Notation`
* :class:`Entity`
* :class:`EntityReference`
* :class:`DocumentFragment`
Most of these reflect information in the XML document that is not of general
utility to most DOM users.

194
Doc/library/xml.etree.elementtree.rst
View file

@ -399,6 +399,12 @@ module. We'll be using the ``countrydata`` XML document from the
# All 'neighbor' nodes that are the second child of their parent
root.findall(".//neighbor[2]")
For XML with namespaces, use the usual qualified ``{namespace}tag`` notation::
# All dublin-core "title" tags in the document
root.findall(".//{http://purl.org/dc/elements/1.1/}title")
Supported XPath syntax
^^^^^^^^^^^^^^^^^^^^^^
@ -411,9 +417,16 @@ Supported XPath syntax
| | For example, ``spam`` selects all child elements |
| | named ``spam``, and ``spam/egg`` selects all |
| | grandchildren named ``egg`` in all children named |
| | ``spam``. |
| | ``spam``. ``{namespace}*`` selects all tags in the |
| | given namespace, ``{*}spam`` selects tags named |
| | ``spam`` in any (or no) namespace, and ``{}*`` |
| | only selects tags that are not in a namespace. |
| | |
| | .. versionchanged:: 3.8 |
| | Support for star-wildcards was added. |
+-----------------------+------------------------------------------------------+
| ``*`` | Selects all child elements. For example, ``*/egg`` |
| ``*`` | Selects all child elements, including comments and |
| | processing instructions. For example, ``*/egg`` |
| | selects all grandchildren named ``egg``. |
+-----------------------+------------------------------------------------------+
| ``.`` | Selects the current node. This is mostly useful |
@ -465,6 +478,53 @@ Reference
Functions
^^^^^^^^^
.. function:: canonicalize(xml_data=None, *, out=None, from_file=None, **options)
`C14N 2.0 <https://www.w3.org/TR/xml-c14n2/>`_ transformation function.
Canonicalization is a way to normalise XML output in a way that allows
byte-by-byte comparisons and digital signatures. It reduced the freedom
that XML serializers have and instead generates a more constrained XML
representation. The main restrictions regard the placement of namespace
declarations, the ordering of attributes, and ignorable whitespace.
This function takes an XML data string (*xml_data*) or a file path or
file-like object (*from_file*) as input, converts it to the canonical
form, and writes it out using the *out* file(-like) object, if provided,
or returns it as a text string if not. The output file receives text,
not bytes. It should therefore be opened in text mode with ``utf-8``
encoding.
Typical uses::
xml_data = "<root>...</root>"
print(canonicalize(xml_data))
with open("c14n_output.xml", mode='w', encoding='utf-8') as out_file:
canonicalize(xml_data, out=out_file)
with open("c14n_output.xml", mode='w', encoding='utf-8') as out_file:
canonicalize(from_file="inputfile.xml", out=out_file)
The configuration *options* are as follows:
- *with_comments*: set to true to include comments (default: false)
- *strip_text*: set to true to strip whitespace before and after text content
(default: false)
- *rewrite_prefixes*: set to true to replace namespace prefixes by "n{number}"
(default: false)
- *qname_aware_tags*: a set of qname aware tag names in which prefixes
should be replaced in text content (default: empty)
- *qname_aware_attrs*: a set of qname aware attribute names in which prefixes
should be replaced in text content (default: empty)
- *exclude_attrs*: a set of attribute names that should not be serialised
- *exclude_tags*: a set of tag names that should not be serialised
In the option list above, "a set" refers to any collection or iterable of
strings, no ordering is expected.
.. versionadded:: 3.8
.. function:: Comment(text=None)
@ -523,8 +583,9 @@ Functions
Parses an XML section into an element tree incrementally, and reports what's
going on to the user. *source* is a filename or :term:`file object`
containing XML data. *events* is a sequence of events to report back. The
supported events are the strings ``"start"``, ``"end"``, ``"start-ns"`` and
``"end-ns"`` (the "ns" events are used to get detailed namespace
supported events are the strings ``"start"``, ``"end"``, ``"comment"``,
``"pi"``, ``"start-ns"`` and ``"end-ns"``
(the "ns" events are used to get detailed namespace
information). If *events* is omitted, only ``"end"`` events are reported.
*parser* is an optional parser instance. If not given, the standard
:class:`XMLParser` parser is used. *parser* must be a subclass of
@ -549,6 +610,10 @@ Functions
.. deprecated:: 3.4
The *parser* argument.
.. versionchanged:: 3.8
The ``comment`` and ``pi`` events were added.
.. function:: parse(source, parser=None)
Parses an XML section into an element tree. *source* is a filename or file
@ -594,6 +659,7 @@ Functions
.. function:: tostring(element, encoding="us-ascii", method="xml", *, \
xml_declaration=None, default_namespace=None,
short_empty_elements=True)
Generates a string representation of an XML element, including all
@ -601,14 +667,19 @@ Functions
the output encoding (default is US-ASCII). Use ``encoding="unicode"`` to
generate a Unicode string (otherwise, a bytestring is generated). *method*
is either ``"xml"``, ``"html"`` or ``"text"`` (default is ``"xml"``).
*short_empty_elements* has the same meaning as in :meth:`ElementTree.write`.
Returns an (optionally) encoded string containing the XML data.
*xml_declaration*, *default_namespace* and *short_empty_elements* has the same
meaning as in :meth:`ElementTree.write`. Returns an (optionally) encoded string
containing the XML data.
.. versionadded:: 3.4
The *short_empty_elements* parameter.
.. versionadded:: 3.8
The *xml_declaration* and *default_namespace* parameters.
.. function:: tostringlist(element, encoding="us-ascii", method="xml", *, \
xml_declaration=None, default_namespace=None,
short_empty_elements=True)
Generates a string representation of an XML element, including all
@ -616,16 +687,19 @@ Functions
the output encoding (default is US-ASCII). Use ``encoding="unicode"`` to
generate a Unicode string (otherwise, a bytestring is generated). *method*
is either ``"xml"``, ``"html"`` or ``"text"`` (default is ``"xml"``).
*short_empty_elements* has the same meaning as in :meth:`ElementTree.write`.
Returns a list of (optionally) encoded strings containing the XML data.
It does not guarantee any specific sequence, except that
``b"".join(tostringlist(element)) == tostring(element)``.
*xml_declaration*, *default_namespace* and *short_empty_elements* has the same
meaning as in :meth:`ElementTree.write`. Returns a list of (optionally) encoded
strings containing the XML data. It does not guarantee any specific sequence,
except that ``b"".join(tostringlist(element)) == tostring(element)``.
.. versionadded:: 3.2
.. versionadded:: 3.4
The *short_empty_elements* parameter.
.. versionadded:: 3.8
The *xml_declaration* and *default_namespace* parameters.
.. function:: XML(text, parser=None)
@ -755,7 +829,8 @@ Element Objects
Finds the first subelement matching *match*. *match* may be a tag name
or a :ref:`path <elementtree-xpath>`. Returns an element instance
or ``None``. *namespaces* is an optional mapping from namespace prefix
to full name.
to full name. Pass ``''`` as prefix to move all unprefixed tag names
in the expression into the given namespace.
.. method:: findall(match, namespaces=None)
@ -763,7 +838,8 @@ Element Objects
Finds all matching subelements, by tag name or
:ref:`path <elementtree-xpath>`. Returns a list containing all matching
elements in document order. *namespaces* is an optional mapping from
namespace prefix to full name.
namespace prefix to full name. Pass ``''`` as prefix to move all
unprefixed tag names in the expression into the given namespace.
.. method:: findtext(match, default=None, namespaces=None)
@ -773,7 +849,8 @@ Element Objects
of the first matching element, or *default* if no element was found.
Note that if the matching element has no text content an empty string
is returned. *namespaces* is an optional mapping from namespace prefix
to full name.
to full name. Pass ``''`` as prefix to move all unprefixed tag names
in the expression into the given namespace.
.. method:: getchildren()
@ -1009,14 +1086,24 @@ TreeBuilder Objects
^^^^^^^^^^^^^^^^^^^
.. class:: TreeBuilder(element_factory=None)
.. class:: TreeBuilder(element_factory=None, *, comment_factory=None, \
pi_factory=None, insert_comments=False, insert_pis=False)
Generic element structure builder. This builder converts a sequence of
start, data, and end method calls to a well-formed element structure. You
can use this class to build an element structure using a custom XML parser,
or a parser for some other XML-like format. *element_factory*, when given,
must be a callable accepting two positional arguments: a tag and
a dict of attributes. It is expected to return a new element instance.
start, data, end, comment and pi method calls to a well-formed element
structure. You can use this class to build an element structure using
a custom XML parser, or a parser for some other XML-like format.
*element_factory*, when given, must be a callable accepting two positional
arguments: a tag and a dict of attributes. It is expected to return a new
element instance.
The *comment_factory* and *pi_factory* functions, when given, should behave
like the :func:`Comment` and :func:`ProcessingInstruction` functions to
create comments and processing instructions. When not given, the default
factories will be used. When *insert_comments* and/or *insert_pis* is true,
comments/pis will be inserted into the tree if they appear within the root
element (but not outside of it).
.. method:: close()
@ -1042,8 +1129,24 @@ TreeBuilder Objects
containing element attributes. Returns the opened element.
.. method:: comment(text)
Creates a comment with the given *text*. If ``insert_comments`` is true,
this will also add it to the tree.
.. versionadded:: 3.8
.. method:: pi(target, text)
Creates a comment with the given *target* name and *text*. If
``insert_pis`` is true, this will also add it to the tree.
.. versionadded:: 3.8
In addition, a custom :class:`TreeBuilder` object can provide the
following method:
following methods:
.. method:: doctype(name, pubid, system)
@ -1053,6 +1156,36 @@ TreeBuilder Objects
.. versionadded:: 3.2
.. method:: start_ns(prefix, uri)
Is called whenever the parser encounters a new namespace declaration,
before the ``start()`` callback for the opening element that defines it.
*prefix* is ``''`` for the default namespace and the declared
namespace prefix name otherwise. *uri* is the namespace URI.
.. versionadded:: 3.8
.. method:: end_ns(prefix)
Is called after the ``end()`` callback of an element that declared
a namespace prefix mapping, with the name of the *prefix* that went
out of scope.
.. versionadded:: 3.8
.. class:: C14NWriterTarget(write, *, \
with_comments=False, strip_text=False, rewrite_prefixes=False, \
qname_aware_tags=None, qname_aware_attrs=None, \
exclude_attrs=None, exclude_tags=None)
A `C14N 2.0 <https://www.w3.org/TR/xml-c14n2/>`_ writer. Arguments are the
same as for the :func:`canonicalize` function. This class does not build a
tree but translates the callback events directly into a serialised form
using the *write* function.
.. versionadded:: 3.8
.. _elementtree-xmlparser-objects:
@ -1088,7 +1221,8 @@ XMLParser Objects
:meth:`XMLParser.feed` calls *target*\'s ``start(tag, attrs_dict)`` method
for each opening tag, its ``end(tag)`` method for each closing tag, and data
is processed by method ``data(data)``. :meth:`XMLParser.close` calls
is processed by method ``data(data)``. For further supported callback
methods, see the :class:`TreeBuilder` class. :meth:`XMLParser.close` calls
*target*\'s method ``close()``. :class:`XMLParser` can be used not only for
building a tree structure. This is an example of counting the maximum depth
of an XML file::
@ -1138,9 +1272,9 @@ XMLPullParser Objects
callback target, :class:`XMLPullParser` collects an internal list of parsing
events and lets the user read from it. *events* is a sequence of events to
report back. The supported events are the strings ``"start"``, ``"end"``,
``"start-ns"`` and ``"end-ns"`` (the "ns" events are used to get detailed
namespace information). If *events* is omitted, only ``"end"`` events are
reported.
``"comment"``, ``"pi"``, ``"start-ns"`` and ``"end-ns"`` (the "ns" events
are used to get detailed namespace information). If *events* is omitted,
only ``"end"`` events are reported.
.. method:: feed(data)
@ -1159,7 +1293,13 @@ XMLPullParser Objects
data fed to the
parser. The iterator yields ``(event, elem)`` pairs, where *event* is a
string representing the type of event (e.g. ``"end"``) and *elem* is the
encountered :class:`Element` object.
encountered :class:`Element` object, or other context value as follows.
* ``start``, ``end``: the current Element.
* ``comment``, ``pi``: the current comment / processing instruction
* ``start-ns``: a tuple ``(prefix, uri)`` naming the declared namespace
mapping.
* ``end-ns``: :const:`None` (this may change in a future version)
Events provided in a previous call to :meth:`read_events` will not be
yielded again. Events are consumed from the internal queue only when
@ -1179,6 +1319,10 @@ XMLPullParser Objects
.. versionadded:: 3.4
.. versionchanged:: 3.8
The ``comment`` and ``pi`` events were added.
Exceptions
^^^^^^^^^^

6
Doc/library/xml.sax.reader.rst
View file

@ -102,13 +102,17 @@ The :class:`XMLReader` interface supports the following methods:
Process an input source, producing SAX events. The *source* object can be a
system identifier (a string identifying the input source -- typically a file
name or a URL), a file-like object, or an :class:`InputSource` object. When
name or a URL), a :class:`pathlib.Path` or :term:`path-like <path-like object>`
object, or an :class:`InputSource` object. When
:meth:`parse` returns, the input is completely processed, and the parser object
can be discarded or reset.
.. versionchanged:: 3.5
Added support of character streams.
.. versionchanged:: 3.8
Added support of path-like objects.
.. method:: XMLReader.getContentHandler()

67
Doc/library/zipfile.rst
View file

@ -52,6 +52,15 @@ The module defines the following items:
:ref:`zipfile-objects` for constructor details.
.. class:: Path
:noindex:
A pathlib-compatible wrapper for zip files. See section
:ref:`path-objects` for details.
.. versionadded:: 3.8
.. class:: PyZipFile
:noindex:
@ -456,6 +465,64 @@ The following data attributes are also available:
truncated.
.. _path-objects:
Path Objects
------------
.. class:: Path(root, at='')
Construct a Path object from a ``root`` zipfile (which may be a
:class:`ZipFile` instance or ``file`` suitable for passing to
the :class:`ZipFile` constructor).
``at`` specifies the location of this Path within the zipfile,
e.g. 'dir/file.txt', 'dir/', or ''. Defaults to the empty string,
indicating the root.
Path objects expose the following features of :mod:`pathlib.Path`
objects:
Path objects are traversable using the ``/`` operator.
.. attribute:: Path.name
The final path component.
.. method:: Path.open(*, **)
Invoke :meth:`ZipFile.open` on the current path. Accepts
the same arguments as :meth:`ZipFile.open`.
.. method:: Path.listdir()
Enumerate the children of the current directory.
.. method:: Path.is_dir()
Return ``True`` if the current context references a directory.
.. method:: Path.is_file()
Return ``True`` if the current context references a file.
.. method:: Path.exists()
Return ``True`` if the current context references a file or
directory in the zip file.
.. method:: Path.read_text(*, **)
Read the current file as unicode text. Positional and
keyword arguments are passed through to
:class:`io.TextIOWrapper` (except ``buffer``, which is
implied by the context).
.. method:: Path.read_bytes()
Read the current file as bytes.
.. _pyzipfile-objects:
PyZipFile Objects

39
Doc/license.rst
View file

@ -561,7 +561,7 @@ SipHash24
---------
The file :file:`Python/pyhash.c` contains Marek Majkowski' implementation of
Dan Bernstein's SipHash24 algorithm. The contains the following note::
Dan Bernstein's SipHash24 algorithm. It contains the following note::
<MIT License>
Copyright (c) 2013 Marek Majkowski <marek@popcount.org>
@ -913,3 +913,40 @@ library unless the build is configured ``--with-system-libmpdec``::
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.
W3C C14N test suite
-------------------
The C14N 2.0 test suite in the :mod:`test` package
(``Lib/test/xmltestdata/c14n-20/``) was retrieved from the W3C website at
https://www.w3.org/TR/xml-c14n2-testcases/ and is distributed under the
3-clause BSD license:
Copyright (c) 2013 W3C(R) (MIT, ERCIM, Keio, Beihang),
All Rights Reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
* Redistributions of works must retain the original copyright notice,
this list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the original copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
* Neither the name of the W3C nor the names of its contributors may be
used to endorse or promote products derived from this work without
specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

40
Doc/reference/datamodel.rst
View file

@ -475,13 +475,13 @@ Callable types
| :attr:`__doc__` | The function's documentation | Writable |
| | string, or ``None`` if | |
| | unavailable; not inherited by | |
| | subclasses | |
| | subclasses. | |
+-------------------------+-------------------------------+-----------+
| :attr:`~definition.\ | The function's name | Writable |
| :attr:`~definition.\ | The function's name. | Writable |
| __name__` | | |
+-------------------------+-------------------------------+-----------+
| :attr:`~definition.\ | The function's | Writable |
| __qualname__` | :term:`qualified name` | |
| __qualname__` | :term:`qualified name`. | |
| | | |
| | .. versionadded:: 3.3 | |
+-------------------------+-------------------------------+-----------+
@ -493,7 +493,7 @@ Callable types
| | argument values for those | |
| | arguments that have defaults, | |
| | or ``None`` if no arguments | |
| | have a default value | |
| | have a default value. | |
+-------------------------+-------------------------------+-----------+
| :attr:`__code__` | The code object representing | Writable |
| | the compiled function body. | |
@ -1311,9 +1311,9 @@ Basic customization
Called by the :func:`format` built-in function,
and by extension, evaluation of :ref:`formatted string literals
<f-strings>` and the :meth:`str.format` method, to produce a "formatted"
string representation of an object. The ``format_spec`` argument is
string representation of an object. The *format_spec* argument is
a string that contains a description of the formatting options desired.
The interpretation of the ``format_spec`` argument is up to the type
The interpretation of the *format_spec* argument is up to the type
implementing :meth:`__format__`, however most classes will either
delegate formatting to one of the built-in types, or use a similar
formatting option syntax.
@ -1857,11 +1857,11 @@ passed through to all metaclass operations described below.
When a class definition is executed, the following steps occur:
* MRO entries are resolved
* the appropriate metaclass is determined
* the class namespace is prepared
* the class body is executed
* the class object is created
* MRO entries are resolved;
* the appropriate metaclass is determined;
* the class namespace is prepared;
* the class body is executed;
* the class object is created.
Resolving MRO entries
@ -1885,11 +1885,11 @@ Determining the appropriate metaclass
The appropriate metaclass for a class definition is determined as follows:
* if no bases and no explicit metaclass are given, then :func:`type` is used
* if no bases and no explicit metaclass are given, then :func:`type` is used;
* if an explicit metaclass is given and it is *not* an instance of
:func:`type`, then it is used directly as the metaclass
:func:`type`, then it is used directly as the metaclass;
* if an instance of :func:`type` is given as the explicit metaclass, or
bases are defined, then the most derived metaclass is used
bases are defined, then the most derived metaclass is used.
The most derived metaclass is selected from the explicitly specified
metaclass (if any) and the metaclasses (i.e. ``type(cls)``) of all specified
@ -1976,7 +1976,7 @@ invoked after creating the class object:
* first, ``type.__new__`` collects all of the descriptors in the class
namespace that define a :meth:`~object.__set_name__` method;
* second, all of these ``__set_name__`` methods are called with the class
being defined and the assigned name of that particular descriptor; and
being defined and the assigned name of that particular descriptor;
* finally, the :meth:`~object.__init_subclass__` hook is called on the
immediate parent of the new class in its method resolution order.
@ -2048,7 +2048,7 @@ Emulating generic types
-----------------------
One can implement the generic class syntax as specified by :pep:`484`
(for example ``List[int]``) by defining a special method
(for example ``List[int]``) by defining a special method:
.. classmethod:: object.__class_getitem__(cls, key)
@ -2680,13 +2680,13 @@ Asynchronous context managers can be used in an :keyword:`async with` statement.
.. method:: object.__aenter__(self)
This method is semantically similar to the :meth:`__enter__`, with only
difference that it must return an *awaitable*.
Semantically similar to :meth:`__enter__`, the only
difference being that it must return an *awaitable*.
.. method:: object.__aexit__(self, exc_type, exc_value, traceback)
This method is semantically similar to the :meth:`__exit__`, with only
difference that it must return an *awaitable*.
Semantically similar to :meth:`__exit__`, the only
difference being that it must return an *awaitable*.
An example of an asynchronous context manager class::

51
Doc/reference/import.rst
View file

@ -345,12 +345,11 @@ of what happens during the loading portion of import::
_init_module_attrs(spec, module)
if spec.loader is None:
if spec.submodule_search_locations is not None:
# namespace package
sys.modules[spec.name] = module
else:
# unsupported
raise ImportError
# unsupported
raise ImportError
if spec.origin is None and spec.submodule_search_locations is not None:
# namespace package
sys.modules[spec.name] = module
elif not hasattr(spec.loader, 'exec_module'):
module = spec.loader.load_module(spec.name)
# Set __loader__ and __package__ if missing.
@ -921,6 +920,46 @@ it is sufficient to raise :exc:`ModuleNotFoundError` directly from
``None``. The latter indicates that the meta path search should continue,
while raising an exception terminates it immediately.
.. _relativeimports:
Package Relative Imports
========================
Relative imports use leading dots. A single leading dot indicates a relative
import, starting with the current package. Two or more leading dots indicate a
relative import to the parent(s) of the current package, one level per dot
after the first. For example, given the following package layout::
package/
__init__.py
subpackage1/
__init__.py
moduleX.py
moduleY.py
subpackage2/
__init__.py
moduleZ.py
moduleA.py
In either ``subpackage1/moduleX.py`` or ``subpackage1/__init__.py``,
the following are valid relative imports::
from .moduleY import spam
from .moduleY import spam as ham
from . import moduleY
from ..subpackage1 import moduleY
from ..subpackage2.moduleZ import eggs
from ..moduleA import foo
Absolute imports may use either the ``import <>`` or ``from <> import <>``
syntax, but relative imports may only use the second form; the reason
for this is that::
import XXX.YYY.ZZZ
should expose ``XXX.YYY.ZZZ`` as a usable expression, but .moduleY is
not a valid expression.
Special considerations for __main__
===================================

11
Doc/reference/lexical_analysis.rst
View file

@ -680,11 +680,12 @@ with a closing curly bracket ``'}'``.
Expressions in formatted string literals are treated like regular
Python expressions surrounded by parentheses, with a few exceptions.
An empty expression is not allowed, and a :keyword:`lambda` expression
must be surrounded by explicit parentheses. Replacement expressions
can contain line breaks (e.g. in triple-quoted strings), but they
cannot contain comments. Each expression is evaluated in the context
where the formatted string literal appears, in order from left to right.
An empty expression is not allowed, and both :keyword:`lambda` and
assignment expressions ``:=`` must be surrounded by explicit parentheses.
Replacement expressions can contain line breaks (e.g. in triple-quoted
strings), but they cannot contain comments. Each expression is evaluated
in the context where the formatted string literal appears, in order from
left to right.
If a conversion is specified, the result of evaluating the expression
is converted before formatting. Conversion ``'!s'`` calls :func:`str` on

11
Doc/reference/simple_stmts.rst
View file

@ -169,12 +169,12 @@ Assignment of an object to a single target is recursively defined as follows.
.. _attr-target-note:
Note: If the object is a class instance and the attribute reference occurs on
both sides of the assignment operator, the RHS expression, ``a.x`` can access
both sides of the assignment operator, the right-hand side expression, ``a.x`` can access
either an instance attribute or (if no instance attribute exists) a class
attribute. The LHS target ``a.x`` is always set as an instance attribute,
attribute. The left-hand side target ``a.x`` is always set as an instance attribute,
creating it if necessary. Thus, the two occurrences of ``a.x`` do not
necessarily refer to the same attribute: if the RHS expression refers to a
class attribute, the LHS creates a new instance attribute as the target of the
necessarily refer to the same attribute: if the right-hand side expression refers to a
class attribute, the left-hand side creates a new instance attribute as the target of the
assignment::
class Cls:
@ -828,7 +828,8 @@ exists. Two dots means up one package level. Three dots is up two levels, etc.
So if you execute ``from . import mod`` from a module in the ``pkg`` package
then you will end up importing ``pkg.mod``. If you execute ``from ..subpkg2
import mod`` from within ``pkg.subpkg1`` you will import ``pkg.subpkg2.mod``.
The specification for relative imports is contained within :pep:`328`.
The specification for relative imports is contained in
the :ref:`relativeimports` section.
:func:`importlib.import_module` is provided to support applications that
determine dynamically the modules to be loaded.

1
Doc/tools/static/switchers.js
View file

@ -22,6 +22,7 @@
'fr': 'French',
'ja': 'Japanese',
'ko': 'Korean',
'zh-cn': 'Simplified Chinese',
};
function build_version_select(current_version, current_release) {

3
Doc/tools/templates/download.html
View file

@ -12,8 +12,7 @@ <h1>Download Python {{ release }} Documentation</h1>
{% if last_updated %}<p><b>Last updated on: {{ last_updated }}.</b></p>{% endif %}
<p>To download an archive containing all the documents for this version of
Python in one of various formats, follow one of links in this table. The numbers
in the table are the size of the download files in megabytes.</p>
Python in one of various formats, follow one of links in this table.</p>
<table class="docutils">
<tr><th>Format</th><th>Packed as .zip</th><th>Packed as .tar.bz2</th></tr>

1
Doc/tools/templates/indexcontent.html
View file

@ -57,6 +57,7 @@ <h1>{{ docstitle|e }}</h1>
<table class="contentstable" align="center"><tr>
<td width="50%">
<p class="biglink"><a class="biglink" href="{{ pathto("bugs") }}">{% trans %}Reporting bugs{% endtrans %}</a></p>
<p class="biglink"><a class="biglink" href="https://devguide.python.org/docquality/#helping-with-documentation">{% trans %}Contributing to Docs{% endtrans %}</a></p>
<p class="biglink"><a class="biglink" href="{{ pathto("about") }}">{% trans %}About the documentation{% endtrans %}</a></p>
</td><td width="50%">
<p class="biglink"><a class="biglink" href="{{ pathto("license") }}">{% trans %}History and License of Python{% endtrans %}</a></p>

23
Doc/tutorial/datastructures.rst
View file

@ -678,18 +678,17 @@ intended.
Comparing Sequences and Other Types
===================================
Sequence objects may be compared to other objects with the same sequence type.
The comparison uses *lexicographical* ordering: first the first two items are
compared, and if they differ this determines the outcome of the comparison; if
they are equal, the next two items are compared, and so on, until either
sequence is exhausted. If two items to be compared are themselves sequences of
the same type, the lexicographical comparison is carried out recursively. If
all items of two sequences compare equal, the sequences are considered equal.
If one sequence is an initial sub-sequence of the other, the shorter sequence is
the smaller (lesser) one. Lexicographical ordering for strings uses the Unicode
code point number to order individual characters. Some examples of comparisons
between sequences of the same type::
Sequence objects typically may be compared to other objects with the same sequence
type. The comparison uses *lexicographical* ordering: first the first two
items are compared, and if they differ this determines the outcome of the
comparison; if they are equal, the next two items are compared, and so on, until
either sequence is exhausted. If two items to be compared are themselves
sequences of the same type, the lexicographical comparison is carried out
recursively. If all items of two sequences compare equal, the sequences are
considered equal. If one sequence is an initial sub-sequence of the other, the
shorter sequence is the smaller (lesser) one. Lexicographical ordering for
strings uses the Unicode code point number to order individual characters.
Some examples of comparisons between sequences of the same type::
(1, 2, 3) < (1, 2, 4)
[1, 2, 3] < [1, 2, 4]

2
Doc/tutorial/inputoutput.rst
View file

@ -322,6 +322,8 @@ equivalent :keyword:`try`\ -\ :keyword:`finally` blocks::
>>> with open('workfile') as f:
... read_data = f.read()
>>> # We can check that the file has been automatically closed.
>>> f.closed
True

2
Doc/tutorial/introduction.rst
View file

@ -383,7 +383,7 @@ items of different types, but usually the items all have the same type. ::
>>> squares
[1, 4, 9, 16, 25]
Like strings (and all other built-in :term:`sequence` type), lists can be
Like strings (and all other built-in :term:`sequence` types), lists can be
indexed and sliced::
>>> squares[0] # indexing returns the item

8
Doc/tutorial/modules.rst
View file

@ -425,9 +425,9 @@ your package (expressed in terms of a hierarchical filesystem):
When importing the package, Python searches through the directories on
``sys.path`` looking for the package subdirectory.
The :file:`__init__.py` files are required to make Python treat the directories
as containing packages; this is done to prevent directories with a common name,
such as ``string``, from unintentionally hiding valid modules that occur later
The :file:`__init__.py` files are required to make Python treat directories
containing the file as packages. This prevents directories with a common name,
such as ``string``, unintentionally hiding valid modules that occur later
on the module search path. In the simplest case, :file:`__init__.py` can just be
an empty file, but it can also execute initialization code for the package or
set the ``__all__`` variable, described later.
@ -523,7 +523,7 @@ Although certain modules are designed to export only names that follow certain
patterns when you use ``import *``, it is still considered bad practice in
production code.
Remember, there is nothing wrong with using ``from Package import
Remember, there is nothing wrong with using ``from package import
specific_submodule``! In fact, this is the recommended notation unless the
importing module needs to use submodules with the same name from different
packages.

8
Doc/tutorial/whatnow.rst
View file

@ -39,7 +39,7 @@ More Python resources:
* https://docs.python.org: Fast access to Python's documentation.
* https://pypi.org: The Python Package Index, previously also nicknamed
the Cheese Shop, is an index of user-created Python modules that are available
the Cheese Shop [#]_, is an index of user-created Python modules that are available
for download. Once you begin releasing code, you can register it here so that
others can find it.
@ -68,3 +68,9 @@ Before posting, be sure to check the list of
:ref:`Frequently Asked Questions <faq-index>` (also called the FAQ). The
FAQ answers many of the questions that come up again and again, and may
already contain the solution for your problem.
.. rubric:: Footnotes
.. [#] "Cheese Shop" is a Monty Python's sketch: a customer enters a cheese shop,
but whatever cheese he asks for, the clerk says it's missing.

11
Doc/using/cmdline.rst
View file

@ -437,6 +437,7 @@ Miscellaneous options
* Enable :ref:`asyncio debug mode <asyncio-debug-mode>`.
* Set the :attr:`~sys.flags.dev_mode` attribute of :attr:`sys.flags` to
``True``
* :class:`io.IOBase` destructor logs ``close()`` exceptions.
* ``-X utf8`` enables UTF-8 mode for operating system interfaces, overriding
the default locale-aware mode. ``-X utf8=0`` explicitly disables UTF-8
@ -465,7 +466,8 @@ Miscellaneous options
The ``-X importtime``, ``-X dev`` and ``-X utf8`` options.
.. versionadded:: 3.8
The ``-X pycache_prefix`` option.
The ``-X pycache_prefix`` option. The ``-X dev`` option now logs
``close()`` exceptions in :class:`io.IOBase` destructor.
Options you shouldn't use
@ -920,15 +922,18 @@ conflict.
Debug-mode variables
~~~~~~~~~~~~~~~~~~~~
Setting these variables only has an effect in a debug build of Python, that is,
if Python was configured with the ``--with-pydebug`` build option.
Setting these variables only has an effect in a debug build of Python.
.. envvar:: PYTHONTHREADDEBUG
If set, Python will print threading debug info.
Need Python configured with the ``--with-pydebug`` build option.
.. envvar:: PYTHONDUMPREFS
If set, Python will dump objects and reference counts still alive after
shutting down the interpreter.
Need Python configured with the ``--with-trace-refs`` build option.

36
Doc/using/windows.rst
View file

@ -154,7 +154,9 @@ of available options is shown below.
| DefaultJustForMeTargetDir | The default install directory for | :file:`%LocalAppData%\\\ |
| | just-for-me installs | Programs\\PythonXY` or |
| | | :file:`%LocalAppData%\\\ |
| | | Programs\\PythonXY-32` |
| | | Programs\\PythonXY-32` or|
| | | :file:`%LocalAppData%\\\ |
| | | Programs\\PythonXY-64` |
+---------------------------+--------------------------------------+--------------------------+
| DefaultCustomTargetDir | The default custom install directory | (empty) |
| | displayed in the UI | |
@ -762,9 +764,16 @@ on Windows which you hope will be useful on Unix, you should use one of the
shebang lines starting with ``/usr``.
Any of the above virtual commands can be suffixed with an explicit version
(either just the major version, or the major and minor version) - for example
``/usr/bin/python2.7`` - which will cause that specific version to be located
and used.
(either just the major version, or the major and minor version).
Furthermore the 32-bit version can be requested by adding "-32" after the
minor version. I.e. ``/usr/bin/python2.7-32`` will request usage of the
32-bit python 2.7.
.. versionadded:: 3.7
Beginning with python launcher 3.7 it is possible to request 64-bit version
by the "-64" suffix. Furthermore it is possible to specify a major and
architecture without minor (i.e. ``/usr/bin/python3-64``).
The ``/usr/bin/env`` form of shebang line has one further special property.
Before looking for installed Python interpreters, this form will search the
@ -806,17 +815,18 @@ Customizing default Python versions
In some cases, a version qualifier can be included in a command to dictate
which version of Python will be used by the command. A version qualifier
starts with a major version number and can optionally be followed by a period
('.') and a minor version specifier. If the minor qualifier is specified, it
may optionally be followed by "-32" to indicate the 32-bit implementation of
that version be used.
('.') and a minor version specifier. Furthermore it is possible to specifiy
if a 32 or 64 bit implementation shall be requested by adding "-32" or "-64".
For example, a shebang line of ``#!python`` has no version qualifier, while
``#!python3`` has a version qualifier which specifies only a major version.
If no version qualifiers are found in a command, the environment variable
``PY_PYTHON`` can be set to specify the default version qualifier - the default
value is "2". Note this value could specify just a major version (e.g. "2") or
a major.minor qualifier (e.g. "2.6"), or even major.minor-32.
If no version qualifiers are found in a command, the environment
variable :envvar:`PY_PYTHON` can be set to specify the default version
qualifier. If it is not set, the default is "3". The variable can
specify any value that may be passed on the command line, such as "3",
"3.7", "3.7-32" or "3.7-64". (Note that the "-64" option is only
available with the launcher included with Python 3.7 or newer.)
If no minor version qualifiers are found, the environment variable
``PY_PYTHON{major}`` (where ``{major}`` is the current major version qualifier
@ -834,8 +844,8 @@ of the specified version if available. This is so the behavior of the launcher
can be predicted knowing only what versions are installed on the PC and
without regard to the order in which they were installed (i.e., without knowing
whether a 32 or 64-bit version of Python and corresponding launcher was
installed last). As noted above, an optional "-32" suffix can be used on a
version specifier to change this behaviour.
installed last). As noted above, an optional "-32" or "-64" suffix can be
used on a version specifier to change this behaviour.
Examples:

339
Doc/whatsnew/3.8.rst
View file

@ -67,6 +67,47 @@ Summary -- Release highlights
New Features
============
Assignment expressions
----------------------
There is new syntax (the "walrus operator", ``:=``) to assign values
to variables as part of an expression. Example::
if (n := len(a)) > 10:
print(f"List is too long ({n} elements, expected <= 10)")
See :pep:`572` for a full description.
(Contributed by Emily Morehouse in :issue:`35224`.)
.. TODO: Emily will sprint on docs at PyCon US 2019.
Positional-only parameters
--------------------------
There is new syntax (``/``) to indicate that some function parameters
must be specified positionally (i.e., cannot be used as keyword
arguments). This is the same notation as shown by ``help()`` for
functions implemented in C (produced by Larry Hastings' "Argument
Clinic" tool). Example::
def pow(x, y, z=None, /):
r = x**y
if z is not None:
r %= z
return r
Now ``pow(2, 10)`` and ``pow(2, 10, 17)`` are valid calls, but
``pow(x=2, y=10)`` and ``pow(2, 10, z=17)`` are invalid.
See :pep:`570` for a full description.
(Contributed by Pablo Galindo in :issue:`36540`.)
.. TODO: Pablo will sprint on docs at PyCon US 2019.
Parallel filesystem cache for compiled bytecode files
-----------------------------------------------------
@ -82,6 +123,31 @@ subdirectories).
(Contributed by Carl Meyer in :issue:`33499`.)
Debug build uses the same ABI as release build
-----------------------------------------------
Python now uses the same ABI whether it built in release or debug mode. On
Unix, when Python is built in debug mode, it is now possible to load C
extensions built in release mode and C extensions built using the stable ABI.
Release builds and debug builds are now ABI compatible: defining the
``Py_DEBUG`` macro no longer implies the ``Py_TRACE_REFS`` macro, which
introduces the only ABI incompatibility. The ``Py_TRACE_REFS`` macro, which
adds the :func:`sys.getobjects` function and the :envvar:`PYTHONDUMPREFS`
environment variable, can be set using the new ``./configure --with-trace-refs``
build option.
(Contributed by Victor Stinner in :issue:`36465`.)
On Unix, C extensions are no longer linked to libpython. It is now possible
for a statically linked Python to load a C extension built using a shared
library Python.
(Contributed by Victor Stinner in :issue:`21536`.)
On Unix, when Python is built in debug mode, import now also looks for C
extensions compiled in release mode and for C extensions compiled with the
stable ABI.
(Contributed by Victor Stinner in :issue:`36722`.)
Other Language Changes
======================
@ -150,17 +216,6 @@ New Modules
Improved Modules
================
* The :meth:`_asdict()` method for :func:`collections.namedtuple` now returns
a :class:`dict` instead of a :class:`collections.OrderedDict`. This works because
regular dicts have guaranteed ordering in since Python 3.7. If the extra
features of :class:`OrderedDict` are required, the suggested remediation is
to cast the result to the desired type: ``OrderedDict(nt._asdict())``.
(Contributed by Raymond Hettinger in :issue:`35864`.)
* The :mod:`unicodedata` module has been upgraded to use the `Unicode 12.0.0
<http://blog.unicode.org/2019/03/announcing-unicode-standard-version-120.html>`_
release.
asyncio
-------
@ -168,12 +223,57 @@ asyncio
On Windows, the default event loop is now :class:`~asyncio.ProactorEventLoop`.
collections
-----------
The :meth:`_asdict()` method for :func:`collections.namedtuple` now returns
a :class:`dict` instead of a :class:`collections.OrderedDict`. This works because
regular dicts have guaranteed ordering since Python 3.7. If the extra
features of :class:`OrderedDict` are required, the suggested remediation is
to cast the result to the desired type: ``OrderedDict(nt._asdict())``.
(Contributed by Raymond Hettinger in :issue:`35864`.)
ctypes
------
On Windows, :class:`~ctypes.CDLL` and subclasses now accept a *winmode* parameter
to specify flags for the underlying ``LoadLibraryEx`` call. The default flags are
set to only load DLL dependencies from trusted locations, including the path
where the DLL is stored (if a full or partial path is used to load the initial
DLL) and paths added by :func:`~os.add_dll_directory`.
datetime
--------
Added new alternate constructors :meth:`datetime.date.fromisocalendar` and
:meth:`datetime.datetime.fromisocalendar`, which construct :class:`date` and
:class:`datetime` objects respectively from ISO year, week number and weekday;
these are the inverse of each class's ``isocalendar`` method.
(Contributed by Paul Ganssle in :issue:`36004`.)
gettext
-------
Added :func:`~gettext.pgettext` and its variants.
(Contributed by Franz Glasner, Éric Araujo, and Cheryl Sabella in :issue:`2504`.)
inspect
-------
The :func:`inspect.getdoc` function can now find docstrings for ``__slots__``
if that attribute is a :class:`dict` where the values are docstrings.
This provides documentation options similar to what we already have
for :func:`property`, :func:`classmethod`, and :func:`staticmethod`::
class AudioClip:
__slots__ = {'bit_rate': 'expressed in kilohertz to one decimal place',
'duration': 'in seconds, rounded up to an integer'}
def __init__(self, bit_rate, duration):
self.bit_rate = round(bit_rate / 1000.0, 1)
self.duration = ceil(duration)
gc
--
@ -224,6 +324,13 @@ Added new function, :func:`math.prod`, as analogous function to :func:`sum`
that returns the product of a 'start' value (default: 1) times an iterable of
numbers. (Contributed by Pablo Galindo in :issue:`35606`)
os
--
Added new function :func:`~os.add_dll_directory` on Windows for providing
additional search paths for native dependencies when importing extension
modules or loading DLLs using :mod:`ctypes`.
os.path
-------
@ -262,6 +369,19 @@ pathlib
contain characters unrepresentable at the OS level.
(Contributed by Serhiy Storchaka in :issue:`33721`.)
Added :meth:`pathlib.Path.link_to()` which creates a hard link pointing
to a path.
(Contributed by Joannah Nanjekye in :issue:`26978`)
socket
------
Added :meth:`~socket.create_server()` and :meth:`~socket.has_dualstack_ipv6()`
convenience functions to automate the necessary tasks usually involved when
creating a server socket, including accepting both IPv4 and IPv6 connections
on the same socket. (Contributed by Giampaolo Rodola in :issue:`17561`.)
shutil
------
@ -269,6 +389,11 @@ shutil
:func:`shutil.copytree` now accepts a new ``dirs_exist_ok`` keyword argument.
(Contributed by Josh Bronson in :issue:`20849`.)
:func:`shutil.make_archive` now defaults to the modern pax (POSIX.1-2001)
format for new archives to improve portability and standards conformance,
inherited from the corresponding change to the :mod:`tarfile` module.
(Contributed by C.A.M. Gerlach in :issue:`30661`.)
ssl
---
@ -286,9 +411,16 @@ Added :func:`statistics.fmean` as a faster, floating point variant of
:func:`statistics.mean()`. (Contributed by Raymond Hettinger and
Steven D'Aprano in :issue:`35904`.)
Added :func:`statistics.geometric_mean()`
(Contributed by Raymond Hettinger in :issue:`27181`.)
Added :func:`statistics.multimode` that returns a list of the most
common values. (Contributed by Raymond Hettinger in :issue:`35892`.)
Added :func:`statistics.quantiles` that divides data or a distribution
in to equiprobable intervals (e.g. quartiles, deciles, or percentiles).
(Contributed by Raymond Hettinger in :issue:`36546`.)
Added :class:`statistics.NormalDist`, a tool for creating
and manipulating normal distributions of a random variable.
(Contributed by Raymond Hettinger in :issue:`36018`.)
@ -296,8 +428,10 @@ and manipulating normal distributions of a random variable.
::
>>> temperature_feb = NormalDist.from_samples([4, 12, -3, 2, 7, 14])
>>> temperature_feb
NormalDist(mu=6.0, sigma=6.356099432828281)
>>> temperature_feb.mean
6.0
>>> temperature_feb.stdev
6.356099432828281
>>> temperature_feb.cdf(3) # Chance of being under 3 degrees
0.3184678262814532
@ -305,8 +439,8 @@ and manipulating normal distributions of a random variable.
>>> temperature_feb.pdf(7) / temperature_feb.pdf(10)
1.2039930378537762
>>> el_nino = NormalDist(4, 2.5)
>>> temperature_feb += el_nino # Add in a climate effect
>>> el_niño = NormalDist(4, 2.5)
>>> temperature_feb += el_niño # Add in a climate effect
>>> temperature_feb
NormalDist(mu=10.0, sigma=6.830080526611674)
@ -348,6 +482,11 @@ Added method :meth:`~tkinter.Canvas.moveto`
in the :class:`tkinter.Canvas` class.
(Contributed by Juliette Monsel in :issue:`23831`.)
The :class:`tkinter.PhotoImage` class now has
:meth:`~tkinter.PhotoImage.transparency_get` and
:meth:`~tkinter.PhotoImage.transparency_set` methods. (Contributed by
Zackery Spytz in :issue:`25451`.)
time
----
@ -357,10 +496,15 @@ Added new clock :data:`~time.CLOCK_UPTIME_RAW` for macOS 10.12.
unicodedata
-----------
* The :mod:`unicodedata` module has been upgraded to use the `Unicode 12.0.0
<http://blog.unicode.org/2019/03/announcing-unicode-standard-version-120.html>`_
release.
* New function :func:`~unicodedata.is_normalized` can be used to verify a string
is in a specific normal form. (Contributed by Max Belanger and David Euresti in
:issue:`32285`).
unittest
--------
@ -377,6 +521,13 @@ venv
activating virtual environments under PowerShell Core 6.1.
(Contributed by Brett Cannon in :issue:`32718`.)
weakref
-------
* The proxy objects returned by :func:`weakref.proxy` now support the matrix
multiplication operators ``@`` and ``@=`` in addition to the other
numeric operators. (Contributed by Mark Dickinson in :issue:`36669`.)
xml
---
@ -385,6 +536,15 @@ xml
external entities by default.
(Contributed by Christian Heimes in :issue:`17239`.)
* The ``.find*()`` methods in the :mod:`xml.etree.ElementTree` module
support wildcard searches like ``{*}tag`` which ignores the namespace
and ``{namespace}*`` which returns all tags in the given namespace.
(Contributed by Stefan Behnel in :issue:`28238`.)
* The :mod:`xml.etree.ElementTree` module provides a new function
:func:`–xml.etree.ElementTree.canonicalize()` that implements C14N 2.0.
(Contributed by Stefan Behnel in :issue:`13611`.)
Optimizations
=============
@ -495,6 +655,12 @@ Build and C API Changes
``1`` for objects implementing ``__index__()``.
(Contributed by Serhiy Storchaka in :issue:`36048`.)
* Heap-allocated type objects will now increase their reference count
in :c:func:`PyObject_Init` (and its parallel macro ``PyObject_INIT``)
instead of in :c:func:`PyType_GenericAlloc`. Types that modify instance
allocation or deallocation may need to be adjusted.
(Contributed by Eddie Elizondo in :issue:`35810`.)
Deprecated
==========
@ -557,6 +723,33 @@ Deprecated
version they will be errors.
(Contributed by Serhiy Storchaka in :issue:`36048`.)
* Deprecated passing the following arguments as keyword arguments:
- *func* in :func:`functools.partialmethod`, :func:`weakref.finalize`,
:meth:`profile.Profile.runcall`, :meth:`cProfile.Profile.runcall`,
:meth:`bdb.Bdb.runcall`, :meth:`trace.Trace.runfunc` and
:func:`curses.wrapper`.
- *function* in :func:`unittest.addModuleCleanup` and
:meth:`unittest.TestCase.addCleanup`.
- *fn* in the :meth:`~concurrent.futures.Executor.submit` method of
:class:`concurrent.futures.ThreadPoolExecutor` and
:class:`concurrent.futures.ProcessPoolExecutor`.
- *callback* in :meth:`contextlib.ExitStack.callback`,
:meth:`contextlib.AsyncExitStack.callback` and
:meth:`contextlib.AsyncExitStack.push_async_callback`.
- *c* and *typeid* in the :meth:`~multiprocessing.managers.Server.create`
method of :class:`multiprocessing.managers.Server` and
:class:`multiprocessing.managers.SharedMemoryServer`.
- *obj* in :func:`weakref.finalize`.
In future releases of Python they will be :ref:`positional-only
<positional-only_parameter>`.
(Contributed by Serhiy Storchaka in :issue:`36492`.)
* The function :func:`~inspect.getfullargspec` in the :mod:`inspect`
module is deprecated in favor of the :func:`inspect.signature`
API. (Contributed by Pablo Galindo in :issue:`36751`.)
API and Feature Removals
========================
@ -613,10 +806,43 @@ Changes in Python behavior
to use equality tests (``==`` and ``!=``) instead.
(Contributed by Serhiy Storchaka in :issue:`34850`.)
* The CPython interpreter can swallow exceptions in some circumstances.
In Python 3.8 this happens in less cases. In particular, exceptions
raised when getting the attribute from the type dictionary are no longer
ignored. (Contributed by Serhiy Storchaka in :issue:`35459`.)
* Removed ``__str__`` implementations from builtin types :class:`bool`,
:class:`int`, :class:`float`, :class:`complex` and few classes from
the standard library. They now inherit ``__str__()`` from :class:`object`.
As result, defining the ``__repr__()`` method in the subclass of these
classes will affect they string representation.
(Contributed by Serhiy Storchaka in :issue:`36793`.)
* On AIX, :attr:`sys.platform` doesn't contain the major version anymore.
It is always ``'aix'``, instead of ``'aix3'`` .. ``'aix7'``. Since
older Python versions include the version number, it is recommended to
always use the ``sys.platform.startswith('aix')``.
(Contributed by M. Felt in :issue:`36588`.)
* :c:func:`PyEval_AcquireLock` and :c:func:`PyEval_AcquireThread` now
terminate the current thread if called while the interpreter is
finalizing, making them consistent with :c:func:`PyEval_RestoreThread`,
:c:func:`Py_END_ALLOW_THREADS`, and :c:func:`PyGILState_Ensure`. If this
behaviour is not desired, guard the call by checking :c:func:`_Py_IsFinalizing`
or :c:func:`sys.is_finalizing`.
Changes in the Python API
-------------------------
* :class:`subprocess.Popen` can now use :func:`os.posix_spawn` in some cases
for better performance. On Windows Subsystem for Linux and QEMU User
Emulation, Popen constructor using :func:`os.posix_spawn` no longer raise an
exception on errors like missing program, but the child process fails with a
non-zero :attr:`~Popen.returncode`.
* The :meth:`imap.IMAP4.logout` method no longer ignores silently arbitrary
exceptions.
* The function :func:`platform.popen` has been removed, it was deprecated since
Python 3.3: use :func:`os.popen` instead.
@ -707,16 +933,99 @@ Changes in the Python API
environment variable and does not use :envvar:`HOME`, which is not normally
set for regular user accounts.
.. _bpo-36085-whatsnew:
* DLL dependencies for extension modules and DLLs loaded with :mod:`ctypes` on
Windows are now resolved more securely. Only the system paths, the directory
containing the DLL or PYD file, and directories added with
:func:`~os.add_dll_directory` are searched for load-time dependencies.
Specifically, :envvar:`PATH` and the current working directory are no longer
used, and modifications to these will no longer have any effect on normal DLL
resolution. If your application relies on these mechanisms, you should check
for :func:`~os.add_dll_directory` and if it exists, use it to add your DLLs
directory while loading your library. Note that Windows 7 users will need to
ensure that Windows Update KB2533625 has been installed (this is also verified
by the installer).
(See :issue:`36085`.)
* The header files and functions related to pgen have been removed after its
replacement by a pure Python implementation. (Contributed by Pablo Galindo
in :issue:`36623`.)
Changes in the C API
--------------------
* On Unix, C extensions are no longer linked to libpython except on
Android. When Python is embedded, ``libpython`` must not be loaded with
``RTLD_LOCAL``, but ``RTLD_GLOBAL`` instead. Previously, using
``RTLD_LOCAL``, it was already not possible to load C extensions which were
not linked to ``libpython``, like C extensions of the standard library built
by the ``*shared*`` section of ``Modules/Setup``.
* Use of ``#`` variants of formats in parsing or building value (e.g.
:c:func:`PyArg_ParseTuple`, :c:func:`Py_BuildValue`, :c:func:`PyObject_CallFunction`,
etc.) without ``PY_SSIZE_T_CLEAN`` defined raises ``DeprecationWarning`` now.
It will be removed in 3.10 or 4.0. Read :ref:`arg-parsing` for detail.
(Contributed by Inada Naoki in :issue:`36381`.)
* Instances of heap-allocated types (such as those created with
:c:func:`PyType_FromSpec`) hold a reference to their type object.
Increasing the reference count of these type objects has been moved from
:c:func:`PyType_GenericAlloc` to the more low-level functions,
:c:func:`PyObject_Init` and :c:func:`PyObject_INIT`.
This makes types created through :c:func:`PyType_FromSpec` behave like
other classes in managed code.
Statically allocated types are not affected.
For the vast majority of cases, there should be no side effect.
However, types that manually increase the reference count after allocating
an instance (perhaps to work around the bug) may now become immortal.
To avoid this, these classes need to call Py_DECREF on the type object
during instance deallocation.
To correctly port these types into 3.8, please apply the following
changes:
* Remove :c:macro:`Py_INCREF` on the type object after allocating an
instance - if any.
This may happen after calling :c:func:`PyObject_New`,
:c:func:`PyObject_NewVar`, :c:func:`PyObject_GC_New`,
:c:func:`PyObject_GC_NewVar`, or any other custom allocator that uses
:c:func:`PyObject_Init` or :c:func:`PyObject_INIT`.
Example::
static foo_struct *
foo_new(PyObject *type) {
foo_struct *foo = PyObject_GC_New(foo_struct, (PyTypeObject *) type);
if (foo == NULL)
return NULL;
#if PY_VERSION_HEX < 0x03080000
// Workaround for Python issue 35810; no longer necessary in Python 3.8
PY_INCREF(type)
#endif
return foo;
}
* Ensure that all custom ``tp_dealloc`` functions of heap-allocated types
decrease the type's reference count.
Example::
static void
foo_dealloc(foo_struct *instance) {
PyObject *type = Py_TYPE(instance);
PyObject_GC_Del(instance);
#if PY_VERSION_HEX >= 0x03080000
// This was not needed before Python 3.8 (Python issue 35810)
Py_DECREF(type);
#endif
}
(Contributed by Eddie Elizondo in :issue:`35810`.)
CPython bytecode changes
------------------------