`__
+by the `PSF Code of Conduct `_.
-One key point is to keep comments on GitHub to only those related to the reviewing
-the code in the pull request. All other discussions -- e.g. about the issue being
-fixed -- should happen on bugs.python.org.
+`Lifecycle of a Pull Request (GH-NNNN)
+```
+Where: [X.Y] is the branch name, e.g. [3.6].
+
+GH-NNNN refers to the PR number from `master`.
+
+PLEASE: Remove this headline!!!
diff --git a/.github/appveyor.yml b/.github/appveyor.yml
index 0f4c174fa72..b052b28f8aa 100644
--- a/.github/appveyor.yml
+++ b/.github/appveyor.yml
@@ -5,10 +5,17 @@ branches:
- master
- /\d\.\d/
- buildbot-custom
+cache:
+ - externals -> PCbuild\*
build_script:
- cmd: PCbuild\build.bat -e
+- cmd: PCbuild\win32\python.exe -m test.pythoninfo
test_script:
-- cmd: PCbuild\rt.bat -q -uall -u-cpu -rwW --slowest --timeout=1200 -j0
+- cmd: PCbuild\rt.bat -q -uall -u-cpu -rwW --slowest --timeout=1200 --fail-env-changed -j0
+environment:
+ HOST_PYTHON: C:\Python36\python.exe
+image:
+- Visual Studio 2017
# Only trigger AppVeyor if actual code or its configuration changes
only_commits:
@@ -21,7 +28,7 @@ only_commits:
- Modules/
- Objects/
- PC/
- - PCBuild/
+ - PCbuild/
- Parser/
- Programs/
- Python/
diff --git a/.gitignore b/.gitignore
index 03c8268b761..59206541ee4 100644
--- a/.gitignore
+++ b/.gitignore
@@ -19,6 +19,9 @@
.gdb_history
Doc/build/
Doc/venv/
+Doc/.venv/
+Doc/env/
+Doc/.env/
Include/pydtrace_probes.h
Lib/distutils/command/*.pdb
Lib/lib2to3/*.pickle
@@ -60,7 +63,7 @@ PCbuild/*.VC.opendb
PCbuild/.vs/
PCbuild/amd64/
PCbuild/obj/
-PCBuild/win32/
+PCbuild/win32/
.purify
Parser/pgen
Parser/pgen.exe
diff --git a/.mention-bot b/.mention-bot
deleted file mode 100644
index 482e241c412..00000000000
--- a/.mention-bot
+++ /dev/null
@@ -1,20 +0,0 @@
-{
- "numFilesToCheck": 10,
- "findPotentialReviewers": true,
- "fileBlacklist": [
- "Misc/ACKS",
- "Misc/NEWS",
- "Doc/whatsnew/*.rst"
- ],
- "userBlacklist": ["gvanrossum", "skrah", "haypo"],
- "userBlacklistForPR": ["benjaminp", "skrah", "berkerpeksag"],
- "alwaysNotifyForPaths": [
- {"name": "tiran",
- "files": [
- "Doc/library/hashlib.rst", "Doc/library/ssl.rst", "Lib/hashlib.py",
- "Lib/ssl.py", "Lib/test/test_hashlib.py", "Lib/test/test_ssl.py",
- "Modules/_hashopenssl.c", "Modules/_ssl*", "Modules/hashlib.h",
- "Python/pyhash.c", "Include/pyhash.h"]
- }
- ]
-}
diff --git a/.travis.yml b/.travis.yml
index d30de21e821..c207bd72da2 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -3,8 +3,10 @@ dist: trusty
sudo: false
group: beta
-# To cache doc-building dependencies.
-cache: pip
+# To cache doc-building dependencies and C compiler output.
+cache:
+ - pip
+ - ccache
branches:
only:
@@ -23,15 +25,6 @@ matrix:
# compiler here and the other to run the coverage build. Clang is preferred
# in this instance for its better error messages.
env: TESTING=cpython
- - os: osx
- language: c
- compiler: clang
- # Testing under macOS is optional until testing stability has been demonstrated.
- env: OPTIONAL=true
- before_install:
- - brew install openssl xz
- - export CPPFLAGS="-I$(brew --prefix openssl)/include"
- - export LDFLAGS="-L$(brew --prefix openssl)/lib"
- os: linux
language: python
# Build the docs against a stable version of Python so code bugs don't hold up doc-related PRs.
@@ -41,7 +34,7 @@ matrix:
- cd Doc
# Sphinx is pinned so that new versions that introduce new warnings won't suddenly cause build failures.
# (Updating the version is fine as long as no warnings are raised by doing so.)
- - python -m pip install sphinx~=1.6.1
+ - python -m pip install sphinx~=1.6.1 blurb
script:
- make check suspicious html SPHINXOPTS="-q -W -j4"
- os: linux
@@ -60,9 +53,10 @@ matrix:
# Need a venv that can parse covered code.
./python -m venv venv
./venv/bin/python -m pip install -U coverage
+ ./venv/bin/python -m test.pythoninfo
script:
# Skip tests that re-run the entire test suite.
- - ./venv/bin/python -m coverage run --pylib -m test -uall,-cpu,-tzdata -x test_multiprocessing_fork -x test_multiprocessing_forkserver -x test_multiprocessing_spawn
+ - ./venv/bin/python -m coverage run --pylib -m test --fail-env-changed -uall,-cpu -x test_multiprocessing_fork -x test_multiprocessing_forkserver -x test_multiprocessing_spawn -x test_concurrent_futures
after_script: # Probably should be after_success once test suite updated to run under coverage.py.
# Make the `coverage` command available to Codecov w/ a version of Python that can parse all source files.
- source ./venv/bin/activate
@@ -87,10 +81,18 @@ before_script:
echo "$changes"
exit 1
fi
+ make pythoninfo
script:
+ # Using the built Python as patchcheck.py is built around the idea of using
+ # a checkout-build of CPython to know things like what base branch the changes
+ # should be compared against.
+ # Only run on Linux as the check only needs to be run once.
+ - if [[ "$TRAVIS_OS_NAME" == "linux" ]]; then ./python Tools/scripts/patchcheck.py --travis $TRAVIS_PULL_REQUEST; fi
# `-r -w` implicitly provided through `make buildbottest`.
- - make buildbottest TESTOPTS="-j4 -uall,-cpu,-tzdata"
+ - make buildbottest TESTOPTS="-j4 -uall,-cpu"
+ # Check that all symbols exported by libpython start with "Py" or "_Py"
+ - make smelly
notifications:
email: false
diff --git a/Doc/Makefile b/Doc/Makefile
index ae59f3294f1..307d1e0e7de 100644
--- a/Doc/Makefile
+++ b/Doc/Makefile
@@ -5,7 +5,9 @@
# You can set these variables from the command line.
PYTHON = python3
-SPHINXBUILD = sphinx-build
+VENVDIR = ./venv
+SPHINXBUILD = PATH=$(VENVDIR)/bin:$$PATH sphinx-build
+BLURB = PATH=$(VENVDIR)/bin:$$PATH blurb
PAPER =
SOURCES =
DISTVERSION = $(shell $(PYTHON) tools/extensions/patchlevel.py)
@@ -38,6 +40,20 @@ help:
@echo " serve to serve the documentation on the localhost (8000)"
build:
+ -mkdir -p build
+# Look first for a Misc/NEWS file (building from a source release tarball
+# or old repo) and use that, otherwise look for a Misc/NEWS.d directory
+# (building from a newer repo) and use blurb to generate the NEWS file.
+ @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; \
+ else \
+ echo "Neither Misc/NEWS.d nor Misc/NEWS found; cannot build docs"; \
+ exit 1; \
+ fi
$(SPHINXBUILD) $(ALLSPHINXOPTS)
@echo
@@ -103,11 +119,12 @@ htmlview: html
$(PYTHON) -c "import webbrowser; webbrowser.open('build/html/index.html')"
clean:
- -rm -rf build/* venv/*
+ -rm -rf build/* $(VENVDIR)/*
venv:
- $(PYTHON) -m venv venv
- ./venv/bin/python3 -m pip install -U Sphinx
+ $(PYTHON) -m venv $(VENVDIR)
+ $(VENVDIR)/bin/python3 -m pip install -U Sphinx blurb
+ @echo "The venv has been created in the $(VENVDIR) directory"
dist:
rm -rf dist
@@ -153,7 +170,7 @@ dist:
cp -pPR build/epub/Python.epub dist/python-$(DISTVERSION)-docs.epub
check:
- $(PYTHON) tools/rstlint.py -i tools -i venv -i README.rst
+ $(PYTHON) tools/rstlint.py -i tools -i $(VENVDIR) -i README.rst
serve:
../Tools/scripts/serve.py build/html
@@ -167,12 +184,12 @@ serve:
# for development releases: always build
autobuild-dev:
- make dist SPHINXOPTS='$(SPHINXOPTS) -Ea -A daily=1 -A versionswitcher=1'
+ make dist SPHINXOPTS='$(SPHINXOPTS) -Ea -A daily=1 -A switchers=1'
-make suspicious
# for quick rebuilds (HTML only)
autobuild-dev-html:
- make html SPHINXOPTS='$(SPHINXOPTS) -Ea -A daily=1 -A versionswitcher=1'
+ make html SPHINXOPTS='$(SPHINXOPTS) -Ea -A daily=1 -A switchers=1'
# for stable releases: only build if not in pre-release stage (alpha, beta)
# release candidate downloads are okay, since the stable tree can be in that stage
diff --git a/Doc/README.rst b/Doc/README.rst
index dcd3d6e80ff..a29d1f3a708 100644
--- a/Doc/README.rst
+++ b/Doc/README.rst
@@ -7,45 +7,53 @@ available <https://docs.python.org/dev/download.html>`_.
Documentation on authoring Python documentation, including information about
both style and markup, is available in the "`Documenting Python
-<https://docs.python.org/devguide/documenting.html>`_" chapter of the
+<https://devguide.python.org/documenting/>`_" chapter of the
developers guide.
Building the docs
=================
-You need to have `Sphinx <http://sphinx-doc.org/>`_ installed; it is the toolset
-used to build the docs. It is not included in this tree, but maintained
-separately and `available from PyPI <https://pypi.python.org/pypi/Sphinx>`_.
+The documentation is built with several tools which are not included in this
+tree but are maintained separately and are available from
+`PyPI <https://pypi.org/>`_.
+
+* `Sphinx <https://pypi.org/project/Sphinx/>`_
+* `blurb <https://pypi.org/project/blurb/>`_
+
+The easiest way to install these tools is to create a virtual environment and
+install the tools into there.
Using make
----------
-A Makefile has been prepared so that on Unix, provided you have installed
-Sphinx, you can just run ::
+To get started on UNIX, you can create a virtual environment with the command ::
- make html
+ make venv
-to build the HTML output files.
+That will install all the tools necessary to build the documentation. Assuming
+the virtual environment was created in the ``env`` directory (the default;
+configurable with the VENVDIR variable), you can run the following command to
+build the HTML output files::
+
+ make html
+
+By default, if the virtual environment is not created, the Makefile will
+look for instances of sphinxbuild and blurb installed on your process PATH
+(configurable with the SPHINXBUILD and BLURB variables).
On Windows, we try to emulate the Makefile as closely as possible with a
-``make.bat`` file.
-
-To use a Python interpreter that's not called ``python``, use the standard
-way to set Makefile variables, using e.g. ::
-
- make html PYTHON=python3
-
-On Windows, set the PYTHON environment variable instead.
-
-To use a specific sphinx-build (something other than ``sphinx-build``), set
-the SPHINXBUILD variable.
+``make.bat`` file. If you need to specify the Python interpreter to use,
+set the PYTHON environment variable instead.
Available make targets are:
* "clean", which removes all build files.
+* "venv", which creates a virtual environment with all necessary tools
+ installed.
+
* "html", which builds standalone HTML files for offline viewing.
* "htmlview", which re-uses the "html" builder, but then opens the main page
@@ -96,7 +104,7 @@ Available make targets are:
Without make
------------
-Install the Sphinx package and its dependencies from PyPI.
+First, install the tool dependencies from PyPI.
Then, from the ``Doc`` directory, run ::
@@ -109,11 +117,10 @@ see the make targets above).
Contributing
============
-Bugs in the content should be reported to the
+Bugs in the content should be reported to the
`Python bug tracker <https://bugs.python.org>`_.
-Bugs in the toolset should be reported in the
-`Sphinx bug tracker <https://github.com/sphinx-doc/sphinx/issues>`_.
+Bugs in the toolset should be reported to the tools themselves.
You can also send a mail to the Python Documentation Team at docs@python.org,
and we will process your request as soon as possible.
diff --git a/Doc/bugs.rst b/Doc/bugs.rst
index 1b0a5a9a937..bc1d10f379c 100644
--- a/Doc/bugs.rst
+++ b/Doc/bugs.rst
@@ -88,5 +88,5 @@ the `core-mentorship mailing list`_ is a friendly place to get answers to
any and all questions pertaining to the process of fixing issues in Python.
.. _Documentation bugs: https://bugs.python.org/issue?@filter=status&@filter=components&components=4&status=1&@columns=id,activity,title,status&@sort=-activity
-.. _Python Developer's Guide: https://docs.python.org/devguide/
+.. _Python Developer's Guide: https://devguide.python.org/
.. _core-mentorship mailing list: https://mail.python.org/mailman/listinfo/core-mentorship/
diff --git a/Doc/c-api/buffer.rst b/Doc/c-api/buffer.rst
index 3d851b7c39c..8c2de9691f3 100644
--- a/Doc/c-api/buffer.rst
+++ b/Doc/c-api/buffer.rst
@@ -473,7 +473,7 @@ Buffer-related functions
(*order* is ``'A'``). Return ``0`` otherwise.
-.. c:function:: void PyBuffer_FillContiguousStrides(int ndim, Py_ssize_t *shape, Py_ssize_t *strides, Py_ssize_t itemsize, char order)
+.. c:function:: void PyBuffer_FillContiguousStrides(int ndims, Py_ssize_t *shape, Py_ssize_t *strides, int itemsize, char order)
Fill the *strides* array with byte-strides of a :term:`contiguous` (C-style if
*order* is ``'C'`` or Fortran-style if *order* is ``'F'``) array of the
diff --git a/Doc/c-api/datetime.rst b/Doc/c-api/datetime.rst
index 39542bd17a3..305e990368c 100644
--- a/Doc/c-api/datetime.rst
+++ b/Doc/c-api/datetime.rst
@@ -188,7 +188,7 @@ not be *NULL*, and the type is not checked:
.. versionadded:: 3.3
-.. c:function:: int PyDateTime_DELTA_GET_MICROSECOND(PyDateTime_Delta *o)
+.. c:function:: int PyDateTime_DELTA_GET_MICROSECONDS(PyDateTime_Delta *o)
Return the number of microseconds, as an int from 0 through 999999.
diff --git a/Doc/c-api/import.rst b/Doc/c-api/import.rst
index 7c16ece0586..8cdc256e7c9 100644
--- a/Doc/c-api/import.rst
+++ b/Doc/c-api/import.rst
@@ -204,6 +204,13 @@ Importing Modules
Return the dictionary used for the module administration (a.k.a.
``sys.modules``). Note that this is a per-interpreter variable.
+.. c:function:: PyObject* PyImport_GetModule(PyObject *name)
+
+ Return the already imported module with the given name. If the
+ module has not been imported yet then returns NULL but does not set
+ an error. Returns NULL and sets an error if the lookup failed.
+
+ .. versionadded:: 3.7
.. c:function:: PyObject* PyImport_GetImporter(PyObject *path)
diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst
index c12e1c7fba3..dc1939db17e 100644
--- a/Doc/c-api/init.rst
+++ b/Doc/c-api/init.rst
@@ -1192,3 +1192,160 @@ These functions are only intended to be used by advanced debugging tools.
Return the next thread state object after *tstate* from the list of all such
objects belonging to the same :c:type:`PyInterpreterState` object.
+
+.. _thread-local-storage:
+
+Thread Local Storage Support
+============================
+
+.. sectionauthor:: Masayuki Yamamoto <ma3yuki.8mamo10@gmail.com>
+
+The Python interpreter provides low-level support for thread-local storage
+(TLS) which wraps the underlying native TLS implementation to support the
+Python-level thread local storage API (:class:`threading.local`). The
+CPython C level APIs are similar to those offered by pthreads and Windows:
+use a thread key and functions to associate a :c:type:`void\*` value per
+thread.
+
+The GIL does *not* need to be held when calling these functions; they supply
+their own locking.
+
+Note that :file:`Python.h` does not include the declaration of the TLS APIs,
+you need to include :file:`pythread.h` to use thread-local storage.
+
+.. note::
+ None of these API functions handle memory management on behalf of the
+ :c:type:`void\*` values. You need to allocate and deallocate them yourself.
+ If the :c:type:`void\*` values happen to be :c:type:`PyObject\*`, these
+ functions don't do refcount operations on them either.
+
+.. _thread-specific-storage-api:
+
+Thread Specific Storage (TSS) API
+---------------------------------
+
+TSS API is introduced to supersede the use of the existing TLS API within the
+CPython interpreter. This API uses a new type :c:type:`Py_tss_t` instead of
+:c:type:`int` to represent thread keys.
+
+.. versionadded:: 3.7
+
+.. seealso:: "A New C-API for Thread-Local Storage in CPython" (:pep:`539`)
+
+
+.. c:type:: Py_tss_t
+
+ This data structure represents the state of a thread key, the definition of
+ which may depend on the underlying TLS implementation, and it has an
+ internal field representing the key's initialization state. There are no
+ public members in this structure.
+
+ When :ref:`Py_LIMITED_API <stable>` is not defined, static allocation of
+ this type by :c:macro:`Py_tss_NEEDS_INIT` is allowed.
+
+
+.. c:macro:: Py_tss_NEEDS_INIT
+
+ This macro expands to the initializer for :c:type:`Py_tss_t` variables.
+ Note that this macro won't be defined with :ref:`Py_LIMITED_API <stable>`.
+
+
+Dynamic Allocation
+~~~~~~~~~~~~~~~~~~
+
+Dynamic allocation of the :c:type:`Py_tss_t`, required in extension modules
+built with :ref:`Py_LIMITED_API <stable>`, where static allocation of this type
+is not possible due to its implementation being opaque at build time.
+
+
+.. c:function:: Py_tss_t* PyThread_tss_alloc()
+
+ Return a value which is the same state as a value initialized with
+ :c:macro:`Py_tss_NEEDS_INIT`, or *NULL* in the case of dynamic allocation
+ failure.
+
+
+.. c:function:: void PyThread_tss_free(Py_tss_t *key)
+
+ Free the given *key* allocated by :c:func:`PyThread_tss_alloc`, after
+ first calling :c:func:`PyThread_tss_delete` to ensure any associated
+ thread locals have been unassigned. This is a no-op if the *key*
+ argument is `NULL`.
+
+ .. note::
+ A freed key becomes a dangling pointer, you should reset the key to
+ `NULL`.
+
+
+Methods
+~~~~~~~
+
+The parameter *key* of these functions must not be *NULL*. Moreover, the
+behaviors of :c:func:`PyThread_tss_set` and :c:func:`PyThread_tss_get` are
+undefined if the given :c:type:`Py_tss_t` has not been initialized by
+:c:func:`PyThread_tss_create`.
+
+
+.. c:function:: int PyThread_tss_is_created(Py_tss_t *key)
+
+ Return a non-zero value if the given :c:type:`Py_tss_t` has been initialized
+ by :c:func:`PyThread_tss_create`.
+
+
+.. c:function:: int PyThread_tss_create(Py_tss_t *key)
+
+ Return a zero value on successful initialization of a TSS key. The behavior
+ is undefined if the value pointed to by the *key* argument is not
+ initialized by :c:macro:`Py_tss_NEEDS_INIT`. This function can be called
+ repeatedly on the same key -- calling it on an already initialized key is a
+ no-op and immediately returns success.
+
+
+.. c:function:: void PyThread_tss_delete(Py_tss_t *key)
+
+ Destroy a TSS key to forget the values associated with the key across all
+ threads, and change the key's initialization state to uninitialized. A
+ destroyed key is able to be initialized again by
+ :c:func:`PyThread_tss_create`. This function can be called repeatedly on
+ the same key -- calling it on an already destroyed key is a no-op.
+
+
+.. c:function:: int PyThread_tss_set(Py_tss_t *key, void *value)
+
+ Return a zero value to indicate successfully associating a :c:type:`void\*`
+ value with a TSS key in the current thread. Each thread has a distinct
+ mapping of the key to a :c:type:`void\*` value.
+
+
+.. c:function:: void* PyThread_tss_get(Py_tss_t *key)
+
+ Return the :c:type:`void\*` value associated with a TSS key in the current
+ thread. This returns *NULL* if no value is associated with the key in the
+ current thread.
+
+
+.. _thread-local-storage-api:
+
+Thread Local Storage (TLS) API
+------------------------------
+
+.. deprecated:: 3.7
+ This API is superseded by
+ :ref:`Thread Specific Storage (TSS) API <thread-specific-storage-api>`.
+
+.. note::
+ This version of the API does not support platforms where the native TLS key
+ is defined in a way that cannot be safely cast to ``int``. On such platforms,
+ :c:func:`PyThread_create_key` will return immediately with a failure status,
+ and the other TLS functions will all be no-ops on such platforms.
+
+Due to the compatibility problem noted above, this version of the API should not
+be used in new code.
+
+.. c:function:: int PyThread_create_key()
+.. c:function:: void PyThread_delete_key(int key)
+.. c:function:: int PyThread_set_key_value(int key, void *value)
+.. c:function:: void* PyThread_get_key_value(int key)
+.. c:function:: void PyThread_delete_key_value(int key)
+.. c:function:: void PyThread_ReInitTLS()
+
diff --git a/Doc/c-api/intro.rst b/Doc/c-api/intro.rst
index 74681d2c851..15006100c73 100644
--- a/Doc/c-api/intro.rst
+++ b/Doc/c-api/intro.rst
@@ -17,11 +17,11 @@ common use. The second reason is to use Python as a component in a larger
application; this technique is generally referred to as :dfn:`embedding` Python
in an application.
-Writing an extension module is a relatively well-understood process, where a
-"cookbook" approach works well. There are several tools that automate the
-process to some extent. While people have embedded Python in other
-applications since its early existence, the process of embedding Python is less
-straightforward than writing an extension.
+Writing an extension module is a relatively well-understood process, where a
+"cookbook" approach works well. There are several tools that automate the
+process to some extent. While people have embedded Python in other
+applications since its early existence, the process of embedding Python is
+less straightforward than writing an extension.
Many API functions are useful independent of whether you're embedding or
extending Python; moreover, most applications that embed Python will need to
@@ -30,6 +30,16 @@ familiar with writing an extension before attempting to embed Python in a real
application.
+Coding standards
+================
+
+If you're writing C code for inclusion in CPython, you **must** follow the
+guidelines and standards defined in :PEP:`7`. These guidelines apply
+regardless of the version of Python you are contributing to. Following these
+conventions is not necessary for your own third party extension modules,
+unless you eventually expect to contribute them to Python.
+
+
.. _api-includes:
Include Files
@@ -81,6 +91,72 @@ header files do properly declare the entry points to be ``extern "C"``, so there
is no need to do anything special to use the API from C++.
+Useful macros
+=============
+
+Several useful macros are defined in the Python header files. Many are
+defined closer to where they are useful (e.g. :c:macro:`Py_RETURN_NONE`).
+Others of a more general utility are defined here. This is not necessarily a
+complete listing.
+
+.. c:macro:: Py_UNREACHABLE()
+
+ Use this when you have a code path that you do not expect to be reached.
+ For example, in the ``default:`` clause in a ``switch`` statement for which
+ all possible values are covered in ``case`` statements. Use this in places
+ where you might be tempted to put an ``assert(0)`` or ``abort()`` call.
+
+ .. versionadded:: 3.7
+
+.. c:macro:: Py_ABS(x)
+
+ Return the absolute value of ``x``.
+
+ .. versionadded:: 3.3
+
+.. c:macro:: Py_MIN(x, y)
+
+ Return the minimum value between ``x`` and ``y``.
+
+ .. versionadded:: 3.3
+
+.. c:macro:: Py_MAX(x, y)
+
+ Return the maximum value between ``x`` and ``y``.
+
+ .. versionadded:: 3.3
+
+.. c:macro:: Py_STRINGIFY(x)
+
+ Convert ``x`` to a C string. E.g. ``Py_STRINGIFY(123)`` returns
+ ``"123"``.
+
+ .. versionadded:: 3.4
+
+.. c:macro:: Py_MEMBER_SIZE(type, member)
+
+ Return the size of a structure (``type``) ``member`` in bytes.
+
+ .. versionadded:: 3.6
+
+.. c:macro:: Py_CHARMASK(c)
+
+ Argument must be a character or an integer in the range [-128, 127] or [0,
+ 255]. This macro returns ``c`` cast to an ``unsigned char``.
+
+.. c:macro:: Py_GETENV(s)
+
+ Like ``getenv(s)``, but returns *NULL* if :option:`-E` was passed on the
+ command line (i.e. if ``Py_IgnoreEnvironmentFlag`` is set).
+
+.. c:macro:: Py_UNUSED(arg)
+
+ Use this for unused arguments in a function definition to silence compiler
+ warnings, e.g. ``PyObject* func(PyObject *Py_UNUSED(ignored))``.
+
+ .. versionadded:: 3.4
+
+
.. _api-objects:
Objects, Types and Reference Counts
diff --git a/Doc/c-api/mapping.rst b/Doc/c-api/mapping.rst
index a71e9428377..308a9761f87 100644
--- a/Doc/c-api/mapping.rst
+++ b/Doc/c-api/mapping.rst
@@ -50,20 +50,29 @@ Mapping Protocol
.. c:function:: PyObject* PyMapping_Keys(PyObject *o)
- On success, return a list or tuple of the keys in object *o*. On failure,
- return *NULL*.
+ On success, return a list of the keys in object *o*. On failure, return
+ *NULL*.
+
+ .. versionchanged:: 3.7
+ Previously, the function returned a list or a tuple.
.. c:function:: PyObject* PyMapping_Values(PyObject *o)
- On success, return a list or tuple of the values in object *o*. On failure,
- return *NULL*.
+ On success, return a list of the values in object *o*. On failure, return
+ *NULL*.
+
+ .. versionchanged:: 3.7
+ Previously, the function returned a list or a tuple.
.. c:function:: PyObject* PyMapping_Items(PyObject *o)
- On success, return a list or tuple of the items in object *o*, where each item
- is a tuple containing a key-value pair. On failure, return *NULL*.
+ On success, return a list of the items in object *o*, where each item is a
+ tuple containing a key-value pair. On failure, return *NULL*.
+
+ .. versionchanged:: 3.7
+ Previously, the function returned a list or a tuple.
.. c:function:: PyObject* PyMapping_GetItemString(PyObject *o, const char *key)
diff --git a/Doc/c-api/memory.rst b/Doc/c-api/memory.rst
index 873fb2ac1d3..4b1e666ef35 100644
--- a/Doc/c-api/memory.rst
+++ b/Doc/c-api/memory.rst
@@ -150,7 +150,7 @@ The default raw memory block allocator uses the following functions:
Frees the memory block pointed to by *p*, which must have been returned by a
previous call to :c:func:`PyMem_RawMalloc`, :c:func:`PyMem_RawRealloc` or
- :c:func:`PyMem_RawCalloc`. Otherwise, or if ``PyMem_Free(p)`` has been
+ :c:func:`PyMem_RawCalloc`. Otherwise, or if ``PyMem_RawFree(p)`` has been
called before, undefined behavior occurs.
If *p* is *NULL*, no operation is performed.
@@ -263,6 +263,69 @@ versions and is therefore deprecated in extension modules.
* ``PyMem_DEL(ptr)``
+Object allocators
+=================
+
+The following function sets, modeled after the ANSI C standard, but specifying
+behavior when requesting zero bytes, are available for allocating and releasing
+memory from the Python heap.
+
+By default, these functions use :ref:`pymalloc memory allocator <pymalloc>`.
+
+.. warning::
+
+ The :term:`GIL <global interpreter lock>` must be held when using these
+ functions.
+
+.. c:function:: void* PyObject_Malloc(size_t n)
+
+ Allocates *n* bytes and returns a pointer of type :c:type:`void\*` to the
+ allocated memory, or *NULL* if the request fails.
+
+ Requesting zero bytes returns a distinct non-*NULL* pointer if possible, as
+ if ``PyObject_Malloc(1)`` had been called instead. The memory will not have
+ been initialized in any way.
+
+
+.. c:function:: void* PyObject_Calloc(size_t nelem, size_t elsize)
+
+ Allocates *nelem* elements each whose size in bytes is *elsize* and returns
+ a pointer of type :c:type:`void\*` to the allocated memory, or *NULL* if the
+ request fails. The memory is initialized to zeros.
+
+ Requesting zero elements or elements of size zero bytes returns a distinct
+ non-*NULL* pointer if possible, as if ``PyObject_Calloc(1, 1)`` had been called
+ instead.
+
+ .. versionadded:: 3.5
+
+
+.. c:function:: void* PyObject_Realloc(void *p, size_t n)
+
+ Resizes the memory block pointed to by *p* to *n* bytes. The contents will be
+ unchanged to the minimum of the old and the new sizes.
+
+ If *p* is *NULL*, the call is equivalent to ``PyObject_Malloc(n)``; else if *n*
+ is equal to zero, the memory block is resized but is not freed, and the
+ returned pointer is non-*NULL*.
+
+ Unless *p* is *NULL*, it must have been returned by a previous call to
+ :c:func:`PyObject_Malloc`, :c:func:`PyObject_Realloc` or :c:func:`PyObject_Calloc`.
+
+ If the request fails, :c:func:`PyObject_Realloc` returns *NULL* and *p* remains
+ a valid pointer to the previous memory area.
+
+
+.. c:function:: void PyObject_Free(void *p)
+
+ Frees the memory block pointed to by *p*, which must have been returned by a
+ previous call to :c:func:`PyObject_Malloc`, :c:func:`PyObject_Realloc` or
+ :c:func:`PyObject_Calloc`. Otherwise, or if ``PyObject_Free(p)`` has been called
+ before, undefined behavior occurs.
+
+ If *p* is *NULL*, no operation is performed.
+
+
Customize Memory Allocators
===========================
@@ -387,7 +450,7 @@ The pymalloc allocator
Python has a *pymalloc* allocator optimized for small objects (smaller or equal
to 512 bytes) with a short lifetime. It uses memory mappings called "arenas"
-with a fixed size of 256 KB. It falls back to :c:func:`PyMem_RawMalloc` and
+with a fixed size of 256 KiB. It falls back to :c:func:`PyMem_RawMalloc` and
:c:func:`PyMem_RawRealloc` for allocations larger than 512 bytes.
*pymalloc* is the default allocator of the :c:data:`PYMEM_DOMAIN_MEM` (ex:
@@ -429,6 +492,28 @@ Customize pymalloc Arena Allocator
Set the arena allocator.
+tracemalloc C API
+=================
+
+.. versionadded:: 3.7
+
+.. c:function: int PyTraceMalloc_Track(unsigned int domain, uintptr_t ptr, size_t size)
+
+ Track an allocated memory block in the :mod:`tracemalloc` module.
+
+ Return 0 on success, return ``-1`` on error (failed to allocate memory to
+ store the trace). Return ``-2`` if tracemalloc is disabled.
+
+ If memory block is already tracked, update the existing trace.
+
+.. c:function: int PyTraceMalloc_Untrack(unsigned int domain, uintptr_t ptr)
+
+ Untrack an allocated memory block in the :mod:`tracemalloc` module.
+ Do nothing if the block was not tracked.
+
+ Return ``-2`` if tracemalloc is disabled, otherwise return ``0``.
+
+
.. _memoryexamples:
Examples
diff --git a/Doc/c-api/slice.rst b/Doc/c-api/slice.rst
index f8395ec8d77..8ad9a29b256 100644
--- a/Doc/c-api/slice.rst
+++ b/Doc/c-api/slice.rst
@@ -53,6 +53,22 @@ Slice Objects
Returns ``0`` on success and ``-1`` on error with exception set.
+ .. note::
+ This function is considered not safe for resizable sequences.
+ Its invocation should be replaced by a combination of
+ :c:func:`PySlice_Unpack` and :c:func:`PySlice_AdjustIndices` where ::
+
+ if (PySlice_GetIndicesEx(slice, length, &start, &stop, &step, &slicelength) < 0) {
+ // return error
+ }
+
+ is replaced by ::
+
+ if (PySlice_Unpack(slice, &start, &stop, &step) < 0) {
+ // return error
+ }
+ slicelength = PySlice_AdjustIndices(length, &start, &stop, step);
+
.. versionchanged:: 3.2
The parameter type for the *slice* parameter was ``PySliceObject*``
before.
@@ -61,7 +77,7 @@ Slice Objects
If ``Py_LIMITED_API`` is not set or set to the value between ``0x03050400``
and ``0x03060000`` (not including) or ``0x03060100`` or higher
:c:func:`!PySlice_GetIndicesEx` is implemented as a macro using
- :c:func:`PySlice_Unpack` and :c:func:`PySlice_AdjustIndices`.
+ :c:func:`!PySlice_Unpack` and :c:func:`!PySlice_AdjustIndices`.
Arguments *start*, *stop* and *step* are evaluated more than once.
.. deprecated:: 3.6.1
diff --git a/Doc/c-api/structures.rst b/Doc/c-api/structures.rst
index 67e4f9d4b9d..797b9045fa8 100644
--- a/Doc/c-api/structures.rst
+++ b/Doc/c-api/structures.rst
@@ -294,3 +294,43 @@ definition with the same method name.
read-only access. Using :c:macro:`T_STRING` for :attr:`type` implies
:c:macro:`READONLY`. Only :c:macro:`T_OBJECT` and :c:macro:`T_OBJECT_EX`
members can be deleted. (They are set to *NULL*).
+
+
+.. c:type:: PyGetSetDef
+
+ Structure to define property-like access for a type. See also description of
+ the :c:member:`PyTypeObject.tp_getset` slot.
+
+ +-------------+------------------+-----------------------------------+
+ | Field | C Type | Meaning |
+ +=============+==================+===================================+
+ | name | const char \* | attribute name |
+ +-------------+------------------+-----------------------------------+
+ | get | getter | C Function to get the attribute |
+ +-------------+------------------+-----------------------------------+
+ | set | setter | optional C function to set or |
+ | | | delete the attribute, if omitted |
+ | | | the attribute is readonly |
+ +-------------+------------------+-----------------------------------+
+ | doc | const char \* | optional docstring |
+ +-------------+------------------+-----------------------------------+
+ | closure | void \* | optional function pointer, |
+ | | | providing additional data for |
+ | | | getter and setter |
+ +-------------+------------------+-----------------------------------+
+
+ The ``get`` function takes one :c:type:`PyObject\*` parameter (the
+ instance) and a function pointer (the associated ``closure``)::
+
+ typedef PyObject *(*getter)(PyObject *, void *);
+
+ It should return a new reference on success or *NULL* with a set exception
+ on failure.
+
+ ``set`` functions take two :c:type:`PyObject\*` parameters (the instance and
+ the value to be set) and a function pointer (the associated ``closure``)::
+
+ typedef int (*setter)(PyObject *, PyObject *, void *);
+
+ In case the attribute should be deleted the second parameter is *NULL*.
+ Should return ``0`` on success or ``-1`` with a set exception on failure.
diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst
index 2f0081aa3db..3bdf45ad9b6 100644
--- a/Doc/c-api/typeobj.rst
+++ b/Doc/c-api/typeobj.rst
@@ -623,6 +623,22 @@ type objects) *must* have the :attr:`ob_size` field.
| :const:`Py_GE` | ``>=`` |
+----------------+------------+
+ The following macro is defined to ease writing rich comparison functions:
+
+ .. c:function:: PyObject *Py_RETURN_RICHCOMPARE(VAL_A, VAL_B, int op)
+
+ Return ``Py_True`` or ``Py_False`` from the function, depending on the
+ result of a comparison.
+ VAL_A and VAL_B must be orderable by C comparison operators (for example,
+ they may be C ints or floats). The third argument specifies the requested
+ operation, as for :c:func:`PyObject_RichCompare`.
+
+ The return value's reference count is properly incremented.
+
+ On error, sets an exception and returns NULL from the function.
+
+ .. versionadded:: 3.7
+
.. c:member:: Py_ssize_t PyTypeObject.tp_weaklistoffset
@@ -719,21 +735,6 @@ type objects) *must* have the :attr:`ob_size` field.
This field is not inherited by subtypes (computed attributes are inherited
through a different mechanism).
- .. XXX belongs elsewhere
-
- Docs for PyGetSetDef::
-
- typedef PyObject *(*getter)(PyObject *, void *);
- typedef int (*setter)(PyObject *, PyObject *, void *);
-
- typedef struct PyGetSetDef {
- const char *name; /* attribute name */
- getter get; /* C function to get the attribute */
- setter set; /* C function to set or delete the attribute */
- const char *doc; /* optional doc string */
- void *closure; /* optional additional data for getter and setter */
- } PyGetSetDef;
-
.. c:member:: PyTypeObject* PyTypeObject.tp_base
diff --git a/Doc/c-api/unicode.rst b/Doc/c-api/unicode.rst
index 84059e46105..45aff1b7e3c 100644
--- a/Doc/c-api/unicode.rst
+++ b/Doc/c-api/unicode.rst
@@ -934,16 +934,22 @@ wchar_t Support
Convert the Unicode object to a wide character string. The output string
always ends with a null character. If *size* is not *NULL*, write the number
of wide characters (excluding the trailing null termination character) into
- *\*size*.
+ *\*size*. Note that the resulting :c:type:`wchar_t` string might contain
+ null characters, which would cause the string to be truncated when used with
+ most C functions. If *size* is *NULL* and the :c:type:`wchar_t*` string
+ contains null characters a :exc:`ValueError` is raised.
Returns a buffer allocated by :c:func:`PyMem_Alloc` (use
- :c:func:`PyMem_Free` to free it) on success. On error, returns *NULL*,
- *\*size* is undefined and raises a :exc:`MemoryError`. Note that the
- resulting :c:type:`wchar_t` string might contain null characters, which
- would cause the string to be truncated when used with most C functions.
+ :c:func:`PyMem_Free` to free it) on success. On error, returns *NULL*
+ and *\*size* is undefined. Raises a :exc:`MemoryError` if memory allocation
+ is failed.
.. versionadded:: 3.2
+ .. versionchanged:: 3.7
+ Raises a :exc:`ValueError` if *size* is *NULL* and the :c:type:`wchar_t*`
+ string contains null characters.
+
.. _builtincodecs:
diff --git a/Doc/c-api/veryhigh.rst b/Doc/c-api/veryhigh.rst
index 6ab5942929f..3897fdd8282 100644
--- a/Doc/c-api/veryhigh.rst
+++ b/Doc/c-api/veryhigh.rst
@@ -141,7 +141,8 @@ the same library that the Python runtime is using.
Read and execute statements from a file associated with an interactive device
until EOF is reached. The user will be prompted using ``sys.ps1`` and
``sys.ps2``. *filename* is decoded from the filesystem encoding
- (:func:`sys.getfilesystemencoding`). Returns ``0`` at EOF.
+ (:func:`sys.getfilesystemencoding`). Returns ``0`` at EOF or a negative
+ number upon failure.
.. c:var:: int (*PyOS_InputHook)(void)
diff --git a/Doc/conf.py b/Doc/conf.py
index c1c2472a196..aaee983984b 100644
--- a/Doc/conf.py
+++ b/Doc/conf.py
@@ -38,7 +38,8 @@ highlight_language = 'python3'
needs_sphinx = '1.2'
# Ignore any .rst files in the venv/ directory.
-exclude_patterns = ['venv/*', 'README.rst']
+venvdir = os.getenv('VENVDIR', 'venv')
+exclude_patterns = [venvdir+'/*', 'README.rst']
# Options for HTML output
@@ -90,13 +91,17 @@ html_split_index = True
# ------------------------
# Get LaTeX to handle Unicode correctly
-latex_elements = {'inputenc': r'\usepackage[utf8x]{inputenc}', 'utf8extra': ''}
+latex_elements = {
+ 'inputenc': r'\usepackage[utf8x]{inputenc}',
+ 'utf8extra': '',
+ 'fontenc': r'\usepackage[T1,T2A]{fontenc}',
+}
# Additional stuff for the LaTeX preamble.
latex_elements['preamble'] = r'''
\authoraddress{
- \strong{Python Software Foundation}\\
- Email: \email{docs@python.org}
+ \sphinxstrong{Python Software Foundation}\\
+ Email: \sphinxemail{docs@python.org}
}
\let\Verbatim=\OriginalVerbatim
\let\endVerbatim=\endOriginalVerbatim
@@ -106,7 +111,7 @@ latex_elements['preamble'] = r'''
latex_elements['papersize'] = 'a4'
# The font size ('10pt', '11pt' or '12pt').
-latex_elements['font_size'] = '10pt'
+latex_elements['pointsize'] = '10pt'
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title, author, document class [howto/manual]).
diff --git a/Doc/copyright.rst b/Doc/copyright.rst
index 22d7705846e..2b5400cd9fb 100644
--- a/Doc/copyright.rst
+++ b/Doc/copyright.rst
@@ -4,7 +4,7 @@ Copyright
Python and this documentation is:
-Copyright © 2001-2016 Python Software Foundation. All rights reserved.
+Copyright © 2001-2017 Python Software Foundation. All rights reserved.
Copyright © 2000 BeOpen.com. All rights reserved.
diff --git a/Doc/distutils/apiref.rst b/Doc/distutils/apiref.rst
index b5b7731074c..7cde1a0701e 100644
--- a/Doc/distutils/apiref.rst
+++ b/Doc/distutils/apiref.rst
@@ -814,13 +814,13 @@ This module provides the :class:`UnixCCompiler` class, a subclass of
.. module:: distutils.msvccompiler
:synopsis: Microsoft Compiler
+.. XXX: This is *waaaaay* out of date!
This module provides :class:`MSVCCompiler`, an implementation of the abstract
:class:`CCompiler` class for Microsoft Visual Studio. Typically, extension
modules need to be compiled with the same compiler that was used to compile
Python. For Python 2.3 and earlier, the compiler was Visual Studio 6. For Python
-2.4 and 2.5, the compiler is Visual Studio .NET 2003. The AMD64 and Itanium
-binaries are created using the Platform SDK.
+2.4 and 2.5, the compiler is Visual Studio .NET 2003.
:class:`MSVCCompiler` will normally choose the right compiler, linker etc. on
its own. To override this choice, the environment variables *DISTUTILS_USE_SDK*
@@ -1086,19 +1086,16 @@ other utility module.
Return a string that identifies the current platform. This is used mainly to
distinguish platform-specific build directories and platform-specific built
- distributions. Typically includes the OS name and version and the architecture
- (as supplied by 'os.uname()'), although the exact information included depends
- on the OS; eg. for IRIX the architecture isn't particularly important (IRIX only
- runs on SGI hardware), but for Linux the kernel version isn't particularly
- important.
+ distributions. Typically includes the OS name and version and the
+ architecture (as supplied by 'os.uname()'), although the exact information
+ included depends on the OS; e.g., on Linux, the kernel version isn't
+ particularly important.
Examples of returned values:
* ``linux-i586``
* ``linux-alpha``
* ``solaris-2.6-sun4u``
- * ``irix-5.3``
- * ``irix64-6.2``
For non-POSIX platforms, currently just returns ``sys.platform``.
diff --git a/Doc/distutils/builtdist.rst b/Doc/distutils/builtdist.rst
index bbd2a8ce831..f523a672340 100644
--- a/Doc/distutils/builtdist.rst
+++ b/Doc/distutils/builtdist.rst
@@ -351,8 +351,8 @@ installed, you can use a 32bit version of Windows to create 64bit extensions
and vice-versa.
To build for an alternate platform, specify the :option:`!--plat-name` option
-to the build command. Valid values are currently 'win32', 'win-amd64' and
-'win-ia64'. For example, on a 32bit version of Windows, you could execute::
+to the build command. Valid values are currently 'win32', and 'win-amd64'.
+For example, on a 32bit version of Windows, you could execute::
python setup.py build --plat-name=win-amd64
@@ -368,7 +368,7 @@ Python itself for the platform you are targeting - it is not possible from a
binary installation of Python (as the .lib etc file for other platforms are
not included.) In practice, this means the user of a 32 bit operating
system will need to use Visual Studio 2008 to open the
-:file:`PCBuild/PCbuild.sln` solution in the Python source tree and build the
+:file:`PCbuild/PCbuild.sln` solution in the Python source tree and build the
"x64" configuration of the 'pythoncore' project before cross-compiling
extensions is possible.
diff --git a/Doc/docutils.conf b/Doc/docutils.conf
new file mode 100644
index 00000000000..bda4f5dc235
--- /dev/null
+++ b/Doc/docutils.conf
@@ -0,0 +1,2 @@
+[restructuredtext parser]
+smartquotes-locales: ja: ""''
diff --git a/Doc/extending/extending.rst b/Doc/extending/extending.rst
index 2dc20fed131..7c273533aba 100644
--- a/Doc/extending/extending.rst
+++ b/Doc/extending/extending.rst
@@ -333,12 +333,12 @@ function.
The method table must be referenced in the module definition structure::
static struct PyModuleDef spammodule = {
- PyModuleDef_HEAD_INIT,
- "spam", /* name of module */
- spam_doc, /* module documentation, may be NULL */
- -1, /* size of per-interpreter state of the module,
- or -1 if the module keeps state in global variables. */
- SpamMethods
+ PyModuleDef_HEAD_INIT,
+ "spam", /* name of module */
+ spam_doc, /* module documentation, may be NULL */
+ -1, /* size of per-interpreter state of the module,
+ or -1 if the module keeps state in global variables. */
+ SpamMethods
};
This structure, in turn, must be passed to the interpreter in the module's
diff --git a/Doc/extending/newtypes.rst b/Doc/extending/newtypes.rst
index bd09aa695d3..0e36ba0aec0 100644
--- a/Doc/extending/newtypes.rst
+++ b/Doc/extending/newtypes.rst
@@ -177,16 +177,9 @@ the module. We'll expand this example later to have more interesting behavior.
For now, all we want to be able to do is to create new :class:`Noddy` objects.
To enable object creation, we have to provide a :c:member:`~PyTypeObject.tp_new` implementation.
In this case, we can just use the default implementation provided by the API
-function :c:func:`PyType_GenericNew`. We'd like to just assign this to the
-:c:member:`~PyTypeObject.tp_new` slot, but we can't, for portability sake, On some platforms or
-compilers, we can't statically initialize a structure member with a function
-defined in another C module, so, instead, we'll assign the :c:member:`~PyTypeObject.tp_new` slot
-in the module initialization function just before calling
-:c:func:`PyType_Ready`::
+function :c:func:`PyType_GenericNew`. ::
- noddy_NoddyType.tp_new = PyType_GenericNew;
- if (PyType_Ready(&noddy_NoddyType) < 0)
- return;
+ PyType_GenericNew, /* tp_new */
All the other type methods are *NULL*, so we'll go over them later --- that's
for a later section!
@@ -728,8 +721,9 @@ functions. With :c:func:`Py_VISIT`, :c:func:`Noddy_traverse` can be simplified:
uniformity across these boring implementations.
We also need to provide a method for clearing any subobjects that can
-participate in cycles. We implement the method and reimplement the deallocator
-to use it::
+participate in cycles.
+
+::
static int
Noddy_clear(Noddy *self)
@@ -747,13 +741,6 @@ to use it::
return 0;
}
- static void
- Noddy_dealloc(Noddy* self)
- {
- Noddy_clear(self);
- Py_TYPE(self)->tp_free((PyObject*)self);
- }
-
Notice the use of a temporary variable in :c:func:`Noddy_clear`. We use the
temporary variable so that we can set each member to *NULL* before decrementing
its reference count. We do this because, as was discussed earlier, if the
@@ -776,6 +763,23 @@ be simplified::
return 0;
}
+Note that :c:func:`Noddy_dealloc` may call arbitrary functions through
+``__del__`` method or weakref callback. It means circular GC can be
+triggered inside the function. Since GC assumes reference count is not zero,
+we need to untrack the object from GC by calling :c:func:`PyObject_GC_UnTrack`
+before clearing members. Here is reimplemented deallocator which uses
+:c:func:`PyObject_GC_UnTrack` and :c:func:`Noddy_clear`.
+
+::
+
+ static void
+ Noddy_dealloc(Noddy* self)
+ {
+ PyObject_GC_UnTrack(self);
+ Noddy_clear(self);
+ Py_TYPE(self)->tp_free((PyObject*)self);
+ }
+
Finally, we add the :const:`Py_TPFLAGS_HAVE_GC` flag to the class flags::
Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE | Py_TPFLAGS_HAVE_GC, /* tp_flags */
diff --git a/Doc/faq/general.rst b/Doc/faq/general.rst
index 8f6a907a8a2..d4a97fd81af 100644
--- a/Doc/faq/general.rst
+++ b/Doc/faq/general.rst
@@ -167,7 +167,7 @@ several useful pieces of freely distributable software. The source will compile
and run out of the box on most UNIX platforms.
Consult the `Getting Started section of the Python Developer's Guide
-<https://docs.python.org/devguide/setup.html>`__ for more
+<https://devguide.python.org/setup/>`__ for more
information on getting the source code and compiling it.
@@ -223,7 +223,7 @@ newsgroups and on the Python home page at https://www.python.org/; an RSS feed o
news is available.
You can also access the development version of Python through Git. See
-`The Python Developer's Guide <https://docs.python.org/devguide/>`_ for details.
+`The Python Developer's Guide <https://devguide.python.org/>`_ for details.
How do I submit bug reports and patches for Python?
@@ -239,7 +239,7 @@ report bugs to Python, you can obtain your Roundup password through Roundup's
`password reset procedure <https://bugs.python.org/user?@template=forgotten>`_.
For more information on how Python is developed, consult `the Python Developer's
-Guide <https://docs.python.org/devguide/>`_.
+Guide <https://devguide.python.org/>`_.
Are there any published articles about Python that I can reference?
diff --git a/Doc/faq/gui.rst b/Doc/faq/gui.rst
index 477d8c63343..38e1796267f 100644
--- a/Doc/faq/gui.rst
+++ b/Doc/faq/gui.rst
@@ -94,15 +94,6 @@ Python bindings for `the FLTK toolkit <http://www.fltk.org>`_, a simple yet
powerful and mature cross-platform windowing system, are available from `the
PyFLTK project <http://pyfltk.sourceforge.net>`_.
-
-FOX
-----
-
-A wrapper for `the FOX toolkit <http://www.fox-toolkit.org/>`_ called `FXpy
-<http://fxpy.sourceforge.net/>`_ is available. FOX supports both Unix variants
-and Windows.
-
-
OpenGL
------
diff --git a/Doc/faq/programming.rst b/Doc/faq/programming.rst
index d9bdb21e79a..1022373d387 100644
--- a/Doc/faq/programming.rst
+++ b/Doc/faq/programming.rst
@@ -1638,7 +1638,7 @@ collected.
Despite the cycle collector, it's still a good idea to define an explicit
``close()`` method on objects to be called whenever you're done with them. The
-``close()`` method can then remove attributes that refer to subobjecs. Don't
+``close()`` method can then remove attributes that refer to subobjects. Don't
call :meth:`__del__` directly -- :meth:`__del__` should call ``close()`` and
``close()`` should make sure that it can be called more than once for the same
object.
diff --git a/Doc/glossary.rst b/Doc/glossary.rst
index dba9186d935..b947520b96b 100644
--- a/Doc/glossary.rst
+++ b/Doc/glossary.rst
@@ -535,7 +535,10 @@ Glossary
iterables include all sequence types (such as :class:`list`, :class:`str`,
and :class:`tuple`) and some non-sequence types like :class:`dict`,
:term:`file objects <file object>`, and objects of any classes you define
- with an :meth:`__iter__` or :meth:`__getitem__` method. Iterables can be
+ with an :meth:`__iter__` method or with a :meth:`__getitem__` method
+ that implements :term:`Sequence` semantics.
+
+ Iterables can be
used in a :keyword:`for` loop and in many other places where a sequence is
needed (:func:`zip`, :func:`map`, ...). When an iterable object is passed
as an argument to the built-in function :func:`iter`, it returns an
diff --git a/Doc/howto/curses.rst b/Doc/howto/curses.rst
index 188a5cf2231..1d3bfb87dc0 100644
--- a/Doc/howto/curses.rst
+++ b/Doc/howto/curses.rst
@@ -65,7 +65,7 @@ and full support for mouse and keyboard input.
The Python curses module
------------------------
-Thy Python module is a fairly simple wrapper over the C functions provided by
+The Python module is a fairly simple wrapper over the C functions provided by
curses; if you're already familiar with curses programming in C, it's really
easy to transfer that knowledge to Python. The biggest difference is that the
Python interface makes things simpler by merging different C functions such as
@@ -538,7 +538,7 @@ the Python interface. Often this isn't because they're difficult to
implement, but because no one has needed them yet. Also, Python
doesn't yet support the menu library associated with ncurses.
Patches adding support for these would be welcome; see
-`the Python Developer's Guide <https://docs.python.org/devguide/>`_ to
+`the Python Developer's Guide <https://devguide.python.org/>`_ to
learn more about submitting patches to Python.
* `Writing Programs with NCURSES <http://invisible-island.net/ncurses/ncurses-intro.html>`_:
diff --git a/Doc/howto/descriptor.rst b/Doc/howto/descriptor.rst
index 2dd6c34e2ce..5e85a9aa659 100644
--- a/Doc/howto/descriptor.rst
+++ b/Doc/howto/descriptor.rst
@@ -180,7 +180,7 @@ descriptor is useful for monitoring just a few chosen attributes::
The protocol is simple and offers exciting possibilities. Several use cases are
so common that they have been packaged into individual function calls.
-Properties, bound and unbound methods, static methods, and class methods are all
+Properties, bound methods, static methods, and class methods are all
based on the descriptor protocol.
@@ -252,10 +252,10 @@ to wrap access to the value attribute in a property data descriptor::
class Cell(object):
. . .
- def getvalue(self, obj):
- "Recalculate cell before returning value"
+ def getvalue(self):
+ "Recalculate the cell before returning value"
self.recalc()
- return obj._value
+ return self._value
value = property(getvalue)
@@ -266,22 +266,23 @@ Python's object oriented features are built upon a function based environment.
Using non-data descriptors, the two are merged seamlessly.
Class dictionaries store methods as functions. In a class definition, methods
-are written using :keyword:`def` and :keyword:`lambda`, the usual tools for
-creating functions. The only difference from regular functions is that the
+are written using :keyword:`def` or :keyword:`lambda`, the usual tools for
+creating functions. Methods only differ from regular functions in that the
first argument is reserved for the object instance. By Python convention, the
instance reference is called *self* but may be called *this* or any other
variable name.
To support method calls, functions include the :meth:`__get__` method for
binding methods during attribute access. This means that all functions are
-non-data descriptors which return bound or unbound methods depending whether
-they are invoked from an object or a class. In pure python, it works like
-this::
+non-data descriptors which return bound methods when they are invoked from an
+object. In pure python, it works like this::
class Function(object):
. . .
def __get__(self, obj, objtype=None):
"Simulate func_descr_get() in Objects/funcobject.c"
+ if obj is None:
+ return self
return types.MethodType(self, obj)
Running the interpreter shows how the function descriptor works in practice::
@@ -291,25 +292,34 @@ Running the interpreter shows how the function descriptor works in practice::
... return x
...
>>> d = D()
- >>> D.__dict__['f'] # Stored internally as a function
- <function f at 0x00C45070>
- >>> D.f # Get from a class becomes an unbound method
- <unbound method D.f>
- >>> d.f # Get from an instance becomes a bound method
+
+ # Access through the class dictionary does not invoke __get__.
+ # It just returns the underlying function object.
+ >>> D.__dict__['f']
+ <function D.f at 0x00C45070>
+
+ # Dotted access from a class calls __get__() which just returns
+ # the underlying function unchanged.
+ >>> D.f
+ <function D.f at 0x00C45070>
+
+ # The function has a __qualname__ attribute to support introspection
+ >>> D.f.__qualname__
+ 'D.f'
+
+ # Dotted access from an instance calls __get__() which returns the
+ # function wrapped in a bound method object
+ >>> d.f
<bound method D.f of <__main__.D object at 0x00B18C90>>
-The output suggests that bound and unbound methods are two different types.
-While they could have been implemented that way, the actual C implementation of
-:c:type:`PyMethod_Type` in :source:`Objects/classobject.c` is a single object
-with two different representations depending on whether the :attr:`im_self`
-field is set or is *NULL* (the C equivalent of ``None``).
-
-Likewise, the effects of calling a method object depend on the :attr:`im_self`
-field. If set (meaning bound), the original function (stored in the
-:attr:`im_func` field) is called as expected with the first argument set to the
-instance. If unbound, all of the arguments are passed unchanged to the original
-function. The actual C implementation of :func:`instancemethod_call()` is only
-slightly more complex in that it includes some type checking.
+ # Internally, the bound method stores the underlying function,
+ # the bound instance, and the class of the bound instance.
+ >>> d.f.__func__
+ <function D.f at 0x1012e5ae8>
+ >>> d.f.__self__
+ <__main__.D object at 0x1012e1f98>
+ >>> d.f.__class__
+ <class 'method'>
Static Methods and Class Methods
diff --git a/Doc/howto/instrumentation.rst b/Doc/howto/instrumentation.rst
index 7fca9aac7b3..b9c51a4a453 100644
--- a/Doc/howto/instrumentation.rst
+++ b/Doc/howto/instrumentation.rst
@@ -312,6 +312,21 @@ Available static markers
Fires when the Python interpreter finishes a garbage collection
cycle. ``arg0`` is the number of collected objects.
+.. c:function:: import__find__load__start(str modulename)
+
+ Fires before :mod:`importlib` attempts to find and load the module.
+ ``arg0`` is the module name.
+
+ .. versionadded:: 3.7
+
+.. c:function:: import__find__load__done(str modulename, int found)
+
+ Fires after :mod:`importlib`'s find_and_load function is called.
+ ``arg0`` is the module name, ``arg1`` indicates if module was
+ successfully loaded.
+
+ .. versionadded:: 3.7
+
SystemTap Tapsets
-----------------
diff --git a/Doc/howto/logging-cookbook.rst b/Doc/howto/logging-cookbook.rst
index 6498ea56957..71ee417f2bc 100644
--- a/Doc/howto/logging-cookbook.rst
+++ b/Doc/howto/logging-cookbook.rst
@@ -1055,7 +1055,7 @@ to indicate additional contextual information to be added to the log). So
you cannot directly make logging calls using :meth:`str.format` or
:class:`string.Template` syntax, because internally the logging package
uses %-formatting to merge the format string and the variable arguments.
-There would no changing this while preserving backward compatibility, since
+There would be no changing this while preserving backward compatibility, since
all logging calls which are out there in existing code will be using %-format
strings.
@@ -1258,8 +1258,8 @@ socket is created separately and passed to the handler (as its 'queue')::
class ZeroMQSocketHandler(QueueHandler):
def enqueue(self, record):
- data = json.dumps(record.__dict__)
- self.queue.send(data)
+ self.queue.send_json(record.__dict__)
+
handler = ZeroMQSocketHandler(sock)
@@ -1272,11 +1272,10 @@ data needed by the handler to create the socket::
self.ctx = ctx or zmq.Context()
socket = zmq.Socket(self.ctx, socktype)
socket.bind(uri)
- QueueHandler.__init__(self, socket)
+ super().__init__(socket)
def enqueue(self, record):
- data = json.dumps(record.__dict__)
- self.queue.send(data)
+ self.queue.send_json(record.__dict__)
def close(self):
self.queue.close()
@@ -1292,12 +1291,13 @@ of queues, for example a ZeroMQ 'subscribe' socket. Here's an example::
def __init__(self, uri, *handlers, **kwargs):
self.ctx = kwargs.get('ctx') or zmq.Context()
socket = zmq.Socket(self.ctx, zmq.SUB)
- socket.setsockopt(zmq.SUBSCRIBE, '') # subscribe to everything
+ socket.setsockopt_string(zmq.SUBSCRIBE, '') # subscribe to everything
socket.connect(uri)
+ super().__init__(socket, *handlers, **kwargs)
def dequeue(self):
- msg = self.queue.recv()
- return logging.makeLogRecord(json.loads(msg))
+ msg = self.queue.recv_json()
+ return logging.makeLogRecord(msg)
.. seealso::
diff --git a/Doc/howto/regex.rst b/Doc/howto/regex.rst
index d9b7c9091d4..e8466ee5423 100644
--- a/Doc/howto/regex.rst
+++ b/Doc/howto/regex.rst
@@ -153,8 +153,8 @@ These sequences can be included inside a character class. For example,
``','`` or ``'.'``.
The final metacharacter in this section is ``.``. It matches anything except a
-newline character, and there's an alternate mode (``re.DOTALL``) where it will
-match even a newline. ``'.'`` is often used where you want to match "any
+newline character, and there's an alternate mode (:const:`re.DOTALL`) where it will
+match even a newline. ``.`` is often used where you want to match "any
character".
@@ -168,14 +168,11 @@ wouldn't be much of an advance. Another capability is that you can specify that
portions of the RE must be repeated a certain number of times.
The first metacharacter for repeating things that we'll look at is ``*``. ``*``
-doesn't match the literal character ``*``; instead, it specifies that the
+doesn't match the literal character ``'*'``; instead, it specifies that the
previous character can be matched zero or more times, instead of exactly once.
-For example, ``ca*t`` will match ``ct`` (0 ``a`` characters), ``cat`` (1 ``a``),
-``caaat`` (3 ``a`` characters), and so forth. The RE engine has various
-internal limitations stemming from the size of C's ``int`` type that will
-prevent it from matching over 2 billion ``a`` characters; patterns
-are usually not written to match that much data.
+For example, ``ca*t`` will match ``'ct'`` (0 ``'a'`` characters), ``'cat'`` (1 ``'a'``),
+``'caaat'`` (3 ``'a'`` characters), and so forth.
Repetitions such as ``*`` are :dfn:`greedy`; when repeating a RE, the matching
engine will try to repeat it as many times as possible. If later portions of the
@@ -185,7 +182,7 @@ fewer repetitions.
A step-by-step example will make this more obvious. Let's consider the
expression ``a[bcd]*b``. This matches the letter ``'a'``, zero or more letters
from the class ``[bcd]``, and finally ends with a ``'b'``. Now imagine matching
-this RE against the string ``abcbd``.
+this RE against the string ``'abcbd'``.
+------+-----------+---------------------------------+
| Step | Matched | Explanation |
@@ -218,7 +215,7 @@ this RE against the string ``abcbd``.
| | | it succeeds. |
+------+-----------+---------------------------------+
-The end of the RE has now been reached, and it has matched ``abcb``. This
+The end of the RE has now been reached, and it has matched ``'abcb'``. This
demonstrates how the matching engine goes as far as it can at first, and if no
match is found it will then progressively back up and retry the rest of the RE
again and again. It will back up until it has tried zero matches for
@@ -229,24 +226,23 @@ Another repeating metacharacter is ``+``, which matches one or more times. Pay
careful attention to the difference between ``*`` and ``+``; ``*`` matches
*zero* or more times, so whatever's being repeated may not be present at all,
while ``+`` requires at least *one* occurrence. To use a similar example,
-``ca+t`` will match ``cat`` (1 ``a``), ``caaat`` (3 ``a``'s), but won't match
-``ct``.
+``ca+t`` will match ``'cat'`` (1 ``'a'``), ``'caaat'`` (3 ``'a'``\ s), but won't
+match ``'ct'``.
There are two more repeating qualifiers. The question mark character, ``?``,
matches either once or zero times; you can think of it as marking something as
-being optional. For example, ``home-?brew`` matches either ``homebrew`` or
-``home-brew``.
+being optional. For example, ``home-?brew`` matches either ``'homebrew'`` or
+``'home-brew'``.
The most complicated repeated qualifier is ``{m,n}``, where *m* and *n* are
decimal integers. This qualifier means there must be at least *m* repetitions,
-and at most *n*. For example, ``a/{1,3}b`` will match ``a/b``, ``a//b``, and
-``a///b``. It won't match ``ab``, which has no slashes, or ``a////b``, which
+and at most *n*. For example, ``a/{1,3}b`` will match ``'a/b'``, ``'a//b'``, and
+``'a///b'``. It won't match ``'ab'``, which has no slashes, or ``'a////b'``, which
has four.
You can omit either *m* or *n*; in that case, a reasonable value is assumed for
the missing value. Omitting *m* is interpreted as a lower limit of 0, while
-omitting *n* results in an upper bound of infinity --- actually, the upper bound
-is the 2-billion limit mentioned earlier, but that might as well be infinity.
+omitting *n* results in an upper bound of infinity.
Readers of a reductionist bent may notice that the three other qualifiers can
all be expressed using this notation. ``{0,}`` is the same as ``*``, ``{1,}``
@@ -366,7 +362,7 @@ for a complete listing.
| | returns them as an :term:`iterator`. |
+------------------+-----------------------------------------------+
-:meth:`~re.regex.match` and :meth:`~re.regex.search` return ``None`` if no match can be found. If
+:meth:`~re.Pattern.match` and :meth:`~re.Pattern.search` return ``None`` if no match can be found. If
they're successful, a :ref:`match object <match-objects>` instance is returned,
containing information about the match: where it starts and ends, the substring
it matched, and more.
@@ -388,24 +384,24 @@ Python interpreter, import the :mod:`re` module, and compile a RE::
Now, you can try matching various strings against the RE ``[a-z]+``. An empty
string shouldn't match at all, since ``+`` means 'one or more repetitions'.
-:meth:`match` should return ``None`` in this case, which will cause the
+:meth:`~re.Pattern.match` should return ``None`` in this case, which will cause the
interpreter to print no output. You can explicitly print the result of
-:meth:`match` to make this clear. ::
+:meth:`!match` to make this clear. ::
>>> p.match("")
>>> print(p.match(""))
None
Now, let's try it on a string that it should match, such as ``tempo``. In this
-case, :meth:`match` will return a :ref:`match object <match-objects>`, so you
+case, :meth:`~re.Pattern.match` will return a :ref:`match object <match-objects>`, so you
should store the result in a variable for later use. ::
>>> m = p.match('tempo')
- >>> m #doctest: +ELLIPSIS
- <_sre.SRE_Match object; span=(0, 5), match='tempo'>
+ >>> m
+ <re.Match object; span=(0, 5), match='tempo'>
Now you can query the :ref:`match object <match-objects>` for information
-about the matching string. :ref:`match object <match-objects>` instances
+about the matching string. Match object instances
also have several methods and attributes; the most important ones are:
+------------------+--------------------------------------------+
@@ -430,18 +426,18 @@ Trying these methods will soon clarify their meaning::
>>> m.span()
(0, 5)
-:meth:`~re.match.group` returns the substring that was matched by the RE. :meth:`~re.match.start`
-and :meth:`~re.match.end` return the starting and ending index of the match. :meth:`~re.match.span`
-returns both start and end indexes in a single tuple. Since the :meth:`match`
-method only checks if the RE matches at the start of a string, :meth:`start`
-will always be zero. However, the :meth:`search` method of patterns
+:meth:`~re.Match.group` returns the substring that was matched by the RE. :meth:`~re.Match.start`
+and :meth:`~re.Match.end` return the starting and ending index of the match. :meth:`~re.Match.span`
+returns both start and end indexes in a single tuple. Since the :meth:`~re.Pattern.match`
+method only checks if the RE matches at the start of a string, :meth:`!start`
+will always be zero. However, the :meth:`~re.Pattern.search` method of patterns
scans through the string, so the match may not start at zero in that
case. ::
>>> print(p.match('::: message'))
None
- >>> m = p.search('::: message'); print(m) #doctest: +ELLIPSIS
- <_sre.SRE_Match object; span=(4, 11), match='message'>
+ >>> m = p.search('::: message'); print(m)
+ <re.Match object; span=(4, 11), match='message'>
>>> m.group()
'message'
>>> m.span()
@@ -459,14 +455,14 @@ In actual programs, the most common style is to store the
print('No match')
Two pattern methods return all of the matches for a pattern.
-:meth:`~re.regex.findall` returns a list of matching strings::
+:meth:`~re.Pattern.findall` returns a list of matching strings::
>>> p = re.compile('\d+')
>>> p.findall('12 drummers drumming, 11 pipers piping, 10 lords a-leaping')
['12', '11', '10']
-:meth:`findall` has to create the entire list before it can be returned as the
-result. The :meth:`~re.regex.finditer` method returns a sequence of
+:meth:`~re.Pattern.findall` has to create the entire list before it can be returned as the
+result. The :meth:`~re.Pattern.finditer` method returns a sequence of
:ref:`match object <match-objects>` instances as an :term:`iterator`::
>>> iterator = p.finditer('12 drummers drumming, 11 ... 10 ...')
@@ -493,7 +489,7 @@ the RE string added as the first argument, and still return either ``None`` or a
>>> print(re.match(r'From\s+', 'Fromage amk'))
None
>>> re.match(r'From\s+', 'From amk Thu May 14 19:12:10 1998') #doctest: +ELLIPSIS
- <_sre.SRE_Match object; span=(0, 5), match='From '>
+ <re.Match object; span=(0, 5), match='From '>
Under the hood, these functions simply create a pattern object for you
and call the appropriate method on it. They also store the compiled
@@ -529,14 +525,14 @@ of each one.
| | characters with the respective property. |
+---------------------------------+--------------------------------------------+
| :const:`DOTALL`, :const:`S` | Make ``.`` match any character, including |
-| | newlines |
+| | newlines. |
+---------------------------------+--------------------------------------------+
-| :const:`IGNORECASE`, :const:`I` | Do case-insensitive matches |
+| :const:`IGNORECASE`, :const:`I` | Do case-insensitive matches. |
+---------------------------------+--------------------------------------------+
-| :const:`LOCALE`, :const:`L` | Do a locale-aware match |
+| :const:`LOCALE`, :const:`L` | Do a locale-aware match. |
+---------------------------------+--------------------------------------------+
| :const:`MULTILINE`, :const:`M` | Multi-line matching, affecting ``^`` and |
-| | ``$`` |
+| | ``$``. |
+---------------------------------+--------------------------------------------+
| :const:`VERBOSE`, :const:`X` | Enable verbose REs, which can be organized |
| (for 'extended') | more cleanly and understandably. |
@@ -549,27 +545,41 @@ of each one.
Perform case-insensitive matching; character class and literal strings will
match letters by ignoring case. For example, ``[A-Z]`` will match lowercase
- letters, too, and ``Spam`` will match ``Spam``, ``spam``, or ``spAM``. This
- lowercasing doesn't take the current locale into account; it will if you also
- set the :const:`LOCALE` flag.
+ letters, too. Full Unicode matching also works unless the :const:`ASCII`
+ flag is used to disable non-ASCII matches. When the Unicode patterns
+ ``[a-z]`` or ``[A-Z]`` are used in combination with the :const:`IGNORECASE`
+ flag, they will match the 52 ASCII letters and 4 additional non-ASCII
+ letters: 'İ' (U+0130, Latin capital letter I with dot above), 'ı' (U+0131,
+ Latin small letter dotless i), 'ſ' (U+017F, Latin small letter long s) and
+ 'K' (U+212A, Kelvin sign). ``Spam`` will match ``'Spam'``, ``'spam'``,
+ ``'spAM'``, or ``'ſpam'`` (the latter is matched only in Unicode mode).
+ This lowercasing doesn't take the current locale into account;
+ it will if you also set the :const:`LOCALE` flag.
.. data:: L
LOCALE
:noindex:
- Make ``\w``, ``\W``, ``\b``, and ``\B``, dependent on the current locale
- instead of the Unicode database.
+ Make ``\w``, ``\W``, ``\b``, ``\B`` and case-insensitive matching dependent
+ on the current locale instead of the Unicode database.
- Locales are a feature of the C library intended to help in writing programs that
- take account of language differences. For example, if you're processing French
- text, you'd want to be able to write ``\w+`` to match words, but ``\w`` only
- matches the character class ``[A-Za-z]``; it won't match ``'é'`` or ``'ç'``. If
- your system is configured properly and a French locale is selected, certain C
- functions will tell the program that ``'é'`` should also be considered a letter.
+ Locales are a feature of the C library intended to help in writing programs
+ that take account of language differences. For example, if you're
+ processing encoded French text, you'd want to be able to write ``\w+`` to
+ match words, but ``\w`` only matches the character class ``[A-Za-z]`` in
+ bytes patterns; it won't match bytes corresponding to ``é`` or ``ç``.
+ If your system is configured properly and a French locale is selected,
+ certain C functions will tell the program that the byte corresponding to
+ ``é`` should also be considered a letter.
Setting the :const:`LOCALE` flag when compiling a regular expression will cause
the resulting compiled object to use these C functions for ``\w``; this is
slower, but also enables ``\w+`` to match French words as you'd expect.
+ The use of this flag is discouraged in Python 3 as the locale mechanism
+ is very unreliable, it only handles one "culture" at a time, and it only
+ works with 8-bit locales. Unicode matching is already enabled by default
+ in Python 3 for Unicode (str) patterns, and it is able to handle different
+ locales/languages.
.. data:: M
@@ -667,11 +677,11 @@ zero-width assertions should never be repeated, because if they match once at a
given location, they can obviously be matched an infinite number of times.
``|``
- Alternation, or the "or" operator. If A and B are regular expressions,
- ``A|B`` will match any string that matches either ``A`` or ``B``. ``|`` has very
+ Alternation, or the "or" operator. If *A* and *B* are regular expressions,
+ ``A|B`` will match any string that matches either *A* or *B*. ``|`` has very
low precedence in order to make it work reasonably when you're alternating
- multi-character strings. ``Crow|Servo`` will match either ``Crow`` or ``Servo``,
- not ``Cro``, a ``'w'`` or an ``'S'``, and ``ervo``.
+ multi-character strings. ``Crow|Servo`` will match either ``'Crow'`` or ``'Servo'``,
+ not ``'Cro'``, a ``'w'`` or an ``'S'``, and ``'ervo'``.
To match a literal ``'|'``, use ``\|``, or enclose it inside a character class,
as in ``[|]``.
@@ -685,23 +695,22 @@ given location, they can obviously be matched an infinite number of times.
line, the RE to use is ``^From``. ::
>>> print(re.search('^From', 'From Here to Eternity')) #doctest: +ELLIPSIS
- <_sre.SRE_Match object; span=(0, 4), match='From'>
+ <re.Match object; span=(0, 4), match='From'>
>>> print(re.search('^From', 'Reciting From Memory'))
None
- .. To match a literal \character{\^}, use \regexp{\e\^} or enclose it
- .. inside a character class, as in \regexp{[{\e}\^]}.
+ To match a literal ``'^'``, use ``\^``.
``$``
Matches at the end of a line, which is defined as either the end of the string,
or any location followed by a newline character. ::
>>> print(re.search('}$', '{block}')) #doctest: +ELLIPSIS
- <_sre.SRE_Match object; span=(6, 7), match='}'>
+ <re.Match object; span=(6, 7), match='}'>
>>> print(re.search('}$', '{block} '))
None
>>> print(re.search('}$', '{block}\n')) #doctest: +ELLIPSIS
- <_sre.SRE_Match object; span=(6, 7), match='}'>
+ <re.Match object; span=(6, 7), match='}'>
To match a literal ``'$'``, use ``\$`` or enclose it inside a character class,
as in ``[$]``.
@@ -725,8 +734,8 @@ given location, they can obviously be matched an infinite number of times.
match when it's contained inside another word. ::
>>> p = re.compile(r'\bclass\b')
- >>> print(p.search('no class at all')) #doctest: +ELLIPSIS
- <_sre.SRE_Match object; span=(3, 8), match='class'>
+ >>> print(p.search('no class at all'))
+ <re.Match object; span=(3, 8), match='class'>
>>> print(p.search('the declassified algorithm'))
None
>>> print(p.search('one subclass is'))
@@ -743,8 +752,8 @@ given location, they can obviously be matched an infinite number of times.
>>> p = re.compile('\bclass\b')
>>> print(p.search('no class at all'))
None
- >>> print(p.search('\b' + 'class' + '\b')) #doctest: +ELLIPSIS
- <_sre.SRE_Match object; span=(0, 7), match='\x08class\x08'>
+ >>> print(p.search('\b' + 'class' + '\b'))
+ <re.Match object; span=(0, 7), match='\x08class\x08'>
Second, inside a character class, where there's no use for this assertion,
``\b`` represents the backspace character, for compatibility with Python's
@@ -786,7 +795,8 @@ of a group with a repeating qualifier, such as ``*``, ``+``, ``?``, or
Groups indicated with ``'('``, ``')'`` also capture the starting and ending
index of the text that they match; this can be retrieved by passing an argument
-to :meth:`group`, :meth:`start`, :meth:`end`, and :meth:`span`. Groups are
+to :meth:`~re.Match.group`, :meth:`~re.Match.start`, :meth:`~re.Match.end`, and
+:meth:`~re.Match.span`. Groups are
numbered starting with 0. Group 0 is always present; it's the whole RE, so
:ref:`match object <match-objects>` methods all have group 0 as their default
argument. Later we'll see how to express groups that don't capture the span
@@ -812,13 +822,13 @@ from left to right. ::
>>> m.group(2)
'b'
-:meth:`group` can be passed multiple group numbers at a time, in which case it
+:meth:`~re.Match.group` can be passed multiple group numbers at a time, in which case it
will return a tuple containing the corresponding values for those groups. ::
>>> m.group(2,1,2)
('b', 'abc', 'b')
-The :meth:`groups` method returns a tuple containing the strings for all the
+The :meth:`~re.Match.groups` method returns a tuple containing the strings for all the
subgroups, from 1 up to however many there are. ::
>>> m.groups()
@@ -1034,7 +1044,7 @@ using the following pattern methods:
| ``sub()`` | Find all substrings where the RE matches, and |
| | replace them with a different string |
+------------------+-----------------------------------------------+
-| ``subn()`` | Does the same thing as :meth:`sub`, but |
+| ``subn()`` | Does the same thing as :meth:`!sub`, but |
| | returns the new string and the number of |
| | replacements |
+------------------+-----------------------------------------------+
@@ -1043,10 +1053,10 @@ using the following pattern methods:
Splitting Strings
-----------------
-The :meth:`split` method of a pattern splits a string apart
+The :meth:`~re.Pattern.split` method of a pattern splits a string apart
wherever the RE matches, returning a list of the pieces. It's similar to the
-:meth:`split` method of strings but provides much more generality in the
-delimiters that you can split by; string :meth:`split` only supports splitting by
+:meth:`~str.split` method of strings but provides much more generality in the
+delimiters that you can split by; string :meth:`!split` only supports splitting by
whitespace or by a fixed string. As you'd expect, there's a module-level
:func:`re.split` function, too.
@@ -1098,7 +1108,7 @@ Search and Replace
------------------
Another common task is to find all the matches for a pattern, and replace them
-with a different string. The :meth:`sub` method takes a replacement value,
+with a different string. The :meth:`~re.Pattern.sub` method takes a replacement value,
which can be either a string or a function, and the string to be processed.
.. method:: .sub(replacement, string[, count=0])
@@ -1112,7 +1122,7 @@ which can be either a string or a function, and the string to be processed.
replaced; *count* must be a non-negative integer. The default value of 0 means
to replace all occurrences.
-Here's a simple example of using the :meth:`sub` method. It replaces colour
+Here's a simple example of using the :meth:`~re.Pattern.sub` method. It replaces colour
names with the word ``colour``::
>>> p = re.compile('(blue|white|red)')
@@ -1121,7 +1131,7 @@ names with the word ``colour``::
>>> p.sub('colour', 'blue socks and red shoes', count=1)
'colour socks and red shoes'
-The :meth:`subn` method does the same work, but returns a 2-tuple containing the
+The :meth:`~re.Pattern.subn` method does the same work, but returns a 2-tuple containing the
new string value and the number of replacements that were performed::
>>> p = re.compile('(blue|white|red)')
@@ -1206,24 +1216,24 @@ Use String Methods
Sometimes using the :mod:`re` module is a mistake. If you're matching a fixed
string, or a single character class, and you're not using any :mod:`re` features
-such as the :const:`IGNORECASE` flag, then the full power of regular expressions
+such as the :const:`~re.IGNORECASE` flag, then the full power of regular expressions
may not be required. Strings have several methods for performing operations with
fixed strings and they're usually much faster, because the implementation is a
single small C loop that's been optimized for the purpose, instead of the large,
more generalized regular expression engine.
One example might be replacing a single fixed string with another one; for
-example, you might replace ``word`` with ``deed``. ``re.sub()`` seems like the
-function to use for this, but consider the :meth:`replace` method. Note that
-:func:`replace` will also replace ``word`` inside words, turning ``swordfish``
+example, you might replace ``word`` with ``deed``. :func:`re.sub` seems like the
+function to use for this, but consider the :meth:`~str.replace` method. Note that
+:meth:`!replace` will also replace ``word`` inside words, turning ``swordfish``
into ``sdeedfish``, but the naive RE ``word`` would have done that, too. (To
avoid performing the substitution on parts of words, the pattern would have to
be ``\bword\b``, in order to require that ``word`` have a word boundary on
-either side. This takes the job beyond :meth:`replace`'s abilities.)
+either side. This takes the job beyond :meth:`!replace`'s abilities.)
Another common task is deleting every occurrence of a single character from a
string or replacing it with another single character. You might do this with
-something like ``re.sub('\n', ' ', S)``, but :meth:`translate` is capable of
+something like ``re.sub('\n', ' ', S)``, but :meth:`~str.translate` is capable of
doing both tasks and will be faster than any regular expression operation can
be.
@@ -1234,18 +1244,18 @@ can be solved with a faster and simpler string method.
match() versus search()
-----------------------
-The :func:`match` function only checks if the RE matches at the beginning of the
-string while :func:`search` will scan forward through the string for a match.
-It's important to keep this distinction in mind. Remember, :func:`match` will
+The :func:`~re.match` function only checks if the RE matches at the beginning of the
+string while :func:`~re.search` will scan forward through the string for a match.
+It's important to keep this distinction in mind. Remember, :func:`!match` will
only report a successful match which will start at 0; if the match wouldn't
-start at zero, :func:`match` will *not* report it. ::
+start at zero, :func:`!match` will *not* report it. ::
>>> print(re.match('super', 'superstition').span())
(0, 5)
>>> print(re.match('super', 'insuperable'))
None
-On the other hand, :func:`search` will scan forward through the string,
+On the other hand, :func:`~re.search` will scan forward through the string,
reporting the first match it finds. ::
>>> print(re.search('super', 'superstition').span())
@@ -1284,12 +1294,12 @@ doesn't work because of the greedy nature of ``.*``. ::
>>> print(re.match('<.*>', s).group())
<html><head><title>Title
-The RE matches the ``'<'`` in ````, and the ``.*`` consumes the rest of
+The RE matches the ``'<'`` in ``''``, and the ``.*`` consumes the rest of
the string. There's still more left in the RE, though, and the ``>`` can't
match at the end of the string, so the regular expression engine has to
backtrack character by character until it finds a match for the ``>``. The
-final match extends from the ``'<'`` in ```` to the ``'>'`` in
-````, which isn't what you want.
+final match extends from the ``'<'`` in ``''`` to the ``'>'`` in
+``''``, which isn't what you want.
In this case, the solution is to use the non-greedy qualifiers ``*?``, ``+?``,
``??``, or ``{m,n}?``, which match as *little* text as possible. In the above
@@ -1315,7 +1325,7 @@ notation, but they're not terribly readable. REs of moderate complexity can
become lengthy collections of backslashes, parentheses, and metacharacters,
making them difficult to read and understand.
-For such REs, specifying the ``re.VERBOSE`` flag when compiling the regular
+For such REs, specifying the :const:`re.VERBOSE` flag when compiling the regular
expression can be helpful, because it allows you to format the regular
expression more clearly.
@@ -1354,5 +1364,5 @@ Friedl's Mastering Regular Expressions, published by O'Reilly. Unfortunately,
it exclusively concentrates on Perl and Java's flavours of regular expressions,
and doesn't contain any Python material at all, so it won't be useful as a
reference for programming in Python. (The first edition covered Python's
-now-removed :mod:`regex` module, which won't help you much.) Consider checking
+now-removed :mod:`!regex` module, which won't help you much.) Consider checking
it out from your library.
diff --git a/Doc/includes/email-alternative.py b/Doc/includes/email-alternative.py
index 2e142b1e3b7..df7ca6f3faa 100644
--- a/Doc/includes/email-alternative.py
+++ b/Doc/includes/email-alternative.py
@@ -32,7 +32,7 @@ msg.add_alternative("""\
Salut!
Cela ressemble à un excellent
-
recipie
déjeuner.
diff --git a/Doc/includes/noddy.c b/Doc/includes/noddy.c
index 19a27a89e88..07b5d5a9b83 100644
--- a/Doc/includes/noddy.c
+++ b/Doc/includes/noddy.c
@@ -27,6 +27,23 @@ static PyTypeObject noddy_NoddyType = {
0, /* tp_as_buffer */
Py_TPFLAGS_DEFAULT, /* tp_flags */
"Noddy objects", /* tp_doc */
+ 0, /* tp_traverse */
+ 0, /* tp_clear */
+ 0, /* tp_richcompare */
+ 0, /* tp_weaklistoffset */
+ 0, /* tp_iter */
+ 0, /* tp_iternext */
+ 0, /* tp_methods */
+ 0, /* tp_members */
+ 0, /* tp_getset */
+ 0, /* tp_base */
+ 0, /* tp_dict */
+ 0, /* tp_descr_get */
+ 0, /* tp_descr_set */
+ 0, /* tp_dictoffset */
+ 0, /* tp_init */
+ 0, /* tp_alloc */
+ PyType_GenericNew, /* tp_new */
};
static PyModuleDef noddymodule = {
@@ -42,7 +59,6 @@ PyInit_noddy(void)
{
PyObject* m;
- noddy_NoddyType.tp_new = PyType_GenericNew;
if (PyType_Ready(&noddy_NoddyType) < 0)
return NULL;
diff --git a/Doc/includes/noddy4.c b/Doc/includes/noddy4.c
index eb9622a87d9..08ba4c3d91a 100644
--- a/Doc/includes/noddy4.c
+++ b/Doc/includes/noddy4.c
@@ -46,6 +46,7 @@ Noddy_clear(Noddy *self)
static void
Noddy_dealloc(Noddy* self)
{
+ PyObject_GC_UnTrack(self);
Noddy_clear(self);
Py_TYPE(self)->tp_free((PyObject*)self);
}
diff --git a/Doc/includes/sqlite3/load_extension.py b/Doc/includes/sqlite3/load_extension.py
index 015aa0de8c4..b997c70668a 100644
--- a/Doc/includes/sqlite3/load_extension.py
+++ b/Doc/includes/sqlite3/load_extension.py
@@ -11,7 +11,7 @@ con.execute("select load_extension('./fts3.so')")
# alternatively you can load the extension using an API call:
# con.load_extension("./fts3.so")
-# disable extension laoding again
+# disable extension loading again
con.enable_load_extension(False)
# example from SQLite wiki
diff --git a/Doc/installing/index.rst b/Doc/installing/index.rst
index b22465df291..09bb8251c35 100644
--- a/Doc/installing/index.rst
+++ b/Doc/installing/index.rst
@@ -211,6 +211,17 @@ On such systems, it is often better to use a virtual environment or a
per-user installation when installing packages with ``pip``.
+Pip not installed
+-----------------
+
+It is possible that ``pip`` does not get installed by default. One potential fix is::
+
+ python -m ensurepip --default-pip
+
+There are also additional resources for `installing pip.
+`__
+
+
Installing binary extensions
----------------------------
diff --git a/Doc/library/2to3.rst b/Doc/library/2to3.rst
index 4c9a528d42e..faf06d91c3d 100644
--- a/Doc/library/2to3.rst
+++ b/Doc/library/2to3.rst
@@ -288,7 +288,8 @@ and off individually. They are described here in more detail.
Fixes duplicate types in the second argument of :func:`isinstance`. For
example, ``isinstance(x, (int, int))`` is converted to ``isinstance(x,
- (int))``.
+ int)`` and ``isinstance(x, (int, float, int))`` is converted to
+ ``isinstance(x, (int, float))``.
.. 2to3fixer:: itertools_imports
@@ -344,20 +345,20 @@ and off individually. They are described here in more detail.
Converts calls to various functions in the :mod:`operator` module to other,
but equivalent, function calls. When needed, the appropriate ``import``
- statements are added, e.g. ``import collections``. The following mapping
+ statements are added, e.g. ``import collections.abc``. The following mapping
are made:
- ================================== ==========================================
+ ================================== =============================================
From To
- ================================== ==========================================
+ ================================== =============================================
``operator.isCallable(obj)`` ``hasattr(obj, '__call__')``
``operator.sequenceIncludes(obj)`` ``operator.contains(obj)``
- ``operator.isSequenceType(obj)`` ``isinstance(obj, collections.Sequence)``
- ``operator.isMappingType(obj)`` ``isinstance(obj, collections.Mapping)``
+ ``operator.isSequenceType(obj)`` ``isinstance(obj, collections.abc.Sequence)``
+ ``operator.isMappingType(obj)`` ``isinstance(obj, collections.abc.Mapping)``
``operator.isNumberType(obj)`` ``isinstance(obj, numbers.Number)``
``operator.repeat(obj, n)`` ``operator.mul(obj, n)``
``operator.irepeat(obj, n)`` ``operator.imul(obj, n)``
- ================================== ==========================================
+ ================================== =============================================
.. 2to3fixer:: paren
diff --git a/Doc/library/_dummy_thread.rst b/Doc/library/_dummy_thread.rst
index ebce74d5a22..7dccbc55475 100644
--- a/Doc/library/_dummy_thread.rst
+++ b/Doc/library/_dummy_thread.rst
@@ -6,18 +6,15 @@
**Source code:** :source:`Lib/_dummy_thread.py`
+.. deprecated:: 3.7
+ Python now always has threading enabled. Please use :mod:`_thread`
+ (or, better, :mod:`threading`) instead.
+
--------------
-This module provides a duplicate interface to the :mod:`_thread` module. It is
-meant to be imported when the :mod:`_thread` module is not provided on a
-platform.
-
-Suggested usage is::
-
- try:
- import _thread
- except ImportError:
- import _dummy_thread as _thread
+This module provides a duplicate interface to the :mod:`_thread` module.
+It was meant to be imported when the :mod:`_thread` module was not provided
+on a platform.
Be careful to not use this module where deadlock might occur from a thread being
created that blocks waiting for another thread to be created. This often occurs
diff --git a/Doc/library/_thread.rst b/Doc/library/_thread.rst
index 0d2d818f5f9..67cb70944f4 100644
--- a/Doc/library/_thread.rst
+++ b/Doc/library/_thread.rst
@@ -23,14 +23,10 @@ threading API built on top of this module.
single: pthreads
pair: threads; POSIX
-The module is optional. It is supported on Windows, Linux, SGI IRIX, Solaris
-2.x, as well as on systems that have a POSIX thread (a.k.a. "pthread")
-implementation. For systems lacking the :mod:`_thread` module, the
-:mod:`_dummy_thread` module is available. It duplicates this module's interface
-and can be used as a drop-in replacement.
-
-It defines the following constants and functions:
+.. versionchanged:: 3.7
+ This module used to be optional, it is now always available.
+This module defines the following constants and functions:
.. exception:: error
diff --git a/Doc/library/abc.rst b/Doc/library/abc.rst
index 966003bd45a..9522dd62049 100644
--- a/Doc/library/abc.rst
+++ b/Doc/library/abc.rst
@@ -24,7 +24,33 @@ a class or instance provides a particular interface, for example, is it
hashable or a mapping.
-This module provides the following classes:
+This module provides the metaclass :class:`ABCMeta` for defining ABCs and
+a helper class :class:`ABC` to alternatively define ABCs through inheritance:
+
+.. class:: ABC
+
+ A helper class that has :class:`ABCMeta` as its metaclass. With this class,
+ an abstract base class can be created by simply deriving from :class:`ABC`
+ avoiding sometimes confusing metaclass usage, for example::
+
+ from abc import ABC
+
+ class MyABC(ABC):
+ pass
+
+ Note that the type of :class:`ABC` is still :class:`ABCMeta`, therefore
+ inheriting from :class:`ABC` requires the usual precautions regarding
+ metaclass usage, as multiple inheritance may lead to metaclass conflicts.
+ One may also define an abstract base class by passing the metaclass
+ keyword and using :class:`ABCMeta` directly, for example::
+
+ from abc import ABCMeta
+
+ class MyABC(metaclass=ABCMeta):
+ pass
+
+ .. versionadded:: 3.4
+
.. class:: ABCMeta
@@ -46,15 +72,15 @@ This module provides the following classes:
Register *subclass* as a "virtual subclass" of this ABC. For
example::
- from abc import ABCMeta
+ from abc import ABC
- class MyABC(metaclass=ABCMeta):
- pass
+ class MyABC(ABC):
+ pass
- MyABC.register(tuple)
+ MyABC.register(tuple)
- assert issubclass(tuple, MyABC)
- assert isinstance((), MyABC)
+ assert issubclass(tuple, MyABC)
+ assert isinstance((), MyABC)
.. versionchanged:: 3.3
Returns the registered subclass, to allow usage as a class decorator.
@@ -95,7 +121,7 @@ This module provides the following classes:
def get_iterator(self):
return iter(self)
- class MyIterable(metaclass=ABCMeta):
+ class MyIterable(ABC):
@abstractmethod
def __iter__(self):
@@ -132,17 +158,6 @@ This module provides the following classes:
available as a method of ``Foo``, so it is provided separately.
-.. class:: ABC
-
- A helper class that has :class:`ABCMeta` as its metaclass. With this class,
- an abstract base class can be created by simply deriving from :class:`ABC`,
- avoiding sometimes confusing metaclass usage.
-
- Note that the type of :class:`ABC` is still :class:`ABCMeta`, therefore
- inheriting from :class:`ABC` requires the usual precautions regarding metaclass
- usage, as multiple inheritance may lead to metaclass conflicts.
-
- .. versionadded:: 3.4
The :mod:`abc` module also provides the following decorators:
@@ -168,7 +183,7 @@ The :mod:`abc` module also provides the following decorators:
descriptors, it should be applied as the innermost decorator, as shown in
the following usage examples::
- class C(metaclass=ABCMeta):
+ class C(ABC):
@abstractmethod
def my_abstract_method(self, ...):
...
@@ -230,7 +245,7 @@ The :mod:`abc` module also provides the following decorators:
is now correctly identified as abstract when applied to an abstract
method::
- class C(metaclass=ABCMeta):
+ class C(ABC):
@classmethod
@abstractmethod
def my_abstract_classmethod(cls, ...):
@@ -251,7 +266,7 @@ The :mod:`abc` module also provides the following decorators:
is now correctly identified as abstract when applied to an abstract
method::
- class C(metaclass=ABCMeta):
+ class C(ABC):
@staticmethod
@abstractmethod
def my_abstract_staticmethod(...):
@@ -263,7 +278,7 @@ The :mod:`abc` module also provides the following decorators:
:func:`abstractmethod`, making this decorator redundant.
-.. decorator:: abstractproperty(fget=None, fset=None, fdel=None, doc=None)
+.. decorator:: abstractproperty
A subclass of the built-in :func:`property`, indicating an abstract
property.
@@ -278,7 +293,7 @@ The :mod:`abc` module also provides the following decorators:
is now correctly identified as abstract when applied to an abstract
method::
- class C(metaclass=ABCMeta):
+ class C(ABC):
@property
@abstractmethod
def my_abstract_property(self):
@@ -288,7 +303,7 @@ The :mod:`abc` module also provides the following decorators:
read-write abstract property by appropriately marking one or more of the
underlying methods as abstract::
- class C(metaclass=ABCMeta):
+ class C(ABC):
@property
def x(self):
...
diff --git a/Doc/library/aifc.rst b/Doc/library/aifc.rst
index 23a96207d08..970a7aeb98a 100644
--- a/Doc/library/aifc.rst
+++ b/Doc/library/aifc.rst
@@ -18,12 +18,6 @@ AIFF is Audio Interchange File Format, a format for storing digital audio
samples in a file. AIFF-C is a newer version of the format that includes the
ability to compress the audio data.
-.. note::
-
- Some operations may only work under IRIX; these will raise :exc:`ImportError`
- when attempting to import the :mod:`cl` module, which is only available on
- IRIX.
-
Audio files have a number of parameters that describe the audio data. The
sampling rate or frame rate is the number of times per second the sound is
sampled. The number of channels indicate if the audio is mono, stereo, or
diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst
index 45303048174..53e670161dd 100644
--- a/Doc/library/argparse.rst
+++ b/Doc/library/argparse.rst
@@ -426,7 +426,9 @@ should not be line-wrapped::
-h, --help show this help message and exit
:class:`RawTextHelpFormatter` maintains whitespace for all sorts of help text,
-including argument descriptions.
+including argument descriptions. However, multiple new lines are replaced with
+one. If you wish to preserve multiple blank lines, add spaces between the
+newlines.
:class:`ArgumentDefaultsHelpFormatter` automatically adds information about
default values to each of the argument help messages::
@@ -898,6 +900,8 @@ values are:
usage: PROG [-h] foo [foo ...]
PROG: error: too few arguments
+.. _`argparse.REMAINDER`:
+
* ``argparse.REMAINDER``. All the remaining command-line arguments are gathered
into a list. This is commonly useful for command line utilities that dispatch
to other command line utilities::
@@ -1324,8 +1328,11 @@ The parse_args() method
created and how they are assigned. See the documentation for
:meth:`add_argument` for details.
- By default, the argument strings are taken from :data:`sys.argv`, and a new empty
- :class:`Namespace` object is created for the attributes.
+ * args_ - List of strings to parse. The default is taken from
+ :data:`sys.argv`.
+
+ * namespace_ - An object to take the attributes. The default is a new empty
+ :class:`Namespace` object.
Option value syntax
@@ -1467,6 +1474,7 @@ unambiguous (the prefix matches a unique option)::
An error is produced for arguments that could produce more than one options.
This feature can be disabled by setting :ref:`allow_abbrev` to ``False``.
+.. _args:
Beyond ``sys.argv``
^^^^^^^^^^^^^^^^^^^
@@ -1488,6 +1496,7 @@ interactive prompt::
>>> parser.parse_args(['1', '2', '3', '4', '--sum'])
Namespace(accumulate=, integers=[1, 2, 3, 4])
+.. _namespace:
The Namespace object
^^^^^^^^^^^^^^^^^^^^
@@ -1530,8 +1539,8 @@ Sub-commands
.. method:: ArgumentParser.add_subparsers([title], [description], [prog], \
[parser_class], [action], \
- [option_string], [dest], [help], \
- [metavar])
+ [option_string], [dest], [required] \
+ [help], [metavar])
Many programs split up their functionality into a number of sub-commands,
for example, the ``svn`` program can invoke sub-commands like ``svn
@@ -1567,6 +1576,9 @@ Sub-commands
* dest_ - name of the attribute under which sub-command name will be
stored; by default ``None`` and no value is stored
+ * required_ - Whether or not a subcommand must be provided, by default
+ ``True``.
+
* help_ - help for sub-parser group in help output, by default ``None``
* metavar_ - string presenting available sub-commands in help; by default it
@@ -1978,6 +1990,45 @@ Exiting methods
This method prints a usage message including the *message* to the
standard error and terminates the program with a status code of 2.
+
+Intermixed parsing
+^^^^^^^^^^^^^^^^^^
+
+.. method:: ArgumentParser.parse_intermixed_args(args=None, namespace=None)
+.. method:: ArgumentParser.parse_known_intermixed_args(args=None, namespace=None)
+
+A number of Unix commands allow the user to intermix optional arguments with
+positional arguments. The :meth:`~ArgumentParser.parse_intermixed_args`
+and :meth:`~ArgumentParser.parse_known_intermixed_args` methods
+support this parsing style.
+
+These parsers do not support all the argparse features, and will raise
+exceptions if unsupported features are used. In particular, subparsers,
+``argparse.REMAINDER``, and mutually exclusive groups that include both
+optionals and positionals are not supported.
+
+The following example shows the difference between
+:meth:`~ArgumentParser.parse_known_args` and
+:meth:`~ArgumentParser.parse_intermixed_args`: the former returns ``['2',
+'3']`` as unparsed arguments, while the latter collects all the positionals
+into ``rest``. ::
+
+ >>> parser = argparse.ArgumentParser()
+ >>> parser.add_argument('--foo')
+ >>> parser.add_argument('cmd')
+ >>> parser.add_argument('rest', nargs='*', type=int)
+ >>> parser.parse_known_args('doit 1 --foo bar 2 3'.split())
+ (Namespace(cmd='doit', foo='bar', rest=[1]), ['2', '3'])
+ >>> parser.parse_intermixed_args('doit 1 --foo bar 2 3'.split())
+ Namespace(cmd='doit', foo='bar', rest=[1, 2, 3])
+
+:meth:`~ArgumentParser.parse_known_intermixed_args` returns a two item tuple
+containing the populated namespace and the list of remaining argument strings.
+:meth:`~ArgumentParser.parse_intermixed_args` raises an error if there are any
+remaining unparsed argument strings.
+
+.. versionadded:: 3.7
+
.. _upgrading-optparse-code:
Upgrading optparse code
@@ -2008,7 +2059,11 @@ A partial upgrade path from :mod:`optparse` to :mod:`argparse`:
* Replace ``(options, args) = parser.parse_args()`` with ``args =
parser.parse_args()`` and add additional :meth:`ArgumentParser.add_argument`
calls for the positional arguments. Keep in mind that what was previously
- called ``options``, now in :mod:`argparse` context is called ``args``.
+ called ``options``, now in the :mod:`argparse` context is called ``args``.
+
+* Replace :meth:`optparse.OptionParser.disable_interspersed_args`
+ by using :meth:`~ArgumentParser.parse_intermixed_args` instead of
+ :meth:`~ArgumentParser.parse_args`.
* Replace callback actions and the ``callback_*`` keyword arguments with
``type`` or ``action`` arguments.
diff --git a/Doc/library/asyncio-dev.rst b/Doc/library/asyncio-dev.rst
index cc4a14b2016..b2ad87b5d02 100644
--- a/Doc/library/asyncio-dev.rst
+++ b/Doc/library/asyncio-dev.rst
@@ -21,7 +21,9 @@ enable *debug mode*.
To enable all debug checks for an application:
* Enable the asyncio debug mode globally by setting the environment variable
- :envvar:`PYTHONASYNCIODEBUG` to ``1``, or by calling :meth:`AbstractEventLoop.set_debug`.
+ :envvar:`PYTHONASYNCIODEBUG` to ``1``, using ``-X dev`` command line option
+ (see the :option:`-X` option), or by calling
+ :meth:`AbstractEventLoop.set_debug`.
* Set the log level of the :ref:`asyncio logger ` to
:py:data:`logging.DEBUG`. For example, call
``logging.basicConfig(level=logging.DEBUG)`` at startup.
@@ -42,6 +44,11 @@ Examples debug checks:
* :exc:`ResourceWarning` warnings are emitted when transports and event loops
are :ref:`not closed explicitly `.
+.. versionchanged:: 3.7
+
+ The new ``-X dev`` command line option can now also be used to enable
+ the debug mode.
+
.. seealso::
The :meth:`AbstractEventLoop.set_debug` method and the :ref:`asyncio logger
@@ -52,7 +59,7 @@ Cancellation
------------
Cancellation of tasks is not common in classic programming. In asynchronous
-programming, not only it is something common, but you have to prepare your
+programming, not only is it something common, but you have to prepare your
code to handle it.
Futures and tasks can be cancelled explicitly with their :meth:`Future.cancel`
diff --git a/Doc/library/asyncio-eventloop.rst b/Doc/library/asyncio-eventloop.rst
index fa6a29604ca..e635cba659a 100644
--- a/Doc/library/asyncio-eventloop.rst
+++ b/Doc/library/asyncio-eventloop.rst
@@ -5,6 +5,8 @@
Base Event Loop
===============
+**Source code:** :source:`Lib/asyncio/events.py`
+
The event loop is the central execution device provided by :mod:`asyncio`.
It provides multiple facilities, including:
@@ -339,9 +341,10 @@ Creating connections
.. coroutinemethod:: AbstractEventLoop.create_datagram_endpoint(protocol_factory, local_addr=None, remote_addr=None, \*, family=0, proto=0, flags=0, reuse_address=None, reuse_port=None, allow_broadcast=None, sock=None)
- Create datagram connection: socket family :py:data:`~socket.AF_INET` or
- :py:data:`~socket.AF_INET6` depending on *host* (or *family* if specified),
- socket type :py:data:`~socket.SOCK_DGRAM`. *protocol_factory* must be a
+ Create datagram connection: socket family :py:data:`~socket.AF_INET`,
+ :py:data:`~socket.AF_INET6` or :py:data:`~socket.AF_UNIX` depending on
+ *host* (or *family* if specified), socket type
+ :py:data:`~socket.SOCK_DGRAM`. *protocol_factory* must be a
callable returning a :ref:`protocol ` instance.
This method is a :ref:`coroutine ` which will try to
@@ -552,6 +555,21 @@ Low-level socket operations
This method is a :ref:`coroutine `.
+.. coroutinemethod:: AbstractEventLoop.sock_recv_into(sock, buf)
+
+ Receive data from the socket. Modeled after blocking
+ :meth:`socket.socket.recv_into` method.
+
+ The received data is written into *buf* (a writable buffer).
+ The return value is the number of bytes written.
+
+ With :class:`SelectorEventLoop` event loop, the socket *sock* must be
+ non-blocking.
+
+ This method is a :ref:`coroutine `.
+
+ .. versionadded:: 3.7
+
.. coroutinemethod:: AbstractEventLoop.sock_sendall(sock, data)
Send data to the socket. Modeled after blocking
@@ -849,6 +867,12 @@ Handle
Cancel the call. If the callback is already canceled or executed,
this method has no effect.
+ .. method:: cancelled()
+
+ Return ``True`` if the call was cancelled.
+
+ .. versionadded:: 3.7
+
Event loop examples
-------------------
diff --git a/Doc/library/asyncio-eventloops.rst b/Doc/library/asyncio-eventloops.rst
index 1dc18fce79d..7970e9039df 100644
--- a/Doc/library/asyncio-eventloops.rst
+++ b/Doc/library/asyncio-eventloops.rst
@@ -3,6 +3,8 @@
Event loops
===========
+**Source code:** :source:`Lib/asyncio/events.py`
+
Event loop functions
--------------------
@@ -146,10 +148,9 @@ process based on the calling context. A policy is an object implementing the
:class:`AbstractEventLoopPolicy` interface.
For most users of :mod:`asyncio`, policies never have to be dealt with
-explicitly, since the default global policy is sufficient.
+explicitly, since the default global policy is sufficient (see below).
-The default policy defines context as the current thread, and manages an event
-loop per thread that interacts with :mod:`asyncio`. The module-level functions
+The module-level functions
:func:`get_event_loop` and :func:`set_event_loop` provide convenient access to
event loops managed by the default policy.
@@ -187,6 +188,13 @@ An event loop policy must implement the following interface:
context, :meth:`set_event_loop` must be called explicitly.
+The default policy defines context as the current thread, and manages an event
+loop per thread that interacts with :mod:`asyncio`. If the current thread
+doesn't already have an event loop associated with it, the default policy's
+:meth:`~AbstractEventLoopPolicy.get_event_loop` method creates one when
+called from the main thread, but raises :exc:`RuntimeError` otherwise.
+
+
Access to the global loop policy
--------------------------------
@@ -198,3 +206,24 @@ Access to the global loop policy
Set the current event loop policy. If *policy* is ``None``, the default
policy is restored.
+
+
+Customizing the event loop policy
+---------------------------------
+
+To implement a new event loop policy, it is recommended you subclass the
+concrete default event loop policy :class:`DefaultEventLoopPolicy`
+and override the methods for which you want to change behavior, for example::
+
+ class MyEventLoopPolicy(asyncio.DefaultEventLoopPolicy):
+
+ def get_event_loop(self):
+ """Get the event loop.
+
+ This may be None or an instance of EventLoop.
+ """
+ loop = super().get_event_loop()
+ # Do something with loop ...
+ return loop
+
+ asyncio.set_event_loop_policy(MyEventLoopPolicy())
diff --git a/Doc/library/asyncio-protocol.rst b/Doc/library/asyncio-protocol.rst
index 3f55506c669..cd84ae76b5d 100644
--- a/Doc/library/asyncio-protocol.rst
+++ b/Doc/library/asyncio-protocol.rst
@@ -1,8 +1,12 @@
.. currentmodule:: asyncio
-++++++++++++++++++++++++++++++++++++++++++++++
-Transports and protocols (callback based API)
-++++++++++++++++++++++++++++++++++++++++++++++
++++++++++++++++++++++++++++++++++++++++++++++
+Transports and protocols (callback based API)
++++++++++++++++++++++++++++++++++++++++++++++
+
+**Source code:** :source:`Lib/asyncio/transports.py`
+
+**Source code:** :source:`Lib/asyncio/protocols.py`
.. _asyncio-transport:
@@ -163,11 +167,17 @@ WriteTransport
Set the *high*- and *low*-water limits for write flow control.
- These two values control when call the protocol's
+ These two values (measured in number of
+ bytes) control when the protocol's
:meth:`pause_writing` and :meth:`resume_writing` methods are called.
If specified, the low-water limit must be less than or equal to the
high-water limit. Neither *high* nor *low* can be negative.
+ :meth:`pause_writing` is called when the buffer size becomes greater
+ than or equal to the *high* value. If writing has been paused,
+ :meth:`resume_writing` is called when the buffer size becomes less
+ than or equal to the *low* value.
+
The defaults are implementation-specific. If only the
high-water limit is given, the low-water limit defaults to an
implementation-specific value less than or equal to the
diff --git a/Doc/library/asyncio-queue.rst b/Doc/library/asyncio-queue.rst
index f11c09ac290..ea787550082 100644
--- a/Doc/library/asyncio-queue.rst
+++ b/Doc/library/asyncio-queue.rst
@@ -3,6 +3,8 @@
Queues
======
+**Source code:** :source:`Lib/asyncio/queues.py`
+
Queues:
* :class:`Queue`
diff --git a/Doc/library/asyncio-stream.rst b/Doc/library/asyncio-stream.rst
index 6177b4bb0f8..491afdd610c 100644
--- a/Doc/library/asyncio-stream.rst
+++ b/Doc/library/asyncio-stream.rst
@@ -6,6 +6,8 @@
Streams (coroutine based API)
+++++++++++++++++++++++++++++
+**Source code:** :source:`Lib/asyncio/streams.py`
+
Stream functions
================
diff --git a/Doc/library/asyncio-subprocess.rst b/Doc/library/asyncio-subprocess.rst
index 16ba9a3cd6c..1c1d0be918d 100644
--- a/Doc/library/asyncio-subprocess.rst
+++ b/Doc/library/asyncio-subprocess.rst
@@ -5,6 +5,8 @@
Subprocess
==========
+**Source code:** :source:`Lib/asyncio/subprocess.py`
+
Windows event loop
------------------
diff --git a/Doc/library/asyncio-sync.rst b/Doc/library/asyncio-sync.rst
index 09093521524..14e3defbf41 100644
--- a/Doc/library/asyncio-sync.rst
+++ b/Doc/library/asyncio-sync.rst
@@ -4,6 +4,8 @@
Synchronization primitives
==========================
+**Source code:** :source:`Lib/asyncio/locks.py`
+
Locks:
* :class:`Lock`
diff --git a/Doc/library/asyncio-task.rst b/Doc/library/asyncio-task.rst
index 804f1925b40..ff35b0add9d 100644
--- a/Doc/library/asyncio-task.rst
+++ b/Doc/library/asyncio-task.rst
@@ -3,6 +3,10 @@
Tasks and coroutines
====================
+**Source code:** :source:`Lib/asyncio/tasks.py`
+
+**Source code:** :source:`Lib/asyncio/coroutines.py`
+
.. _coroutine:
Coroutines
@@ -212,7 +216,7 @@ Future
raise an exception when the future isn't done yet.
- Callbacks registered with :meth:`add_done_callback` are always called
- via the event loop's :meth:`~AbstractEventLoop.call_soon_threadsafe`.
+ via the event loop's :meth:`~AbstractEventLoop.call_soon`.
- This class is not compatible with the :func:`~concurrent.futures.wait` and
:func:`~concurrent.futures.as_completed` functions in the
@@ -370,7 +374,7 @@ Task
running in different threads. While a task waits for the completion of a
future, the event loop executes a new task.
- The cancellation of a task is different from the cancelation of a
+ The cancellation of a task is different from the cancellation of a
future. Calling :meth:`cancel` will throw a
:exc:`~concurrent.futures.CancelledError` to the wrapped
coroutine. :meth:`~Future.cancelled` only returns ``True`` if the
diff --git a/Doc/library/atexit.rst b/Doc/library/atexit.rst
index 1d84d4587fd..5c60b604c68 100644
--- a/Doc/library/atexit.rst
+++ b/Doc/library/atexit.rst
@@ -21,7 +21,7 @@ program is killed by a signal not handled by Python, when a Python fatal
internal error is detected, or when :func:`os._exit` is called.
-.. function:: register(func, *args, **kargs)
+.. function:: register(func, *args, **kwargs)
Register *func* as a function to be executed at termination. Any optional
arguments that are to be passed to *func* must be passed as arguments to
diff --git a/Doc/library/calendar.rst b/Doc/library/calendar.rst
index a415b4792a6..56b75ef0f85 100644
--- a/Doc/library/calendar.rst
+++ b/Doc/library/calendar.rst
@@ -19,11 +19,13 @@ the week to Sunday (6) or to any other weekday. Parameters that specify dates
are given as integers. For related
functionality, see also the :mod:`datetime` and :mod:`time` modules.
-Most of these functions and classes rely on the :mod:`datetime` module which
-uses an idealized calendar, the current Gregorian calendar extended
+The functions and classes defined in this module
+use an idealized calendar, the current Gregorian calendar extended indefinitely
in both directions. This matches the definition of the "proleptic Gregorian"
calendar in Dershowitz and Reingold's book "Calendrical Calculations", where
-it's the base calendar for all computations.
+it's the base calendar for all computations. Zero and negative years are
+interpreted as prescribed by the ISO 8601 standard. Year 0 is 1 BC, year -1 is
+2 BC, and so on.
.. class:: Calendar(firstweekday=0)
@@ -53,17 +55,40 @@ it's the base calendar for all computations.
month that are required to get a complete week.
- .. method:: itermonthdays2(year, month)
-
- Return an iterator for the month *month* in the year *year* similar to
- :meth:`itermonthdates`. Days returned will be tuples consisting of a day
- number and a week day number.
-
-
.. method:: itermonthdays(year, month)
Return an iterator for the month *month* in the year *year* similar to
- :meth:`itermonthdates`. Days returned will simply be day numbers.
+ :meth:`itermonthdates`, but not restricted by the :class:`datetime.date`
+ range. Days returned will simply be day of the month numbers. For the
+ days outside of the specified month, the day number is ``0``.
+
+
+ .. method:: itermonthdays2(year, month)
+
+ Return an iterator for the month *month* in the year *year* similar to
+ :meth:`itermonthdates`, but not restricted by the :class:`datetime.date`
+ range. Days returned will be tuples consisting of a day of the month
+ number and a week day number.
+
+
+ .. method:: itermonthdays3(year, month)
+
+ Return an iterator for the month *month* in the year *year* similar to
+ :meth:`itermonthdates`, but not restricted by the :class:`datetime.date`
+ range. Days returned will be tuples consisting of a year, a month and a day
+ of the month numbers.
+
+ .. versionadded:: 3.7
+
+
+ .. method:: itermonthdays4(year, month)
+
+ Return an iterator for the month *month* in the year *year* similar to
+ :meth:`itermonthdates`, but not restricted by the :class:`datetime.date`
+ range. Days returned will be tuples consisting of a year, a month, a day
+ of the month, and a day of the week numbers.
+
+ .. versionadded:: 3.7
.. method:: monthdatescalendar(year, month)
diff --git a/Doc/library/codecs.rst b/Doc/library/codecs.rst
index 0ecd89ba75b..6e249ecf2b1 100644
--- a/Doc/library/codecs.rst
+++ b/Doc/library/codecs.rst
@@ -554,19 +554,19 @@ define in order to be compatible with the Python codec registry.
if necessary, to reset the encoder and to get the output.
-.. method:: IncrementalEncoder.getstate()
+ .. method:: getstate()
- Return the current state of the encoder which must be an integer. The
- implementation should make sure that ``0`` is the most common state. (States
- that are more complicated than integers can be converted into an integer by
- marshaling/pickling the state and encoding the bytes of the resulting string
- into an integer).
+ Return the current state of the encoder which must be an integer. The
+ implementation should make sure that ``0`` is the most common
+ state. (States that are more complicated than integers can be converted
+ into an integer by marshaling/pickling the state and encoding the bytes
+ of the resulting string into an integer).
-.. method:: IncrementalEncoder.setstate(state)
+ .. method:: setstate(state)
- Set the state of the encoder to *state*. *state* must be an encoder state
- returned by :meth:`getstate`.
+ Set the state of the encoder to *state*. *state* must be an encoder state
+ returned by :meth:`getstate`.
.. _incremental-decoder-objects:
@@ -802,7 +802,7 @@ The design is such that one can use the factory functions returned by the
:func:`lookup` function to construct the instance.
-.. class:: StreamReaderWriter(stream, Reader, Writer, errors)
+.. class:: StreamReaderWriter(stream, Reader, Writer, errors='strict')
Creates a :class:`StreamReaderWriter` instance. *stream* must be a file-like
object. *Reader* and *Writer* must be factory functions or classes providing the
@@ -826,7 +826,7 @@ The design is such that one can use the factory functions returned by the
:func:`lookup` function to construct the instance.
-.. class:: StreamRecoder(stream, encode, decode, Reader, Writer, errors)
+.. class:: StreamRecoder(stream, encode, decode, Reader, Writer, errors='strict')
Creates a :class:`StreamRecoder` instance which implements a two-way conversion:
*encode* and *decode* work on the frontend — the data visible to
diff --git a/Doc/library/collections.abc.rst b/Doc/library/collections.abc.rst
index 58b03b9bd76..60154532094 100644
--- a/Doc/library/collections.abc.rst
+++ b/Doc/library/collections.abc.rst
@@ -107,7 +107,12 @@ ABC Inherits from Abstract Methods Mixin
.. class:: Iterable
ABC for classes that provide the :meth:`__iter__` method.
- See also the definition of :term:`iterable`.
+
+ Checking ``isinstance(obj, Iterable)`` detects classes that are registered
+ as :class:`Iterable` or that have an :meth:`__iter__` method, but it does
+ not detect classes that iterate with the :meth:`__getitem__` method.
+ The only reliable way to determine whether an object is :term:`iterable`
+ is to call ``iter(obj)``.
.. class:: Collection
diff --git a/Doc/library/collections.rst b/Doc/library/collections.rst
index d6d2056dfc4..cda829694a3 100644
--- a/Doc/library/collections.rst
+++ b/Doc/library/collections.rst
@@ -763,7 +763,7 @@ Named tuples assign meaning to each position in a tuple and allow for more reada
self-documenting code. They can be used wherever regular tuples are used, and
they add the ability to access fields by name instead of position index.
-.. function:: namedtuple(typename, field_names, *, verbose=False, rename=False, module=None)
+.. function:: namedtuple(typename, field_names, *, rename=False, module=None)
Returns a new tuple subclass named *typename*. The new subclass is used to
create tuple-like objects that have fields accessible by attribute lookup as
@@ -786,10 +786,6 @@ they add the ability to access fields by name instead of position index.
converted to ``['abc', '_1', 'ghi', '_3']``, eliminating the keyword
``def`` and the duplicate fieldname ``abc``.
- If *verbose* is true, the class definition is printed after it is
- built. This option is outdated; instead, it is simpler to print the
- :attr:`_source` attribute.
-
If *module* is defined, the ``__module__`` attribute of the named tuple is
set to that value.
@@ -806,6 +802,9 @@ they add the ability to access fields by name instead of position index.
.. versionchanged:: 3.6
Added the *module* parameter.
+ .. versionchanged:: 3.7
+ Remove the *verbose* parameter and the :attr:`_source` attribute.
+
.. doctest::
:options: +NORMALIZE_WHITESPACE
@@ -878,15 +877,6 @@ field names, the method and attribute names start with an underscore.
>>> for partnum, record in inventory.items():
... inventory[partnum] = record._replace(price=newprices[partnum], timestamp=time.now())
-.. attribute:: somenamedtuple._source
-
- A string with the pure Python source code used to create the named
- tuple class. The source makes the named tuple self-documenting.
- It can be printed, executed using :func:`exec`, or saved to a file
- and imported.
-
- .. versionadded:: 3.3
-
.. attribute:: somenamedtuple._fields
Tuple of strings listing the field names. Useful for introspection
diff --git a/Doc/library/concurrency.rst b/Doc/library/concurrency.rst
index 0de281bd149..826bf86d081 100644
--- a/Doc/library/concurrency.rst
+++ b/Doc/library/concurrency.rst
@@ -26,6 +26,6 @@ The following are support modules for some of the above services:
.. toctree::
- dummy_threading.rst
_thread.rst
_dummy_thread.rst
+ dummy_threading.rst
diff --git a/Doc/library/concurrent.futures.rst b/Doc/library/concurrent.futures.rst
index d85576b8bed..d4b698e1c17 100644
--- a/Doc/library/concurrent.futures.rst
+++ b/Doc/library/concurrent.futures.rst
@@ -124,11 +124,17 @@ And::
executor.submit(wait_on_future)
-.. class:: ThreadPoolExecutor(max_workers=None, thread_name_prefix='')
+.. class:: ThreadPoolExecutor(max_workers=None, thread_name_prefix='', initializer=None, initargs=())
An :class:`Executor` subclass that uses a pool of at most *max_workers*
threads to execute calls asynchronously.
+ *initializer* is an optional callable that is called at the start of
+ each worker thread; *initargs* is a tuple of arguments passed to the
+ initializer. Should *initializer* raise an exception, all currently
+ pending jobs will raise a :exc:`~concurrent.futures.thread.BrokenThreadPool`,
+ as well any attempt to submit more jobs to the pool.
+
.. versionchanged:: 3.5
If *max_workers* is ``None`` or
not given, it will default to the number of processors on the machine,
@@ -142,6 +148,10 @@ And::
control the threading.Thread names for worker threads created by
the pool for easier debugging.
+ .. versionchanged:: 3.7
+ Added the *initializer* and *initargs* arguments.
+
+
.. _threadpoolexecutor-example:
ThreadPoolExecutor Example
@@ -191,13 +201,22 @@ that :class:`ProcessPoolExecutor` will not work in the interactive interpreter.
Calling :class:`Executor` or :class:`Future` methods from a callable submitted
to a :class:`ProcessPoolExecutor` will result in deadlock.
-.. class:: ProcessPoolExecutor(max_workers=None)
+.. class:: ProcessPoolExecutor(max_workers=None, mp_context=None, initializer=None, initargs=())
An :class:`Executor` subclass that executes calls asynchronously using a pool
of at most *max_workers* processes. If *max_workers* is ``None`` or not
given, it will default to the number of processors on the machine.
If *max_workers* is lower or equal to ``0``, then a :exc:`ValueError`
will be raised.
+ *mp_context* can be a multiprocessing context or None. It will be used to
+ launch the workers. If *mp_context* is ``None`` or not given, the default
+ multiprocessing context is used.
+
+ *initializer* is an optional callable that is called at the start of
+ each worker process; *initargs* is a tuple of arguments passed to the
+ initializer. Should *initializer* raise an exception, all currently
+ pending jobs will raise a :exc:`~concurrent.futures.thread.BrokenThreadPool`,
+ as well any attempt to submit more jobs to the pool.
.. versionchanged:: 3.3
When one of the worker processes terminates abruptly, a
@@ -205,6 +224,12 @@ to a :class:`ProcessPoolExecutor` will result in deadlock.
was undefined but operations on the executor or its futures would often
freeze or deadlock.
+ .. versionchanged:: 3.7
+ The *mp_context* argument was added to allow users to control the
+ start_method for worker processes created by the pool.
+
+ Added the *initializer* and *initargs* arguments.
+
.. _processpoolexecutor-example:
@@ -425,13 +450,31 @@ Exception classes
Raised when a future operation exceeds the given timeout.
+.. exception:: BrokenExecutor
+
+ Derived from :exc:`RuntimeError`, this exception class is raised
+ when an executor is broken for some reason, and cannot be used
+ to submit or execute new tasks.
+
+ .. versionadded:: 3.7
+
+.. currentmodule:: concurrent.futures.thread
+
+.. exception:: BrokenThreadPool
+
+ Derived from :exc:`~concurrent.futures.BrokenExecutor`, this exception
+ class is raised when one of the workers of a :class:`ThreadPoolExecutor`
+ has failed initializing.
+
+ .. versionadded:: 3.7
+
.. currentmodule:: concurrent.futures.process
.. exception:: BrokenProcessPool
- Derived from :exc:`RuntimeError`, this exception class is raised when
- one of the workers of a :class:`ProcessPoolExecutor` has terminated
- in a non-clean fashion (for example, if it was killed from the outside).
+ Derived from :exc:`~concurrent.futures.BrokenExecutor` (formerly
+ :exc:`RuntimeError`), this exception class is raised when one of the
+ workers of a :class:`ProcessPoolExecutor` has terminated in a non-clean
+ fashion (for example, if it was killed from the outside).
.. versionadded:: 3.3
-
diff --git a/Doc/library/configparser.rst b/Doc/library/configparser.rst
index 61eab4e6a4b..dd8257720b7 100644
--- a/Doc/library/configparser.rst
+++ b/Doc/library/configparser.rst
@@ -944,6 +944,11 @@ ConfigParser Objects
.. versionchanged:: 3.5
The *converters* argument was added.
+ .. versionchanged:: 3.7
+ The *defaults* argument is read with :meth:`read_dict()`,
+ providing consistent behavior across the parser: non-string
+ keys and values are implicitly converted to strings.
+
.. method:: defaults()
@@ -990,7 +995,8 @@ ConfigParser Objects
Attempt to read and parse a list of filenames, returning a list of
filenames which were successfully parsed.
- If *filenames* is a string or :term:`path-like object`, it is treated as
+ If *filenames* is a string, a :class:`bytes` object or a
+ :term:`path-like object`, it is treated as
a single filename. If a file named in *filenames* cannot be opened, that
file will be ignored. This is designed so that you can specify a list of
potential configuration file locations (for example, the current
@@ -1017,6 +1023,9 @@ ConfigParser Objects
.. versionadded:: 3.6.1
The *filenames* parameter accepts a :term:`path-like object`.
+ .. versionadded:: 3.7
+ The *filenames* parameter accepts a :class:`bytes` object.
+
.. method:: read_file(f, source=None)
@@ -1208,8 +1217,10 @@ RawConfigParser Objects
default_section=configparser.DEFAULTSECT[, \
interpolation])
- Legacy variant of the :class:`ConfigParser` with interpolation disabled
- by default and unsafe ``add_section`` and ``set`` methods.
+ Legacy variant of the :class:`ConfigParser`. It has interpolation
+ disabled by default and allows for non-string section names, option
+ names, and values via its unsafe ``add_section`` and ``set`` methods,
+ as well as the legacy ``defaults=`` keyword argument handling.
.. note::
Consider using :class:`ConfigParser` instead which checks types of
@@ -1325,4 +1336,3 @@ Exceptions
.. [1] Config parsers allow for heavy customization. If you are interested in
changing the behaviour outlined by the footnote reference, consult the
`Customizing Parser Behaviour`_ section.
-
diff --git a/Doc/library/crypt.rst b/Doc/library/crypt.rst
index dbd42740384..dd62cb32b9d 100644
--- a/Doc/library/crypt.rst
+++ b/Doc/library/crypt.rst
@@ -41,17 +41,24 @@ are available on all platforms):
.. data:: METHOD_SHA512
A Modular Crypt Format method with 16 character salt and 86 character
- hash. This is the strongest method.
+ hash based on the SHA-512 hash function. This is the strongest method.
.. data:: METHOD_SHA256
Another Modular Crypt Format method with 16 character salt and 43
- character hash.
+ character hash based on the SHA-256 hash function.
+
+.. data:: METHOD_BLOWFISH
+
+ Another Modular Crypt Format method with 22 character salt and 31
+ character hash based on the Blowfish cipher.
+
+ .. versionadded:: 3.7
.. data:: METHOD_MD5
Another Modular Crypt Format method with 8 character salt and 22
- character hash.
+ character hash based on the MD5 hash function.
.. data:: METHOD_CRYPT
@@ -109,19 +116,29 @@ The :mod:`crypt` module defines the following functions:
Accept ``crypt.METHOD_*`` values in addition to strings for *salt*.
-.. function:: mksalt(method=None)
+.. function:: mksalt(method=None, *, rounds=None)
Return a randomly generated salt of the specified method. If no
*method* is given, the strongest method available as returned by
:func:`methods` is used.
- The return value is a string either of 2 characters in length for
- ``crypt.METHOD_CRYPT``, or 19 characters starting with ``$digit$`` and
- 16 random characters from the set ``[./a-zA-Z0-9]``, suitable for
- passing as the *salt* argument to :func:`crypt`.
+ The return value is a string suitable for passing as the *salt* argument
+ to :func:`crypt`.
+
+ *rounds* specifies the number of rounds for ``METHOD_SHA256``,
+ ``METHOD_SHA512`` and ``METHOD_BLOWFISH``.
+ For ``METHOD_SHA256`` and ``METHOD_SHA512`` it must be an integer between
+ ``1000`` and ``999_999_999``, the default is ``5000``. For
+ ``METHOD_BLOWFISH`` it must be a power of two between ``16`` (2\ :sup:`4`)
+ and ``2_147_483_648`` (2\ :sup:`31`), the default is ``4096``
+ (2\ :sup:`12`).
.. versionadded:: 3.3
+ .. versionchanged:: 3.7
+ Added the *rounds* parameter.
+
+
Examples
--------
diff --git a/Doc/library/csv.rst b/Doc/library/csv.rst
index 43714f74792..e1290d4c9b5 100644
--- a/Doc/library/csv.rst
+++ b/Doc/library/csv.rst
@@ -172,7 +172,7 @@ The :mod:`csv` module defines the following classes:
A short usage example::
>>> import csv
- >>> with open('names.csv') as csvfile:
+ >>> with open('names.csv', newline='') as csvfile:
... reader = csv.DictReader(csvfile)
... for row in reader:
... print(row['first_name'], row['last_name'])
@@ -211,7 +211,7 @@ The :mod:`csv` module defines the following classes:
import csv
- with open('names.csv', 'w') as csvfile:
+ with open('names.csv', 'w', newline='') as csvfile:
fieldnames = ['first_name', 'last_name']
writer = csv.DictWriter(csvfile, fieldnames=fieldnames)
@@ -270,7 +270,7 @@ The :mod:`csv` module defines the following classes:
An example for :class:`Sniffer` use::
- with open('example.csv') as csvfile:
+ with open('example.csv', newline='') as csvfile:
dialect = csv.Sniffer().sniff(csvfile.read(1024))
csvfile.seek(0)
reader = csv.reader(csvfile, dialect)
diff --git a/Doc/library/curses.ascii.rst b/Doc/library/curses.ascii.rst
index b6ac2517335..04b2a260af0 100644
--- a/Doc/library/curses.ascii.rst
+++ b/Doc/library/curses.ascii.rst
@@ -176,14 +176,12 @@ C library:
Checks for a non-ASCII character (ordinal values 0x80 and above).
-These functions accept either integers or strings; when the argument is a
+These functions accept either integers or single-character strings; when the argument is a
string, it is first converted using the built-in function :func:`ord`.
-Note that all these functions check ordinal bit values derived from the first
+Note that all these functions check ordinal bit values derived from the
character of the string you pass in; they do not actually know anything about
-the host machine's character encoding. For functions that know about the
-character encoding (and handle internationalization properly) see the
-:mod:`string` module.
+the host machine's character encoding.
The following two functions take either a single-character string or integer
byte value; they return a value of the same type.
diff --git a/Doc/library/curses.panel.rst b/Doc/library/curses.panel.rst
index c99c37a5651..d770c03c837 100644
--- a/Doc/library/curses.panel.rst
+++ b/Doc/library/curses.panel.rst
@@ -74,7 +74,7 @@ Panel objects have the following methods:
.. method:: Panel.hidden()
- Returns true if the panel is hidden (not visible), false otherwise.
+ Returns ``True`` if the panel is hidden (not visible), ``False`` otherwise.
.. method:: Panel.hide()
diff --git a/Doc/library/curses.rst b/Doc/library/curses.rst
index 2786e51a7e9..13717f7b35e 100644
--- a/Doc/library/curses.rst
+++ b/Doc/library/curses.rst
@@ -19,6 +19,14 @@ for Windows, DOS, and possibly other systems as well. This extension module is
designed to match the API of ncurses, an open-source curses library hosted on
Linux and the BSD variants of Unix.
+.. note::
+
+ Whenever the documentation mentions a *character* it can be specified
+ as an integer, a one-character Unicode string or a one-byte byte string.
+
+ Whenever the documentation mentions a *character string* it can be specified
+ as a Unicode string or a byte string.
+
.. note::
Since version 5.4, the ncurses library decides how to interpret non-ASCII data
@@ -104,8 +112,8 @@ The module :mod:`curses` defines the following functions:
.. function:: color_content(color_number)
Return the intensity of the red, green, and blue (RGB) components in the color
- *color_number*, which must be between ``0`` and :const:`COLORS`. A 3-tuple is
- returned, containing the R,G,B values for the given color, which will be between
+ *color_number*, which must be between ``0`` and :const:`COLORS`. Return a 3-tuple,
+ containing the R,G,B values for the given color, which will be between
``0`` (no component) and ``1000`` (maximum amount of component).
@@ -119,9 +127,9 @@ The module :mod:`curses` defines the following functions:
.. function:: curs_set(visibility)
- Set the cursor state. *visibility* can be set to 0, 1, or 2, for invisible,
- normal, or very visible. If the terminal supports the visibility requested, the
- previous cursor state is returned; otherwise, an exception is raised. On many
+ Set the cursor state. *visibility* can be set to ``0``, ``1``, or ``2``, for invisible,
+ normal, or very visible. If the terminal supports the visibility requested, return the
+ previous cursor state; otherwise raise an exception. On many
terminals, the "visible" mode is an underline cursor and the "very visible" mode
is a block cursor.
@@ -154,12 +162,12 @@ The module :mod:`curses` defines the following functions:
representing the desired next state. The :func:`doupdate` ground updates the
physical screen to match the virtual screen.
- The virtual screen may be updated by a :meth:`noutrefresh` call after write
- operations such as :meth:`addstr` have been performed on a window. The normal
- :meth:`refresh` call is simply :meth:`noutrefresh` followed by :func:`doupdate`;
+ The virtual screen may be updated by a :meth:`~window.noutrefresh` call after write
+ operations such as :meth:`~window.addstr` have been performed on a window. The normal
+ :meth:`~window.refresh` call is simply :meth:`!noutrefresh` followed by :func:`!doupdate`;
if you have to update multiple windows, you can speed performance and perhaps
- reduce screen flicker by issuing :meth:`noutrefresh` calls on all windows,
- followed by a single :func:`doupdate`.
+ reduce screen flicker by issuing :meth:`!noutrefresh` calls on all windows,
+ followed by a single :func:`!doupdate`.
.. function:: echo()
@@ -175,7 +183,7 @@ The module :mod:`curses` defines the following functions:
.. function:: erasechar()
- Return the user's current erase character. Under Unix operating systems this
+ Return the user's current erase character as a one-byte bytes object. Under Unix operating systems this
is a property of the controlling tty of the curses program, and is not set by
the curses library itself.
@@ -183,9 +191,9 @@ The module :mod:`curses` defines the following functions:
.. function:: filter()
The :func:`.filter` routine, if used, must be called before :func:`initscr` is
- called. The effect is that, during those calls, :envvar:`LINES` is set to 1; the
- capabilities clear, cup, cud, cud1, cuu1, cuu, vpa are disabled; and the home
- string is set to the value of cr. The effect is that the cursor is confined to
+ called. The effect is that, during those calls, :envvar:`LINES` is set to ``1``; the
+ capabilities ``clear``, ``cup``, ``cud``, ``cud1``, ``cuu1``, ``cuu``, ``vpa`` are disabled; and the ``home``
+ string is set to the value of ``cr``. The effect is that the cursor is confined to
the current line, and so are screen updates. This may be used for enabling
character-at-a-time line editing without touching the rest of the screen.
@@ -205,7 +213,7 @@ The module :mod:`curses` defines the following functions:
.. function:: getmouse()
- After :meth:`getch` returns :const:`KEY_MOUSE` to signal a mouse event, this
+ After :meth:`~window.getch` returns :const:`KEY_MOUSE` to signal a mouse event, this
method should be call to retrieve the queued mouse event, represented as a
5-tuple ``(id, x, y, z, bstate)``. *id* is an ID value used to distinguish
multiple devices, and *x*, *y*, *z* are the event's coordinates. (*z* is
@@ -219,8 +227,8 @@ The module :mod:`curses` defines the following functions:
.. function:: getsyx()
- Return the current coordinates of the virtual screen cursor in y and x. If
- leaveok is currently true, then -1,-1 is returned.
+ Return the current coordinates of the virtual screen cursor as a tuple
+ ``(y, x)``. If :meth:`leaveok ` is currently ``True``, then return ``(-1, -1)``.
.. function:: getwin(file)
@@ -260,7 +268,7 @@ The module :mod:`curses` defines the following functions:
Used for half-delay mode, which is similar to cbreak mode in that characters
typed by the user are immediately available to the program. However, after
- blocking for *tenths* tenths of seconds, an exception is raised if nothing has
+ blocking for *tenths* tenths of seconds, raise an exception if nothing has
been typed. The value of *tenths* must be a number between ``1`` and ``255``. Use
:func:`nocbreak` to leave half-delay mode.
@@ -273,7 +281,7 @@ The module :mod:`curses` defines the following functions:
:const:`COLORS`. Each of *r*, *g*, *b*, must be a value between ``0`` and
``1000``. When :func:`init_color` is used, all occurrences of that color on the
screen immediately change to the new definition. This function is a no-op on
- most terminals; it is active only if :func:`can_change_color` returns ``1``.
+ most terminals; it is active only if :func:`can_change_color` returns ``True``.
.. function:: init_pair(pair_number, fg, bg)
@@ -313,32 +321,32 @@ The module :mod:`curses` defines the following functions:
.. function:: keyname(k)
- Return the name of the key numbered *k*. The name of a key generating printable
+ Return the name of the key numbered *k* as a bytes object. The name of a key generating printable
ASCII character is the key's character. The name of a control-key combination
- is a two-character string consisting of a caret followed by the corresponding
+ is a two-byte bytes object consisting of a caret (``b'^'``) followed by the corresponding
printable ASCII character. The name of an alt-key combination (128--255) is a
- string consisting of the prefix 'M-' followed by the name of the corresponding
+ bytes object consisting of the prefix ``b'M-'`` followed by the name of the corresponding
ASCII character.
.. function:: killchar()
- Return the user's current line kill character. Under Unix operating systems
+ Return the user's current line kill character as a one-byte bytes object. Under Unix operating systems
this is a property of the controlling tty of the curses program, and is not set
by the curses library itself.
.. function:: longname()
- Return a string containing the terminfo long name field describing the current
+ Return a bytes object containing the terminfo long name field describing the current
terminal. The maximum length of a verbose description is 128 characters. It is
defined only after the call to :func:`initscr`.
-.. function:: meta(yes)
+.. function:: meta(flag)
- If *yes* is 1, allow 8-bit characters to be input. If *yes* is 0, allow only
- 7-bit chars.
+ If *flag* is ``True``, allow 8-bit characters to be input. If
+ *flag* is ``False``, allow only 7-bit chars.
.. function:: mouseinterval(interval)
@@ -352,7 +360,7 @@ The module :mod:`curses` defines the following functions:
Set the mouse events to be reported, and return a tuple ``(availmask,
oldmask)``. *availmask* indicates which of the specified mouse events can be
- reported; on complete failure it returns 0. *oldmask* is the previous value of
+ reported; on complete failure it returns ``0``. *oldmask* is the previous value of
the given window's mouse event mask. If this function is never called, no mouse
events are ever reported.
@@ -365,13 +373,13 @@ The module :mod:`curses` defines the following functions:
.. function:: newpad(nlines, ncols)
Create and return a pointer to a new pad data structure with the given number
- of lines and columns. A pad is returned as a window object.
+ of lines and columns. Return a pad as a window object.
A pad is like a window, except that it is not restricted by the screen size, and
is not necessarily associated with a particular part of the screen. Pads can be
used when a large window is needed, and only a part of the window will be on the
screen at one time. Automatic refreshes of pads (such as from scrolling or
- echoing of input) do not occur. The :meth:`refresh` and :meth:`noutrefresh`
+ echoing of input) do not occur. The :meth:`~window.refresh` and :meth:`~window.noutrefresh`
methods of a pad require 6 arguments to specify the part of the pad to be
displayed and the location on the screen to be used for the display. The
arguments are *pminrow*, *pmincol*, *sminrow*, *smincol*, *smaxrow*, *smaxcol*; the *p*
@@ -419,9 +427,9 @@ The module :mod:`curses` defines the following functions:
.. function:: noqiflush()
- When the :func:`noqiflush` routine is used, normal flush of input and output queues
- associated with the INTR, QUIT and SUSP characters will not be done. You may
- want to call :func:`noqiflush` in a signal handler if you want output to
+ When the :func:`!noqiflush` routine is used, normal flush of input and output queues
+ associated with the ``INTR``, ``QUIT`` and ``SUSP`` characters will not be done. You may
+ want to call :func:`!noqiflush` in a signal handler if you want output to
continue as though the interrupt had not occurred, after the handler exits.
@@ -442,14 +450,14 @@ The module :mod:`curses` defines the following functions:
:func:`color_pair` is the counterpart to this function.
-.. function:: putp(string)
+.. function:: putp(str)
Equivalent to ``tputs(str, 1, putchar)``; emit the value of a specified
terminfo capability for the current terminal. Note that the output of :func:`putp`
always goes to standard output.
-.. function:: qiflush( [flag] )
+.. function:: qiflush([flag])
If *flag* is ``False``, the effect is the same as calling :func:`noqiflush`. If
*flag* is ``True``, or no argument is provided, the queues will be flushed when
@@ -486,7 +494,7 @@ The module :mod:`curses` defines the following functions:
Backend function used by :func:`resizeterm`, performing most of the work;
when resizing the windows, :func:`resize_term` blank-fills the areas that are
extended. The calling application should fill in these areas with
- appropriate data. The :func:`resize_term` function attempts to resize all
+ appropriate data. The :func:`!resize_term` function attempts to resize all
windows. However, due to the calling convention of pads, it is not possible
to resize these without additional interaction with the application.
@@ -506,16 +514,17 @@ The module :mod:`curses` defines the following functions:
.. function:: setsyx(y, x)
- Set the virtual screen cursor to *y*, *x*. If *y* and *x* are both -1, then
- leaveok is set.
+ Set the virtual screen cursor to *y*, *x*. If *y* and *x* are both ``-1``, then
+ :meth:`leaveok ` is set ``True``.
-.. function:: setupterm([termstr, fd])
+.. function:: setupterm(term=None, fd=-1)
- Initialize the terminal. *termstr* is a string giving the terminal name; if
- omitted, the value of the :envvar:`TERM` environment variable will be used. *fd* is the
+ Initialize the terminal. *term* is a string giving
+ the terminal name, or ``None``; if omitted or ``None``, the value of the
+ :envvar:`TERM` environment variable will be used. *fd* is the
file descriptor to which any initialization sequences will be sent; if not
- supplied, the file descriptor for ``sys.stdout`` will be used.
+ supplied or ``-1``, the file descriptor for ``sys.stdout`` will be used.
.. function:: start_color()
@@ -540,13 +549,14 @@ The module :mod:`curses` defines the following functions:
.. function:: termname()
- Return the value of the environment variable :envvar:`TERM`, truncated to 14 characters.
+ Return the value of the environment variable :envvar:`TERM`, as a bytes object,
+ truncated to 14 characters.
.. function:: tigetflag(capname)
Return the value of the Boolean capability corresponding to the terminfo
- capability name *capname*. The value ``-1`` is returned if *capname* is not a
+ capability name *capname* as an integer. Return the value ``-1`` if *capname* is not a
Boolean capability, or ``0`` if it is canceled or absent from the terminal
description.
@@ -554,7 +564,7 @@ The module :mod:`curses` defines the following functions:
.. function:: tigetnum(capname)
Return the value of the numeric capability corresponding to the terminfo
- capability name *capname*. The value ``-2`` is returned if *capname* is not a
+ capability name *capname* as an integer. Return the value ``-2`` if *capname* is not a
numeric capability, or ``-1`` if it is canceled or absent from the terminal
description.
@@ -562,13 +572,14 @@ The module :mod:`curses` defines the following functions:
.. function:: tigetstr(capname)
Return the value of the string capability corresponding to the terminfo
- capability name *capname*. ``None`` is returned if *capname* is not a string
- capability, or is canceled or absent from the terminal description.
+ capability name *capname* as a bytes object. Return ``None`` if *capname*
+ is not a terminfo "string capability", or is canceled or absent from the
+ terminal description.
.. function:: tparm(str[, ...])
- Instantiate the string *str* with the supplied parameters, where *str* should
+ Instantiate the bytes object *str* with the supplied parameters, where *str* should
be a parameterized string obtained from the terminfo database. E.g.
``tparm(tigetstr("cup"), 5, 3)`` could result in ``b'\033[6;4H'``, the exact
result depending on terminal type.
@@ -588,18 +599,18 @@ The module :mod:`curses` defines the following functions:
.. function:: unctrl(ch)
- Return a string which is a printable representation of the character *ch*.
- Control characters are displayed as a caret followed by the character, for
- example as ``^C``. Printing characters are left as they are.
+ Return a bytes object which is a printable representation of the character *ch*.
+ Control characters are represented as a caret followed by the character, for
+ example as ``b'^C'``. Printing characters are left as they are.
.. function:: ungetch(ch)
- Push *ch* so the next :meth:`getch` will return it.
+ Push *ch* so the next :meth:`~window.getch` will return it.
.. note::
- Only one *ch* can be pushed before :meth:`getch` is called.
+ Only one *ch* can be pushed before :meth:`!getch` is called.
.. function:: update_lines_cols()
@@ -611,11 +622,11 @@ The module :mod:`curses` defines the following functions:
.. function:: unget_wch(ch)
- Push *ch* so the next :meth:`get_wch` will return it.
+ Push *ch* so the next :meth:`~window.get_wch` will return it.
.. note::
- Only one *ch* can be pushed before :meth:`get_wch` is called.
+ Only one *ch* can be pushed before :meth:`!get_wch` is called.
.. versionadded:: 3.3
@@ -640,7 +651,7 @@ The module :mod:`curses` defines the following functions:
Allow use of default values for colors on terminals supporting this feature. Use
this to support transparency in your application. The default color is assigned
- to the color number -1. After calling this function, ``init_pair(x,
+ to the color number ``-1``. After calling this function, ``init_pair(x,
curses.COLOR_RED, -1)`` initializes, for instance, color pair *x* to a red
foreground color on the default background.
@@ -652,7 +663,7 @@ The module :mod:`curses` defines the following functions:
this function will restore the terminal to a sane state before re-raising the
exception and generating a traceback. The callable object *func* is then passed
the main window 'stdscr' as its first argument, followed by any other arguments
- passed to :func:`wrapper`. Before calling *func*, :func:`wrapper` turns on
+ passed to :func:`!wrapper`. Before calling *func*, :func:`!wrapper` turns on
cbreak mode, turns off echo, enables the terminal keypad, and initializes colors
if the terminal has color support. On exit (whether normally or by exception)
it restores cooked mode, turns on echo, and disables the terminal keypad.
@@ -670,13 +681,6 @@ the following methods and attributes:
.. method:: window.addch(ch[, attr])
window.addch(y, x, ch[, attr])
- .. note::
-
- A *character* means a C character (an ASCII code), rather than a Python
- character (a string of length 1). (This note is true whenever the
- documentation mentions a character.) The built-in :func:`ord` is handy for
- conveying strings to codes.
-
Paint character *ch* at ``(y, x)`` with attributes *attr*, overwriting any
character previously painter at that location. By default, the character
position and attributes are the current settings for the window object.
@@ -685,15 +689,16 @@ the following methods and attributes:
.. method:: window.addnstr(str, n[, attr])
window.addnstr(y, x, str, n[, attr])
- Paint at most *n* characters of the string *str* at ``(y, x)`` with attributes
+ Paint at most *n* characters of the character string *str* at
+ ``(y, x)`` with attributes
*attr*, overwriting anything previously on the display.
.. method:: window.addstr(str[, attr])
window.addstr(y, x, str[, attr])
- Paint the string *str* at ``(y, x)`` with attributes *attr*, overwriting
- anything previously on the display.
+ Paint the character string *str* at ``(y, x)`` with attributes
+ *attr*, overwriting anything previously on the display.
.. method:: window.attroff(attr)
@@ -710,8 +715,8 @@ the following methods and attributes:
.. method:: window.attrset(attr)
- Set the "background" set of attributes to *attr*. This set is initially 0 (no
- attributes).
+ Set the "background" set of attributes to *attr*. This set is initially
+ ``0`` (no attributes).
.. method:: window.bkgd(ch[, attr])
@@ -741,8 +746,7 @@ the following methods and attributes:
Draw a border around the edges of the window. Each parameter specifies the
character to use for a specific part of the border; see the table below for more
- details. The characters can be specified as integers or as one-character
- strings.
+ details.
.. note::
@@ -783,11 +787,11 @@ the following methods and attributes:
window.chgat(y, x, num, attr)
Set the attributes of *num* characters at the current cursor position, or at
- position ``(y, x)`` if supplied. If no value of *num* is given or *num* = -1,
- the attribute will be set on all the characters to the end of the line. This
- function does not move the cursor. The changed line will be touched using the
- :meth:`touchline` method so that the contents will be redisplayed by the next
- window refresh.
+ position ``(y, x)`` if supplied. If *num* is not given or is ``-1``,
+ the attribute will be set on all the characters to the end of the line. This
+ function moves cursor to position ``(y, x)`` if supplied. The changed line
+ will be touched using the :meth:`touchline` method so that the contents will
+ be redisplayed by the next window refresh.
.. method:: window.clear()
@@ -796,9 +800,9 @@ the following methods and attributes:
call to :meth:`refresh`.
-.. method:: window.clearok(yes)
+.. method:: window.clearok(flag)
- If *yes* is 1, the next call to :meth:`refresh` will clear the window
+ If *flag* is ``True``, the next call to :meth:`refresh` will clear the window
completely.
@@ -880,15 +884,16 @@ the following methods and attributes:
.. method:: window.getch([y, x])
Get a character. Note that the integer returned does *not* have to be in ASCII
- range: function keys, keypad keys and so on return numbers higher than 256. In
- no-delay mode, -1 is returned if there is no input, else :func:`getch` waits
- until a key is pressed.
+ range: function keys, keypad keys and so on are represented by numbers higher
+ than 255. In no-delay mode, return ``-1`` if there is no input, otherwise
+ wait until a key is pressed.
.. method:: window.get_wch([y, x])
Get a wide character. Return a character for most keys, or an integer for
function keys, keypad keys, and other special keys.
+ In no-delay mode, raise an exception if there is no input.
.. versionadded:: 3.3
@@ -897,7 +902,7 @@ the following methods and attributes:
Get a character, returning a string instead of an integer, as :meth:`getch`
does. Function keys, keypad keys and other special keys return a multibyte
- string containing the key name. In no-delay mode, an exception is raised if
+ string containing the key name. In no-delay mode, raise an exception if
there is no input.
@@ -909,13 +914,16 @@ the following methods and attributes:
.. method:: window.getparyx()
Return the beginning coordinates of this window relative to its parent window
- into two integer variables y and x. Return ``-1, -1`` if this window has no
+ as a tuple ``(y, x)``. Return ``(-1, -1)`` if this window has no
parent.
-.. method:: window.getstr([y, x])
+.. method:: window.getstr()
+ window.getstr(n)
+ window.getstr(y, x)
+ window.getstr(y, x, n)
- Read a string from the user, with primitive line editing capacity.
+ Read a bytes object from the user, with primitive line editing capacity.
.. method:: window.getyx()
@@ -939,9 +947,9 @@ the following methods and attributes:
insert/delete is enabled by default.
-.. method:: window.idlok(yes)
+.. method:: window.idlok(flag)
- If called with *yes* equal to 1, :mod:`curses` will try and use hardware line
+ If *flag* is ``True``, :mod:`curses` will try and use hardware line
editing facilities. Otherwise, line insertion/deletion are disabled.
@@ -1003,7 +1011,7 @@ the following methods and attributes:
.. method:: window.instr([n])
window.instr(y, x[, n])
- Return a string of characters, extracted from the window starting at the
+ Return a bytes object of characters, extracted from the window starting at the
current cursor position, or at *y*, *x* if specified. Attributes are stripped
from the characters. If *n* is specified, :meth:`instr` returns a string
at most *n* characters long (exclusive of the trailing NUL).
@@ -1022,20 +1030,20 @@ the following methods and attributes:
:meth:`refresh`; otherwise return ``False``.
-.. method:: window.keypad(yes)
+.. method:: window.keypad(flag)
- If *yes* is 1, escape sequences generated by some keys (keypad, function keys)
- will be interpreted by :mod:`curses`. If *yes* is 0, escape sequences will be
+ If *flag* is ``True``, escape sequences generated by some keys (keypad, function keys)
+ will be interpreted by :mod:`curses`. If *flag* is ``False``, escape sequences will be
left as is in the input stream.
-.. method:: window.leaveok(yes)
+.. method:: window.leaveok(flag)
- If *yes* is 1, cursor is left where it is on update, instead of being at "cursor
+ If *flag* is ``True``, cursor is left where it is on update, instead of being at "cursor
position." This reduces cursor movement where possible. If possible the cursor
will be made invisible.
- If *yes* is 0, cursor will always be at "cursor position" after an update.
+ If *flag* is ``False``, cursor will always be at "cursor position" after an update.
.. method:: window.move(new_y, new_x)
@@ -1055,16 +1063,16 @@ the following methods and attributes:
Move the window so its upper-left corner is at ``(new_y, new_x)``.
-.. method:: window.nodelay(yes)
+.. method:: window.nodelay(flag)
- If *yes* is ``1``, :meth:`getch` will be non-blocking.
+ If *flag* is ``True``, :meth:`getch` will be non-blocking.
-.. method:: window.notimeout(yes)
+.. method:: window.notimeout(flag)
- If *yes* is ``1``, escape sequences will not be timed out.
+ If *flag* is ``True``, escape sequences will not be timed out.
- If *yes* is ``0``, after a few milliseconds, an escape sequence will not be
+ If *flag* is ``False``, after a few milliseconds, an escape sequence will not be
interpreted, and will be left in the input stream as is.
@@ -1153,8 +1161,8 @@ the following methods and attributes:
Control what happens when the cursor of a window is moved off the edge of the
window or scrolling region, either as a result of a newline action on the bottom
- line, or typing the last character of the last line. If *flag* is false, the
- cursor is left on the bottom line. If *flag* is true, the window is scrolled up
+ line, or typing the last character of the last line. If *flag* is ``False``, the
+ cursor is left on the bottom line. If *flag* is ``True``, the window is scrolled up
one line. Note that in order to get the physical scrolling effect on the
terminal, it is also necessary to call :meth:`idlok`.
@@ -1202,7 +1210,7 @@ the following methods and attributes:
.. method:: window.syncok(flag)
- If called with *flag* set to ``True``, then :meth:`syncup` is called automatically
+ If *flag* is ``True``, then :meth:`syncup` is called automatically
whenever there is a change in the window.
@@ -1216,9 +1224,9 @@ the following methods and attributes:
Set blocking or non-blocking read behavior for the window. If *delay* is
negative, blocking read is used (which will wait indefinitely for input). If
- *delay* is zero, then non-blocking read is used, and -1 will be returned by
- :meth:`getch` if no input is waiting. If *delay* is positive, then
- :meth:`getch` will block for *delay* milliseconds, and return -1 if there is
+ *delay* is zero, then non-blocking read is used, and :meth:`getch` will
+ return ``-1`` if no input is waiting. If *delay* is positive, then
+ :meth:`getch` will block for *delay* milliseconds, and return ``-1`` if there is
still no input at the end of that time.
@@ -1226,7 +1234,7 @@ the following methods and attributes:
Pretend *count* lines have been changed, starting with line *start*. If
*changed* is supplied, it specifies whether the affected lines are marked as
- having been changed (*changed*\ =1) or unchanged (*changed*\ =0).
+ having been changed (*changed*\ ``=True``) or unchanged (*changed*\ ``=False``).
.. method:: window.touchwin()
@@ -1268,7 +1276,7 @@ The :mod:`curses` module defines the following data members:
.. data:: version
- A string representing the current version of the module. Also available as
+ A bytes object representing the current version of the module. Also available as
:const:`__version__`.
Some constants are available to specify character cell attributes.
diff --git a/Doc/library/datetime.rst b/Doc/library/datetime.rst
index e757e5d685b..dce51a16e86 100644
--- a/Doc/library/datetime.rst
+++ b/Doc/library/datetime.rst
@@ -287,11 +287,12 @@ Supported operations:
| | ``[D day[s], ][H]H:MM:SS[.UUUUUU]``, where D |
| | is negative for negative ``t``. (5) |
+--------------------------------+-----------------------------------------------+
-| ``repr(t)`` | Returns a string in the form |
-| | ``datetime.timedelta(D[, S[, U]])``, where D |
-| | is negative for negative ``t``. (5) |
+| ``repr(t)`` | Returns a string representation of the |
+| | :class:`timedelta` object as a constructor |
+| | call with canonical attribute values. |
+--------------------------------+-----------------------------------------------+
+
Notes:
(1)
@@ -312,7 +313,7 @@ Notes:
unusual results for negative timedeltas. For example:
>>> timedelta(hours=-5)
- datetime.timedelta(-1, 68400)
+ datetime.timedelta(days=-1, seconds=68400)
>>> print(_)
-1 day, 19:00:00
@@ -364,13 +365,13 @@ Example usage:
True
>>> ten_years = 10 * year
>>> ten_years, ten_years.days // 365
- (datetime.timedelta(3650), 10)
+ (datetime.timedelta(days=3650), 10)
>>> nine_years = ten_years - year
>>> nine_years, nine_years.days // 365
- (datetime.timedelta(3285), 9)
+ (datetime.timedelta(days=3285), 9)
>>> three_years = nine_years // 3
>>> three_years, three_years.days // 365
- (datetime.timedelta(1095), 3)
+ (datetime.timedelta(days=1095), 3)
>>> abs(three_years - ten_years) == 2 * three_years + year
True
@@ -1070,16 +1071,20 @@ Instance methods:
If :attr:`.tzinfo` is ``None``, returns ``None``, else returns
``self.tzinfo.utcoffset(self)``, and raises an exception if the latter doesn't
- return ``None``, or a :class:`timedelta` object representing a whole number of
- minutes with magnitude less than one day.
+ return ``None`` or a :class:`timedelta` object with magnitude less than one day.
+
+ .. versionchanged:: 3.7
+ The UTC offset is not restricted to a whole number of minutes.
.. method:: datetime.dst()
If :attr:`.tzinfo` is ``None``, returns ``None``, else returns
``self.tzinfo.dst(self)``, and raises an exception if the latter doesn't return
- ``None``, or a :class:`timedelta` object representing a whole number of minutes
- with magnitude less than one day.
+ ``None`` or a :class:`timedelta` object with magnitude less than one day.
+
+ .. versionchanged:: 3.7
+ The DST offset is not restricted to a whole number of minutes.
.. method:: datetime.tzname()
@@ -1349,12 +1354,12 @@ Using datetime with tzinfo:
>>> dt1.dst()
datetime.timedelta(0)
>>> dt1.utcoffset()
- datetime.timedelta(0, 3600)
+ datetime.timedelta(seconds=3600)
>>> dt2 = datetime(2006, 6, 14, 13, 0, tzinfo=gmt1)
>>> dt2.dst()
- datetime.timedelta(0, 3600)
+ datetime.timedelta(seconds=3600)
>>> dt2.utcoffset()
- datetime.timedelta(0, 7200)
+ datetime.timedelta(seconds=7200)
>>> # Convert datetime to another time zone
>>> dt3 = dt2.astimezone(GMT2())
>>> dt3 # doctest: +ELLIPSIS
@@ -1561,17 +1566,20 @@ Instance methods:
If :attr:`.tzinfo` is ``None``, returns ``None``, else returns
``self.tzinfo.utcoffset(None)``, and raises an exception if the latter doesn't
- return ``None`` or a :class:`timedelta` object representing a whole number of
- minutes with magnitude less than one day.
+ return ``None`` or a :class:`timedelta` object with magnitude less than one day.
+
+ .. versionchanged:: 3.7
+ The UTC offset is not restricted to a whole number of minutes.
.. method:: time.dst()
If :attr:`.tzinfo` is ``None``, returns ``None``, else returns
``self.tzinfo.dst(None)``, and raises an exception if the latter doesn't return
- ``None``, or a :class:`timedelta` object representing a whole number of minutes
- with magnitude less than one day.
+ ``None``, or a :class:`timedelta` object with magnitude less than one day.
+ .. versionchanged:: 3.7
+ The DST offset is not restricted to a whole number of minutes.
.. method:: time.tzname()
@@ -1640,13 +1648,14 @@ Example:
.. method:: tzinfo.utcoffset(dt)
- Return offset of local time from UTC, in minutes east of UTC. If local time is
+ Return offset of local time from UTC, as a :class:`timedelta` object that is
+ positive east of UTC. If local time is
west of UTC, this should be negative. Note that this is intended to be the
total offset from UTC; for example, if a :class:`tzinfo` object represents both
time zone and DST adjustments, :meth:`utcoffset` should return their sum. If
the UTC offset isn't known, return ``None``. Else the value returned must be a
- :class:`timedelta` object specifying a whole number of minutes in the range
- -1439 to 1439 inclusive (1440 = 24\*60; the magnitude of the offset must be less
+ :class:`timedelta` object strictly between ``-timedelta(hours=24)`` and
+ ``timedelta(hours=24)`` (the magnitude of the offset must be less
than one day). Most implementations of :meth:`utcoffset` will probably look
like one of these two::
@@ -1659,10 +1668,14 @@ Example:
The default implementation of :meth:`utcoffset` raises
:exc:`NotImplementedError`.
+ .. versionchanged:: 3.7
+ The UTC offset is not restricted to a whole number of minutes.
+
.. method:: tzinfo.dst(dt)
- Return the daylight saving time (DST) adjustment, in minutes east of UTC, or
+ Return the daylight saving time (DST) adjustment, as a :class:`timedelta`
+ object or
``None`` if DST information isn't known. Return ``timedelta(0)`` if DST is not
in effect. If DST is in effect, return the offset as a :class:`timedelta` object
(see :meth:`utcoffset` for details). Note that DST offset, if applicable, has
@@ -1707,6 +1720,9 @@ Example:
The default implementation of :meth:`dst` raises :exc:`NotImplementedError`.
+ .. versionchanged:: 3.7
+ The DST offset is not restricted to a whole number of minutes.
+
.. method:: tzinfo.tzname(dt)
@@ -1886,14 +1902,17 @@ made to civil time.
The *offset* argument must be specified as a :class:`timedelta`
object representing the difference between the local time and UTC. It must
be strictly between ``-timedelta(hours=24)`` and
- ``timedelta(hours=24)`` and represent a whole number of minutes,
- otherwise :exc:`ValueError` is raised.
+ ``timedelta(hours=24)``, otherwise :exc:`ValueError` is raised.
The *name* argument is optional. If specified it must be a string that
will be used as the value returned by the :meth:`datetime.tzname` method.
.. versionadded:: 3.2
+ .. versionchanged:: 3.7
+ The UTC offset is not restricted to a whole number of minutes.
+
+
.. method:: timezone.utcoffset(dt)
Return the fixed value specified when the :class:`timezone` instance is
@@ -1901,6 +1920,9 @@ made to civil time.
:class:`timedelta` instance equal to the difference between the
local time and UTC.
+ .. versionchanged:: 3.7
+ The UTC offset is not restricted to a whole number of minutes.
+
.. method:: timezone.tzname(dt)
Return the fixed value specified when the :class:`timezone` instance
@@ -2024,8 +2046,8 @@ format codes.
| | number, zero-padded on the | 999999 | |
| | left. | | |
+-----------+--------------------------------+------------------------+-------+
-| ``%z`` | UTC offset in the form +HHMM | (empty), +0000, -0400, | \(6) |
-| | or -HHMM (empty string if the | +1030 | |
+| ``%z`` | UTC offset in the form | (empty), +0000, -0400, | \(6) |
+| | ±HHMM[SS] (empty string if the | +1030 | |
| | object is naive). | | |
+-----------+--------------------------------+------------------------+-------+
| ``%Z`` | Time zone name (empty string | (empty), UTC, EST, CST | |
@@ -2138,12 +2160,26 @@ Notes:
For an aware object:
``%z``
- :meth:`utcoffset` is transformed into a 5-character string of the form
- +HHMM or -HHMM, where HH is a 2-digit string giving the number of UTC
+ :meth:`utcoffset` is transformed into a string of the form
+ ±HHMM[SS[.uuuuuu]], where HH is a 2-digit string giving the number of UTC
offset hours, and MM is a 2-digit string giving the number of UTC offset
- minutes. For example, if :meth:`utcoffset` returns
- ``timedelta(hours=-3, minutes=-30)``, ``%z`` is replaced with the string
- ``'-0330'``.
+ minutes, SS is a 2-digit string string giving the number of UTC offset
+ seconds and uuuuuu is a 2-digit string string giving the number of UTC
+ offset microseconds. The uuuuuu part is omitted when the offset is a
+ whole number of minutes and both the uuuuuu and the SS parts are omitted
+ when the offset is a whole number of minutes. For example, if
+ :meth:`utcoffset` returns ``timedelta(hours=-3, minutes=-30)``, ``%z`` is
+ replaced with the string ``'-0330'``.
+
+ .. versionchanged:: 3.7
+ The UTC offset is not restricted to a whole number of minutes.
+
+ .. versionchanged:: 3.7
+ When the ``%z`` directive is provided to the :meth:`strptime` method,
+ the UTC offsets can have a colon as a separator between hours, minutes
+ and seconds.
+ For example, ``'+01:00:00'`` will be parsed as an offset of one hour.
+ In addition, providing ``'Z'`` is identical to ``'+00:00'``.
``%Z``
If :meth:`tzname` returns ``None``, ``%Z`` is replaced by an empty
diff --git a/Doc/library/dis.rst b/Doc/library/dis.rst
index bc32380e976..01d46f88fb5 100644
--- a/Doc/library/dis.rst
+++ b/Doc/library/dis.rst
@@ -53,8 +53,9 @@ code.
.. class:: Bytecode(x, *, first_line=None, current_offset=None)
- Analyse the bytecode corresponding to a function, generator, method, string
- of source code, or a code object (as returned by :func:`compile`).
+ Analyse the bytecode corresponding to a function, generator, asynchronous
+ generator, coroutine, method, string of source code, or a code object (as
+ returned by :func:`compile`).
This is a convenience wrapper around many of the functions listed below, most
notably :func:`get_instructions`, as iterating over a :class:`Bytecode`
@@ -92,6 +93,9 @@ code.
Return a formatted multi-line string with detailed information about the
code object, like :func:`code_info`.
+ .. versionchanged:: 3.7
+ This can now handle coroutine and asynchronous generator objects.
+
Example::
>>> bytecode = dis.Bytecode(myfunc)
@@ -114,7 +118,8 @@ operation is being performed, so the intermediate analysis object isn't useful:
.. function:: code_info(x)
Return a formatted multi-line string with detailed code object information
- for the supplied function, generator, method, source code string or code object.
+ for the supplied function, generator, asynchronous generator, coroutine,
+ method, source code string or code object.
Note that the exact contents of code info strings are highly implementation
dependent and they may change arbitrarily across Python VMs or Python
@@ -122,6 +127,9 @@ operation is being performed, so the intermediate analysis object isn't useful:
.. versionadded:: 3.2
+ .. versionchanged:: 3.7
+ This can now handle coroutine and asynchronous generator objects.
+
.. function:: show_code(x, *, file=None)
@@ -141,12 +149,13 @@ operation is being performed, so the intermediate analysis object isn't useful:
.. function:: dis(x=None, *, file=None, depth=None)
Disassemble the *x* object. *x* can denote either a module, a class, a
- method, a function, a generator, a code object, a string of source code or
- a byte sequence of raw bytecode. For a module, it disassembles all functions.
- For a class, it disassembles all methods (including class and static methods).
- For a code object or sequence of raw bytecode, it prints one line per bytecode
- instruction. It also recursively disassembles nested code objects (the code
- of comprehensions, generator expressions and nested functions, and the code
+ method, a function, a generator, an asynchronous generator, a couroutine,
+ a code object, a string of source code or a byte sequence of raw bytecode.
+ For a module, it disassembles all functions. For a class, it disassembles
+ all methods (including class and static methods). For a code object or
+ sequence of raw bytecode, it prints one line per bytecode instruction.
+ It also recursively disassembles nested code objects (the code of
+ comprehensions, generator expressions and nested functions, and the code
used for building nested classes).
Strings are first compiled to code objects with the :func:`compile`
built-in function before being disassembled. If no object is provided, this
@@ -164,6 +173,9 @@ operation is being performed, so the intermediate analysis object isn't useful:
.. versionchanged:: 3.7
Implemented recursive disassembling and added *depth* parameter.
+ .. versionchanged:: 3.7
+ This can now handle coroutine and asynchronous generator objects.
+
.. function:: distb(tb=None, *, file=None)
@@ -546,8 +558,11 @@ the original TOS1.
.. opcode:: GET_AITER
- Implements ``TOS = get_awaitable(TOS.__aiter__())``. See ``GET_AWAITABLE``
- for details about ``get_awaitable``
+ Implements ``TOS = TOS.__aiter__()``.
+
+ .. versionchanged:: 3.7
+ Returning awaitable objects from ``__aiter__`` is no longer
+ supported.
.. opcode:: GET_ANEXT
@@ -1062,7 +1077,7 @@ All of the following opcodes use their arguments.
Pops all function arguments, and the function itself off the stack, and
pushes the return value. Note that this opcode pops at most three items
from the stack. Var-positional and var-keyword arguments are packed
- by :opcode:`BUILD_MAP_UNPACK_WITH_CALL` and
+ by :opcode:`BUILD_TUPLE_UNPACK_WITH_CALL` and
:opcode:`BUILD_MAP_UNPACK_WITH_CALL`.
.. versionadded:: 3.6
diff --git a/Doc/library/dummy_threading.rst b/Doc/library/dummy_threading.rst
index 30a3ebba674..dfc3289abb1 100644
--- a/Doc/library/dummy_threading.rst
+++ b/Doc/library/dummy_threading.rst
@@ -6,20 +6,15 @@
**Source code:** :source:`Lib/dummy_threading.py`
+.. deprecated:: 3.7
+ Python now always has threading enabled. Please use :mod:`threading` instead.
+
--------------
-This module provides a duplicate interface to the :mod:`threading` module. It
-is meant to be imported when the :mod:`_thread` module is not provided on a
-platform.
-
-Suggested usage is::
-
- try:
- import threading
- except ImportError:
- import dummy_threading as threading
+This module provides a duplicate interface to the :mod:`threading` module.
+It was meant to be imported when the :mod:`_thread` module was not provided
+on a platform.
Be careful to not use this module where deadlock might occur from a thread being
created that blocks waiting for another thread to be created. This often occurs
with blocking I/O.
-
diff --git a/Doc/library/ensurepip.rst b/Doc/library/ensurepip.rst
index c797f63326d..ed22180dc3f 100644
--- a/Doc/library/ensurepip.rst
+++ b/Doc/library/ensurepip.rst
@@ -78,6 +78,9 @@ options:
Providing both of the script selection options will trigger an exception.
+.. versionchanged:: 3.7.0
+ The exit status is non-zero if the command fails.
+
Module API
----------
diff --git a/Doc/library/fnmatch.rst b/Doc/library/fnmatch.rst
index 634c26e9570..abf95235505 100644
--- a/Doc/library/fnmatch.rst
+++ b/Doc/library/fnmatch.rst
@@ -86,7 +86,7 @@ patterns.
'(?s:.*\\.txt)\\Z'
>>> reobj = re.compile(regex)
>>> reobj.match('foobar.txt')
- <_sre.SRE_Match object; span=(0, 10), match='foobar.txt'>
+
.. seealso::
diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst
index 925da5094c6..e47225718c1 100644
--- a/Doc/library/functions.rst
+++ b/Doc/library/functions.rst
@@ -7,24 +7,24 @@ Built-in Functions
The Python interpreter has a number of functions and types built into it that
are always available. They are listed here in alphabetical order.
-=================== ================= ================== ================ ====================
-.. .. Built-in Functions .. ..
-=================== ================= ================== ================ ====================
-:func:`abs` |func-dict|_ :func:`help` :func:`min` :func:`setattr`
-:func:`all` :func:`dir` :func:`hex` :func:`next` :func:`slice`
-:func:`any` :func:`divmod` :func:`id` :func:`object` :func:`sorted`
-:func:`ascii` :func:`enumerate` :func:`input` :func:`oct` :func:`staticmethod`
-:func:`bin` :func:`eval` :func:`int` :func:`open` |func-str|_
-:func:`bool` :func:`exec` :func:`isinstance` :func:`ord` :func:`sum`
-|func-bytearray|_ :func:`filter` :func:`issubclass` :func:`pow` :func:`super`
-|func-bytes|_ :func:`float` :func:`iter` :func:`print` |func-tuple|_
-:func:`callable` :func:`format` :func:`len` :func:`property` :func:`type`
-:func:`chr` |func-frozenset|_ |func-list|_ |func-range|_ :func:`vars`
-:func:`classmethod` :func:`getattr` :func:`locals` :func:`repr` :func:`zip`
-:func:`compile` :func:`globals` :func:`map` :func:`reversed` :func:`__import__`
+=================== ================= ================== ================== ====================
+.. .. Built-in Functions .. ..
+=================== ================= ================== ================== ====================
+:func:`abs` :func:`delattr` :func:`hash` |func-memoryview|_ |func-set|_
+:func:`all` |func-dict|_ :func:`help` :func:`min` :func:`setattr`
+:func:`any` :func:`dir` :func:`hex` :func:`next` :func:`slice`
+:func:`ascii` :func:`divmod` :func:`id` :func:`object` :func:`sorted`
+:func:`bin` :func:`enumerate` :func:`input` :func:`oct` :func:`staticmethod`
+:func:`bool` :func:`eval` :func:`int` :func:`open` |func-str|_
+:func:`breakpoint` :func:`exec` :func:`isinstance` :func:`ord` :func:`sum`
+|func-bytearray|_ :func:`filter` :func:`issubclass` :func:`pow` :func:`super`
+|func-bytes|_ :func:`float` :func:`iter` :func:`print` |func-tuple|_
+:func:`callable` :func:`format` :func:`len` :func:`property` :func:`type`
+:func:`chr` |func-frozenset|_ |func-list|_ |func-range|_ :func:`vars`
+:func:`classmethod` :func:`getattr` :func:`locals` :func:`repr` :func:`zip`
+:func:`compile` :func:`globals` :func:`map` :func:`reversed` :func:`__import__`
:func:`complex` :func:`hasattr` :func:`max` :func:`round`
-:func:`delattr` :func:`hash` |func-memoryview|_ |func-set|_
-=================== ================= ================== ================ ====================
+=================== ================= ================== ================== ====================
.. using :func:`dict` would create a link to another page, so local targets are
used, with replacement texts to make the output in the table consistent
@@ -81,9 +81,24 @@ are always available. They are listed here in alphabetical order.
.. function:: bin(x)
- Convert an integer number to a binary string. The result is a valid Python
- expression. If *x* is not a Python :class:`int` object, it has to define an
- :meth:`__index__` method that returns an integer.
+ Convert an integer number to a binary string prefixed with "0b". The result
+ is a valid Python expression. If *x* is not a Python :class:`int` object, it
+ has to define an :meth:`__index__` method that returns an integer. Some
+ examples:
+
+ >>> bin(3)
+ '0b11'
+ >>> bin(-10)
+ '-0b1010'
+
+ If prefix "0b" is desired or not, you can use either of the following ways.
+
+ >>> format(14, '#b'), format(14, 'b')
+ ('0b1110', '1110')
+ >>> f'{14:#b}', f'{14:b}'
+ ('0b1110', '1110')
+
+ See also :func:`format` for more information.
.. class:: bool([x])
@@ -98,6 +113,20 @@ are always available. They are listed here in alphabetical order.
.. index:: pair: Boolean; type
+.. function:: breakpoint(*args, **kws)
+
+ This function drops you into the debugger at the call site. Specifically,
+ it calls :func:`sys.breakpointhook`, passing ``args`` and ``kws`` straight
+ through. By default, ``sys.breakpointhook()`` calls
+ :func:`pdb.set_trace()` expecting no arguments. In this case, it is
+ purely a convenience function so you don't have to explicitly import
+ :mod:`pdb` or type as much code to enter the debugger. However,
+ :func:`sys.breakpointhook` can be set to some other function and
+ :func:`breakpoint` will automatically call that, allowing you to drop into
+ the debugger of choice.
+
+ .. versionadded:: 3.7
+
.. _func-bytearray:
.. class:: bytearray([source[, encoding[, errors]]])
:noindex:
@@ -167,9 +196,9 @@ are always available. They are listed here in alphabetical order.
base 16). :exc:`ValueError` will be raised if *i* is outside that range.
-.. function:: classmethod(function)
+.. decorator:: classmethod
- Return a class method for *function*.
+ Transform a method into a class method.
A class method receives the class as implicit first argument, just like an
instance method receives the instance. To declare a class method, use this
@@ -635,16 +664,26 @@ are always available. They are listed here in alphabetical order.
.. function:: hex(x)
- Convert an integer number to a lowercase hexadecimal string
- prefixed with "0x", for example:
+ Convert an integer number to a lowercase hexadecimal string prefixed with
+ "0x". If x is not a Python :class:`int` object, it has to define an
+ __index__() method that returns an integer. Some examples:
>>> hex(255)
'0xff'
>>> hex(-42)
'-0x2a'
- If x is not a Python :class:`int` object, it has to define an __index__()
- method that returns an integer.
+ If you want to convert an integer number to an uppercase or lower hexadecimal
+ string with prefix or not, you can use either of the following ways:
+
+ >>> '%#x' % 255, '%x' % 255, '%X' % 255
+ ('0xff', 'ff', 'FF')
+ >>> format(255, '#x'), format(255, 'x'), format(255, 'X')
+ ('0xff', 'ff', 'FF')
+ >>> f'{255:#x}', f'{255:x}', f'{255:X}'
+ ('0xff', 'ff', 'FF')
+
+ See also :func:`format` for more information.
See also :func:`int` for converting a hexadecimal string to an
integer using a base of 16.
@@ -878,10 +917,27 @@ are always available. They are listed here in alphabetical order.
.. function:: oct(x)
- Convert an integer number to an octal string. The result is a valid Python
- expression. If *x* is not a Python :class:`int` object, it has to define an
- :meth:`__index__` method that returns an integer.
+ Convert an integer number to an octal string prefixed with "0o". The result
+ is a valid Python expression. If *x* is not a Python :class:`int` object, it
+ has to define an :meth:`__index__` method that returns an integer. For
+ example:
+ >>> oct(8)
+ '0o10'
+ >>> oct(-56)
+ '-0o70'
+
+ If you want to convert an integer number to octal string either with prefix
+ "0o" or not, you can use either of the following ways.
+
+ >>> '%#o' % 10, '%o' % 10
+ ('0o12', '12')
+ >>> format(10, '#o'), format(10, 'o')
+ ('0o12', '12')
+ >>> f'{10:#o}', f'{10:o}'
+ ('0o12', '12')
+
+ See also :func:`format` for more information.
.. index::
single: file object; open() built-in function
@@ -1319,7 +1375,7 @@ are always available. They are listed here in alphabetical order.
:func:`itertools.islice` for an alternate version that returns an iterator.
-.. function:: sorted(iterable[, key][, reverse])
+.. function:: sorted(iterable, *, key=None, reverse=False)
Return a new sorted list from the items in *iterable*.
@@ -1342,9 +1398,9 @@ are always available. They are listed here in alphabetical order.
For sorting examples and a brief sorting tutorial, see :ref:`sortinghowto`.
-.. function:: staticmethod(function)
+.. decorator:: staticmethod
- Return a static method for *function*.
+ Transform a method into a static method.
A static method does not receive an implicit first argument. To declare a static
method, use this idiom::
@@ -1363,12 +1419,21 @@ are always available. They are listed here in alphabetical order.
:func:`classmethod` for a variant that is useful for creating alternate class
constructors.
+ Like all decorators, it is also possible to call ``staticmethod`` as
+ a regular function and do something with its result. This is needed
+ in some cases where you need a reference to a function from a class
+ body and you want to avoid the automatic transformation to instance
+ method. For these cases, use this idiom:
+
+ class C:
+ builtin_open = staticmethod(open)
+
For more information on static methods, consult the documentation on the
standard type hierarchy in :ref:`types`.
- .. index::
- single: string; str() (built-in function)
+.. index::
+ single: string; str() (built-in function)
.. _func-str:
.. class:: str(object='')
diff --git a/Doc/library/functools.rst b/Doc/library/functools.rst
index 9a8defee546..28062c11890 100644
--- a/Doc/library/functools.rst
+++ b/Doc/library/functools.rst
@@ -264,9 +264,9 @@ The :mod:`functools` module defines the following functions:
return value
-.. decorator:: singledispatch(default)
+.. decorator:: singledispatch
- Transforms a function into a :term:`single-dispatch ` :term:`generic function`.
To define a generic function, decorate it with the ``@singledispatch``
diff --git a/Doc/library/gc.rst b/Doc/library/gc.rst
index 87d682445ba..153d8fb7045 100644
--- a/Doc/library/gc.rst
+++ b/Doc/library/gc.rst
@@ -174,6 +174,33 @@ The :mod:`gc` module provides the following functions:
.. versionadded:: 3.1
+.. function:: freeze()
+
+ Freeze all the objects tracked by gc - move them to a permanent generation
+ and ignore all the future collections. This can be used before a POSIX
+ fork() call to make the gc copy-on-write friendly or to speed up collection.
+ Also collection before a POSIX fork() call may free pages for future
+ allocation which can cause copy-on-write too so it's advised to disable gc
+ in master process and freeze before fork and enable gc in child process.
+
+ .. versionadded:: 3.7
+
+
+.. function:: unfreeze()
+
+ Unfreeze the objects in the permanent generation, put them back into the
+ oldest generation.
+
+ .. versionadded:: 3.7
+
+
+.. function:: get_freeze_count()
+
+ Return the number of objects in the permanent generation.
+
+ .. versionadded:: 3.7
+
+
The following variables are provided for read-only access (you can mutate the
values but should not rebind them):
diff --git a/Doc/library/gettext.rst b/Doc/library/gettext.rst
index 3a87bf59177..407853c2d7e 100644
--- a/Doc/library/gettext.rst
+++ b/Doc/library/gettext.rst
@@ -48,9 +48,10 @@ class-based API instead.
.. function:: bind_textdomain_codeset(domain, codeset=None)
- Bind the *domain* to *codeset*, changing the encoding of strings returned by the
- :func:`gettext` family of functions. If *codeset* is omitted, then the current
- binding is returned.
+ Bind the *domain* to *codeset*, changing the encoding of byte strings
+ returned by the :func:`lgettext`, :func:`ldgettext`, :func:`lngettext`
+ and :func:`ldngettext` functions.
+ If *codeset* is omitted, then the current binding is returned.
.. function:: textdomain(domain=None)
@@ -67,28 +68,14 @@ class-based API instead.
:func:`_` in the local namespace (see examples below).
-.. function:: lgettext(message)
-
- Equivalent to :func:`gettext`, but the translation is returned in the
- preferred system encoding, if no other encoding was explicitly set with
- :func:`bind_textdomain_codeset`.
-
-
.. function:: dgettext(domain, message)
- Like :func:`gettext`, but look the message up in the specified *domain*.
-
-
-.. function:: ldgettext(domain, message)
-
- Equivalent to :func:`dgettext`, but the translation is returned in the
- preferred system encoding, if no other encoding was explicitly set with
- :func:`bind_textdomain_codeset`.
+ Like :func:`.gettext`, but look the message up in the specified *domain*.
.. function:: ngettext(singular, plural, n)
- Like :func:`gettext`, but consider plural forms. If a translation is found,
+ Like :func:`.gettext`, but consider plural forms. If a translation is found,
apply the plural formula to *n*, and return the resulting message (some
languages have more than two plural forms). If no translation is found, return
*singular* if *n* is 1; return *plural* otherwise.
@@ -101,24 +88,33 @@ class-based API instead.
formulas for a variety of languages.
-.. function:: lngettext(singular, plural, n)
-
- Equivalent to :func:`ngettext`, but the translation is returned in the
- preferred system encoding, if no other encoding was explicitly set with
- :func:`bind_textdomain_codeset`.
-
-
.. function:: dngettext(domain, singular, plural, n)
Like :func:`ngettext`, but look the message up in the specified *domain*.
+.. function:: lgettext(message)
+.. function:: ldgettext(domain, message)
+.. function:: lngettext(singular, plural, n)
.. function:: ldngettext(domain, singular, plural, n)
- Equivalent to :func:`dngettext`, but the translation is returned in the
- preferred system encoding, if no other encoding was explicitly set with
+ Equivalent to the corresponding functions without the ``l`` prefix
+ (:func:`.gettext`, :func:`dgettext`, :func:`ngettext` and :func:`dngettext`),
+ but the translation is returned as a byte string encoded in the preferred
+ system encoding if no other encoding was explicitly set with
:func:`bind_textdomain_codeset`.
+ .. warning::
+
+ These functions should be avoided in Python 3, because they return
+ encoded bytes. It's much better to use alternatives which return
+ Unicode strings instead, since most Python applications will want to
+ manipulate human readable text as strings instead of bytes. Further,
+ it's possible that you may get unexpected Unicode-related exceptions
+ if there are encoding problems with the translated strings. It is
+ possible that the ``l*()`` functions will be deprecated in future Python
+ versions due to their inherent problems and limitations.
+
Note that GNU :program:`gettext` also defines a :func:`dcgettext` method, but
this was deemed not useful and so it is currently unimplemented.
@@ -138,7 +134,7 @@ Class-based API
The class-based API of the :mod:`gettext` module gives you more flexibility and
greater convenience than the GNU :program:`gettext` API. It is the recommended
-way of localizing your Python applications and modules. :mod:`gettext` defines
+way of localizing your Python applications and modules. :mod:`!gettext` defines
a "translations" class which implements the parsing of GNU :file:`.mo` format
files, and has methods for returning strings. Instances of this "translations"
class can also install themselves in the built-in namespace as the function
@@ -179,8 +175,9 @@ class can also install themselves in the built-in namespace as the function
names are cached. The actual class instantiated is either *class_* if
provided, otherwise :class:`GNUTranslations`. The class's constructor must
take a single :term:`file object` argument. If provided, *codeset* will change
- the charset used to encode translated strings in the :meth:`lgettext` and
- :meth:`lngettext` methods.
+ the charset used to encode translated strings in the
+ :meth:`~NullTranslations.lgettext` and :meth:`~NullTranslations.lngettext`
+ methods.
If multiple files are found, later files are used as fallbacks for earlier ones.
To allow setting the fallback, :func:`copy.copy` is used to clone each
@@ -222,7 +219,7 @@ Translation classes are what actually implement the translation of original
source file message strings to translated message strings. The base class used
by all translation classes is :class:`NullTranslations`; this provides the basic
interface you can use to write your own specialized translation classes. Here
-are the methods of :class:`NullTranslations`:
+are the methods of :class:`!NullTranslations`:
.. class:: NullTranslations(fp=None)
@@ -250,26 +247,29 @@ are the methods of :class:`NullTranslations`:
.. method:: gettext(message)
- If a fallback has been set, forward :meth:`gettext` to the fallback.
- Otherwise, return the translated message. Overridden in derived classes.
-
-
- .. method:: lgettext(message)
-
- If a fallback has been set, forward :meth:`lgettext` to the fallback.
- Otherwise, return the translated message. Overridden in derived classes.
+ If a fallback has been set, forward :meth:`!gettext` to the fallback.
+ Otherwise, return *message*. Overridden in derived classes.
.. method:: ngettext(singular, plural, n)
- If a fallback has been set, forward :meth:`ngettext` to the fallback.
- Otherwise, return the translated message. Overridden in derived classes.
+ If a fallback has been set, forward :meth:`!ngettext` to the fallback.
+ Otherwise, return *singular* if *n* is 1; return *plural* otherwise.
+ Overridden in derived classes.
+ .. method:: lgettext(message)
.. method:: lngettext(singular, plural, n)
- If a fallback has been set, forward :meth:`lngettext` to the fallback.
- Otherwise, return the translated message. Overridden in derived classes.
+ Equivalent to :meth:`.gettext` and :meth:`.ngettext`, but the translation
+ is returned as a byte string encoded in the preferred system encoding
+ if no encoding was explicitly set with :meth:`set_output_charset`.
+ Overridden in derived classes.
+
+ .. warning::
+
+ These methods should be avoided in Python 3. See the warning for the
+ :func:`lgettext` function.
.. method:: info()
@@ -279,32 +279,28 @@ are the methods of :class:`NullTranslations`:
.. method:: charset()
- Return the "protected" :attr:`_charset` variable, which is the encoding of
- the message catalog file.
+ Return the encoding of the message catalog file.
.. method:: output_charset()
- Return the "protected" :attr:`_output_charset` variable, which defines the
- encoding used to return translated messages in :meth:`lgettext` and
- :meth:`lngettext`.
+ Return the encoding used to return translated messages in :meth:`.lgettext`
+ and :meth:`.lngettext`.
.. method:: set_output_charset(charset)
- Change the "protected" :attr:`_output_charset` variable, which defines the
- encoding used to return translated messages.
+ Change the encoding used to return translated messages.
.. method:: install(names=None)
- This method installs :meth:`self.gettext` into the built-in namespace,
+ This method installs :meth:`.gettext` into the built-in namespace,
binding it to ``_``.
If the *names* parameter is given, it must be a sequence containing the
names of functions you want to install in the builtins namespace in
- addition to :func:`_`. Supported names are ``'gettext'`` (bound to
- :meth:`self.gettext`), ``'ngettext'`` (bound to :meth:`self.ngettext`),
+ addition to :func:`_`. Supported names are ``'gettext'``, ``'ngettext'``,
``'lgettext'`` and ``'lngettext'``.
Note that this is only one way, albeit the most convenient way, to make
@@ -349,49 +345,52 @@ If the :file:`.mo` file's magic number is invalid, the major version number is
unexpected, or if other problems occur while reading the file, instantiating a
:class:`GNUTranslations` class can raise :exc:`OSError`.
-The following methods are overridden from the base class implementation:
+.. class:: GNUTranslations
+
+ The following methods are overridden from the base class implementation:
+
+ .. method:: gettext(message)
+
+ Look up the *message* id in the catalog and return the corresponding message
+ string, as a Unicode string. If there is no entry in the catalog for the
+ *message* id, and a fallback has been set, the look up is forwarded to the
+ fallback's :meth:`~NullTranslations.gettext` method. Otherwise, the
+ *message* id is returned.
-.. method:: GNUTranslations.gettext(message)
+ .. method:: ngettext(singular, plural, n)
- Look up the *message* id in the catalog and return the corresponding message
- string, as a Unicode string. If there is no entry in the catalog for the
- *message* id, and a fallback has been set, the look up is forwarded to the
- fallback's :meth:`gettext` method. Otherwise, the *message* id is returned.
+ Do a plural-forms lookup of a message id. *singular* is used as the message id
+ for purposes of lookup in the catalog, while *n* is used to determine which
+ plural form to use. The returned message string is a Unicode string.
+
+ If the message id is not found in the catalog, and a fallback is specified,
+ the request is forwarded to the fallback's :meth:`~NullTranslations.ngettext`
+ method. Otherwise, when *n* is 1 *singular* is returned, and *plural* is
+ returned in all other cases.
+
+ Here is an example::
+
+ n = len(os.listdir('.'))
+ cat = GNUTranslations(somefile)
+ message = cat.ngettext(
+ 'There is %(num)d file in this directory',
+ 'There are %(num)d files in this directory',
+ n) % {'num': n}
-.. method:: GNUTranslations.lgettext(message)
+ .. method:: lgettext(message)
+ .. method:: lngettext(singular, plural, n)
- Equivalent to :meth:`gettext`, but the translation is returned as a
- bytestring encoded in the selected output charset, or in the preferred system
- encoding if no encoding was explicitly set with :meth:`set_output_charset`.
+ Equivalent to :meth:`.gettext` and :meth:`.ngettext`, but the translation
+ is returned as a byte string encoded in the preferred system encoding
+ if no encoding was explicitly set with
+ :meth:`~NullTranslations.set_output_charset`.
+ .. warning::
-.. method:: GNUTranslations.ngettext(singular, plural, n)
-
- Do a plural-forms lookup of a message id. *singular* is used as the message id
- for purposes of lookup in the catalog, while *n* is used to determine which
- plural form to use. The returned message string is a Unicode string.
-
- If the message id is not found in the catalog, and a fallback is specified, the
- request is forwarded to the fallback's :meth:`ngettext` method. Otherwise, when
- *n* is 1 *singular* is returned, and *plural* is returned in all other cases.
-
- Here is an example::
-
- n = len(os.listdir('.'))
- cat = GNUTranslations(somefile)
- message = cat.ngettext(
- 'There is %(num)d file in this directory',
- 'There are %(num)d files in this directory',
- n) % {'num': n}
-
-
-.. method:: GNUTranslations.lngettext(singular, plural, n)
-
- Equivalent to :meth:`gettext`, but the translation is returned as a
- bytestring encoded in the selected output charset, or in the preferred system
- encoding if no encoding was explicitly set with :meth:`set_output_charset`.
+ These methods should be avoided in Python 3. See the warning for the
+ :func:`lgettext` function.
Solaris message catalog support
@@ -509,7 +508,7 @@ module::
import gettext
t = gettext.translation('spam', '/usr/share/locale')
- _ = t.lgettext
+ _ = t.gettext
Localizing your application
diff --git a/Doc/library/hashlib.rst b/Doc/library/hashlib.rst
index 9d563566d49..452705f4d2a 100644
--- a/Doc/library/hashlib.rst
+++ b/Doc/library/hashlib.rst
@@ -267,7 +267,7 @@ include a `salt `_.
should be about 16 or more bytes from a proper source, e.g. :func:`os.urandom`.
*n* is the CPU/Memory cost factor, *r* the block size, *p* parallelization
- factor and *maxmem* limits memory (OpenSSL 1.1.0 defaults to 32 MB).
+ factor and *maxmem* limits memory (OpenSSL 1.1.0 defaults to 32 MiB).
*dklen* is the length of the derived key.
Availability: OpenSSL 1.1+
@@ -506,18 +506,23 @@ to users and later verify them to make sure they weren't tampered with::
>>> AUTH_SIZE = 16
>>>
>>> def sign(cookie):
- ... h = blake2b(data=cookie, digest_size=AUTH_SIZE, key=SECRET_KEY)
- ... return h.hexdigest()
+ ... h = blake2b(digest_size=AUTH_SIZE, key=SECRET_KEY)
+ ... h.update(cookie)
+ ... return h.hexdigest().encode('utf-8')
>>>
- >>> cookie = b'user:vatrogasac'
+ >>> def verify(cookie, sig):
+ ... good_sig = sign(cookie)
+ ... return compare_digest(good_sig, sig)
+ >>>
+ >>> cookie = b'user-alice'
>>> sig = sign(cookie)
>>> print("{0},{1}".format(cookie.decode('utf-8'), sig))
- user:vatrogasac,349cf904533767ed2d755279a8df84d0
- >>> compare_digest(cookie, sig)
+ user-alice,b'43b3c982cf697e0c5ab22172d1ca7421'
+ >>> verify(cookie, sig)
True
- >>> compare_digest(b'user:policajac', sig)
+ >>> verify(b'user-bob', sig)
False
- >>> compare_digesty(cookie, '0102030405060708090a0b0c0d0e0f00')
+ >>> verify(cookie, b'0102030405060708090a0b0c0d0e0f00')
False
Even though there's a native keyed hashing mode, BLAKE2 can, of course, be used
diff --git a/Doc/library/http.client.rst b/Doc/library/http.client.rst
index 53de40f63ca..c4b7c79730f 100644
--- a/Doc/library/http.client.rst
+++ b/Doc/library/http.client.rst
@@ -31,7 +31,8 @@ HTTPS protocols. It is normally not used directly --- the module
The module provides the following classes:
-.. class:: HTTPConnection(host, port=None[, timeout], source_address=None)
+.. class:: HTTPConnection(host, port=None[, timeout], source_address=None, \
+ blocksize=8192)
An :class:`HTTPConnection` instance represents one transaction with an HTTP
server. It should be instantiated passing it a host and optional port
@@ -42,6 +43,8 @@ The module provides the following classes:
(if it is not given, the global default timeout setting is used).
The optional *source_address* parameter may be a tuple of a (host, port)
to use as the source address the HTTP connection is made from.
+ The optional *blocksize* parameter sets the buffer size in bytes for
+ sending a file-like message body.
For example, the following calls all create instances that connect to the server
at the same host and port::
@@ -58,11 +61,14 @@ The module provides the following classes:
The *strict* parameter was removed. HTTP 0.9-style "Simple Responses" are
not longer supported.
+ .. versionchanged:: 3.7
+ *blocksize* parameter was added.
+
.. class:: HTTPSConnection(host, port=None, key_file=None, \
cert_file=None[, timeout], \
source_address=None, *, context=None, \
- check_hostname=None)
+ check_hostname=None, blocksize=8192)
A subclass of :class:`HTTPConnection` that uses SSL for communication with
secure servers. Default port is ``443``. If *context* is specified, it
@@ -338,6 +344,14 @@ HTTPConnection Objects
Close the connection to the server.
+
+.. attribute:: HTTPConnection.blocksize
+
+ Buffer size in bytes for sending a file-like message body.
+
+ .. versionadded:: 3.7
+
+
As an alternative to using the :meth:`request` method described above, you can
also send your request step by step, by using the four functions below.
diff --git a/Doc/library/http.rst b/Doc/library/http.rst
index be661c5e8c2..7c34004a3ae 100644
--- a/Doc/library/http.rst
+++ b/Doc/library/http.rst
@@ -98,6 +98,7 @@ Code Enum Name Details
``415`` ``UNSUPPORTED_MEDIA_TYPE`` HTTP/1.1 :rfc:`7231`, Section 6.5.13
``416`` ``REQUEST_RANGE_NOT_SATISFIABLE`` HTTP/1.1 Range Requests :rfc:`7233`, Section 4.4
``417`` ``EXPECTATION_FAILED`` HTTP/1.1 :rfc:`7231`, Section 6.5.14
+``421`` ``MISDIRECTED_REQUEST`` HTTP/2 :rfc:`7540`, Section 9.1.2
``422`` ``UNPROCESSABLE_ENTITY`` WebDAV :rfc:`4918`, Section 11.2
``423`` ``LOCKED`` WebDAV :rfc:`4918`, Section 11.3
``424`` ``FAILED_DEPENDENCY`` WebDAV :rfc:`4918`, Section 11.4
@@ -122,3 +123,6 @@ In order to preserve backwards compatibility, enum values are also present
in the :mod:`http.client` module in the form of constants. The enum name is
equal to the constant name (i.e. ``http.HTTPStatus.OK`` is also available as
``http.client.OK``).
+
+.. versionchanged:: 3.7
+ Added ``421 MISDIRECTED_REQUEST`` status code.
diff --git a/Doc/library/idle.rst b/Doc/library/idle.rst
index a945b6d7712..af153593e3c 100644
--- a/Doc/library/idle.rst
+++ b/Doc/library/idle.rst
@@ -190,7 +190,9 @@ Format Paragraph
paragraph will be formatted to less than N columns, where N defaults to 72.
Strip trailing whitespace
- Remove any space characters after the last non-space character of a line.
+ Remove trailing space and other whitespace characters after the last
+ non-whitespace character of a line by applying str.rstrip to each line,
+ including lines within multiline strings.
.. index::
single: Run script
@@ -599,15 +601,15 @@ starting from a console (``python -m idlelib)`` and see if a message appears.
IDLE-console differences
^^^^^^^^^^^^^^^^^^^^^^^^
-As much as possible, the result of executing Python code with IDLE is the
-same as executing the same code in a console window. However, the different
-interface and operation occasionally affect visible results. For instance,
-``sys.modules`` starts with more entries.
+With rare exceptions, the result of executing Python code with IDLE is
+intended to be the same as executing the same code in a console window.
+However, the different interface and operation occasionally affect
+visible results. For instance, ``sys.modules`` starts with more entries.
IDLE also replaces ``sys.stdin``, ``sys.stdout``, and ``sys.stderr`` with
objects that get input from and send output to the Shell window.
-When this window has the focus, it controls the keyboard and screen.
-This is normally transparent, but functions that directly access the keyboard
+When Shell has the focus, it controls the keyboard and screen. This is
+normally transparent, but functions that directly access the keyboard
and screen will not work. If ``sys`` is reset with ``importlib.reload(sys)``,
IDLE's changes are lost and things like ``input``, ``raw_input``, and
``print`` will not work correctly.
@@ -617,6 +619,29 @@ Some consoles only work with a single physical line at a time. IDLE uses
``exec`` to run each statement. As a result, ``'__builtins__'`` is always
defined for each statement.
+Developing tkinter applications
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+IDLE is intentionally different from standard Python in order to
+facilitate development of tkinter programs. Enter ``import tkinter as tk;
+root = tk.Tk()`` in standard Python and nothing appears. Enter the same
+in IDLE and a tk window appears. In standard Python, one must also enter
+``root.update()`` to see the window. IDLE does the equivalent in the
+background, about 20 times a second, which is about every 50 milleseconds.
+Next enter ``b = tk.Button(root, text='button'); b.pack()``. Again,
+nothing visibly changes in standard Python until one enters ``root.update()``.
+
+Most tkinter programs run ``root.mainloop()``, which usually does not
+return until the tk app is destroyed. If the program is run with
+``python -i`` or from an IDLE editor, a ``>>>`` shell prompt does not
+appear until ``mainloop()`` returns, at which time there is nothing left
+to interact with.
+
+When running a tkinter program from an IDLE editor, one can comment out
+the mainloop call. One then gets a shell prompt immediately and can
+interact with the live application. One just has to remember to
+re-enable the mainloop call when running in standard Python.
+
Running without a subprocess
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -671,24 +696,7 @@ Extensions
^^^^^^^^^^
IDLE contains an extension facility. Preferences for extensions can be
-changed with Configure Extensions. See the beginning of config-extensions.def
-in the idlelib directory for further information. The default extensions
-are currently:
-
-* FormatParagraph
-
-* AutoExpand
-
-* ZoomHeight
-
-* ScriptBinding
-
-* CallTips
-
-* ParenMatch
-
-* AutoComplete
-
-* CodeContext
-
-* RstripExtension
+changed with the Extensions tab of the preferences dialog. See the
+beginning of config-extensions.def in the idlelib directory for further
+information. The only current default extension is zzdummy, an example
+also used for testing.
diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst
index 45a02e568e1..3d350e8d0d5 100644
--- a/Doc/library/importlib.rst
+++ b/Doc/library/importlib.rst
@@ -32,7 +32,7 @@ generically as an :term:`importer`) to participate in the import process.
:ref:`import`
The language reference for the :keyword:`import` statement.
- `Packages specification `__
+ `Packages specification `_
- `UuidCreate `_
- `UuidToString `_
+ `FCICreate `_
+ `UuidCreate `_
+ `UuidToString `_
.. _database-objects:
@@ -152,12 +152,18 @@ Database Objects
:c:func:`MsiGetSummaryInformation`. *count* is the maximum number of updated
values.
+.. method:: Database.Close()
+
+ Close the database object, through :c:func:`MsiCloseHandle`.
+
+ .. versionadded:: 3.7
.. seealso::
- `MSIDatabaseOpenView `_
- `MSIDatabaseCommit `_
- `MSIGetSummaryInformation `_
+ `MSIDatabaseOpenView `_
+ `MSIDatabaseCommit `_
+ `MSIGetSummaryInformation `_
+ `MsiCloseHandle `_
.. _view-objects:
@@ -203,11 +209,11 @@ View Objects
.. seealso::
- `MsiViewExecute `_
- `MSIViewGetColumnInfo `_
- `MsiViewFetch `_
- `MsiViewModify `_
- `MsiViewClose `_
+ `MsiViewExecute `_
+ `MSIViewGetColumnInfo `_
+ `MsiViewFetch `_
+ `MsiViewModify `_
+ `MsiViewClose `_
.. _summary-objects:
@@ -247,10 +253,10 @@ Summary Information Objects
.. seealso::
- `MsiSummaryInfoGetProperty `_
- `MsiSummaryInfoGetPropertyCount `_
- `MsiSummaryInfoSetProperty `_
- `MsiSummaryInfoPersist `_
+ `MsiSummaryInfoGetProperty `_
+ `MsiSummaryInfoGetPropertyCount `_
+ `MsiSummaryInfoSetProperty `_
+ `MsiSummaryInfoPersist `_
.. _record-objects:
@@ -301,18 +307,18 @@ Record Objects
.. seealso::
- `MsiRecordGetFieldCount `_
- `MsiRecordSetString `_
- `MsiRecordSetStream `_
- `MsiRecordSetInteger `_
- `MsiRecordClear `_
+ `MsiRecordGetFieldCount `_
+ `MsiRecordSetString `_
+ `MsiRecordSetStream `_
+ `MsiRecordSetInteger `_
+ `MsiRecordClearData `_
.. _msi-errors:
Errors
------
-All wrappers around MSI functions raise :exc:`MsiError`; the string inside the
+All wrappers around MSI functions raise :exc:`MSIError`; the string inside the
exception will contain more detail.
@@ -392,15 +398,15 @@ Directory Objects
.. method:: remove_pyc()
- Remove ``.pyc``/``.pyo`` files on uninstall.
+ Remove ``.pyc`` files on uninstall.
.. seealso::
- `Directory Table `_
- `File Table `_
- `Component Table `_
- `FeatureComponents Table `_
+ `Directory Table `_
+ `File Table `_
+ `Component Table `_
+ `FeatureComponents Table `_
.. _features:
@@ -425,7 +431,7 @@ Features
.. seealso::
- `Feature Table `_
+ `Feature Table `_
.. _msi-gui:
@@ -520,13 +526,13 @@ for installing Python packages.
.. seealso::
- `Dialog Table `_
- `Control Table `_
- `Control Types `_
- `ControlCondition Table `_
- `ControlEvent Table `_
- `EventMapping Table `_
- `RadioButton Table `_
+ `Dialog Table `_
+ `Control Table `_
+ `Control Types `_
+ `ControlCondition Table `_
+ `ControlEvent Table `_
+ `EventMapping Table `_
+ `RadioButton Table `_
.. _msi-tables:
diff --git a/Doc/library/multiprocessing.rst b/Doc/library/multiprocessing.rst
index 6b4a8cbd299..3619cccfe63 100644
--- a/Doc/library/multiprocessing.rst
+++ b/Doc/library/multiprocessing.rst
@@ -598,6 +598,22 @@ The :mod:`multiprocessing` package mostly replicates the API of the
acquired a lock or semaphore etc. then terminating it is liable to
cause other processes to deadlock.
+ .. method:: kill()
+
+ Same as :meth:`terminate()` but using the ``SIGKILL`` signal on Unix.
+
+ .. versionadded:: 3.7
+
+ .. method:: close()
+
+ Close the :class:`Process` object, releasing all resources associated
+ with it. :exc:`ValueError` is raised if the underlying process
+ is still running. Once :meth:`close` returns successfully, most
+ other methods and attributes of the :class:`Process` object will
+ raise :exc:`ValueError`.
+
+ .. versionadded:: 3.7
+
Note that the :meth:`start`, :meth:`join`, :meth:`is_alive`,
:meth:`terminate` and :attr:`exitcode` methods should only be called by
the process that created the process object.
@@ -1018,13 +1034,13 @@ Connection objects are usually created using :func:`Pipe` -- see also
Send an object to the other end of the connection which should be read
using :meth:`recv`.
- The object must be picklable. Very large pickles (approximately 32 MB+,
+ The object must be picklable. Very large pickles (approximately 32 MiB+,
though it depends on the OS) may raise a :exc:`ValueError` exception.
.. method:: recv()
Return an object sent from the other end of the connection using
- :meth:`send`. Blocks until there its something to receive. Raises
+ :meth:`send`. Blocks until there is something to receive. Raises
:exc:`EOFError` if there is nothing left to receive
and the other end was closed.
@@ -1055,7 +1071,7 @@ Connection objects are usually created using :func:`Pipe` -- see also
If *offset* is given then data is read from that position in *buffer*. If
*size* is given then that many bytes will be read from buffer. Very large
- buffers (approximately 32 MB+, though it depends on the OS) may raise a
+ buffers (approximately 32 MiB+, though it depends on the OS) may raise a
:exc:`ValueError` exception
.. method:: recv_bytes([maxlength])
@@ -2165,7 +2181,7 @@ with the :class:`Pool` class.
.. versionadded:: 3.3
- .. method:: starmap_async(func, iterable[, chunksize[, callback[, error_back]]])
+ .. method:: starmap_async(func, iterable[, chunksize[, callback[, error_callback]]])
A combination of :meth:`starmap` and :meth:`map_async` that iterates over
*iterable* of iterables and calls *func* with the iterables unpacked.
@@ -2280,7 +2296,7 @@ multiple connections at the same time.
If a welcome message is not received, then
:exc:`~multiprocessing.AuthenticationError` is raised.
-.. function:: Client(address[, family[, authenticate[, authkey]]])
+.. function:: Client(address[, family[, authkey]])
Attempt to set up a connection to the listener which is using address
*address*, returning a :class:`~multiprocessing.Connection`.
@@ -2289,14 +2305,13 @@ multiple connections at the same time.
generally be omitted since it can usually be inferred from the format of
*address*. (See :ref:`multiprocessing-address-formats`)
- If *authenticate* is ``True`` or *authkey* is a byte string then digest
- authentication is used. The key used for authentication will be either
- *authkey* or ``current_process().authkey`` if *authkey* is ``None``.
- If authentication fails then
- :exc:`~multiprocessing.AuthenticationError` is raised. See
- :ref:`multiprocessing-auth-keys`.
+ If *authkey* is given and not None, it should be a byte string and will be
+ used as the secret key for an HMAC-based authentication challenge. No
+ authentication is done if *authkey* is None.
+ :exc:`~multiprocessing.AuthenticationError` is raised if authentication fails.
+ See :ref:`multiprocessing-auth-keys`.
-.. class:: Listener([address[, family[, backlog[, authenticate[, authkey]]]]])
+.. class:: Listener([address[, family[, backlog[, authkey]]]])
A wrapper for a bound socket or Windows named pipe which is 'listening' for
connections.
@@ -2325,17 +2340,10 @@ multiple connections at the same time.
to the :meth:`~socket.socket.listen` method of the socket once it has been
bound.
- If *authenticate* is ``True`` (``False`` by default) or *authkey* is not
- ``None`` then digest authentication is used.
-
- If *authkey* is a byte string then it will be used as the
- authentication key; otherwise it must be ``None``.
-
- If *authkey* is ``None`` and *authenticate* is ``True`` then
- ``current_process().authkey`` is used as the authentication key. If
- *authkey* is ``None`` and *authenticate* is ``False`` then no
- authentication is done. If authentication fails then
- :exc:`~multiprocessing.AuthenticationError` is raised.
+ If *authkey* is given and not None, it should be a byte string and will be
+ used as the secret key for an HMAC-based authentication challenge. No
+ authentication is done if *authkey* is None.
+ :exc:`~multiprocessing.AuthenticationError` is raised if authentication fails.
See :ref:`multiprocessing-auth-keys`.
.. method:: accept()
diff --git a/Doc/library/operator.rst b/Doc/library/operator.rst
index 8121b480cb6..e4d6d05a23a 100644
--- a/Doc/library/operator.rst
+++ b/Doc/library/operator.rst
@@ -17,9 +17,10 @@
The :mod:`operator` module exports a set of efficient functions corresponding to
the intrinsic operators of Python. For example, ``operator.add(x, y)`` is
-equivalent to the expression ``x+y``. The function names are those used for
-special class methods; variants without leading and trailing ``__`` are also
-provided for convenience.
+equivalent to the expression ``x+y``. Many function names are those used for
+special methods, without the double underscores. For backward compatibility,
+many of these have a variant with the double underscores kept. The variants
+without the double underscores are preferred for clarity.
The functions fall into categories that perform object comparisons, logical
operations, mathematical operations and sequence operations.
@@ -321,6 +322,9 @@ expect a function argument.
>>> itemgetter(slice(2,None))('ABCDEFG')
'CDEFG'
+ >>> soldier = dict(rank='captain', name='dotterbart')
+ >>> itemgetter('rank')(soldier)
+ 'captain'
Example of using :func:`itemgetter` to retrieve specific fields from a
tuple record:
diff --git a/Doc/library/os.path.rst b/Doc/library/os.path.rst
index 38a93315770..06d4ecedd86 100644
--- a/Doc/library/os.path.rst
+++ b/Doc/library/os.path.rst
@@ -192,23 +192,17 @@ the :mod:`glob` module.)
.. function:: getatime(path)
- Return the time of last access of *path*. The return value is a number giving
+ Return the time of last access of *path*. The return value is a floating point number giving
the number of seconds since the epoch (see the :mod:`time` module). Raise
:exc:`OSError` if the file does not exist or is inaccessible.
- If :func:`os.stat_float_times` returns ``True``, the result is a floating point
- number.
-
.. function:: getmtime(path)
- Return the time of last modification of *path*. The return value is a number
+ Return the time of last modification of *path*. The return value is a floating point number
giving the number of seconds since the epoch (see the :mod:`time` module).
Raise :exc:`OSError` if the file does not exist or is inaccessible.
- If :func:`os.stat_float_times` returns ``True``, the result is a floating point
- number.
-
.. versionchanged:: 3.6
Accepts a :term:`path-like object`.
diff --git a/Doc/library/os.rst b/Doc/library/os.rst
index 86add0cb8e1..95c81137230 100644
--- a/Doc/library/os.rst
+++ b/Doc/library/os.rst
@@ -2335,8 +2335,6 @@ features:
* the time of creation on Windows, expressed in nanoseconds as an
integer.
- See also the :func:`stat_float_times` function.
-
.. note::
The exact meaning and resolution of the :attr:`st_atime`,
@@ -2431,33 +2429,6 @@ features:
Added the :attr:`st_file_attributes` member on Windows.
-.. function:: stat_float_times([newvalue])
-
- Determine whether :class:`stat_result` represents time stamps as float objects.
- If *newvalue* is ``True``, future calls to :func:`~os.stat` return floats, if it is
- ``False``, future calls return ints. If *newvalue* is omitted, return the
- current setting.
-
- For compatibility with older Python versions, accessing :class:`stat_result` as
- a tuple always returns integers.
-
- Python now returns float values by default. Applications which do not work
- correctly with floating point time stamps can use this function to restore the
- old behaviour.
-
- The resolution of the timestamps (that is the smallest possible fraction)
- depends on the system. Some systems only support second resolution; on these
- systems, the fraction will always be zero.
-
- It is recommended that this setting is only changed at program startup time in
- the *__main__* module; libraries should never change this setting. If an
- application uses a library that works incorrectly if floating point time stamps
- are processed, this application should turn the feature off until the library
- has been corrected.
-
- .. deprecated:: 3.3
-
-
.. function:: statvfs(path)
Perform a :c:func:`statvfs` system call on the given path. The return value is
diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst
index 0c9bd0d940a..3d28a1bea30 100644
--- a/Doc/library/pathlib.rst
+++ b/Doc/library/pathlib.rst
@@ -761,6 +761,18 @@ call fails (for example because the path doesn't exist):
other errors (such as permission errors) are propagated.
+.. method:: Path.is_mount()
+
+ Return ``True`` if the path is a :dfn:`mount point`: a point in a
+ file system where a different file system has been mounted. On POSIX, the
+ function checks whether *path*'s parent, :file:`path/..`, is on a different
+ device than *path*, or whether :file:`path/..` and *path* point to the same
+ i-node on the same device --- this should detect mount points for all Unix
+ and POSIX variants. Not implemented on Windows.
+
+ .. versionadded:: 3.7
+
+
.. method:: Path.is_symlink()
Return ``True`` if the path points to a symbolic link, ``False`` otherwise.
diff --git a/Doc/library/pdb.rst b/Doc/library/pdb.rst
index 6225a3a1f07..4f3148fb5c3 100644
--- a/Doc/library/pdb.rst
+++ b/Doc/library/pdb.rst
@@ -118,11 +118,15 @@ slightly different way:
is entered.
-.. function:: set_trace()
+.. function:: set_trace(*, header=None)
- Enter the debugger at the calling stack frame. This is useful to hard-code a
- breakpoint at a given point in a program, even if the code is not otherwise
- being debugged (e.g. when an assertion fails).
+ Enter the debugger at the calling stack frame. This is useful to hard-code
+ a breakpoint at a given point in a program, even if the code is not
+ otherwise being debugged (e.g. when an assertion fails). If given,
+ *header* is printed to the console just before debugging begins.
+
+ .. versionchanged:: 3.7
+ The keyword-only argument *header*.
.. function:: post_mortem(traceback=None)
diff --git a/Doc/library/profile.rst b/Doc/library/profile.rst
index 5796e3acb6a..48426a00c9a 100644
--- a/Doc/library/profile.rst
+++ b/Doc/library/profile.rst
@@ -123,13 +123,18 @@ them in various ways.
The file :mod:`cProfile` can also be invoked as a script to profile another
script. For example::
- python -m cProfile [-o output_file] [-s sort_order] myscript.py
+ python -m cProfile [-o output_file] [-s sort_order] (-m module | myscript.py)
``-o`` writes the profile results to a file instead of to stdout
``-s`` specifies one of the :func:`~pstats.Stats.sort_stats` sort values to sort
the output by. This only applies when ``-o`` is not supplied.
+``-m`` specifies that a module is being profiled instead of a script.
+
+ .. versionadded:: 3.7
+ Added the ``-m`` option.
+
The :mod:`pstats` module's :class:`~pstats.Stats` class has a variety of methods
for manipulating and printing the data saved into a profile results file::
@@ -575,7 +580,7 @@ procedure can be used to obtain a better constant for a given platform (see
The method executes the number of Python calls given by the argument, directly
and again under the profiler, measuring the time for both. It then computes the
hidden overhead per profiler event, and returns that as a float. For example,
-on a 1.8Ghz Intel Core i5 running Mac OS X, and using Python's time.clock() as
+on a 1.8Ghz Intel Core i5 running Mac OS X, and using Python's time.process_time() as
the timer, the magical number is about 4.04e-6.
The object of this exercise is to get a fairly consistent result. If your
diff --git a/Doc/library/pyclbr.rst b/Doc/library/pyclbr.rst
index 32842717bc6..ea34dd0638c 100644
--- a/Doc/library/pyclbr.rst
+++ b/Doc/library/pyclbr.rst
@@ -10,93 +10,63 @@
--------------
-The :mod:`pyclbr` module can be used to determine some limited information
-about the classes, methods and top-level functions defined in a module. The
-information provided is sufficient to implement a traditional three-pane
-class browser. The information is extracted from the source code rather
-than by importing the module, so this module is safe to use with untrusted
-code. This restriction makes it impossible to use this module with modules
-not implemented in Python, including all standard and optional extension
+The :mod:`pyclbr` module provides limited information about the
+functions, classes, and methods defined in a python-coded module. The
+information is sufficient to implement a module browser. The
+information is extracted from the python source code rather than by
+importing the module, so this module is safe to use with untrusted code.
+This restriction makes it impossible to use this module with modules not
+implemented in Python, including all standard and optional extension
modules.
.. function:: readmodule(module, path=None)
- Read a module and return a dictionary mapping class names to class
- descriptor objects. The parameter *module* should be the name of a
- module as a string; it may be the name of a module within a package. The
- *path* parameter should be a sequence, and is used to augment the value
- of ``sys.path``, which is used to locate module source code.
+ Return a dictionary mapping module-level class names to class
+ descriptors. If possible, descriptors for imported base classes are
+ included. Parameter *module* is a string with the name of the module
+ to read; it may be the name of a module within a package. If given,
+ *path* is a sequence of directory paths prepended to ``sys.path``,
+ which is used to locate the module source code.
.. function:: readmodule_ex(module, path=None)
- Like :func:`readmodule`, but the returned dictionary, in addition to
- mapping class names to class descriptor objects, also maps top-level
- function names to function descriptor objects. Moreover, if the module
- being read is a package, the key ``'__path__'`` in the returned
- dictionary has as its value a list which contains the package search
- path.
+ Return a dictionary-based tree containing a function or class
+ descriptors for each function and class defined in the module with a
+ ``def`` or ``class`` statement. The returned dictionary maps
+ module-level function and class names to their descriptors. Nested
+ objects are entered into the children dictionary of their parent. As
+ with readmodule, *module* names the module to be read and *path* is
+ prepended to sys.path. If the module being read is a package, the
+ returned dictionary has a key ``'__path__'`` whose value is a list
+ containing the package search path.
+.. versionadded:: 3.7
+ Descriptors for nested definitions. They are accessed through the
+ new children attibute. Each has a new parent attribute.
-.. _pyclbr-class-objects:
-
-Class Objects
--------------
-
-The :class:`Class` objects used as values in the dictionary returned by
-:func:`readmodule` and :func:`readmodule_ex` provide the following data
-attributes:
-
-
-.. attribute:: Class.module
-
- The name of the module defining the class described by the class descriptor.
-
-
-.. attribute:: Class.name
-
- The name of the class.
-
-
-.. attribute:: Class.super
-
- A list of :class:`Class` objects which describe the immediate base
- classes of the class being described. Classes which are named as
- superclasses but which are not discoverable by :func:`readmodule` are
- listed as a string with the class name instead of as :class:`Class`
- objects.
-
-
-.. attribute:: Class.methods
-
- A dictionary mapping method names to line numbers.
-
-
-.. attribute:: Class.file
-
- Name of the file containing the ``class`` statement defining the class.
-
-
-.. attribute:: Class.lineno
-
- The line number of the ``class`` statement within the file named by
- :attr:`~Class.file`.
+The descriptors returned by these functions are instances of
+Function and Class classes. Users are not expected to create instances
+of these classes.
.. _pyclbr-function-objects:
Function Objects
----------------
+Class :class:`Function` instances describe functions defined by def
+statements. They have the following attributes:
-The :class:`Function` objects used as values in the dictionary returned by
-:func:`readmodule_ex` provide the following attributes:
+
+.. attribute:: Function.file
+
+ Name of the file in which the function is defined.
.. attribute:: Function.module
- The name of the module defining the function described by the function
- descriptor.
+ The name of the module defining the function described.
.. attribute:: Function.name
@@ -104,13 +74,80 @@ The :class:`Function` objects used as values in the dictionary returned by
The name of the function.
-.. attribute:: Function.file
-
- Name of the file containing the ``def`` statement defining the function.
-
-
.. attribute:: Function.lineno
- The line number of the ``def`` statement within the file named by
- :attr:`~Function.file`.
+ The line number in the file where the definition starts.
+
+.. attribute:: Function.parent
+
+ For top-level functions, None. For nested functions, the parent.
+
+ .. versionadded:: 3.7
+
+
+.. attribute:: Function.children
+
+ A dictionary mapping names to descriptors for nested functions and
+ classes.
+
+ .. versionadded:: 3.7
+
+
+.. _pyclbr-class-objects:
+
+Class Objects
+-------------
+Class :class:`Class` instances describe classes defined by class
+statements. They have the same attributes as Functions and two more.
+
+
+.. attribute:: Class.file
+
+ Name of the file in which the class is defined.
+
+
+.. attribute:: Class.module
+
+ The name of the module defining the class described.
+
+
+.. attribute:: Class.name
+
+ The name of the class.
+
+
+.. attribute:: Class.lineno
+
+ The line number in the file where the definition starts.
+
+
+.. attribute:: Class.parent
+
+ For top-level classes, None. For nested classes, the parent.
+
+ .. versionadded:: 3.7
+
+
+.. attribute:: Class.children
+
+ A dictionary mapping names to descriptors for nested functions and
+ classes.
+
+ .. versionadded:: 3.7
+
+
+.. attribute:: Class.super
+
+ A list of :class:`Class` objects which describe the immediate base
+ classes of the class being described. Classes which are named as
+ superclasses but which are not discoverable by :func:`readmodule_ex`
+ are listed as a string with the class name instead of as
+ :class:`Class` objects.
+
+
+.. attribute:: Class.methods
+
+ A dictionary mapping method names to line numbers. This can be
+ derived from the newer children dictionary, but remains for
+ back-compatibility.
diff --git a/Doc/library/pydoc.rst b/Doc/library/pydoc.rst
index f1bfab9a3b1..f956b9d2176 100644
--- a/Doc/library/pydoc.rst
+++ b/Doc/library/pydoc.rst
@@ -70,6 +70,12 @@ will start a HTTP server on port 1234, allowing you to browse the
documentation at ``http://localhost:1234/`` in your preferred Web browser.
Specifying ``0`` as the port number will select an arbitrary unused port.
+:program:`pydoc -n ` will start the server listening at the given
+hostname. By default the hostname is 'localhost' but if you want the server to
+be reached from other machines, you may want to change the host name that the
+server responds to. During development this is especially useful if you want
+to run pydoc from within a container.
+
:program:`pydoc -b` will start the server and additionally open a web
browser to a module index page. Each served page has a navigation bar at the
top where you can *Get* help on an individual item, *Search* all modules with a
@@ -98,3 +104,6 @@ Reference Manual pages.
:mod:`pydoc` now uses :func:`inspect.signature` rather than
:func:`inspect.getfullargspec` to extract signature information from
callables.
+
+.. versionchanged:: 3.7
+ Added the ``-n`` option.
diff --git a/Doc/library/re.rst b/Doc/library/re.rst
index 9fafc0f462d..ca09a91c0d2 100644
--- a/Doc/library/re.rst
+++ b/Doc/library/re.rst
@@ -14,8 +14,9 @@
This module provides regular expression matching operations similar to
those found in Perl.
-Both patterns and strings to be searched can be Unicode strings as well as
-8-bit strings. However, Unicode strings and 8-bit strings cannot be mixed:
+Both patterns and strings to be searched can be Unicode strings (:class:`str`)
+as well as 8-bit strings (:class:`bytes`).
+However, Unicode strings and 8-bit strings cannot be mixed:
that is, you cannot match a Unicode string with a byte pattern or
vice-versa; similarly, when asking for a substitution, the replacement
string must be of the same type as both the pattern and the search string.
@@ -81,9 +82,7 @@ strings to be matched ``'in single quotes'``.)
Some characters, like ``'|'`` or ``'('``, are special. Special
characters either stand for classes of ordinary characters, or affect
-how the regular expressions around them are interpreted. Regular
-expression pattern strings may not contain null bytes, but can specify
-the null byte using a ``\number`` notation such as ``'\x00'``.
+how the regular expressions around them are interpreted.
Repetition qualifiers (``*``, ``+``, ``?``, ``{m,n}``, etc) cannot be
directly nested. This avoids ambiguity with the non-greedy modifier suffix
@@ -94,16 +93,16 @@ the expression ``(?:a{6})*`` matches any multiple of six ``'a'`` characters.
The special characters are:
-``'.'``
+``.``
(Dot.) In the default mode, this matches any character except a newline. If
the :const:`DOTALL` flag has been specified, this matches any character
including a newline.
-``'^'``
+``^``
(Caret.) Matches the start of the string, and in :const:`MULTILINE` mode also
matches immediately after each newline.
-``'$'``
+``$``
Matches the end of the string or just before the newline at the end of the
string, and in :const:`MULTILINE` mode also matches before a newline. ``foo``
matches both 'foo' and 'foobar', while the regular expression ``foo$`` matches
@@ -112,28 +111,28 @@ The special characters are:
a single ``$`` in ``'foo\n'`` will find two (empty) matches: one just before
the newline, and one at the end of the string.
-``'*'``
+``*``
Causes the resulting RE to match 0 or more repetitions of the preceding RE, as
many repetitions as are possible. ``ab*`` will match 'a', 'ab', or 'a' followed
by any number of 'b's.
-``'+'``
+``+``
Causes the resulting RE to match 1 or more repetitions of the preceding RE.
``ab+`` will match 'a' followed by any non-zero number of 'b's; it will not
match just 'a'.
-``'?'``
+``?``
Causes the resulting RE to match 0 or 1 repetitions of the preceding RE.
``ab?`` will match either 'a' or 'ab'.
``*?``, ``+?``, ``??``
The ``'*'``, ``'+'``, and ``'?'`` qualifiers are all :dfn:`greedy`; they match
as much text as possible. Sometimes this behaviour isn't desired; if the RE
- ``<.*>`` is matched against `` b ``, it will match the entire
- string, and not just ````. Adding ``?`` after the qualifier makes it
+ ``<.*>`` is matched against ``' b '``, it will match the entire
+ string, and not just ``''``. Adding ``?`` after the qualifier makes it
perform the match in :dfn:`non-greedy` or :dfn:`minimal` fashion; as *few*
characters as possible will be matched. Using the RE ``<.*?>`` will match
- only `` ``.
+ only ``' '``.
``{m}``
Specifies that exactly *m* copies of the previous RE should be matched; fewer
@@ -145,8 +144,8 @@ The special characters are:
RE, attempting to match as many repetitions as possible. For example,
``a{3,5}`` will match from 3 to 5 ``'a'`` characters. Omitting *m* specifies a
lower bound of zero, and omitting *n* specifies an infinite upper bound. As an
- example, ``a{4,}b`` will match ``aaaab`` or a thousand ``'a'`` characters
- followed by a ``b``, but not ``aaab``. The comma may not be omitted or the
+ example, ``a{4,}b`` will match ``'aaaab'`` or a thousand ``'a'`` characters
+ followed by a ``'b'``, but not ``'aaab'``. The comma may not be omitted or the
modifier would be confused with the previously described form.
``{m,n}?``
@@ -156,7 +155,7 @@ The special characters are:
6-character string ``'aaaaaa'``, ``a{3,5}`` will match 5 ``'a'`` characters,
while ``a{3,5}?`` will only match 3 characters.
-``'\'``
+``\``
Either escapes special characters (permitting you to match characters like
``'*'``, ``'?'``, and so forth), or signals a special sequence; special
sequences are discussed below.
@@ -179,8 +178,8 @@ The special characters are:
them by a ``'-'``, for example ``[a-z]`` will match any lowercase ASCII letter,
``[0-5][0-9]`` will match all the two-digits numbers from ``00`` to ``59``, and
``[0-9A-Fa-f]`` will match any hexadecimal digit. If ``-`` is escaped (e.g.
- ``[a\-z]``) or if it's placed as the first or last character (e.g. ``[a-]``),
- it will match a literal ``'-'``.
+ ``[a\-z]``) or if it's placed as the first or last character
+ (e.g. ``[-a]`` or ``[a-]``), it will match a literal ``'-'``.
* Special characters lose their special meaning inside sets. For example,
``[(+*)]`` will match any of the literal characters ``'('``, ``'+'``,
@@ -201,13 +200,27 @@ The special characters are:
place it at the beginning of the set. For example, both ``[()[\]{}]`` and
``[]()[{}]`` will both match a parenthesis.
-``'|'``
- ``A|B``, where A and B can be arbitrary REs, creates a regular expression that
- will match either A or B. An arbitrary number of REs can be separated by the
+ * Support of nested sets and set operations as in `Unicode Technical
+ Standard #18`_ might be added in the future. This would change the
+ syntax, so to facilitate this change a :exc:`FutureWarning` will be raised
+ in ambiguous cases for the time being.
+ That include sets starting with a literal ``'['`` or containing literal
+ character sequences ``'--'``, ``'&&'``, ``'~~'``, and ``'||'``. To
+ avoid a warning escape them with a backslash.
+
+ .. _Unicode Technical Standard #18: https://unicode.org/reports/tr18/
+
+ .. versionchanged:: 3.7
+ :exc:`FutureWarning` is raised if a character set contains constructs
+ that will change semantically in the future.
+
+``|``
+ ``A|B``, where *A* and *B* can be arbitrary REs, creates a regular expression that
+ will match either *A* or *B*. An arbitrary number of REs can be separated by the
``'|'`` in this way. This can be used inside groups (see below) as well. As
the target string is scanned, REs separated by ``'|'`` are tried from left to
right. When one pattern completely matches, that branch is accepted. This means
- that once ``A`` matches, ``B`` will not be tested further, even if it would
+ that once *A* matches, *B* will not be tested further, even if it would
produce a longer overall match. In other words, the ``'|'`` operator is never
greedy. To match a literal ``'|'``, use ``\|``, or enclose it inside a
character class, as in ``[|]``.
@@ -217,7 +230,7 @@ The special characters are:
start and end of a group; the contents of a group can be retrieved after a match
has been performed, and can be matched later in the string with the ``\number``
special sequence, described below. To match the literals ``'('`` or ``')'``,
- use ``\(`` or ``\)``, or enclose them inside a character class: ``[(] [)]``.
+ use ``\(`` or ``\)``, or enclose them inside a character class: ``[(]``, ``[)]``.
``(?...)``
This is an extension notation (a ``'?'`` following a ``'('`` is not meaningful
@@ -232,10 +245,11 @@ The special characters are:
letters set the corresponding flags: :const:`re.A` (ASCII-only matching),
:const:`re.I` (ignore case), :const:`re.L` (locale dependent),
:const:`re.M` (multi-line), :const:`re.S` (dot matches all),
- and :const:`re.X` (verbose), for the entire regular expression. (The
- flags are described in :ref:`contents-of-module-re`.) This
- is useful if you wish to include the flags as part of the regular
- expression, instead of passing a *flag* argument to the
+ :const:`re.U` (Unicode matching), and :const:`re.X` (verbose),
+ for the entire regular expression.
+ (The flags are described in :ref:`contents-of-module-re`.)
+ This is useful if you wish to include the flags as part of the
+ regular expression, instead of passing a *flag* argument to the
:func:`re.compile` function. Flags should be used first in the
expression string.
@@ -245,16 +259,32 @@ The special characters are:
*cannot* be retrieved after performing a match or referenced later in the
pattern.
-``(?imsx-imsx:...)``
- (Zero or more letters from the set ``'i'``, ``'m'``, ``'s'``, ``'x'``,
- optionally followed by ``'-'`` followed by one or more letters from the
- same set.) The letters set or removes the corresponding flags:
- :const:`re.I` (ignore case), :const:`re.M` (multi-line), :const:`re.S`
- (dot matches all), and :const:`re.X` (verbose), for the part of the
- expression. (The flags are described in :ref:`contents-of-module-re`.)
+``(?aiLmsux-imsx:...)``
+ (Zero or more letters from the set ``'a'``, ``'i'``, ``'L'``, ``'m'``,
+ ``'s'``, ``'u'``, ``'x'``, optionally followed by ``'-'`` followed by
+ one or more letters from the ``'i'``, ``'m'``, ``'s'``, ``'x'``.)
+ The letters set or remove the corresponding flags:
+ :const:`re.A` (ASCII-only matching), :const:`re.I` (ignore case),
+ :const:`re.L` (locale dependent), :const:`re.M` (multi-line),
+ :const:`re.S` (dot matches all), :const:`re.U` (Unicode matching),
+ and :const:`re.X` (verbose), for the part of the expression.
+ (The flags are described in :ref:`contents-of-module-re`.)
+
+ The letters ``'a'``, ``'L'`` and ``'u'`` are mutually exclusive when used
+ as inline flags, so they can't be combined or follow ``'-'``. Instead,
+ when one of them appears in an inline group, it overrides the matching mode
+ in the enclosing group. In Unicode patterns ``(?a:...)`` switches to
+ ASCII-only matching, and ``(?u:...)`` switches to Unicode matching
+ (default). In byte pattern ``(?L:...)`` switches to locale depending
+ matching, and ``(?a:...)`` switches to ASCII-only matching (default).
+ This override is only in effect for the narrow inline group, and the
+ original matching mode is restored outside of the group.
.. versionadded:: 3.6
+ .. versionchanged:: 3.7
+ The letters ``'a'``, ``'L'`` and ``'u'`` also can be used in a group.
+
``(?P...)``
Similar to regular parentheses, but the substring matched by the group is
accessible via the symbolic group name *name*. Group names must be valid
@@ -272,10 +302,10 @@ The special characters are:
| in the same pattern itself | * ``(?P=quote)`` (as shown) |
| | * ``\1`` |
+---------------------------------------+----------------------------------+
- | when processing match object ``m`` | * ``m.group('quote')`` |
+ | when processing match object *m* | * ``m.group('quote')`` |
| | * ``m.end('quote')`` (etc.) |
+---------------------------------------+----------------------------------+
- | in a string passed to the ``repl`` | * ``\g`` |
+ | in a string passed to the *repl* | * ``\g`` |
| argument of ``re.sub()`` | * ``\g<1>`` |
| | * ``\1`` |
+---------------------------------------+----------------------------------+
@@ -289,18 +319,18 @@ The special characters are:
``(?=...)``
Matches if ``...`` matches next, but doesn't consume any of the string. This is
- called a lookahead assertion. For example, ``Isaac (?=Asimov)`` will match
+ called a :dfn:`lookahead assertion`. For example, ``Isaac (?=Asimov)`` will match
``'Isaac '`` only if it's followed by ``'Asimov'``.
``(?!...)``
- Matches if ``...`` doesn't match next. This is a negative lookahead assertion.
+ Matches if ``...`` doesn't match next. This is a :dfn:`negative lookahead assertion`.
For example, ``Isaac (?!Asimov)`` will match ``'Isaac '`` only if it's *not*
followed by ``'Asimov'``.
``(?<=...)``
Matches if the current position in the string is preceded by a match for ``...``
that ends at the current position. This is called a :dfn:`positive lookbehind
- assertion`. ``(?<=abc)def`` will find a match in ``abcdef``, since the
+ assertion`. ``(?<=abc)def`` will find a match in ``'abcdef'``, since the
lookbehind will back up 3 characters and check if the contained pattern matches.
The contained pattern must only match strings of some fixed length, meaning that
``abc`` or ``a|b`` are allowed, but ``a*`` and ``a{3,4}`` are not. Note that
@@ -358,44 +388,41 @@ character ``'$'``.
``\b``
Matches the empty string, but only at the beginning or end of a word.
- A word is defined as a sequence of Unicode alphanumeric or underscore
- characters, so the end of a word is indicated by whitespace or a
- non-alphanumeric, non-underscore Unicode character. Note that formally,
+ A word is defined as a sequence of word characters. Note that formally,
``\b`` is defined as the boundary between a ``\w`` and a ``\W`` character
(or vice versa), or between ``\w`` and the beginning/end of the string.
This means that ``r'\bfoo\b'`` matches ``'foo'``, ``'foo.'``, ``'(foo)'``,
``'bar foo baz'`` but not ``'foobar'`` or ``'foo3'``.
- By default Unicode alphanumerics are the ones used, but this can be changed
- by using the :const:`ASCII` flag. Inside a character range, ``\b``
- represents the backspace character, for compatibility with Python's string
- literals.
+ By default Unicode alphanumerics are the ones used in Unicode patterns, but
+ this can be changed by using the :const:`ASCII` flag. Word boundaries are
+ determined by the current locale if the :const:`LOCALE` flag is used.
+ Inside a character range, ``\b`` represents the backspace character, for
+ compatibility with Python's string literals.
``\B``
Matches the empty string, but only when it is *not* at the beginning or end
of a word. This means that ``r'py\B'`` matches ``'python'``, ``'py3'``,
``'py2'``, but not ``'py'``, ``'py.'``, or ``'py!'``.
- ``\B`` is just the opposite of ``\b``, so word characters are
- Unicode alphanumerics or the underscore, although this can be changed
- by using the :const:`ASCII` flag.
+ ``\B`` is just the opposite of ``\b``, so word characters in Unicode
+ patterns are Unicode alphanumerics or the underscore, although this can
+ be changed by using the :const:`ASCII` flag. Word boundaries are
+ determined by the current locale if the :const:`LOCALE` flag is used.
``\d``
For Unicode (str) patterns:
Matches any Unicode decimal digit (that is, any character in
Unicode character category [Nd]). This includes ``[0-9]``, and
also many other digit characters. If the :const:`ASCII` flag is
- used only ``[0-9]`` is matched (but the flag affects the entire
- regular expression, so in such cases using an explicit ``[0-9]``
- may be a better choice).
+ used only ``[0-9]`` is matched.
+
For 8-bit (bytes) patterns:
Matches any decimal digit; this is equivalent to ``[0-9]``.
``\D``
- Matches any character which is not a Unicode decimal digit. This is
+ Matches any character which is not a decimal digit. This is
the opposite of ``\d``. If the :const:`ASCII` flag is used this
- becomes the equivalent of ``[^0-9]`` (but the flag affects the entire
- regular expression, so in such cases using an explicit ``[^0-9]`` may
- be a better choice).
+ becomes the equivalent of ``[^0-9]``.
``\s``
For Unicode (str) patterns:
@@ -403,39 +430,36 @@ character ``'$'``.
``[ \t\n\r\f\v]``, and also many other characters, for example the
non-breaking spaces mandated by typography rules in many
languages). If the :const:`ASCII` flag is used, only
- ``[ \t\n\r\f\v]`` is matched (but the flag affects the entire
- regular expression, so in such cases using an explicit
- ``[ \t\n\r\f\v]`` may be a better choice).
+ ``[ \t\n\r\f\v]`` is matched.
For 8-bit (bytes) patterns:
Matches characters considered whitespace in the ASCII character set;
this is equivalent to ``[ \t\n\r\f\v]``.
``\S``
- Matches any character which is not a Unicode whitespace character. This is
+ Matches any character which is not a whitespace character. This is
the opposite of ``\s``. If the :const:`ASCII` flag is used this
- becomes the equivalent of ``[^ \t\n\r\f\v]`` (but the flag affects the entire
- regular expression, so in such cases using an explicit ``[^ \t\n\r\f\v]`` may
- be a better choice).
+ becomes the equivalent of ``[^ \t\n\r\f\v]``.
``\w``
For Unicode (str) patterns:
Matches Unicode word characters; this includes most characters
that can be part of a word in any language, as well as numbers and
the underscore. If the :const:`ASCII` flag is used, only
- ``[a-zA-Z0-9_]`` is matched (but the flag affects the entire
- regular expression, so in such cases using an explicit
- ``[a-zA-Z0-9_]`` may be a better choice).
+ ``[a-zA-Z0-9_]`` is matched.
+
For 8-bit (bytes) patterns:
Matches characters considered alphanumeric in the ASCII character set;
- this is equivalent to ``[a-zA-Z0-9_]``.
+ this is equivalent to ``[a-zA-Z0-9_]``. If the :const:`LOCALE` flag is
+ used, matches characters considered alphanumeric in the current locale
+ and the underscore.
``\W``
- Matches any character which is not a Unicode word character. This is
+ Matches any character which is not a word character. This is
the opposite of ``\w``. If the :const:`ASCII` flag is used this
- becomes the equivalent of ``[^a-zA-Z0-9_]`` (but the flag affects the
- entire regular expression, so in such cases using an explicit
- ``[^a-zA-Z0-9_]`` may be a better choice).
+ becomes the equivalent of ``[^a-zA-Z0-9_]``. If the :const:`LOCALE` flag is
+ used, matches characters considered alphanumeric in the current locale
+ and the underscore.
``\Z``
Matches only at the end of the string.
@@ -443,15 +467,15 @@ character ``'$'``.
Most of the standard escapes supported by Python string literals are also
accepted by the regular expression parser::
- \a \b \f \n \N
- \r \t \u \U
- \v \x \\
+ \a \b \f \n
+ \N \r \t \u
+ \U \v \x \\
(Note that ``\b`` is used to represent word boundaries, and means "backspace"
only inside character classes.)
``'\u'``, ``'\U'``, and ``'\N'`` escape sequences are only recognized in Unicode
-patterns. In bytes patterns they are not treated specially.
+patterns. In bytes patterns they are errors.
Octal escapes are included in a limited form. If the first digit is a 0, or if
there are three octal digits, it is considered an octal escape. Otherwise, it is
@@ -493,9 +517,10 @@ form.
.. function:: compile(pattern, flags=0)
- Compile a regular expression pattern into a regular expression object, which
- can be used for matching using its :func:`~regex.match` and
- :func:`~regex.search` methods, described below.
+ Compile a regular expression pattern into a :ref:`regular expression object
+ `, which can be used for matching using its
+ :func:`~Pattern.match`, :func:`~Pattern.search` and other methods, described
+ below.
The expression's behaviour can be modified by specifying a *flags* value.
Values can be any of the following variables, combined using bitwise OR (the
@@ -528,6 +553,7 @@ form.
Make ``\w``, ``\W``, ``\b``, ``\B``, ``\d``, ``\D``, ``\s`` and ``\S``
perform ASCII-only matching instead of full Unicode matching. This is only
meaningful for Unicode patterns, and is ignored for byte patterns.
+ Corresponds to the inline flag ``(?a)``.
Note that for backward compatibility, the :const:`re.U` flag still
exists (as well as its synonym :const:`re.UNICODE` and its embedded
@@ -539,26 +565,38 @@ form.
.. data:: DEBUG
Display debug information about compiled expression.
+ No corresponding inline flag.
.. data:: I
IGNORECASE
Perform case-insensitive matching; expressions like ``[A-Z]`` will also
- match lowercase letters. The current locale does not change the effect of
- this flag. Full Unicode matching (such as ``Ü`` matching ``ü``) also
- works unless the :const:`re.ASCII` flag is also used to disable non-ASCII
- matches.
+ match lowercase letters. Full Unicode matching (such as ``Ü`` matching
+ ``ü``) also works unless the :const:`re.ASCII` flag is used to disable
+ non-ASCII matches. The current locale does not change the effect of this
+ flag unless the :const:`re.LOCALE` flag is also used.
+ Corresponds to the inline flag ``(?i)``.
+ Note that when the Unicode patterns ``[a-z]`` or ``[A-Z]`` are used in
+ combination with the :const:`IGNORECASE` flag, they will match the 52 ASCII
+ letters and 4 additional non-ASCII letters: 'İ' (U+0130, Latin capital
+ letter I with dot above), 'ı' (U+0131, Latin small letter dotless i),
+ 'ſ' (U+017F, Latin small letter long s) and 'K' (U+212A, Kelvin sign).
+ If the :const:`ASCII` flag is used, only letters 'a' to 'z'
+ and 'A' to 'Z' are matched.
.. data:: L
LOCALE
- Make ``\w``, ``\W``, ``\b``, ``\B``, ``\s`` and ``\S`` dependent on the
- current locale. The use of this flag is discouraged as the locale mechanism
- is very unreliable, and it only handles one "culture" at a time anyway;
- you should use Unicode matching instead, which is the default in Python 3
- for Unicode (str) patterns. This flag can be used only with bytes patterns.
+ Make ``\w``, ``\W``, ``\b``, ``\B`` and case-insensitive matching
+ dependent on the current locale. This flag can be used only with bytes
+ patterns. The use of this flag is discouraged as the locale mechanism
+ is very unreliable, it only handles one "culture" at a time, and it only
+ works with 8-bit locales. Unicode matching is already enabled by default
+ in Python 3 for Unicode (str) patterns, and it is able to handle different
+ locales/languages.
+ Corresponds to the inline flag ``(?L)``.
.. versionchanged:: 3.6
:const:`re.LOCALE` can be used only with bytes patterns and is
@@ -579,6 +617,7 @@ form.
end of each line (immediately preceding each newline). By default, ``'^'``
matches only at the beginning of the string, and ``'$'`` only at the end of the
string and immediately before the newline (if any) at the end of the string.
+ Corresponds to the inline flag ``(?m)``.
.. data:: S
@@ -586,6 +625,7 @@ form.
Make the ``'.'`` special character match any character at all, including a
newline; without this flag, ``'.'`` will match anything *except* a newline.
+ Corresponds to the inline flag ``(?s)``.
.. data:: X
@@ -594,7 +634,8 @@ form.
This flag allows you to write regular expressions that look nicer and are
more readable by allowing you to visually separate logical sections of the
pattern and add comments. Whitespace within the pattern is ignored, except
- when in a character class or when preceded by an unescaped backslash.
+ when in a character class, or when preceded by an unescaped backslash,
+ or within tokens like ``*?``, ``(?:`` or ``(?P<...>``.
When a line contains a ``#`` that is not in a character class and is not
preceded by an unescaped backslash, all characters from the leftmost such
``#`` through the end of the line are ignored.
@@ -607,7 +648,7 @@ form.
\d * # some fractional digits""", re.X)
b = re.compile(r"\d+\.\d*")
-
+ Corresponds to the inline flag ``(?x)``.
.. function:: search(pattern, string, flags=0)
@@ -662,7 +703,7 @@ form.
If there are capturing groups in the separator and it matches at the start of
the string, the result will start with an empty string. The same holds for
- the end of the string:
+ the end of the string::
>>> re.split('(\W+)', '...words, words...')
['', '...', 'words', ', ', 'words', '...', '']
@@ -673,7 +714,7 @@ form.
.. note::
:func:`split` doesn't currently split a string on an empty pattern match.
- For example:
+ For example::
>>> re.split('x*', 'axbc')
['a', 'bc']
@@ -730,7 +771,7 @@ form.
converted to a single newline character, ``\r`` is converted to a carriage return, and
so forth. Unknown escapes such as ``\&`` are left alone. Backreferences, such
as ``\6``, are replaced with the substring matched by group 6 in the pattern.
- For example:
+ For example::
>>> re.sub(r'def\s+([a-zA-Z_][a-zA-Z_0-9]*)\s*\(\s*\):',
... r'static PyObject*\npy_\1(void)\n{',
@@ -738,8 +779,8 @@ form.
'static PyObject*\npy_myfunc(void)\n{'
If *repl* is a function, it is called for every non-overlapping occurrence of
- *pattern*. The function takes a single match object argument, and returns the
- replacement string. For example:
+ *pattern*. The function takes a single :ref:`match object `
+ argument, and returns the replacement string. For example::
>>> def dashrepl(matchobj):
... if matchobj.group(0) == '-': return ' '
@@ -749,7 +790,7 @@ form.
>>> re.sub(r'\sAND\s', ' & ', 'Baked Beans And Spam', flags=re.IGNORECASE)
'Baked Beans & Spam'
- The pattern may be a string or an RE object.
+ The pattern may be a string or a :ref:`pattern object `.
The optional argument *count* is the maximum number of pattern occurrences to be
replaced; *count* must be a non-negative integer. If omitted or zero, all
@@ -805,12 +846,20 @@ form.
>>> legal_chars = string.ascii_lowercase + string.digits + "!#$%&'*+-.^_`|~:"
>>> print('[%s]+' % re.escape(legal_chars))
- [abcdefghijklmnopqrstuvwxyz0123456789!\#\$%&'\*\+\-\.\^_`\|~:]+
+ [abcdefghijklmnopqrstuvwxyz0123456789!\#\$%\&'\*\+\-\.\^_`\|\~:]+
>>> operators = ['+', '-', '*', '/', '**']
>>> print('|'.join(map(re.escape, sorted(operators, reverse=True))))
/|\-|\+|\*\*|\*
+ This functions must not be used for the replacement string in :func:`sub`
+ and :func:`subn`, only backslashes should be escaped. For example::
+
+ >>> digits_re = r'\d+'
+ >>> sample = '/usr/sbin/sendmail - 0 errors, 12 warnings'
+ >>> print(re.sub(digits_re, digits_re.replace('\\', r'\\'), sample))
+ /usr/sbin/sendmail - \d+ errors, \d+ warnings
+
.. versionchanged:: 3.3
The ``'_'`` character is no longer escaped.
@@ -863,7 +912,7 @@ Regular Expression Objects
Compiled regular expression objects support the following methods and
attributes:
-.. method:: regex.search(string[, pos[, endpos]])
+.. method:: Pattern.search(string[, pos[, endpos]])
Scan through *string* looking for the first location where this regular
expression produces a match, and return a corresponding :ref:`match object
@@ -882,15 +931,15 @@ attributes:
from *pos* to ``endpos - 1`` will be searched for a match. If *endpos* is less
than *pos*, no match will be found; otherwise, if *rx* is a compiled regular
expression object, ``rx.search(string, 0, 50)`` is equivalent to
- ``rx.search(string[:50], 0)``.
+ ``rx.search(string[:50], 0)``. ::
- >>> pattern = re.compile("d")
- >>> pattern.search("dog") # Match at index 0
- <_sre.SRE_Match object; span=(0, 1), match='d'>
- >>> pattern.search("dog", 1) # No match; search doesn't include the "d"
+ >>> pattern = re.compile("d")
+ >>> pattern.search("dog") # Match at index 0
+
+ >>> pattern.search("dog", 1) # No match; search doesn't include the "d"
-.. method:: regex.match(string[, pos[, endpos]])
+.. method:: Pattern.match(string[, pos[, endpos]])
If zero or more characters at the *beginning* of *string* match this regular
expression, return a corresponding :ref:`match object `.
@@ -898,86 +947,86 @@ attributes:
different from a zero-length match.
The optional *pos* and *endpos* parameters have the same meaning as for the
- :meth:`~regex.search` method.
+ :meth:`~Pattern.search` method. ::
- >>> pattern = re.compile("o")
- >>> pattern.match("dog") # No match as "o" is not at the start of "dog".
- >>> pattern.match("dog", 1) # Match as "o" is the 2nd character of "dog".
- <_sre.SRE_Match object; span=(1, 2), match='o'>
+ >>> pattern = re.compile("o")
+ >>> pattern.match("dog") # No match as "o" is not at the start of "dog".
+ >>> pattern.match("dog", 1) # Match as "o" is the 2nd character of "dog".
+
If you want to locate a match anywhere in *string*, use
- :meth:`~regex.search` instead (see also :ref:`search-vs-match`).
+ :meth:`~Pattern.search` instead (see also :ref:`search-vs-match`).
-.. method:: regex.fullmatch(string[, pos[, endpos]])
+.. method:: Pattern.fullmatch(string[, pos[, endpos]])
If the whole *string* matches this regular expression, return a corresponding
:ref:`match object `. Return ``None`` if the string does not
match the pattern; note that this is different from a zero-length match.
The optional *pos* and *endpos* parameters have the same meaning as for the
- :meth:`~regex.search` method.
+ :meth:`~Pattern.search` method. ::
- >>> pattern = re.compile("o[gh]")
- >>> pattern.fullmatch("dog") # No match as "o" is not at the start of "dog".
- >>> pattern.fullmatch("ogre") # No match as not the full string matches.
- >>> pattern.fullmatch("doggie", 1, 3) # Matches within given limits.
- <_sre.SRE_Match object; span=(1, 3), match='og'>
+ >>> pattern = re.compile("o[gh]")
+ >>> pattern.fullmatch("dog") # No match as "o" is not at the start of "dog".
+ >>> pattern.fullmatch("ogre") # No match as not the full string matches.
+ >>> pattern.fullmatch("doggie", 1, 3) # Matches within given limits.
+
.. versionadded:: 3.4
-.. method:: regex.split(string, maxsplit=0)
+.. method:: Pattern.split(string, maxsplit=0)
Identical to the :func:`split` function, using the compiled pattern.
-.. method:: regex.findall(string[, pos[, endpos]])
+.. method:: Pattern.findall(string[, pos[, endpos]])
Similar to the :func:`findall` function, using the compiled pattern, but
also accepts optional *pos* and *endpos* parameters that limit the search
- region like for :meth:`match`.
+ region like for :meth:`search`.
-.. method:: regex.finditer(string[, pos[, endpos]])
+.. method:: Pattern.finditer(string[, pos[, endpos]])
Similar to the :func:`finditer` function, using the compiled pattern, but
also accepts optional *pos* and *endpos* parameters that limit the search
- region like for :meth:`match`.
+ region like for :meth:`search`.
-.. method:: regex.sub(repl, string, count=0)
+.. method:: Pattern.sub(repl, string, count=0)
Identical to the :func:`sub` function, using the compiled pattern.
-.. method:: regex.subn(repl, string, count=0)
+.. method:: Pattern.subn(repl, string, count=0)
Identical to the :func:`subn` function, using the compiled pattern.
-.. attribute:: regex.flags
+.. attribute:: Pattern.flags
The regex matching flags. This is a combination of the flags given to
:func:`.compile`, any ``(?...)`` inline flags in the pattern, and implicit
flags such as :data:`UNICODE` if the pattern is a Unicode string.
-.. attribute:: regex.groups
+.. attribute:: Pattern.groups
The number of capturing groups in the pattern.
-.. attribute:: regex.groupindex
+.. attribute:: Pattern.groupindex
A dictionary mapping any symbolic group names defined by ``(?P)`` to group
numbers. The dictionary is empty if no symbolic groups were used in the
pattern.
-.. attribute:: regex.pattern
+.. attribute:: Pattern.pattern
- The pattern string from which the RE object was compiled.
+ The pattern string from which the pattern object was compiled.
.. versionchanged:: 3.7
@@ -991,7 +1040,7 @@ Match Objects
-------------
Match objects always have a boolean value of ``True``.
-Since :meth:`~regex.match` and :meth:`~regex.search` return ``None``
+Since :meth:`~Pattern.match` and :meth:`~Pattern.search` return ``None``
when there is no match, you can test whether there was a match with a simple
``if`` statement::
@@ -1002,10 +1051,10 @@ when there is no match, you can test whether there was a match with a simple
Match objects support the following methods and attributes:
-.. method:: match.expand(template)
+.. method:: Match.expand(template)
Return the string obtained by doing backslash substitution on the template
- string *template*, as done by the :meth:`~regex.sub` method.
+ string *template*, as done by the :meth:`~Pattern.sub` method.
Escapes such as ``\n`` are converted to the appropriate characters,
and numeric backreferences (``\1``, ``\2``) and named backreferences
(``\g<1>``, ``\g``) are replaced by the contents of the
@@ -1014,7 +1063,7 @@ Match objects support the following methods and attributes:
.. versionchanged:: 3.5
Unmatched groups are replaced with an empty string.
-.. method:: match.group([group1, ...])
+.. method:: Match.group([group1, ...])
Returns one or more subgroups of the match. If there is a single argument, the
result is a single string; if there are multiple arguments, the result is a
@@ -1026,7 +1075,7 @@ Match objects support the following methods and attributes:
pattern, an :exc:`IndexError` exception is raised. If a group is contained in a
part of the pattern that did not match, the corresponding result is ``None``.
If a group is contained in a part of the pattern that matched multiple times,
- the last match is returned.
+ the last match is returned. ::
>>> m = re.match(r"(\w+) (\w+)", "Isaac Newton, physicist")
>>> m.group(0) # The entire match
@@ -1043,7 +1092,7 @@ Match objects support the following methods and attributes:
string argument is not used as a group name in the pattern, an :exc:`IndexError`
exception is raised.
- A moderately complicated example:
+ A moderately complicated example::
>>> m = re.match(r"(?P\w+) (?P\w+)", "Malcolm Reynolds")
>>> m.group('first_name')
@@ -1051,24 +1100,24 @@ Match objects support the following methods and attributes:
>>> m.group('last_name')
'Reynolds'
- Named groups can also be referred to by their index:
+ Named groups can also be referred to by their index::
>>> m.group(1)
'Malcolm'
>>> m.group(2)
'Reynolds'
- If a group matches multiple times, only the last match is accessible:
+ If a group matches multiple times, only the last match is accessible::
>>> m = re.match(r"(..)+", "a1b2c3") # Matches 3 times.
>>> m.group(1) # Returns only the last match.
'c3'
-.. method:: match.__getitem__(g)
+.. method:: Match.__getitem__(g)
This is identical to ``m.group(g)``. This allows easier access to
- an individual group from a match:
+ an individual group from a match::
>>> m = re.match(r"(\w+) (\w+)", "Isaac Newton, physicist")
>>> m[0] # The entire match
@@ -1081,13 +1130,13 @@ Match objects support the following methods and attributes:
.. versionadded:: 3.6
-.. method:: match.groups(default=None)
+.. method:: Match.groups(default=None)
Return a tuple containing all the subgroups of the match, from 1 up to however
many groups are in the pattern. The *default* argument is used for groups that
did not participate in the match; it defaults to ``None``.
- For example:
+ For example::
>>> m = re.match(r"(\d+)\.(\d+)", "24.1632")
>>> m.groups()
@@ -1095,7 +1144,7 @@ Match objects support the following methods and attributes:
If we make the decimal place and everything after it optional, not all groups
might participate in the match. These groups will default to ``None`` unless
- the *default* argument is given:
+ the *default* argument is given::
>>> m = re.match(r"(\d+)\.?(\d+)?", "24")
>>> m.groups() # Second group defaults to None.
@@ -1104,19 +1153,19 @@ Match objects support the following methods and attributes:
('24', '0')
-.. method:: match.groupdict(default=None)
+.. method:: Match.groupdict(default=None)
Return a dictionary containing all the *named* subgroups of the match, keyed by
the subgroup name. The *default* argument is used for groups that did not
- participate in the match; it defaults to ``None``. For example:
+ participate in the match; it defaults to ``None``. For example::
>>> m = re.match(r"(?P\w+) (?P\w+)", "Malcolm Reynolds")
>>> m.groupdict()
{'first_name': 'Malcolm', 'last_name': 'Reynolds'}
-.. method:: match.start([group])
- match.end([group])
+.. method:: Match.start([group])
+ Match.end([group])
Return the indices of the start and end of the substring matched by *group*;
*group* defaults to zero (meaning the whole matched substring). Return ``-1`` if
@@ -1131,7 +1180,7 @@ Match objects support the following methods and attributes:
``m.start(0)`` is 1, ``m.end(0)`` is 2, ``m.start(1)`` and ``m.end(1)`` are both
2, and ``m.start(2)`` raises an :exc:`IndexError` exception.
- An example that will remove *remove_this* from email addresses:
+ An example that will remove *remove_this* from email addresses::
>>> email = "tony@tiremove_thisger.net"
>>> m = re.search("remove_this", email)
@@ -1139,28 +1188,28 @@ Match objects support the following methods and attributes:
'tony@tiger.net'
-.. method:: match.span([group])
+.. method:: Match.span([group])
For a match *m*, return the 2-tuple ``(m.start(group), m.end(group))``. Note
that if *group* did not contribute to the match, this is ``(-1, -1)``.
*group* defaults to zero, the entire match.
-.. attribute:: match.pos
+.. attribute:: Match.pos
- The value of *pos* which was passed to the :meth:`~regex.search` or
- :meth:`~regex.match` method of a :ref:`regex object `. This is
+ The value of *pos* which was passed to the :meth:`~Pattern.search` or
+ :meth:`~Pattern.match` method of a :ref:`regex object `. This is
the index into the string at which the RE engine started looking for a match.
-.. attribute:: match.endpos
+.. attribute:: Match.endpos
- The value of *endpos* which was passed to the :meth:`~regex.search` or
- :meth:`~regex.match` method of a :ref:`regex object `. This is
+ The value of *endpos* which was passed to the :meth:`~Pattern.search` or
+ :meth:`~Pattern.match` method of a :ref:`regex object `. This is
the index into the string beyond which the RE engine will not go.
-.. attribute:: match.lastindex
+.. attribute:: Match.lastindex
The integer index of the last matched capturing group, or ``None`` if no group
was matched at all. For example, the expressions ``(a)b``, ``((a)(b))``, and
@@ -1169,21 +1218,21 @@ Match objects support the following methods and attributes:
string.
-.. attribute:: match.lastgroup
+.. attribute:: Match.lastgroup
The name of the last matched capturing group, or ``None`` if the group didn't
have a name, or if no group was matched at all.
-.. attribute:: match.re
+.. attribute:: Match.re
- The regular expression object whose :meth:`~regex.match` or
- :meth:`~regex.search` method produced this match instance.
+ The :ref:`regular expression object ` whose :meth:`~Pattern.match` or
+ :meth:`~Pattern.search` method produced this match instance.
-.. attribute:: match.string
+.. attribute:: Match.string
- The string passed to :meth:`~regex.match` or :meth:`~regex.search`.
+ The string passed to :meth:`~Pattern.match` or :meth:`~Pattern.search`.
.. versionchanged:: 3.7
@@ -1215,7 +1264,7 @@ a 5-character string with each character representing a card, "a" for ace, "k"
for king, "q" for queen, "j" for jack, "t" for 10, and "2" through "9"
representing the card with that value.
-To see if a given string is a valid hand, one could do the following:
+To see if a given string is a valid hand, one could do the following::
>>> valid = re.compile(r"^[a2-9tjqk]{5}$")
>>> displaymatch(valid.match("akt5q")) # Valid.
@@ -1226,7 +1275,7 @@ To see if a given string is a valid hand, one could do the following:
""
That last hand, ``"727ak"``, contained a pair, or two of the same valued cards.
-To match this with a regular expression, one could use backreferences as such:
+To match this with a regular expression, one could use backreferences as such::
>>> pair = re.compile(r".*(.).*\1")
>>> displaymatch(pair.match("717ak")) # Pair of 7s.
@@ -1236,7 +1285,7 @@ To match this with a regular expression, one could use backreferences as such:
""
To find out what card the pair consists of, one could use the
-:meth:`~match.group` method of the match object in the following manner:
+:meth:`~Match.group` method of the match object in the following manner:
.. doctest::
@@ -1316,7 +1365,7 @@ For example::
>>> re.match("c", "abcdef") # No match
>>> re.search("c", "abcdef") # Match
- <_sre.SRE_Match object; span=(2, 3), match='c'>
+
Regular expressions beginning with ``'^'`` can be used with :func:`search` to
restrict the match at the beginning of the string::
@@ -1324,15 +1373,15 @@ restrict the match at the beginning of the string::
>>> re.match("c", "abcdef") # No match
>>> re.search("^c", "abcdef") # No match
>>> re.search("^a", "abcdef") # Match
- <_sre.SRE_Match object; span=(0, 1), match='a'>
+
Note however that in :const:`MULTILINE` mode :func:`match` only matches at the
beginning of the string, whereas using :func:`search` with a regular expression
-beginning with ``'^'`` will match at the beginning of each line.
+beginning with ``'^'`` will match at the beginning of each line. ::
>>> re.match('X', 'A\nB\nX', re.MULTILINE) # No match
>>> re.search('^X', 'A\nB\nX', re.MULTILINE) # Match
- <_sre.SRE_Match object; span=(4, 5), match='X'>
+
Making a Phonebook
@@ -1344,7 +1393,7 @@ easily read and modified by Python as demonstrated in the following example that
creates a phonebook.
First, here is the input. Normally it may come from a file, here we are using
-triple-quoted string syntax:
+triple-quoted string syntax::
>>> text = """Ross McFluff: 834.345.1254 155 Elm Street
...
@@ -1419,7 +1468,7 @@ Finding all Adverbs
:func:`findall` matches *all* occurrences of a pattern, not just the first
one as :func:`search` does. For example, if one was a writer and wanted to
find all of the adverbs in some text, he or she might use :func:`findall` in
-the following manner:
+the following manner::
>>> text = "He was carefully disguised but captured quickly by police."
>>> re.findall(r"\w+ly", text)
@@ -1433,7 +1482,7 @@ If one wants more information about all matches of a pattern than the matched
text, :func:`finditer` is useful as it provides :ref:`match objects
` instead of strings. Continuing with the previous example, if
one was a writer who wanted to find all of the adverbs *and their positions* in
-some text, he or she would use :func:`finditer` in the following manner:
+some text, he or she would use :func:`finditer` in the following manner::
>>> text = "He was carefully disguised but captured quickly by police."
>>> for m in re.finditer(r"\w+ly", text):
@@ -1448,22 +1497,22 @@ Raw String Notation
Raw string notation (``r"text"``) keeps regular expressions sane. Without it,
every backslash (``'\'``) in a regular expression would have to be prefixed with
another one to escape it. For example, the two following lines of code are
-functionally identical:
+functionally identical::
>>> re.match(r"\W(.)\1\W", " ff ")
- <_sre.SRE_Match object; span=(0, 4), match=' ff '>
+
>>> re.match("\\W(.)\\1\\W", " ff ")
- <_sre.SRE_Match object; span=(0, 4), match=' ff '>
+
When one wants to match a literal backslash, it must be escaped in the regular
expression. With raw string notation, this means ``r"\\"``. Without raw string
notation, one must use ``"\\\\"``, making the following lines of code
-functionally identical:
+functionally identical::
>>> re.match(r"\\", r"\\")
- <_sre.SRE_Match object; span=(0, 1), match='\\'>
+
>>> re.match("\\\\", r"\\")
- <_sre.SRE_Match object; span=(0, 1), match='\\'>
+
Writing a Tokenizer
diff --git a/Doc/library/readline.rst b/Doc/library/readline.rst
index 54c54b461ce..837816e952a 100644
--- a/Doc/library/readline.rst
+++ b/Doc/library/readline.rst
@@ -312,13 +312,13 @@ sessions, by only appending the new history. ::
try:
readline.read_history_file(histfile)
- h_len = readline.get_history_length()
+ h_len = readline.get_current_history_length()
except FileNotFoundError:
open(histfile, 'wb').close()
h_len = 0
def save(prev_h_len, histfile):
- new_h_len = readline.get_history_length()
+ new_h_len = readline.get_current_history_length()
readline.set_history_length(1000)
readline.append_history_file(new_h_len - prev_h_len, histfile)
atexit.register(save, h_len, histfile)
diff --git a/Doc/library/signal.rst b/Doc/library/signal.rst
index 46d71def08a..2bc39d9f133 100644
--- a/Doc/library/signal.rst
+++ b/Doc/library/signal.rst
@@ -273,13 +273,14 @@ The :mod:`signal` module defines the following functions:
.. versionadded:: 3.3
-.. function:: setitimer(which, seconds[, interval])
+.. function:: setitimer(which, seconds, interval=0.0)
Sets given interval timer (one of :const:`signal.ITIMER_REAL`,
:const:`signal.ITIMER_VIRTUAL` or :const:`signal.ITIMER_PROF`) specified
by *which* to fire after *seconds* (float is accepted, different from
- :func:`alarm`) and after that every *interval* seconds. The interval
- timer specified by *which* can be cleared by setting seconds to zero.
+ :func:`alarm`) and after that every *interval* seconds (if *interval*
+ is non-zero). The interval timer specified by *which* can be cleared by
+ setting *seconds* to zero.
When an interval timer fires, a signal is sent to the process.
The signal sent is dependent on the timer being used;
diff --git a/Doc/library/socket.rst b/Doc/library/socket.rst
index 8af6bc5439b..42fd7ea0f0b 100644
--- a/Doc/library/socket.rst
+++ b/Doc/library/socket.rst
@@ -103,6 +103,10 @@ created. Socket addresses are represented as follows:
``'can0'``. The network interface name ``''`` can be used to receive packets
from all network interfaces of this family.
+ - :const:`CAN_ISOTP` protocol require a tuple ``(interface, rx_addr, tx_addr)``
+ where both additional parameters are unsigned long integer that represent a
+ CAN identifier (standard or extended).
+
- A string or a tuple ``(id, unit)`` is used for the :const:`SYSPROTO_CONTROL`
protocol of the :const:`PF_SYSTEM` family. The string is the name of a
kernel control using a dynamically-assigned ID. The tuple can be used if ID
@@ -149,6 +153,14 @@ created. Socket addresses are represented as follows:
.. versionadded:: 3.6
+- :const:`AF_VSOCK` allows communication between virtual machines and
+ their hosts. The sockets are represented as a ``(CID, port)`` tuple
+ where the context ID or CID and port are integers.
+
+ Availability: Linux >= 4.8 QEMU >= 2.8 ESX >= 4.0 ESX Workstation >= 6.5
+
+ .. versionadded:: 3.7
+
- Certain other address families (:const:`AF_PACKET`, :const:`AF_CAN`)
support specific representations.
@@ -341,6 +353,16 @@ Constants
.. versionadded:: 3.5
+.. data:: CAN_ISOTP
+
+ CAN_ISOTP, in the CAN protocol family, is the ISO-TP (ISO 15765-2) protocol.
+ ISO-TP constants, documented in the Linux documentation.
+
+ Availability: Linux >= 2.6.25
+
+ .. versionadded:: 3.7
+
+
.. data:: AF_RDS
PF_RDS
SOL_RDS
@@ -381,6 +403,18 @@ Constants
.. versionadded:: 3.6
+
+.. data:: AF_VSOCK
+ IOCTL_VM_SOCKETS_GET_LOCAL_CID
+ VMADDR*
+ SO_VM*
+
+ Constants for Linux host/guest communication.
+
+ Availability: Linux >= 4.8.
+
+ .. versionadded:: 3.7
+
.. data:: AF_LINK
Availability: BSD, OSX.
@@ -427,7 +461,7 @@ The following functions all create :ref:`socket objects `.
:const:`SOCK_DGRAM`, :const:`SOCK_RAW` or perhaps one of the other ``SOCK_``
constants. The protocol number is usually zero and may be omitted or in the
case where the address family is :const:`AF_CAN` the protocol should be one
- of :const:`CAN_RAW` or :const:`CAN_BCM`. If *fileno* is specified, the other
+ of :const:`CAN_RAW`, :const:`CAN_BCM` or :const:`CAN_ISOTP`. If *fileno* is specified, the other
arguments are ignored, causing the socket with the specified file descriptor
to return. Unlike :func:`socket.fromfd`, *fileno* will return the same
socket and not a duplicate. This may help close a detached socket using
@@ -445,6 +479,8 @@ The following functions all create :ref:`socket objects `.
.. versionchanged:: 3.4
The returned socket is now non-inheritable.
+ .. versionchanged:: 3.7
+ The CAN_ISOTP protocol was added.
.. function:: socketpair([family[, type[, proto]]])
@@ -1661,7 +1697,7 @@ the interface::
# disabled promiscuous mode
s.ioctl(socket.SIO_RCVALL, socket.RCVALL_OFF)
-The last example shows how to use the socket interface to communicate to a CAN
+The next example shows how to use the socket interface to communicate to a CAN
network using the raw socket protocol. To use CAN with the broadcast
manager protocol instead, open a socket with::
@@ -1671,7 +1707,7 @@ After binding (:const:`CAN_RAW`) or connecting (:const:`CAN_BCM`) the socket, yo
can use the :meth:`socket.send`, and the :meth:`socket.recv` operations (and
their counterparts) on the socket object as usual.
-This example might require special privileges::
+This last example might require special privileges::
import socket
import struct
diff --git a/Doc/library/socketserver.rst b/Doc/library/socketserver.rst
index 218a31c848a..e12c8c97844 100644
--- a/Doc/library/socketserver.rst
+++ b/Doc/library/socketserver.rst
@@ -289,7 +289,7 @@ Server Objects
.. XXX should the default implementations of these be documented, or should
it be assumed that the user will look at socketserver.py?
- .. method:: finish_request()
+ .. method:: finish_request(request, client_address)
Actually processes the request by instantiating :attr:`RequestHandlerClass` and
calling its :meth:`~BaseRequestHandler.handle` method.
diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst
index 9fef7d7f03f..c7b9af4037f 100644
--- a/Doc/library/sqlite3.rst
+++ b/Doc/library/sqlite3.rst
@@ -172,9 +172,13 @@ Module functions and constants
.. function:: connect(database[, timeout, detect_types, isolation_level, check_same_thread, factory, cached_statements, uri])
- Opens a connection to the SQLite database file *database*. You can use
- ``":memory:"`` to open a database connection to a database that resides in RAM
- instead of on disk.
+ Opens a connection to the SQLite database file *database*. By default returns a
+ :class:`Connection` object, unless a custom *factory* is given.
+
+ *database* is a :term:`path-like object` giving the pathname (absolute or
+ relative to the current working directory) of the database file to be opened.
+ You can use ``":memory:"`` to open a database connection to a database that
+ resides in RAM instead of on disk.
When a database is accessed by multiple connections, and one of the processes
modifies the database, the SQLite database is locked until that transaction is
@@ -223,6 +227,9 @@ Module functions and constants
.. versionchanged:: 3.4
Added the *uri* parameter.
+ .. versionchanged:: 3.7
+ *database* can now also be a :term:`path-like object`, not only a string.
+
.. function:: register_converter(typename, callable)
@@ -421,6 +428,10 @@ Connection Objects
If you want to clear any previously installed progress handler, call the
method with :const:`None` for *handler*.
+ Returning a non-zero value from the handler function will terminate the
+ currently executing query and cause it to raise an :exc:`OperationalError`
+ exception.
+
.. method:: set_trace_callback(trace_callback)
diff --git a/Doc/library/ssl.rst b/Doc/library/ssl.rst
index 729a239a1ba..9b3bdd5489d 100644
--- a/Doc/library/ssl.rst
+++ b/Doc/library/ssl.rst
@@ -129,11 +129,26 @@ Functions, Constants, and Exceptions
.. versionadded:: 3.3
+.. exception:: SSLCertVerificationError
+
+ A subclass of :exc:`SSLError` raised when certificate validation has
+ failed.
+
+ .. versionadded:: 3.7
+
+ .. attribute:: verify_code
+
+ A numeric error number that denotes the verification error.
+
+ .. attribute:: verify_message
+
+ A human readable string of the verification error.
+
.. exception:: CertificateError
Raised to signal an error with a certificate (such as mismatching
hostname). Certificate errors detected by OpenSSL, though, raise
- an :exc:`SSLError`.
+ an :exc:`SSLCertVerificationError`.
Socket creation
@@ -193,11 +208,11 @@ instead.
.. table::
======================== ============ ============ ============= ========= =========== ===========
- *client* / **server** **SSLv2** **SSLv3** **TLS** **TLSv1** **TLSv1.1** **TLSv1.2**
+ *client* / **server** **SSLv2** **SSLv3** **TLS** [3]_ **TLSv1** **TLSv1.1** **TLSv1.2**
------------------------ ------------ ------------ ------------- --------- ----------- -----------
*SSLv2* yes no no [1]_ no no no
*SSLv3* no yes no [2]_ no no no
- *TLS* (*SSLv23*) no [1]_ no [2]_ yes yes yes yes
+ *TLS* (*SSLv23*) [3]_ no [1]_ no [2]_ yes yes yes yes
*TLSv1* no no yes yes no no
*TLSv1.1* no no yes no yes no
*TLSv1.2* no no yes no no yes
@@ -206,6 +221,9 @@ instead.
.. rubric:: Footnotes
.. [1] :class:`SSLContext` disables SSLv2 with :data:`OP_NO_SSLv2` by default.
.. [2] :class:`SSLContext` disables SSLv3 with :data:`OP_NO_SSLv3` by default.
+ .. [3] TLS 1.3 protocol will be available with :data:`PROTOCOL_TLS` in
+ OpenSSL >= 1.1.1. There is no dedicated PROTOCOL constant for just
+ TLS 1.3.
.. note::
@@ -215,7 +233,7 @@ instead.
The *ciphers* parameter sets the available ciphers for this SSL object.
It should be a string in the `OpenSSL cipher list format
- `_.
+ `_.
The parameter ``do_handshake_on_connect`` specifies whether to do the SSL
handshake automatically after doing a :meth:`socket.connect`, or whether the
@@ -294,6 +312,11 @@ purposes.
3DES was dropped from the default cipher string.
+ .. versionchanged:: 3.7
+
+ TLS 1.3 cipher suites TLS_AES_128_GCM_SHA256, TLS_AES_256_GCM_SHA384,
+ and TLS_CHACHA20_POLY1305_SHA256 were added to the default cipher string.
+
Random generation
^^^^^^^^^^^^^^^^^
@@ -764,6 +787,16 @@ Constants
.. versionadded:: 3.4
+.. data:: OP_NO_TLSv1_3
+
+ Prevents a TLSv1.3 connection. This option is only applicable in conjunction
+ with :const:`PROTOCOL_TLS`. It prevents the peers from choosing TLSv1.3 as
+ the protocol version. TLS 1.3 is available with OpenSSL 1.1.1 or later.
+ When Python has been compiled against an older version of OpenSSL, the
+ flag defaults to *0*.
+
+ .. versionadded:: 3.7
+
.. data:: OP_CIPHER_SERVER_PREFERENCE
Use the server's cipher ordering preference, rather than the client's.
@@ -838,6 +871,12 @@ Constants
.. versionadded:: 3.3
+.. data:: HAS_TLSv1_3
+
+ Whether the OpenSSL library has built-in support for the TLS 1.3 protocol.
+
+ .. versionadded:: 3.7
+
.. data:: CHANNEL_BINDING_TYPES
List of supported TLS channel binding types. Strings in this list
@@ -1426,7 +1465,7 @@ to speed up repeated connections from the same clients.
Set the available ciphers for sockets created with this context.
It should be a string in the `OpenSSL cipher list format
- `_.
+ `_.
If no cipher can be selected (because compile-time options or other
configuration forbids use of all the specified ciphers), an
:class:`SSLError` will be raised.
@@ -1447,8 +1486,9 @@ to speed up repeated connections from the same clients.
This method will raise :exc:`NotImplementedError` if :data:`HAS_ALPN` is
False.
- OpenSSL 1.1.0+ will abort the handshake and raise :exc:`SSLError` when
- both sides support ALPN but cannot agree on a protocol.
+ OpenSSL 1.1.0 to 1.1.0e will abort the handshake and raise :exc:`SSLError`
+ when both sides support ALPN but cannot agree on a protocol. 1.1.0f+
+ behaves like 1.0.2, :meth:`SSLSocket.selected_alpn_protocol` returns None.
.. versionadded:: 3.5
@@ -1553,8 +1593,9 @@ to speed up repeated connections from the same clients.
do_handshake_on_connect=True, suppress_ragged_eofs=True, \
server_hostname=None, session=None)
- Wrap an existing Python socket *sock* and return an :class:`SSLSocket`
- object. *sock* must be a :data:`~socket.SOCK_STREAM` socket; other socket
+ Wrap an existing Python socket *sock* and return an instance of
+ :attr:`SSLContext.sslsocket_class` (default :class:`SSLSocket`).
+ *sock* must be a :data:`~socket.SOCK_STREAM` socket; other socket
types are unsupported.
The returned SSL socket is tied to the context, its settings and
@@ -1577,12 +1618,25 @@ to speed up repeated connections from the same clients.
.. versionchanged:: 3.6
*session* argument was added.
+ .. versionchanged:: 3.7
+ The method returns on instance of :attr:`SSLContext.sslsocket_class`
+ instead of hard-coded :class:`SSLSocket`.
+
+.. attribute:: SSLContext.sslsocket_class
+
+ The return type of :meth:`SSLContext.wrap_sockets`, defaults to
+ :class:`SSLSocket`. The attribute can be overridden on instance of class
+ in order to return a custom subclass of :class:`SSLSocket`.
+
+ .. versionadded:: 3.7
+
.. method:: SSLContext.wrap_bio(incoming, outgoing, server_side=False, \
server_hostname=None, session=None)
- Create a new :class:`SSLObject` instance by wrapping the BIO objects
- *incoming* and *outgoing*. The SSL routines will read input data from the
- incoming BIO and write data to the outgoing BIO.
+ Wrap the BIO objects *incoming* and *outgoing* and return an instance of
+ 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.
The *server_side*, *server_hostname* and *session* parameters have the
same meaning as in :meth:`SSLContext.wrap_socket`.
@@ -1590,6 +1644,18 @@ to speed up repeated connections from the same clients.
.. versionchanged:: 3.6
*session* argument was added.
+ .. versionchanged:: 3.7
+ The method returns on instance of :attr:`SSLContext.sslobject_class`
+ instead of hard-coded :class:`SSLObject`.
+
+.. attribute:: SSLContext.sslobject_class
+
+ The return type of :meth:`SSLContext.wrap_bio`, defaults to
+ :class:`SSLObject`. The attribute can be overridden on instance of class
+ in order to return a custom subclass of :class:`SSLObject`.
+
+ .. versionadded:: 3.7
+
.. method:: SSLContext.session_stats()
Get statistics about the SSL sessions created or managed by this context.
@@ -1608,7 +1674,10 @@ to speed up repeated connections from the same clients.
:meth:`SSLSocket.do_handshake`. The context's
:attr:`~SSLContext.verify_mode` must be set to :data:`CERT_OPTIONAL` or
:data:`CERT_REQUIRED`, and you must pass *server_hostname* to
- :meth:`~SSLContext.wrap_socket` in order to match the hostname.
+ :meth:`~SSLContext.wrap_socket` in order to match the hostname. Enabling
+ hostname checking automatically sets :attr:`~SSLContext.verify_mode` from
+ :data:`CERT_NONE` to :data:`CERT_REQUIRED`. It cannot be set back to
+ :data:`CERT_NONE` as long as hostname checking is enabled.
Example::
@@ -1625,6 +1694,13 @@ to speed up repeated connections from the same clients.
.. versionadded:: 3.4
+ .. versionchanged:: 3.7
+
+ :attr:`~SSLContext.verify_mode` is now automatically changed
+ to :data:`CERT_REQUIRED` when hostname checking is enabled and
+ :attr:`~SSLContext.verify_mode` is :data:`CERT_NONE`. Previously
+ the same operation would have failed with a :exc:`ValueError`.
+
.. note::
This features requires OpenSSL 0.9.8f or newer.
@@ -2327,3 +2403,9 @@ successful call of :func:`~ssl.RAND_add`, :func:`~ssl.RAND_bytes` or
`IANA TLS: Transport Layer Security (TLS) Parameters `_
IANA
+
+ `RFC 7525: Recommendations for Secure Use of Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS) `_
+ IETF
+
+ `Mozilla's Server Side TLS recommendations `_
+ Mozilla
diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst
index 24762b13145..0bcafd33b20 100644
--- a/Doc/library/stdtypes.rst
+++ b/Doc/library/stdtypes.rst
@@ -39,31 +39,26 @@ Truth Value Testing
single: false
Any object can be tested for truth value, for use in an :keyword:`if` or
-:keyword:`while` condition or as operand of the Boolean operations below. The
-following values are considered false:
-
- .. index:: single: None (Built-in object)
-
-* ``None``
-
- .. index:: single: False (Built-in object)
-
-* ``False``
-
-* zero of any numeric type, for example, ``0``, ``0.0``, ``0j``.
-
-* any empty sequence, for example, ``''``, ``()``, ``[]``.
-
-* any empty mapping, for example, ``{}``.
-
-* instances of user-defined classes, if the class defines a :meth:`__bool__` or
- :meth:`__len__` method, when that method returns the integer zero or
- :class:`bool` value ``False``. [1]_
+:keyword:`while` condition or as operand of the Boolean operations below.
.. index:: single: true
-All other values are considered true --- so objects of many types are always
-true.
+By default, an object is considered true unless its class defines either a
+:meth:`__bool__` method that returns ``False`` or a :meth:`__len__` method that
+returns zero, when called with the object. [1]_ Here are most of the built-in
+objects considered false:
+
+ .. index::
+ single: None (Built-in object)
+ single: False (Built-in object)
+
+* constants defined to be false: ``None`` and ``False``.
+
+* zero of any numeric type: ``0``, ``0.0``, ``0j``, ``Decimal(0)``,
+ ``Fraction(0, 1)``
+
+* empty sequences and collections: ``''``, ``()``, ``[]``, ``{}``, ``set()``,
+ ``range(0)``
.. index::
operator: or
@@ -354,7 +349,7 @@ Notes:
The numeric literals accepted include the digits ``0`` to ``9`` or any
Unicode equivalent (code points with the ``Nd`` property).
- See http://www.unicode.org/Public/8.0.0/ucd/extracted/DerivedNumericType.txt
+ See http://www.unicode.org/Public/10.0.0/ucd/extracted/DerivedNumericType.txt
for a complete list of code points with the ``Nd`` property.
@@ -1161,7 +1156,7 @@ application).
:ref:`mutable ` sequence operations. Lists also provide the
following additional method:
- .. method:: list.sort(*, key=None, reverse=None)
+ .. method:: list.sort(*, key=None, reverse=False)
This method sorts the list in place, using only ``<`` comparisons
between items. Exceptions are not suppressed - if any comparison operations
@@ -2578,8 +2573,9 @@ arbitrary binary data.
bytearray.partition(sep)
Split the sequence at the first occurrence of *sep*, and return a 3-tuple
- containing the part before the separator, the separator, and the part
- after the separator. If the separator is not found, return a 3-tuple
+ 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.
@@ -2634,8 +2630,9 @@ arbitrary binary data.
bytearray.rpartition(sep)
Split the sequence at the last occurrence of *sep*, and return a 3-tuple
- containing the part before the separator, the separator, and the part
- after the separator. If the separator is not found, return a 3-tuple
+ 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.
diff --git a/Doc/library/string.rst b/Doc/library/string.rst
index 8176a81d4cf..5b254285257 100644
--- a/Doc/library/string.rst
+++ b/Doc/library/string.rst
@@ -754,9 +754,30 @@ attributes:
be set in the subclass's class namespace).
* *idpattern* -- This is the regular expression describing the pattern for
- non-braced placeholders (the braces will be added automatically as
- appropriate). The default value is the regular expression
- ``[_a-z][_a-z0-9]*``.
+ non-braced placeholders. The default value is the regular expression
+ ``(?-i:[_a-zA-Z][_a-zA-Z0-9]*)``. If this is given and *braceidpattern* is
+ ``None`` this pattern will also apply to braced placeholders.
+
+ .. note::
+
+ Since default *flags* is ``re.IGNORECASE``, pattern ``[a-z]`` can match
+ with some non-ASCII characters. That's why we use local ``-i`` flag here.
+
+ While *flags* is kept to ``re.IGNORECASE`` for backward compatibility,
+ you can override it to ``0`` or ``re.IGNORECASE | re.ASCII`` when
+ subclassing.
+
+ .. versionchanged:: 3.7
+ *braceidpattern* can be used to define separate patterns used inside and
+ outside the braces.
+
+* *braceidpattern* -- This is like *idpattern* but describes the pattern for
+ braced placeholders. Defaults to ``None`` which means to fall back to
+ *idpattern* (i.e. the same pattern is used both inside and outside braces).
+ If given, this allows you to define different patterns for braced and
+ unbraced placeholders.
+
+ .. versionadded:: 3.7
* *flags* -- The regular expression flags that will be applied when compiling
the regular expression used for recognizing substitutions. The default value
diff --git a/Doc/library/struct.rst b/Doc/library/struct.rst
index bb32a65d2e4..2d0866c7e09 100644
--- a/Doc/library/struct.rst
+++ b/Doc/library/struct.rst
@@ -443,6 +443,9 @@ The :mod:`struct` module also defines the following type:
The format string used to construct this Struct object.
+ .. versionchanged:: 3.7
+ The format string type is now :class:`str` instead of :class:`bytes`.
+
.. attribute:: size
The calculated size of the struct (and hence of the bytes object produced
diff --git a/Doc/library/subprocess.rst b/Doc/library/subprocess.rst
index 2eaa48e070d..a2c184a0460 100644
--- a/Doc/library/subprocess.rst
+++ b/Doc/library/subprocess.rst
@@ -61,7 +61,7 @@ compatibility with older versions, see the :ref:`call-function-trio` section.
The *input* argument is passed to :meth:`Popen.communicate` and thus to the
subprocess's stdin. If used it must be a byte sequence, or a string if
- *encoding* or *errors* is specified or *universal_newlines* is true. When
+ *encoding* or *errors* is specified or *text* is true. When
used, the internal :class:`Popen` object is automatically created with
``stdin=PIPE``, and the *stdin* argument may not be used as well.
@@ -70,10 +70,11 @@ compatibility with older versions, see the :ref:`call-function-trio` section.
exception hold the arguments, the exit code, and stdout and stderr if they
were captured.
- If *encoding* or *errors* are specified, or *universal_newlines* is true,
+ If *encoding* or *errors* are specified, or *text* is true,
file objects for stdin, stdout and stderr are opened in text mode using the
specified *encoding* and *errors* or the :class:`io.TextIOWrapper` default.
- Otherwise, file objects are opened in binary mode.
+ The *universal_newlines* argument is equivalent to *text* and is provided
+ for backwards compatibility. By default, file objects are opened in binary mode.
Examples::
@@ -95,6 +96,10 @@ compatibility with older versions, see the :ref:`call-function-trio` section.
Added *encoding* and *errors* parameters
+ .. versionchanged:: 3.7
+
+ Added the *text* parameter, as a more understandable alias of *universal_newlines*
+
.. class:: CompletedProcess
The return value from :func:`run`, representing a process that has finished.
@@ -114,8 +119,8 @@ compatibility with older versions, see the :ref:`call-function-trio` section.
.. attribute:: stdout
Captured stdout from the child process. A bytes sequence, or a string if
- :func:`run` was called with an encoding or errors. ``None`` if stdout was not
- captured.
+ :func:`run` was called with an encoding, errors, or text=True.
+ ``None`` if stdout was not captured.
If you ran the process with ``stderr=subprocess.STDOUT``, stdout and
stderr will be combined in this attribute, and :attr:`stderr` will be
@@ -124,8 +129,8 @@ compatibility with older versions, see the :ref:`call-function-trio` section.
.. attribute:: stderr
Captured stderr from the child process. A bytes sequence, or a string if
- :func:`run` was called with an encoding or errors. ``None`` if stderr was not
- captured.
+ :func:`run` was called with an encoding, errors, or text=True.
+ ``None`` if stderr was not captured.
.. method:: check_returncode()
@@ -511,8 +516,20 @@ functions.
If given, *startupinfo* will be a :class:`STARTUPINFO` object, which is
passed to the underlying ``CreateProcess`` function.
- *creationflags*, if given, can be :data:`CREATE_NEW_CONSOLE` or
- :data:`CREATE_NEW_PROCESS_GROUP`. (Windows only)
+ *creationflags*, if given, can be one or more of the following flags:
+
+ * :data:`CREATE_NEW_CONSOLE`
+ * :data:`CREATE_NEW_PROCESS_GROUP`
+ * :data:`ABOVE_NORMAL_PRIORITY_CLASS`
+ * :data:`BELOW_NORMAL_PRIORITY_CLASS`
+ * :data:`HIGH_PRIORITY_CLASS`
+ * :data:`IDLE_PRIORITY_CLASS`
+ * :data:`NORMAL_PRIORITY_CLASS`
+ * :data:`REALTIME_PRIORITY_CLASS`
+ * :data:`CREATE_NO_WINDOW`
+ * :data:`DETACHED_PROCESS`
+ * :data:`CREATE_DEFAULT_ERROR_MODE`
+ * :data:`CREATE_BREAKAWAY_FROM_JOB`
Popen objects are supported as context managers via the :keyword:`with` statement:
on exit, standard file descriptors are closed, and the process is waited for.
@@ -584,7 +601,7 @@ Instances of the :class:`Popen` class have the following methods:
.. method:: Popen.poll()
Check if child process has terminated. Set and return
- :attr:`~Popen.returncode` attribute.
+ :attr:`~Popen.returncode` attribute. Otherwise, returns ``None``.
.. method:: Popen.wait(timeout=None)
@@ -798,8 +815,8 @@ on Windows.
:class:`Popen` is called with ``shell=True``.
-Constants
-^^^^^^^^^
+Windows Constants
+^^^^^^^^^^^^^^^^^
The :mod:`subprocess` module exposes the following constants.
@@ -846,6 +863,84 @@ The :mod:`subprocess` module exposes the following constants.
This flag is ignored if :data:`CREATE_NEW_CONSOLE` is specified.
+.. data:: ABOVE_NORMAL_PRIORITY_CLASS
+
+ A :class:`Popen` ``creationflags`` parameter to specify that a new process
+ will have an above average priority.
+
+ .. versionadded:: 3.7
+
+.. data:: BELOW_NORMAL_PRIORITY_CLASS
+
+ A :class:`Popen` ``creationflags`` parameter to specify that a new process
+ will have a below average priority.
+
+ .. versionadded:: 3.7
+
+.. data:: HIGH_PRIORITY_CLASS
+
+ A :class:`Popen` ``creationflags`` parameter to specify that a new process
+ will have a high priority.
+
+ .. versionadded:: 3.7
+
+.. data:: IDLE_PRIORITY_CLASS
+
+ A :class:`Popen` ``creationflags`` parameter to specify that a new process
+ will have an idle (lowest) priority.
+
+ .. versionadded:: 3.7
+
+.. data:: NORMAL_PRIORITY_CLASS
+
+ A :class:`Popen` ``creationflags`` parameter to specify that a new process
+ will have an normal priority. (default)
+
+ .. versionadded:: 3.7
+
+.. data:: REALTIME_PRIORITY_CLASS
+
+ A :class:`Popen` ``creationflags`` parameter to specify that a new process
+ will have realtime priority.
+ You should almost never use REALTIME_PRIORITY_CLASS, because this interrupts
+ system threads that manage mouse input, keyboard input, and background disk
+ flushing. This class can be appropriate for applications that "talk" directly
+ to hardware or that perform brief tasks that should have limited interruptions.
+
+ .. versionadded:: 3.7
+
+.. data:: CREATE_NO_WINDOW
+
+ A :class:`Popen` ``creationflags`` parameter to specify that a new process
+ will not create a window
+
+ .. versionadded:: 3.7
+
+.. data:: DETACHED_PROCESS
+
+ A :class:`Popen` ``creationflags`` parameter to specify that a new process
+ will not inherit its parent's console.
+ This value cannot be used with CREATE_NEW_CONSOLE.
+
+ .. versionadded:: 3.7
+
+.. data:: CREATE_DEFAULT_ERROR_MODE
+
+ A :class:`Popen` ``creationflags`` parameter to specify that a new process
+ does not inherit the error mode of the calling process. Instead, the new
+ process gets the default error mode.
+ This feature is particularly useful for multithreaded shell applications
+ that run with hard errors disabled.
+
+ .. versionadded:: 3.7
+
+.. data:: CREATE_BREAKAWAY_FROM_JOB
+
+ A :class:`Popen` ``creationflags`` parameter to specify that a new process
+ is not associated with the job.
+
+ .. versionadded:: 3.7
+
.. _call-function-trio:
Older high-level API
@@ -1165,27 +1260,32 @@ handling consistency are valid for these functions.
.. function:: getstatusoutput(cmd)
- Return ``(status, output)`` of executing *cmd* in a shell.
+ Return ``(exitcode, output)`` of executing *cmd* in a shell.
Execute the string *cmd* in a shell with :meth:`Popen.check_output` and
- return a 2-tuple ``(status, output)``. The locale encoding is used;
+ return a 2-tuple ``(exitcode, output)``. The locale encoding is used;
see the notes on :ref:`frequently-used-arguments` for more details.
A trailing newline is stripped from the output.
- The exit status for the command can be interpreted
- according to the rules for the C function :c:func:`wait`. Example::
+ The exit code for the command can be interpreted as the return code
+ of subprocess. Example::
>>> subprocess.getstatusoutput('ls /bin/ls')
(0, '/bin/ls')
>>> subprocess.getstatusoutput('cat /bin/junk')
- (256, 'cat: /bin/junk: No such file or directory')
+ (1, 'cat: /bin/junk: No such file or directory')
>>> subprocess.getstatusoutput('/bin/junk')
- (256, 'sh: /bin/junk: not found')
+ (127, 'sh: /bin/junk: not found')
+ >>> subprocess.getstatusoutput('/bin/kill $$')
+ (-15, '')
Availability: POSIX & Windows
.. versionchanged:: 3.3.4
- Windows support added
+ Windows support was added.
+
+ The function now returns (exitcode, output) instead of (status, output)
+ as it did in Python 3.3.3 and earlier. See :func:`WEXITSTATUS`.
.. function:: getoutput(cmd)
diff --git a/Doc/library/sunau.rst b/Doc/library/sunau.rst
index c8357e4fcc8..2064fd7e20b 100644
--- a/Doc/library/sunau.rst
+++ b/Doc/library/sunau.rst
@@ -63,6 +63,8 @@ The :mod:`sunau` module defines the following functions:
A synonym for :func:`.open`, maintained for backwards compatibility.
+ .. deprecated-removed:: 3.7 3.9
+
The :mod:`sunau` module defines the following exception:
diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst
index 54b99e0fd99..faf540c4ea4 100644
--- a/Doc/library/sys.rst
+++ b/Doc/library/sys.rst
@@ -109,6 +109,40 @@ always available.
This function should be used for internal and specialized purposes only.
+.. function:: breakpointhook()
+
+ This hook function is called by built-in :func:`breakpoint`. By default,
+ it drops you into the :mod:`pdb` debugger, but it can be set to any other
+ function so that you can choose which debugger gets used.
+
+ The signature of this function is dependent on what it calls. For example,
+ the default binding (e.g. ``pdb.set_trace()``) expects no arguments, but
+ you might bind it to a function that expects additional arguments
+ (positional and/or keyword). The built-in ``breakpoint()`` function passes
+ its ``*args`` and ``**kws`` straight through. Whatever
+ ``breakpointhooks()`` returns is returned from ``breakpoint()``.
+
+ The default implementation first consults the environment variable
+ :envvar:`PYTHONBREAKPOINT`. If that is set to ``"0"`` then this function
+ returns immediately; i.e. it is a no-op. If the environment variable is
+ not set, or is set to the empty string, ``pdb.set_trace()`` is called.
+ Otherwise this variable should name a function to run, using Python's
+ dotted-import nomenclature, e.g. ``package.subpackage.module.function``.
+ In this case, ``package.subpackage.module`` would be imported and the
+ resulting module must have a callable named ``function()``. This is run,
+ passing in ``*args`` and ``**kws``, and whatever ``function()`` returns,
+ ``sys.breakpointhook()`` returns to the built-in :func:`breakpoint`
+ function.
+
+ Note that if anything goes wrong while importing the callable named by
+ :envvar:`PYTHONBREAKPOINT`, a :exc:`RuntimeWarning` is reported and the
+ breakpoint is ignored.
+
+ Also note that if ``sys.breakpointhook()`` is overridden programmatically,
+ :envvar:`PYTHONBREAKPOINT` is *not* consulted.
+
+ .. versionadded:: 3.7
+
.. function:: _debugmallocstats()
Print low-level information to stderr about the state of CPython's memory
@@ -187,14 +221,19 @@ always available.
customized by assigning another three-argument function to ``sys.excepthook``.
-.. data:: __displayhook__
+.. data:: __breakpointhook__
+ __displayhook__
__excepthook__
- These objects contain the original values of ``displayhook`` and ``excepthook``
- at the start of the program. They are saved so that ``displayhook`` and
- ``excepthook`` can be restored in case they happen to get replaced with broken
+ These objects contain the original values of ``breakpointhook``,
+ ``displayhook``, and ``excepthook`` at the start of the program. They are
+ saved so that ``breakpointhook``, ``displayhook`` and ``excepthook`` can be
+ restored in case they happen to get replaced with broken or alternative
objects.
+ .. versionadded:: 3.7
+ __breakpointhook__
+
.. function:: exc_info()
@@ -610,7 +649,7 @@ always available.
:class:`~collections.namedtuple` of the form `(firstiter, finalizer)`,
where *firstiter* and *finalizer* are expected to be either ``None`` or
functions which take an :term:`asynchronous generator iterator` as an
- argument, and are used to schedule finalization of an asychronous
+ argument, and are used to schedule finalization of an asynchronous
generator by an event loop.
.. versionadded:: 3.6
@@ -1068,7 +1107,7 @@ always available.
Trace functions should have three arguments: *frame*, *event*, and
*arg*. *frame* is the current stack frame. *event* is a string: ``'call'``,
``'line'``, ``'return'``, ``'exception'``, ``'c_call'``, ``'c_return'``, or
- ``'c_exception'``. *arg* depends on the event type.
+ ``'c_exception'``, ``'opcode'``. *arg* depends on the event type.
The trace function is invoked (with *event* set to ``'call'``) whenever a new
local scope is entered; it should return a reference to a local trace
@@ -1091,6 +1130,8 @@ always available.
``None``; the return value specifies the new local trace function. See
:file:`Objects/lnotab_notes.txt` for a detailed explanation of how this
works.
+ Per-line events may be disabled for a frame by setting
+ :attr:`f_trace_lines` to :const:`False` on that frame.
``'return'``
A function (or other code block) is about to return. The local trace
@@ -1113,6 +1154,14 @@ always available.
``'c_exception'``
A C function has raised an exception. *arg* is the C function object.
+ ``'opcode'``
+ The interpreter is about to execute a new opcode (see :mod:`dis` for
+ opcode details). The local trace function is called; *arg* is
+ ``None``; the return value specifies the new local trace function.
+ Per-opcode events are not emitted by default: they must be explicitly
+ requested by setting :attr:`f_trace_opcodes` to :const:`True` on the
+ frame.
+
Note that as an exception is propagated down the chain of callers, an
``'exception'`` event is generated at each level.
@@ -1125,6 +1174,11 @@ always available.
implementation platform, rather than part of the language definition, and
thus may not be available in all Python implementations.
+ .. versionchanged:: 3.7
+
+ ``'opcode'`` event type added; :attr:`f_trace_lines` and
+ :attr:`f_trace_opcodes` attributes added to frames
+
.. function:: set_asyncgen_hooks(firstiter, finalizer)
Accepts two optional keyword arguments which are callables that accept an
@@ -1221,9 +1275,9 @@ always available.
Under all platforms though, you can override this value by setting the
:envvar:`PYTHONIOENCODING` environment variable before starting Python.
- * When interactive, standard streams are line-buffered. Otherwise, they
- are block-buffered like regular text files. You can override this
- value with the :option:`-u` command-line option.
+ * When interactive, ``stdout`` and ``stderr`` streams are line-buffered.
+ Otherwise, they are block-buffered like regular text files. You can
+ override this value with the :option:`-u` command-line option.
.. note::
@@ -1282,7 +1336,7 @@ always available.
| | * ``None`` if this information is unknown |
+------------------+---------------------------------------------------------+
| :const:`version` | Name and version of the thread library. It is a string, |
- | | or ``None`` if these informations are unknown. |
+ | | or ``None`` if this information is unknown. |
+------------------+---------------------------------------------------------+
.. versionadded:: 3.3
diff --git a/Doc/library/sysconfig.rst b/Doc/library/sysconfig.rst
index f066a765d00..9f549fbc513 100644
--- a/Doc/library/sysconfig.rst
+++ b/Doc/library/sysconfig.rst
@@ -173,23 +173,19 @@ Other functions
This is used mainly to distinguish platform-specific build directories and
platform-specific built distributions. Typically includes the OS name and
- version and the architecture (as supplied by :func:`os.uname`), although the
- exact information included depends on the OS; e.g. for IRIX the architecture
- isn't particularly important (IRIX only runs on SGI hardware), but for Linux
- the kernel version isn't particularly important.
+ version and the architecture (as supplied by 'os.uname()'), although the
+ exact information included depends on the OS; e.g., on Linux, the kernel
+ version isn't particularly important.
Examples of returned values:
- linux-i586
- linux-alpha (?)
- solaris-2.6-sun4u
- - irix-5.3
- - irix64-6.2
Windows will return one of:
- win-amd64 (64bit Windows on AMD64 (aka x86_64, Intel64, EM64T, etc)
- - win-ia64 (64bit Windows on Itanium)
- win32 (all others - specifically, sys.platform is returned)
Mac OS X can return:
diff --git a/Doc/library/termios.rst b/Doc/library/termios.rst
index ad6a9f7c972..7693ecd0278 100644
--- a/Doc/library/termios.rst
+++ b/Doc/library/termios.rst
@@ -12,7 +12,7 @@
--------------
This module provides an interface to the POSIX calls for tty I/O control. For a
-complete description of these calls, see :manpage:`termios(2)` Unix manual
+complete description of these calls, see :manpage:`termios(3)` Unix manual
page. It is only available for those Unix versions that support POSIX
*termios* style tty I/O control configured during installation.
diff --git a/Doc/library/test.rst b/Doc/library/test.rst
index 9d4ff7ad8b4..01ba1ec7062 100644
--- a/Doc/library/test.rst
+++ b/Doc/library/test.rst
@@ -186,7 +186,7 @@ options, run :program:`python -m test -h`.
Some other ways to execute the regression tests depend on what platform the
tests are being executed on. On Unix, you can run :program:`make test` at the
top-level directory where Python was built. On Windows,
-executing :program:`rt.bat` from your :file:`PCBuild` directory will run all
+executing :program:`rt.bat` from your :file:`PCbuild` directory will run all
regression tests.
@@ -440,7 +440,7 @@ The :mod:`test.support` module defines the following functions:
otherwise.
-.. decorator:: skip_unless_symlink()
+.. decorator:: skip_unless_symlink
A decorator for running tests that require support for symbolic links.
diff --git a/Doc/library/threading.rst b/Doc/library/threading.rst
index cda859fe4cb..95e27cab7c8 100644
--- a/Doc/library/threading.rst
+++ b/Doc/library/threading.rst
@@ -11,8 +11,8 @@
This module constructs higher-level threading interfaces on top of the lower
level :mod:`_thread` module. See also the :mod:`queue` module.
-The :mod:`dummy_threading` module is provided for situations where
-:mod:`threading` cannot be used because :mod:`_thread` is missing.
+.. versionchanged:: 3.7
+ This module used to be optional, it is now always available.
.. note::
@@ -291,10 +291,10 @@ since it is impossible to detect the termination of alien threads.
.. attribute:: ident
The 'thread identifier' of this thread or ``None`` if the thread has not
- been started. This is a nonzero integer. See the
- :func:`_thread.get_ident()` function. Thread identifiers may be recycled
- when a thread exits and another thread is created. The identifier is
- available even after the thread has exited.
+ been started. This is a nonzero integer. See the :func:`get_ident`
+ function. Thread identifiers may be recycled when a thread exits and
+ another thread is created. The identifier is available even after the
+ thread has exited.
.. method:: is_alive()
@@ -875,8 +875,8 @@ Barrier Objects
This class provides a simple synchronization primitive for use by a fixed number
of threads that need to wait for each other. Each of the threads tries to pass
the barrier by calling the :meth:`~Barrier.wait` method and will block until
-all of the threads have made the call. At this points, the threads are released
-simultaneously.
+all of the threads have made their :meth:`~Barrier.wait` calls. At this point,
+the threads are released simultaneously.
The barrier can be reused any number of times for the same number of threads.
diff --git a/Doc/library/time.rst b/Doc/library/time.rst
index ef0e69a5e8c..ccbb3f37877 100644
--- a/Doc/library/time.rst
+++ b/Doc/library/time.rst
@@ -118,14 +118,10 @@ An explanation of some terminology and conventions is in order.
+-------------------------+-------------------------+-------------------------+
-The module defines the following functions and data items:
-
-.. data:: altzone
-
- The offset of the local DST timezone, in seconds west of UTC, if one is defined.
- This is negative if the local DST timezone is east of UTC (as in Western Europe,
- including the UK). Only use this if ``daylight`` is nonzero.
+.. _time-functions:
+Functions
+---------
.. function:: asctime([t])
@@ -162,91 +158,69 @@ The module defines the following functions and data items:
:func:`perf_counter` or :func:`process_time` instead, depending on your
requirements, to have a well defined behaviour.
+.. function:: pthread_getcpuclockid(thread_id)
+
+ Return the *clk_id* of the thread-specific CPU-time clock for the specified *thread_id*.
+
+ Use :func:`threading.get_ident` or the :attr:`~threading.Thread.ident`
+ attribute of :class:`threading.Thread` objects to get a suitable value
+ for *thread_id*.
+
+ .. warning::
+ Passing an invalid or expired *thread_id* may result in
+ undefined behavior, such as segmentation fault.
+
+ Availability: Unix (see the man page for :manpage:`pthread_getcpuclockid(3)` for
+ further information)
+
+ .. versionadded:: 3.7
.. function:: clock_getres(clk_id)
- Return the resolution (precision) of the specified clock *clk_id*.
+ Return the resolution (precision) of the specified clock *clk_id*. Refer to
+ :ref:`time-clock-id-constants` for a list of accepted values for *clk_id*.
Availability: Unix.
.. versionadded:: 3.3
-.. function:: clock_gettime(clk_id)
+.. function:: clock_gettime(clk_id) -> float
- Return the time of the specified clock *clk_id*.
+ Return the time of the specified clock *clk_id*. Refer to
+ :ref:`time-clock-id-constants` for a list of accepted values for *clk_id*.
Availability: Unix.
.. versionadded:: 3.3
-.. function:: clock_settime(clk_id, time)
+.. function:: clock_gettime_ns(clk_id) -> int
- Set the time of the specified clock *clk_id*.
+ Similar to :func:`clock_gettime` but return time as nanoseconds.
+
+ Availability: Unix.
+
+ .. versionadded:: 3.7
+
+
+.. function:: clock_settime(clk_id, time: float)
+
+ Set the time of the specified clock *clk_id*. Currently,
+ :data:`CLOCK_REALTIME` is the only accepted value for *clk_id*.
Availability: Unix.
.. versionadded:: 3.3
-.. data:: CLOCK_HIGHRES
+.. function:: clock_settime_ns(clk_id, time: int)
- The Solaris OS has a CLOCK_HIGHRES timer that attempts to use an optimal
- hardware source, and may give close to nanosecond resolution. CLOCK_HIGHRES
- is the nonadjustable, high-resolution clock.
-
- Availability: Solaris.
-
- .. versionadded:: 3.3
-
-
-.. data:: CLOCK_MONOTONIC
-
- Clock that cannot be set and represents monotonic time since some unspecified
- starting point.
+ Similar to :func:`clock_settime` but set time with nanoseconds.
Availability: Unix.
- .. versionadded:: 3.3
-
-
-.. data:: CLOCK_MONOTONIC_RAW
-
- Similar to :data:`CLOCK_MONOTONIC`, but provides access to a raw
- hardware-based time that is not subject to NTP adjustments.
-
- Availability: Linux 2.6.28 or later.
-
- .. versionadded:: 3.3
-
-
-.. data:: CLOCK_PROCESS_CPUTIME_ID
-
- High-resolution per-process timer from the CPU.
-
- Availability: Unix.
-
- .. versionadded:: 3.3
-
-
-.. data:: CLOCK_REALTIME
-
- System-wide real-time clock. Setting this clock requires appropriate
- privileges.
-
- Availability: Unix.
-
- .. versionadded:: 3.3
-
-
-.. data:: CLOCK_THREAD_CPUTIME_ID
-
- Thread-specific CPU-time clock.
-
- Availability: Unix.
-
- .. versionadded:: 3.3
+ .. versionadded:: 3.7
.. function:: ctime([secs])
@@ -257,11 +231,6 @@ The module defines the following functions and data items:
``asctime(localtime(secs))``. Locale information is not used by :func:`ctime`.
-.. data:: daylight
-
- Nonzero if a DST timezone is defined.
-
-
.. function:: get_clock_info(name)
Get information on the specified clock as a namespace object.
@@ -272,6 +241,7 @@ The module defines the following functions and data items:
* ``'monotonic'``: :func:`time.monotonic`
* ``'perf_counter'``: :func:`time.perf_counter`
* ``'process_time'``: :func:`time.process_time`
+ * ``'thread_time'``: :func:`time.thread_time`
* ``'time'``: :func:`time.time`
The result has the following attributes:
@@ -279,7 +249,7 @@ The module defines the following functions and data items:
- *adjustable*: ``True`` if the clock can be changed automatically (e.g. by
a NTP daemon) or manually by the system administrator, ``False`` otherwise
- *implementation*: The name of the underlying C function used to get
- the clock value
+ the clock value. Refer to :ref:`time-clock-id-constants` for possible values.
- *monotonic*: ``True`` if the clock cannot go backward,
``False`` otherwise
- *resolution*: The resolution of the clock in seconds (:class:`float`)
@@ -316,7 +286,7 @@ The module defines the following functions and data items:
The earliest date for which it can generate a time is platform-dependent.
-.. function:: monotonic()
+.. function:: monotonic() -> float
Return the value (in fractional seconds) of a monotonic clock, i.e. a clock
that cannot go backwards. The clock is not affected by system clock updates.
@@ -336,7 +306,16 @@ The module defines the following functions and data items:
The function is now always available.
-.. function:: perf_counter()
+.. function:: monotonic_ns() -> int
+
+ Similar to :func:`monotonic`, but return time as nanoseconds.
+
+ .. versionadded:: 3.7
+
+.. function:: perf_counter() -> float
+
+ .. index::
+ single: benchmarking
Return the value (in fractional seconds) of a performance counter, i.e. a
clock with the highest available resolution to measure a short duration. It
@@ -346,8 +325,19 @@ The module defines the following functions and data items:
.. versionadded:: 3.3
+.. function:: perf_counter_ns() -> int
-.. function:: process_time()
+ Similar to :func:`perf_counter`, but return time as nanoseconds.
+
+ .. versionadded:: 3.7
+
+
+.. function:: process_time() -> float
+
+ .. index::
+ single: CPU time
+ single: processor time
+ single: benchmarking
Return the value (in fractional seconds) of the sum of the system and user
CPU time of the current process. It does not include time elapsed during
@@ -357,6 +347,12 @@ The module defines the following functions and data items:
.. versionadded:: 3.3
+.. function:: process_time_ns() -> int
+
+ Similar to :func:`process_time` but return time as nanoseconds.
+
+ .. versionadded:: 3.7
+
.. function:: sleep(secs)
Suspend execution of the calling thread for the given number of seconds.
@@ -582,7 +578,7 @@ The module defines the following functions and data items:
:class:`struct_time`, or having elements of the wrong type, a
:exc:`TypeError` is raised.
-.. function:: time()
+.. function:: time() -> float
Return the time in seconds since the epoch_ as a floating point
number. The specific date of the epoch and the handling of
@@ -607,18 +603,39 @@ The module defines the following functions and data items:
:class:`struct_time` object is returned, from which the components
of the calendar date may be accessed as attributes.
-.. data:: timezone
- The offset of the local (non-DST) timezone, in seconds west of UTC (negative in
- most of Western Europe, positive in the US, zero in the UK).
+.. function:: thread_time() -> float
+
+ .. index::
+ single: CPU time
+ single: processor time
+ single: benchmarking
+
+ Return the value (in fractional seconds) of the sum of the system and user
+ CPU time of the current thread. It does not include time elapsed during
+ sleep. It is thread-specific by definition. The reference point of the
+ returned value is undefined, so that only the difference between the results
+ of consecutive calls in the same thread is valid.
+
+ Availability: Windows, Linux, Unix systems supporting
+ ``CLOCK_THREAD_CPUTIME_ID``.
+
+ .. versionadded:: 3.7
-.. data:: tzname
+.. function:: thread_time_ns() -> int
- A tuple of two strings: the first is the name of the local non-DST timezone, the
- second is the name of the local DST timezone. If no DST timezone is defined,
- the second string should not be used.
+ Similar to :func:`thread_time` but return time as nanoseconds.
+ .. versionadded:: 3.7
+
+
+.. function:: time_ns() -> int
+
+ Similar to :func:`time` but returns time as an integer number of nanoseconds
+ since the epoch_.
+
+ .. versionadded:: 3.7
.. function:: tzset()
@@ -708,6 +725,146 @@ The module defines the following functions and data items:
('EET', 'EEST')
+.. _time-clock-id-constants:
+
+Clock ID Constants
+------------------
+
+These constants are used as parameters for :func:`clock_getres` and
+:func:`clock_gettime`.
+
+.. data:: CLOCK_BOOTTIME
+
+ Identical to :data:`CLOCK_MONOTONIC`, except it also includes any time that
+ the system is suspended.
+
+ This allows applications to get a suspend-aware monotonic clock without
+ having to deal with the complications of :data:`CLOCK_REALTIME`, which may
+ have discontinuities if the time is changed using ``settimeofday()`` or
+ similar.
+
+ Availability: Linux 2.6.39 or later.
+
+ .. versionadded:: 3.7
+
+
+.. data:: CLOCK_HIGHRES
+
+ The Solaris OS has a ``CLOCK_HIGHRES`` timer that attempts to use an optimal
+ hardware source, and may give close to nanosecond resolution.
+ ``CLOCK_HIGHRES`` is the nonadjustable, high-resolution clock.
+
+ Availability: Solaris.
+
+ .. versionadded:: 3.3
+
+
+.. data:: CLOCK_MONOTONIC
+
+ Clock that cannot be set and represents monotonic time since some unspecified
+ starting point.
+
+ Availability: Unix.
+
+ .. versionadded:: 3.3
+
+
+.. data:: CLOCK_MONOTONIC_RAW
+
+ Similar to :data:`CLOCK_MONOTONIC`, but provides access to a raw
+ hardware-based time that is not subject to NTP adjustments.
+
+ Availability: Linux 2.6.28 or later.
+
+ .. versionadded:: 3.3
+
+
+.. data:: CLOCK_PROCESS_CPUTIME_ID
+
+ High-resolution per-process timer from the CPU.
+
+ Availability: Unix.
+
+ .. versionadded:: 3.3
+
+
+.. data:: CLOCK_PROF
+
+ High-resolution per-process timer from the CPU.
+
+ Availability: FreeBSD 3 or later, NetBSD 7 or later, OpenBSD.
+
+ .. versionadded:: 3.7
+
+
+.. data:: CLOCK_THREAD_CPUTIME_ID
+
+ Thread-specific CPU-time clock.
+
+ Availability: Unix.
+
+ .. versionadded:: 3.3
+
+
+.. data:: CLOCK_UPTIME
+
+ Time whose absolute value is the time the system has been running and not
+ suspended, providing accurate uptime measurement, both absolute and
+ interval.
+
+ Availability: FreeBSD 7 or later, OpenBSD 5.5 or later.
+
+ .. versionadded:: 3.7
+
+
+The following constant is the only parameter that can be sent to
+:func:`clock_settime`.
+
+.. data:: CLOCK_REALTIME
+
+ System-wide real-time clock. Setting this clock requires appropriate
+ privileges.
+
+ Availability: Unix.
+
+ .. versionadded:: 3.3
+
+
+.. _time-timezone-constants:
+
+Timezone Constants
+-------------------
+
+.. data:: altzone
+
+ The offset of the local DST timezone, in seconds west of UTC, if one is defined.
+ This is negative if the local DST timezone is east of UTC (as in Western Europe,
+ including the UK). Only use this if ``daylight`` is nonzero. See note below.
+
+.. data:: daylight
+
+ Nonzero if a DST timezone is defined. See note below.
+
+.. data:: timezone
+
+ The offset of the local (non-DST) timezone, in seconds west of UTC (negative in
+ most of Western Europe, positive in the US, zero in the UK). See note below.
+
+.. data:: tzname
+
+ A tuple of two strings: the first is the name of the local non-DST timezone, the
+ second is the name of the local DST timezone. If no DST timezone is defined,
+ the second string should not be used. See note below.
+
+.. note::
+
+ For the above Timezone constants (:data:`altzone`, :data:`daylight`, :data:`timezone`,
+ and :data:`tzname`), the value is determined by the timezone rules in effect
+ at module load time or the last time :func:`tzset` is called and may be incorrect
+ for times in the past. It is recommended to use the :attr:`tm_gmtoff` and
+ :attr:`tm_zone` results from :func:`localtime` to obtain timezone information.
+
+
.. seealso::
Module :mod:`datetime`
diff --git a/Doc/library/tkinter.ttk.rst b/Doc/library/tkinter.ttk.rst
index 3dad182cccd..927f7f3c6c1 100644
--- a/Doc/library/tkinter.ttk.rst
+++ b/Doc/library/tkinter.ttk.rst
@@ -1099,26 +1099,42 @@ ttk.Treeview
If *selop* is not specified, returns selected items. Otherwise, it will
act according to the following selection methods.
+ .. deprecated-removed:: 3.6 3.8
+ Using ``selection()`` for changing the selection state is deprecated.
+ Use the following selection methods instead.
- .. method:: selection_set(items)
+
+ .. method:: selection_set(*items)
*items* becomes the new selection.
+ .. versionchanged:: 3.6
+ *items* can be passed as separate arguments, not just as a single tuple.
- .. method:: selection_add(items)
+
+ .. method:: selection_add(*items)
Add *items* to the selection.
+ .. versionchanged:: 3.6
+ *items* can be passed as separate arguments, not just as a single tuple.
- .. method:: selection_remove(items)
+
+ .. method:: selection_remove(*items)
Remove *items* from the selection.
+ .. versionchanged:: 3.6
+ *items* can be passed as separate arguments, not just as a single tuple.
- .. method:: selection_toggle(items)
+
+ .. method:: selection_toggle(*items)
Toggle the selection state of each item in *items*.
+ .. versionchanged:: 3.6
+ *items* can be passed as separate arguments, not just as a single tuple.
+
.. method:: set(item, column=None, value=None)
diff --git a/Doc/library/token.rst b/Doc/library/token.rst
index b7ca9dbca72..373991027e4 100644
--- a/Doc/library/token.rst
+++ b/Doc/library/token.rst
@@ -98,8 +98,6 @@ The token constants are:
RARROW
ELLIPSIS
OP
- AWAIT
- ASYNC
ERRORTOKEN
N_TOKENS
NT_OFFSET
@@ -129,9 +127,11 @@ the :mod:`tokenize` module.
.. versionchanged:: 3.5
- Added :data:`AWAIT` and :data:`ASYNC` tokens. Starting with
- Python 3.7, "async" and "await" will be tokenized as :data:`NAME`
- tokens, and :data:`AWAIT` and :data:`ASYNC` will be removed.
+ Added :data:`AWAIT` and :data:`ASYNC` tokens.
.. versionchanged:: 3.7
Added :data:`COMMENT`, :data:`NL` and :data:`ENCODING` tokens.
+
+.. versionchanged:: 3.7
+ Removed :data:`AWAIT` and :data:`ASYNC` tokens. "async" and "await" are
+ now tokenized as :data:`NAME` tokens.
diff --git a/Doc/library/tokenize.rst b/Doc/library/tokenize.rst
index cd27a101a8f..02a0428f21b 100644
--- a/Doc/library/tokenize.rst
+++ b/Doc/library/tokenize.rst
@@ -16,8 +16,9 @@ implemented in Python. The scanner in this module returns comments as tokens
as well, making it useful for implementing "pretty-printers," including
colorizers for on-screen displays.
-To simplify token stream handling, all :ref:`operators` and :ref:`delimiters`
-tokens are returned using the generic :data:`~token.OP` token type. The exact
+To simplify token stream handling, all :ref:`operator ` and
+:ref:`delimiter ` tokens and :data:`Ellipsis` are returned using
+the generic :data:`~token.OP` token type. The exact
type can be determined by checking the ``exact_type`` property on the
:term:`named tuple` returned from :func:`tokenize.tokenize`.
diff --git a/Doc/library/tracemalloc.rst b/Doc/library/tracemalloc.rst
index e16566963ee..048ee64aac9 100644
--- a/Doc/library/tracemalloc.rst
+++ b/Doc/library/tracemalloc.rst
@@ -412,6 +412,9 @@ Filter
Address space of a memory block (``int`` or ``None``).
+ tracemalloc uses the domain ``0`` to trace memory allocations made by
+ Python. C extensions can use other domains to trace other resources.
+
.. attribute:: inclusive
If *inclusive* is ``True`` (include), only match memory blocks allocated
@@ -622,6 +625,16 @@ Trace
The :attr:`Snapshot.traces` attribute is a sequence of :class:`Trace`
instances.
+ .. versionchanged:: 3.6
+ Added the :attr:`domain` attribute.
+
+ .. attribute:: domain
+
+ Address space of a memory block (``int``). Read-only property.
+
+ tracemalloc uses the domain ``0`` to trace memory allocations made by
+ Python. C extensions can use other domains to trace other resources.
+
.. attribute:: size
Size of the memory block in bytes (``int``).
diff --git a/Doc/library/turtle.rst b/Doc/library/turtle.rst
index 041b651bbca..595a244342c 100644
--- a/Doc/library/turtle.rst
+++ b/Doc/library/turtle.rst
@@ -2367,7 +2367,7 @@ The demo scripts are:
| wikipedia | a pattern from the wikipedia | :func:`clone`, |
| | article on turtle graphics | :func:`undo` |
+----------------+------------------------------+-----------------------+
-| yingyang | another elementary example | :func:`circle` |
+| yinyang | another elementary example | :func:`circle` |
+----------------+------------------------------+-----------------------+
Have fun!
diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst
index 1780739ad1d..9883d8bbe86 100644
--- a/Doc/library/typing.rst
+++ b/Doc/library/typing.rst
@@ -111,8 +111,7 @@ More precisely, the expression ``some_value is Derived(some_value)`` is always
true at runtime.
This also means that it is not possible to create a subtype of ``Derived``
-since it is an identity function at runtime, not an actual type. Similarly, it
-is not possible to create another :func:`NewType` based on a ``Derived`` type::
+since it is an identity function at runtime, not an actual type::
from typing import NewType
@@ -121,9 +120,16 @@ is not possible to create another :func:`NewType` based on a ``Derived`` type::
# Fails at runtime and does not typecheck
class AdminUserId(UserId): pass
- # Also does not typecheck
+However, it is possible to create a :func:`NewType` based on a 'derived' ``NewType``::
+
+ from typing import NewType
+
+ UserId = NewType('UserId', int)
+
ProUserId = NewType('ProUserId', UserId)
+and typechecking for ``ProUserId`` will work as expected.
+
See :pep:`484` for more details.
.. note::
@@ -891,17 +897,17 @@ The module defines the following classes, functions and decorators:
See :pep:`484` for details and comparison with other typing semantics.
-.. decorator:: no_type_check(arg)
+.. decorator:: no_type_check
Decorator to indicate that annotations are not type hints.
- The argument must be a class or function; if it is a class, it
+ This works as class or function :term:`decorator`. With a class, it
applies recursively to all methods defined in that class (but not
to methods defined in its superclasses or subclasses).
This mutates the function(s) in place.
-.. decorator:: no_type_check_decorator(decorator)
+.. decorator:: no_type_check_decorator
Decorator to give another decorator the :func:`no_type_check` effect.
@@ -939,7 +945,7 @@ The module defines the following classes, functions and decorators:
Union[int, str] == Union[str, int]
- * When a class and its subclass are present, the former is skipped, e.g.::
+ * When a class and its subclass are present, the latter is skipped, e.g.::
Union[int, object] == object
diff --git a/Doc/library/unicodedata.rst b/Doc/library/unicodedata.rst
index 2a977760952..7a5a1f8ef18 100644
--- a/Doc/library/unicodedata.rst
+++ b/Doc/library/unicodedata.rst
@@ -17,8 +17,8 @@
This module provides access to the Unicode Character Database (UCD) which
defines character properties for all Unicode characters. The data contained in
-this database is compiled from the `UCD version 9.0.0
-`_.
+this database is compiled from the `UCD version 10.0.0
+`_.
The module uses the same names and symbols as defined by Unicode
Standard Annex #44, `"Unicode Character Database"
@@ -168,6 +168,6 @@ Examples:
.. rubric:: Footnotes
-.. [#] http://www.unicode.org/Public/9.0.0/ucd/NameAliases.txt
+.. [#] http://www.unicode.org/Public/10.0.0/ucd/NameAliases.txt
-.. [#] http://www.unicode.org/Public/9.0.0/ucd/NamedSequences.txt
+.. [#] http://www.unicode.org/Public/10.0.0/ucd/NamedSequences.txt
diff --git a/Doc/library/unittest.mock.rst b/Doc/library/unittest.mock.rst
index 9e8bf11a92d..b6eb8ccb59d 100644
--- a/Doc/library/unittest.mock.rst
+++ b/Doc/library/unittest.mock.rst
@@ -2365,3 +2365,23 @@ alternative object as the *autospec* argument:
a mocked class to create a mock instance *does not* create a real instance.
It is only attribute lookups - along with calls to :func:`dir` - that are done.
+Sealing mocks
+~~~~~~~~~~~~~
+
+.. function:: seal(mock)
+
+ Seal will disable the creation of mock children by preventing to get or set
+ any new attribute on the sealed mock. The sealing process is performed recursively.
+
+ If a mock instance is assigned to an attribute instead of being dynamically created
+ it won't be considered in the sealing chain. This allows to prevent seal from fixing
+ part of the mock object.
+
+ >>> mock = Mock()
+ >>> mock.submock.attribute1 = 2
+ >>> mock.not_submock = mock.Mock()
+ >>> seal(mock)
+ >>> mock.submock.attribute2 # This will raise AttributeError.
+ >>> mock.not_submock.attribute2 # This won't raise.
+
+ .. versionadded:: 3.7
diff --git a/Doc/library/unittest.rst b/Doc/library/unittest.rst
index 2099bd1e2e9..e52f140029c 100644
--- a/Doc/library/unittest.rst
+++ b/Doc/library/unittest.rst
@@ -402,10 +402,14 @@ you can do it yourself::
def suite():
suite = unittest.TestSuite()
- suite.addTest(WidgetTestCase('test_default_size'))
- suite.addTest(WidgetTestCase('test_resize'))
+ suite.addTest(WidgetTestCase('test_default_widget_size'))
+ suite.addTest(WidgetTestCase('test_widget_resize'))
return suite
+ if __name__ == '__main__':
+ runner = unittest.TextTestRunner()
+ runner.run(suite())
+
You can place the definitions of test cases and test suites in the same modules
as the code they are to test (such as :file:`widget.py`), but there are several
advantages to placing the test code in a separate module, such as
diff --git a/Doc/library/wave.rst b/Doc/library/wave.rst
index a9b3205322d..5c315c51617 100644
--- a/Doc/library/wave.rst
+++ b/Doc/library/wave.rst
@@ -51,6 +51,8 @@ The :mod:`wave` module defines the following function and exception:
A synonym for :func:`.open`, maintained for backwards compatibility.
+ .. deprecated-removed:: 3.7 3.9
+
.. exception:: Error
diff --git a/Doc/library/xml.etree.elementtree.rst b/Doc/library/xml.etree.elementtree.rst
index 7d814ad406e..61808596a55 100644
--- a/Doc/library/xml.etree.elementtree.rst
+++ b/Doc/library/xml.etree.elementtree.rst
@@ -437,6 +437,11 @@ Supported XPath syntax
| ``[tag]`` | Selects all elements that have a child named |
| | ``tag``. Only immediate children are supported. |
+-----------------------+------------------------------------------------------+
+| ``[.='text']`` | Selects all elements whose complete text content, |
+| | including descendants, equals the given ``text``. |
+| | |
+| | .. versionadded:: 3.7 |
++-----------------------+------------------------------------------------------+
| ``[tag='text']`` | Selects all elements that have a child named |
| | ``tag`` whose complete text content, including |
| | descendants, equals the given ``text``. |
diff --git a/Doc/library/zipapp.rst b/Doc/library/zipapp.rst
index 71753cb9a0d..9076593c4b1 100644
--- a/Doc/library/zipapp.rst
+++ b/Doc/library/zipapp.rst
@@ -79,6 +79,15 @@ The following options are understood:
:option:`--main` cannot be specified when copying an archive.
+.. cmdoption:: -c, --compress
+
+ Compress files with the deflate method, reducing the size of the output
+ file. By default, files are stored uncompressed in the archive.
+
+ :option:`--compress` has no effect when copying an archive.
+
+ .. versionadded:: 3.7
+
.. cmdoption:: --info
Display the interpreter embedded in the archive, for diagnostic purposes. In
@@ -98,7 +107,7 @@ Python API
The module defines two convenience functions:
-.. function:: create_archive(source, target=None, interpreter=None, main=None)
+.. function:: create_archive(source, target=None, interpreter=None, main=None, filter=None, compressed=False)
Create an application archive from *source*. The source can be any
of the following:
@@ -143,6 +152,16 @@ The module defines two convenience functions:
contain a ``__main__.py`` file, as otherwise the resulting archive
would not be executable.
+ The optional *filter* argument specifies a callback function that
+ is passed a Path object representing the path to the file being added
+ (relative to the source directory). It should return ``True`` if the
+ file is to be added.
+
+ The optional *compressed* argument determines whether files are
+ compressed. If set to ``True``, files in the archive are compressed
+ with the deflate method; otherwise, files are stored uncompressed.
+ This argument has no effect when copying an existing archive.
+
If a file object is specified for *source* or *target*, it is the
caller's responsibility to close it after calling create_archive.
@@ -152,6 +171,9 @@ The module defines two convenience functions:
passed to the ``zipfile.ZipFile`` class, and must supply the methods
needed by that class.
+ .. versionadded:: 3.7
+ Added the *filter* and *compressed* arguments.
+
.. function:: get_interpreter(archive)
Return the interpreter specified in the ``#!`` line at the start of the
diff --git a/Doc/make.bat b/Doc/make.bat
index d9c0ad0adec..3f201de1db7 100644
--- a/Doc/make.bat
+++ b/Doc/make.bat
@@ -5,8 +5,30 @@ pushd %~dp0
set this=%~n0
-if "%SPHINXBUILD%" EQU "" set SPHINXBUILD=sphinx-build
-if "%PYTHON%" EQU "" set PYTHON=py
+call ..\PCbuild\find_python.bat %PYTHON%
+if not defined SPHINXBUILD if defined PYTHON (
+ %PYTHON% -c "import sphinx" > nul 2> nul
+ if errorlevel 1 (
+ echo Installing sphinx with %PYTHON%
+ %PYTHON% -m pip install sphinx
+ if errorlevel 1 exit /B
+ )
+ set SPHINXBUILD=%PYTHON% -c "import sphinx, sys; sys.argv[0] = 'sphinx-build'; sphinx.main()"
+)
+
+if not defined BLURB if defined PYTHON (
+ %PYTHON% -c "import blurb" > nul 2> nul
+ if errorlevel 1 (
+ echo Installing blurb with %PYTHON%
+ %PYTHON% -m pip install blurb
+ if errorlevel 1 exit /B
+ )
+ set BLURB=%PYTHON% -m blurb
+)
+
+if not defined PYTHON set PYTHON=py
+if not defined SPHINXBUILD set SPHINXBUILD=sphinx-build
+if not defined BLURB set BLURB=blurb
if "%1" NEQ "htmlhelp" goto :skiphhcsearch
if exist "%HTMLHELP%" goto :skiphhcsearch
@@ -36,7 +58,7 @@ if "%1" EQU "help" goto help
if "%1" EQU "check" goto check
if "%1" EQU "serve" goto serve
if "%1" == "clean" (
- rmdir /q /s %BUILDDIR%
+ rmdir /q /s "%BUILDDIR%"
goto end
)
@@ -85,13 +107,28 @@ echo.be passed by setting the SPHINXOPTS environment variable.
goto end
:build
+if not exist "%BUILDDIR%" mkdir "%BUILDDIR%"
+
+if exist ..\Misc\NEWS (
+ echo.Copying Misc\NEWS to build\NEWS
+ copy ..\Misc\NEWS build\NEWS > nul
+) else if exist ..\Misc\NEWS.D (
+ if defined BLURB (
+ echo.Merging Misc/NEWS with %BLURB%
+ %BLURB% merge -f build\NEWS
+ ) else (
+ echo.No Misc/NEWS file and Blurb is not available.
+ exit /B 1
+ )
+)
+
if NOT "%PAPER%" == "" (
set SPHINXOPTS=-D latex_elements.papersize=%PAPER% %SPHINXOPTS%
)
-cmd /C %SPHINXBUILD% %SPHINXOPTS% -b%1 -dbuild\doctrees . %BUILDDIR%\%*
+cmd /S /C "%SPHINXBUILD% %SPHINXOPTS% -b%1 -dbuild\doctrees . "%BUILDDIR%\%1" %2 %3 %4 %5 %6 %7 %8 %9"
if "%1" EQU "htmlhelp" (
- cmd /C "%HTMLHELP%" build\htmlhelp\python%DISTVERSION:.=%.hhp
+ "%HTMLHELP%" "%BUILDDIR%\htmlhelp\python%DISTVERSION:.=%.hhp"
rem hhc.exe seems to always exit with code 1, reset to 0 for less than 2
if not errorlevel 2 cmd /C exit /b 0
)
@@ -111,19 +148,19 @@ if NOT "%2" EQU "" (
)
cmd /C %this% html
-if EXIST %BUILDDIR%\html\index.html (
- echo.Opening %BUILDDIR%\html\index.html in the default web browser...
- start %BUILDDIR%\html\index.html
+if EXIST "%BUILDDIR%\html\index.html" (
+ echo.Opening "%BUILDDIR%\html\index.html" in the default web browser...
+ start "%BUILDDIR%\html\index.html"
)
goto end
:check
-cmd /C %PYTHON% tools\rstlint.py -i tools
+cmd /S /C "%PYTHON% tools\rstlint.py -i tools"
goto end
:serve
-cmd /C %PYTHON% ..\Tools\scripts\serve.py %BUILDDIR%\html
+cmd /S /C "%PYTHON% ..\Tools\scripts\serve.py "%BUILDDIR%\html""
goto end
:end
diff --git a/Doc/reference/compound_stmts.rst b/Doc/reference/compound_stmts.rst
index 4b425a48209..dca93624004 100644
--- a/Doc/reference/compound_stmts.rst
+++ b/Doc/reference/compound_stmts.rst
@@ -773,7 +773,6 @@ Is semantically equivalent to::
mgr = (EXPR)
aexit = type(mgr).__aexit__
aenter = type(mgr).__aenter__(mgr)
- exc = True
VAR = await aenter
try:
diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst
index 24a2618b01e..153b58b4fbf 100644
--- a/Doc/reference/datamodel.rst
+++ b/Doc/reference/datamodel.rst
@@ -970,10 +970,20 @@ Internal types
.. index::
single: f_trace (frame attribute)
+ single: f_trace_lines (frame attribute)
+ single: f_trace_opcodes (frame attribute)
single: f_lineno (frame attribute)
Special writable attributes: :attr:`f_trace`, if not ``None``, is a function
- called at the start of each source code line (this is used by the debugger);
+ called for various events during code execution (this is used by the debugger).
+ Normally an event is triggered for each new source line - this can be
+ disabled by setting :attr:`f_trace_lines` to :const:`False`.
+
+ Implementations *may* allow per-opcode events to be requested by setting
+ :attr:`f_trace_opcodes` to :const:`True`. Note that this may lead to
+ undefined interpreter behaviour if exceptions raised by the trace
+ function escape to the function being traced.
+
:attr:`f_lineno` is the current line number of the frame --- writing to this
from within a trace function jumps to the given line (only for the bottom-most
frame). A debugger can implement a Jump command (aka Set Next Statement)
@@ -1886,8 +1896,8 @@ Metaclass example
^^^^^^^^^^^^^^^^^
The potential uses for metaclasses are boundless. Some ideas that have been
-explored include logging, interface checking, automatic delegation, automatic
-property creation, proxies, frameworks, and automatic resource
+explored include enum, logging, interface checking, automatic delegation,
+automatic property creation, proxies, frameworks, and automatic resource
locking/synchronization.
Here is an example of a metaclass that uses an :class:`collections.OrderedDict`
@@ -2510,9 +2520,8 @@ generators, coroutines do not directly support iteration.
Asynchronous Iterators
----------------------
-An *asynchronous iterable* is able to call asynchronous code in its
-``__aiter__`` implementation, and an *asynchronous iterator* can call
-asynchronous code in its ``__anext__`` method.
+An *asynchronous iterator* can call asynchronous code in
+its ``__anext__`` method.
Asynchronous iterators can be used in an :keyword:`async for` statement.
@@ -2542,48 +2551,14 @@ An example of an asynchronous iterable object::
.. versionadded:: 3.5
-.. note::
+.. versionchanged:: 3.7
+ Prior to Python 3.7, ``__aiter__`` could return an *awaitable*
+ that would resolve to an
+ :term:`asynchronous iterator `.
- .. versionchanged:: 3.5.2
- Starting with CPython 3.5.2, ``__aiter__`` can directly return
- :term:`asynchronous iterators `. Returning
- an :term:`awaitable` object will result in a
- :exc:`PendingDeprecationWarning`.
-
- The recommended way of writing backwards compatible code in
- CPython 3.5.x is to continue returning awaitables from
- ``__aiter__``. If you want to avoid the PendingDeprecationWarning
- and keep the code backwards compatible, the following decorator
- can be used::
-
- import functools
- import sys
-
- if sys.version_info < (3, 5, 2):
- def aiter_compat(func):
- @functools.wraps(func)
- async def wrapper(self):
- return func(self)
- return wrapper
- else:
- def aiter_compat(func):
- return func
-
- Example::
-
- class AsyncIterator:
-
- @aiter_compat
- def __aiter__(self):
- return self
-
- async def __anext__(self):
- ...
-
- Starting with CPython 3.6, the :exc:`PendingDeprecationWarning`
- will be replaced with the :exc:`DeprecationWarning`.
- In CPython 3.7, returning an awaitable from ``__aiter__`` will
- result in a :exc:`RuntimeError`.
+ Starting with Python 3.7, ``__aiter__`` must return an
+ asynchronous iterator object. Returning anything else
+ will result in a :exc:`TypeError` error.
.. _async-context-managers:
diff --git a/Doc/reference/expressions.rst b/Doc/reference/expressions.rst
index ddcbd5567c1..1cff8a52df9 100644
--- a/Doc/reference/expressions.rst
+++ b/Doc/reference/expressions.rst
@@ -326,14 +326,16 @@ range(10) for y in bar(x))``.
The parentheses can be omitted on calls with only one argument. See section
:ref:`calls` for details.
-Since Python 3.6, if the generator appears in an :keyword:`async def` function,
-then :keyword:`async for` clauses and :keyword:`await` expressions are permitted
-as with an asynchronous comprehension. If a generator expression
-contains either :keyword:`async for` clauses or :keyword:`await` expressions
-it is called an :dfn:`asynchronous generator expression`.
-An asynchronous generator expression yields a new asynchronous
-generator object, which is an asynchronous iterator
-(see :ref:`async-iterators`).
+If a generator expression contains either :keyword:`async for`
+clauses or :keyword:`await` expressions it is called an
+:dfn:`asynchronous generator expression`. An asynchronous generator
+expression returns a new asynchronous generator object,
+which is an asynchronous iterator (see :ref:`async-iterators`).
+
+.. versionchanged:: 3.7
+ Prior to Python 3.7, asynchronous generator expressions could
+ only appear in :keyword:`async def` coroutines. Starting
+ with 3.7, any function can use asynchronous generator expressions.
.. _yieldexpr:
@@ -1687,8 +1689,8 @@ precedence and have a left-to-right chaining feature as described in the
| ``+``, ``-`` | Addition and subtraction |
+-----------------------------------------------+-------------------------------------+
| ``*``, ``@``, ``/``, ``//``, ``%`` | Multiplication, matrix |
-| | multiplication division, |
-| | remainder [#]_ |
+| | multiplication, division, floor |
+| | division, remainder [#]_ |
+-----------------------------------------------+-------------------------------------+
| ``+x``, ``-x``, ``~x`` | Positive, negative, bitwise NOT |
+-----------------------------------------------+-------------------------------------+
diff --git a/Doc/reference/import.rst b/Doc/reference/import.rst
index d504f373874..881e0aed32e 100644
--- a/Doc/reference/import.rst
+++ b/Doc/reference/import.rst
@@ -28,11 +28,10 @@ such as the importing of parent packages, and the updating of various caches
(including :data:`sys.modules`), only the :keyword:`import` statement performs
a name binding operation.
-When calling :func:`__import__` as part of an import statement, the
-standard builtin :func:`__import__` is called. Other mechanisms for
-invoking the import system (such as :func:`importlib.import_module`) may
-choose to subvert :func:`__import__` and use its own solution to
-implement import semantics.
+When an :keyword:`import` statement is executed, the standard builtin
+:func:`__import__` function is called. Other mechanisms for invoking the
+import system (such as :func:`importlib.import_module`) may choose to bypass
+:func:`__import__` and use their own solutions to implement import semantics.
When a module is first imported, Python searches for the module and if found,
it creates a module object [#fnmo]_, initializing it. If the named module
@@ -519,8 +518,9 @@ and the loader that executes it. Most importantly, it allows the
import machinery to perform the boilerplate operations of loading,
whereas without a module spec the loader had that responsibility.
-See :class:`~importlib.machinery.ModuleSpec` for more specifics on what
-information a module's spec may hold.
+The module's spec is exposed as the ``__spec__`` attribute on a module object.
+See :class:`~importlib.machinery.ModuleSpec` for details on the contents of
+the module spec.
.. versionadded:: 3.4
@@ -965,7 +965,7 @@ References
The import machinery has evolved considerably since Python's early days. The
original `specification for packages
-`_ is still available to read,
+`_ to support backwards
+ `_ to support backwards
compatibility
* *Other_ID_Continue* - likewise
@@ -340,13 +340,13 @@ exactly as written here:
.. sourcecode:: text
- False class finally is return
- None continue for lambda try
- True def from nonlocal while
- and del global not with
- as elif if or yield
- assert else import pass
- break except in raise
+ False await else import pass
+ None break except in raise
+ True class finally is return
+ and continue for lambda try
+ as def from nonlocal while
+ assert del global not with
+ async elif if or yield
.. _id-classes:
@@ -446,9 +446,6 @@ instance of the :class:`bytes` type instead of the :class:`str` type. They
may only contain ASCII characters; bytes with a numeric value of 128 or greater
must be expressed with escapes.
-As of Python 3.3 it is possible again to prefix string literals with a
-``u`` prefix to simplify maintenance of dual 2.x and 3.x codebases.
-
Both string and bytes literals may optionally be prefixed with a letter ``'r'``
or ``'R'``; such strings are called :dfn:`raw strings` and treat backslashes as
literal characters. As a result, in string literals, ``'\U'`` and ``'\u'``
@@ -676,6 +673,12 @@ Some examples of formatted string literals::
>>> value = decimal.Decimal("12.34567")
>>> f"result: {value:{width}.{precision}}" # nested fields
'result: 12.35'
+ >>> today = datetime(year=2017, month=1, day=27)
+ >>> f"{today:%b %d, %Y}" # using date format specifier
+ 'January 27, 2017'
+ >>> number = 1024
+ >>> f"{number:#0x}" # using integer format specifier
+ '0x400'
A consequence of sharing the same syntax as regular string literals is
that characters in the replacement fields must not conflict with the
@@ -793,10 +796,6 @@ Some examples of floating point literals::
3.14 10. .001 1e100 3.14e-10 0e0 3.14_15_93
-Note that numeric literals do not include a sign; a phrase like ``-1`` is
-actually an expression composed of the unary operator ``-`` and the literal
-``1``.
-
.. versionchanged:: 3.6
Underscores are now allowed for grouping purposes in literals.
@@ -875,4 +874,4 @@ occurrence outside string literals and comments is an unconditional error:
.. rubric:: Footnotes
-.. [#] http://www.unicode.org/Public/8.0.0/ucd/NameAliases.txt
+.. [#] http://www.unicode.org/Public/10.0.0/ucd/NameAliases.txt
diff --git a/Doc/reference/simple_stmts.rst b/Doc/reference/simple_stmts.rst
index 8786d73f68a..8d17383853a 100644
--- a/Doc/reference/simple_stmts.rst
+++ b/Doc/reference/simple_stmts.rst
@@ -931,7 +931,7 @@ annotation.
.. impl-detail::
- The current implementation does not enforce some of these restriction, but
+ The current implementation does not enforce some of these restrictions, but
programs should not abuse this freedom, as future implementations may enforce
them or silently change the meaning of the program.
diff --git a/Doc/tools/extensions/pyspecific.py b/Doc/tools/extensions/pyspecific.py
index 461e7a28b55..00acd4f55b8 100644
--- a/Doc/tools/extensions/pyspecific.py
+++ b/Doc/tools/extensions/pyspecific.py
@@ -15,6 +15,7 @@ from os import path
from time import asctime
from pprint import pformat
from docutils.io import StringOutput
+from docutils.parsers.rst import Directive
from docutils.utils import new_document
from docutils import nodes, utils
@@ -23,7 +24,6 @@ from sphinx import addnodes
from sphinx.builders import Builder
from sphinx.locale import translators
from sphinx.util.nodes import split_explicit_title
-from sphinx.util.compat import Directive
from sphinx.writers.html import HTMLTranslator
from sphinx.writers.text import TextWriter
from sphinx.writers.latex import LaTeXTranslator
@@ -272,9 +272,9 @@ class MiscNews(Directive):
# Support for building "topic help" for pydoc
pydoc_topic_labels = [
- 'assert', 'assignment', 'atom-identifiers', 'atom-literals',
- 'attribute-access', 'attribute-references', 'augassign', 'binary',
- 'bitwise', 'bltin-code-objects', 'bltin-ellipsis-object',
+ 'assert', 'assignment', 'async', 'atom-identifiers', 'atom-literals',
+ 'attribute-access', 'attribute-references', 'augassign', 'await',
+ 'binary', 'bitwise', 'bltin-code-objects', 'bltin-ellipsis-object',
'bltin-null-object', 'bltin-type-objects', 'booleans',
'break', 'callable-types', 'calls', 'class', 'comparisons', 'compound',
'context-managers', 'continue', 'conversions', 'customization', 'debugger',
diff --git a/Doc/tools/static/switchers.js b/Doc/tools/static/switchers.js
new file mode 100644
index 00000000000..c450f5eafff
--- /dev/null
+++ b/Doc/tools/static/switchers.js
@@ -0,0 +1,145 @@
+(function() {
+ 'use strict';
+
+ // Parses versions in URL segments like:
+ // "3", "dev", "release/2.7" or "3.6rc2"
+ var version_regexs = [
+ '(?:\\d)',
+ '(?:\\d\\.\\d[\\w\\d\\.]*)',
+ '(?:dev)',
+ '(?:release/\\d.\\d[\\x\\d\\.]*)'];
+
+ var all_versions = {
+ '3.7': 'dev (3.7)',
+ '3.6': '3.6',
+ '3.5': '3.5',
+ '2.7': '2.7',
+ };
+
+ var all_languages = {
+ 'en': 'English',
+ 'fr': 'French',
+ 'ja': 'Japanese',
+ };
+
+ function build_version_select(current_version, current_release) {
+ var buf = [''];
+
+ $.each(all_versions, function(version, title) {
+ buf.push('' + current_release + ' ');
+ else
+ buf.push('>' + title + '');
+ });
+
+ buf.push(' ');
+ return buf.join('');
+ }
+
+ function build_language_select(current_language) {
+ var buf = [''];
+
+ $.each(all_languages, function(language, title) {
+ if (language == current_language)
+ buf.push('' +
+ all_languages[current_language] + ' ');
+ else
+ buf.push('' + title + ' ');
+ });
+ buf.push(' ');
+ return buf.join('');
+ }
+
+ function navigate_to_first_existing(urls) {
+ // Navigate to the first existing URL in urls.
+ var url = urls.shift();
+ if (urls.length == 0) {
+ window.location.href = url;
+ return;
+ }
+ $.ajax({
+ url: url,
+ success: function() {
+ window.location.href = url;
+ },
+ error: function() {
+ navigate_to_first_existing(urls);
+ }
+ });
+ }
+
+ function on_version_switch() {
+ var selected_version = $(this).children('option:selected').attr('value') + '/';
+ var url = window.location.href;
+ var current_language = language_segment_from_url(url);
+ var current_version = version_segment_in_url(url);
+ var new_url = url.replace('.org/' + current_language + current_version,
+ '.org/' + current_language + selected_version);
+ if (new_url != url) {
+ navigate_to_first_existing([
+ new_url,
+ url.replace('.org/' + current_language + current_version,
+ '.org/' + selected_version),
+ 'https://docs.python.org/' + current_language + selected_version,
+ 'https://docs.python.org/' + selected_version,
+ 'https://docs.python.org/'
+ ]);
+ }
+ }
+
+ function on_language_switch() {
+ var selected_language = $(this).children('option:selected').attr('value') + '/';
+ var url = window.location.href;
+ var current_language = language_segment_from_url(url);
+ var current_version = version_segment_in_url(url);
+ if (selected_language == 'en/') // Special 'default' case for english.
+ selected_language = '';
+ var new_url = url.replace('.org/' + current_language + current_version,
+ '.org/' + selected_language + current_version);
+ if (new_url != url) {
+ navigate_to_first_existing([
+ new_url,
+ 'https://docs.python.org/'
+ ]);
+ }
+ }
+
+ // Returns the path segment of the language as a string, like 'fr/'
+ // or '' if not found.
+ function language_segment_from_url(url) {
+ var language_regexp = '\.org/([a-z]{2}(?:-[a-z]{2})?/)';
+ var match = url.match(language_regexp);
+ if (match !== null)
+ return match[1];
+ return '';
+ }
+
+ // Returns the path segment of the version as a string, like '3.6/'
+ // or '' if not found.
+ function version_segment_in_url(url) {
+ var language_segment = '(?:[a-z]{2}(?:-[a-z]{2})?/)';
+ var version_segment = '(?:(?:' + version_regexs.join('|') + ')/)';
+ var version_regexp = '\\.org/' + language_segment + '?(' + version_segment + ')';
+ var match = url.match(version_regexp);
+ if (match !== null)
+ return match[1];
+ return ''
+ }
+
+ $(document).ready(function() {
+ var release = DOCUMENTATION_OPTIONS.VERSION;
+ var language_segment = language_segment_from_url(window.location.href);
+ var current_language = language_segment.replace(/\/+$/g, '') || 'en';
+ var version = release.substr(0, 3);
+ var version_select = build_version_select(version, release);
+
+ $('.version_switcher_placeholder').html(version_select);
+ $('.version_switcher_placeholder select').bind('change', on_version_switch);
+
+ var language_select = build_language_select(current_language);
+
+ $('.language_switcher_placeholder').html(language_select);
+ $('.language_switcher_placeholder select').bind('change', on_language_switch);
+ });
+})();
diff --git a/Doc/tools/static/version_switch.js b/Doc/tools/static/version_switch.js
deleted file mode 100644
index 8b36a616718..00000000000
--- a/Doc/tools/static/version_switch.js
+++ /dev/null
@@ -1,67 +0,0 @@
-(function() {
- 'use strict';
-
- var all_versions = {
- '3.7': 'dev (3.7)',
- '3.6': '3.6',
- '3.5': '3.5',
- '3.4': '3.4',
- '3.3': '3.3',
- '2.7': '2.7',
- };
-
- function build_select(current_version, current_release) {
- var buf = [''];
-
- $.each(all_versions, function(version, title) {
- buf.push('' + current_release + ' ');
- else
- buf.push('>' + title + '');
- });
-
- buf.push(' ');
- return buf.join('');
- }
-
- function patch_url(url, new_version) {
- var url_re = /\.org\/(\d|py3k|dev|((release\/)?\d\.\d[\w\d\.]*))\//,
- new_url = url.replace(url_re, '.org/' + new_version + '/');
-
- if (new_url == url && !new_url.match(url_re)) {
- // python 2 url without version?
- new_url = url.replace(/\.org\//, '.org/' + new_version + '/');
- }
- return new_url;
- }
-
- function on_switch() {
- var selected = $(this).children('option:selected').attr('value');
-
- var url = window.location.href,
- new_url = patch_url(url, selected);
-
- if (new_url != url) {
- // check beforehand if url exists, else redirect to version's start page
- $.ajax({
- url: new_url,
- success: function() {
- window.location.href = new_url;
- },
- error: function() {
- window.location.href = 'https://docs.python.org/' + selected;
- }
- });
- }
- }
-
- $(document).ready(function() {
- var release = DOCUMENTATION_OPTIONS.VERSION;
- var version = release.substr(0, 3);
- var select = build_select(version, release);
-
- $('.version_switcher_placeholder').html(select);
- $('.version_switcher_placeholder select').bind('change', on_switch);
- });
-})();
diff --git a/Doc/tools/susp-ignored.csv b/Doc/tools/susp-ignored.csv
index c0c95d0fea1..d52f81b76b5 100644
--- a/Doc/tools/susp-ignored.csv
+++ b/Doc/tools/susp-ignored.csv
@@ -130,9 +130,6 @@ library/exceptions,,:err,err.object[err.start:err.end]
library/functions,,:step,a[start:stop:step]
library/functions,,:stop,"a[start:stop, i]"
library/functions,,:stop,a[start:stop:step]
-library/hashlib,,:vatrogasac,>>> cookie = b'user:vatrogasac'
-library/hashlib,,:vatrogasac,"user:vatrogasac,349cf904533767ed2d755279a8df84d0"
-library/hashlib,,:policajac,">>> compare_digest(b'user:policajac', sig)"
library/hashlib,,:LEAF,"h00 = blake2b(buf[0:LEAF_SIZE], fanout=FANOUT, depth=DEPTH,"
library/http.client,,:port,host:port
library/http.cookies,,`,!#$%&'*+-.^_`|~:
@@ -303,7 +300,7 @@ whatsnew/3.2,,:gz,">>> with tarfile.open(name='myarchive.tar.gz', mode='w:gz') a
whatsnew/3.2,,:location,zope9-location = ${zope9:location}
whatsnew/3.2,,:prefix,zope-conf = ${custom:prefix}/etc/zope.conf
library/re,,`,!#$%&'*+-.^_`|~:
-library/re,,`,!\#\$%&'\*\+\-\.\^_`\|~:
+library/re,,`,!\#\$%\&'\*\+\-\.\^_`\|\~:
library/tarfile,,:xz,'x:xz'
library/xml.etree.elementtree,,:sometag,prefix:sometag
library/xml.etree.elementtree,,:fictional,">> addr6 = ipaddress.IPv6Address('::1')
whatsnew/3.5,,:root,ERROR:root:exception
whatsnew/3.5,,:exception,ERROR:root:exception
-whatsnew/changelog,,:version,import sys; I = version[:version.index(' ')]
+whatsnew/changelog,,`,'`'
whatsnew/changelog,,:end,str[start:end]
library/binascii,,`,'`'
library/uu,,`,'`'
whatsnew/3.7,,`,'`'
-whatsnew/changelog,,`,'`'
diff --git a/Doc/tools/templates/customsourcelink.html b/Doc/tools/templates/customsourcelink.html
index 42172909cae..fca44e9163c 100644
--- a/Doc/tools/templates/customsourcelink.html
+++ b/Doc/tools/templates/customsourcelink.html
@@ -4,7 +4,7 @@