mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-09-26 18:29:57 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 10

Merge branch 'master' into fix-issue-30688

Browse source
This commit is contained in:
Serhiy Storchaka 2017-11-20 19:17:59 +02:00 • committed by GitHub
commit 1113472faa
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1258 changed files with 113979 additions and 91396 deletions
Download patch file Download diff file Expand all files Collapse all files

3
.gitattributes vendored
View file

@ -27,9 +27,6 @@ Lib/test/test_email/data/*.txt -text
Lib/test/xmltestdata/* -text
Lib/test/coding20731.py -text
# Special files in third party code
Modules/zlib/zlib.map -text
# CRLF files
*.bat text eol=crlf
*.ps1 text eol=crlf

53
.github/CODEOWNERS vendored Normal file
View file

@ -0,0 +1,53 @@
# See https://help.github.com/articles/about-codeowners/
# for more info about CODEOWNERS file
# It uses the same pattern rule for gitignore file
# https://git-scm.com/docs/gitignore#_pattern_format
# asyncio
**/*asyncio* @1st1
# Core
**/*genobject* @1st1
# Hashing
**/*hashlib* @python/crypto-team
**/*pyhash* @python/crypto-team
# Import (including importlib)
**/*import* @python/import-team
# SSL
**/*ssl* @python/crypto-team
# CSPRNG
Python/bootstrap_hash.c @python/crypto-team
# Email and related
**/*mail* @python/email-team
**/*smtp* @python/email-team
**/*mime* @python/email-team
**/*imap* @python/email-team
**/*poplib* @python/email-team
# subprocess
**/*subprocess* @gpshead
# Windows
/PC/ @python/windows-team
/PCbuild/ @python/windows-team
# Windows installer packages
/Tools/msi/ @python/windows-team
/Tools/nuget/ @python/windows-team
**/*itertools* @rhettinger
**/*collections* @rhettinger
**/*random* @rhettinger
**/*queue* @rhettinger
**/*bisect* @rhettinger
**/*heapq* @rhettinger
**/*functools* @ncoghlan @rhettinger
**/*decimal* @rhettinger @skrah
**/*idlelib* @terryjreedy

14
.github/CODE_OF_CONDUCT.rst vendored Normal file
View file

@ -0,0 +1,14 @@
Code of Conduct
===============
Please note that all interactions on
`Python Software Foundation <https://www.python.org/psf-landing/>`__-supported
infrastructure is `covered
<https://www.python.org/psf/records/board/minutes/2014-01-06/#management-of-the-psfs-web-properties>`__
by the `PSF Code of Conduct <https://www.python.org/psf/codeofconduct/>`__,
which includes all infrastructure used in the development of Python itself
(e.g. mailing lists, issue trackers, GitHub, etc.).
In general this means everyone is expected to be open, considerate, and
respectful of others no matter what their position is within the project.

38
.github/CONTRIBUTING.rst vendored
View file

@ -12,31 +12,47 @@ Build Status
+ `Stable buildbots <http://buildbot.python.org/3.6.stable/>`_
- 3.5
+ `Stable buildbots <http://buildbot.python.org/3.5.stable/>`_
- 2.7
+ `Stable buildbots <http://buildbot.python.org/2.7.stable/>`_
Thank You
---------
First off, thanks for contributing to the maintenance of the Python programming
language and the CPython interpreter! Even if your contribution is not
ultimately accepted, the fact you put time and effort into helping out is
greatly appreciated.
Contribution Guidelines
-----------------------
Please read the `devguide <https://cpython-devguide.readthedocs.io/>`_ for
Please read the `devguide <https://devguide.python.org/>`_ for
guidance on how to contribute to this project. The documentation covers
everything from how to build the code to submitting a pull request. There are
also suggestions on how you can most effectively help the project.
Please be aware that our workflow does deviate slightly from the typical GitHub
project. Details on how to properly submit a pull request are covered in
`Lifecycle of a Pull Request <https://cpython-devguide.readthedocs.io/pullrequest.html>`_.
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 <https://devguide.python.org/pullrequest/>`_.
We utilize various bots and status checks to help with this, so do follow the
comments they leave and their "Details" links, respectively. The key points of
our workflow that are not covered by a bot or status check are:
If you are making a code contribution or large documentation contribution,
please feel free to add yourself to the ``Misc/ACKS`` file alphabetically.
- All discussions that are not directly related to the code in the pull request
should happen on bugs.python.org
- Upon your first non-trivial pull request (which includes documentation changes),
feel free to add yourself to ``Misc/ACKS``
Setting Expectations
--------------------
Due to the fact that this project is entirely volunteer-run (i.e. no one is paid
to work on Python full-time), we unfortunately can make no guarantees as to if
or when a core developer will get around to reviewing your pull request.
If no core developer has done a review or responded to changes made because of a
"changes requested" review, please feel free to email python-dev to ask if
someone could take a look at your pull request.
Code of Conduct

10
.github/PULL_REQUEST_TEMPLATE.md vendored Normal file
View file

@ -0,0 +1,10 @@
!!! If this is a backport PR (PR made against branches other than `master`),
please ensure that the PR title is in the following format:
```
[X.Y] <title from the original PR> (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!!!

11
.github/appveyor.yml vendored
View file

@ -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/

5
.gitignore vendored
View file

@ -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

20
.mention-bot
View file

@ -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"]
}
]
}

30
.travis.yml
View file

@ -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

31
Doc/Makefile
View file

@ -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

53
Doc/README.rst
View file

@ -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.

2
Doc/bugs.rst
View file

@ -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/

2
Doc/c-api/buffer.rst
View file

@ -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

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

@ -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.

7
Doc/c-api/import.rst
View file

@ -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)

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

@ -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()

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

@ -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

21
Doc/c-api/mapping.rst
View file

@ -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)

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

@ -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

18
Doc/c-api/slice.rst
View file

@ -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

40
Doc/c-api/structures.rst
View file

@ -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.

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

@ -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

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

@ -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:

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

@ -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)

15
Doc/conf.py
View file

@ -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]).

2
Doc/copyright.rst
View file

@ -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.

15
Doc/distutils/apiref.rst
View file

@ -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``.

6
Doc/distutils/builtdist.rst
View file

@ -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.

2
Doc/docutils.conf Normal file
View file

@ -0,0 +1,2 @@
[restructuredtext parser]
smartquotes-locales: ja: ""''

12
Doc/extending/extending.rst
View file

@ -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

40
Doc/extending/newtypes.rst
View file

@ -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 */

6
Doc/faq/general.rst
View file

@ -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?

9
Doc/faq/gui.rst
View file

@ -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
------

2
Doc/faq/programming.rst
View file

@ -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.

5
Doc/glossary.rst
View file

@ -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

4
Doc/howto/curses.rst
View file

@ -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>`_:

62
Doc/howto/descriptor.rst
View file

@ -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

15
Doc/howto/instrumentation.rst
View file

@ -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
-----------------

18
Doc/howto/logging-cookbook.rst
View file

@ -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::

190
Doc/howto/regex.rst
View file

@ -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</title>
The RE matches the ``'<'`` in ``<html>``, and the ``.*`` consumes the rest of
The RE matches the ``'<'`` in ``'<html>'``, 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 ``<html>`` to the ``'>'`` in
``</title>``, which isn't what you want.
final match extends from the ``'<'`` in ``'<html>'`` to the ``'>'`` in
``'</title>'``, 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.

2
Doc/includes/email-alternative.py
View file

@ -32,7 +32,7 @@ msg.add_alternative("""\
<body>
<p>Salut!</p>
<p>Cela ressemble à un excellent
<a href="http://www.yummly.com/recipe/Roasted-Asparagus-Epicurious-203718>
<a href="http://www.yummly.com/recipe/Roasted-Asparagus-Epicurious-203718">
recipie
</a> déjeuner.
</p>

18
Doc/includes/noddy.c
View file

@ -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;

1
Doc/includes/noddy4.c
View file

@ -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);
}

2
Doc/includes/sqlite3/load_extension.py
View file

@ -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

11
Doc/installing/index.rst
View file

@ -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.
<https://packaging.python.org/tutorials/installing-packages/#install-pip-setuptools-and-wheel>`__
Installing binary extensions
----------------------------

15
Doc/library/2to3.rst
View file

@ -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

17
Doc/library/_dummy_thread.rst
View file

@ -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

10
Doc/library/_thread.rst
View file

@ -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

65
Doc/library/abc.rst
View file

@ -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):
...

6
Doc/library/aifc.rst
View file

@ -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

67
Doc/library/argparse.rst
View file

@ -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=<built-in function sum>, 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.

11
Doc/library/asyncio-dev.rst
View file

@ -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 <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 <asyncio-close-transports>`.
.. 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`

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

@ -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 <asyncio-protocol>` instance.
This method is a :ref:`coroutine <coroutine>` which will try to
@ -552,6 +555,21 @@ Low-level socket operations
This method is a :ref:`coroutine <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 <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
-------------------

35
Doc/library/asyncio-eventloops.rst
View file

@ -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())

18
Doc/library/asyncio-protocol.rst
View file

@ -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

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

@ -3,6 +3,8 @@
Queues
======
**Source code:** :source:`Lib/asyncio/queues.py`
Queues:
* :class:`Queue`

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

@ -6,6 +6,8 @@
Streams (coroutine based API)
+++++++++++++++++++++++++++++
**Source code:** :source:`Lib/asyncio/streams.py`
Stream functions
================

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

@ -5,6 +5,8 @@
Subprocess
==========
**Source code:** :source:`Lib/asyncio/subprocess.py`
Windows event loop
------------------

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

@ -4,6 +4,8 @@
Synchronization primitives
==========================
**Source code:** :source:`Lib/asyncio/locks.py`
Locks:
* :class:`Lock`

8
Doc/library/asyncio-task.rst
View file

@ -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

2
Doc/library/atexit.rst
View file

@ -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

47
Doc/library/calendar.rst
View file

@ -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)

22
Doc/library/codecs.rst
View file

@ -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

7
Doc/library/collections.abc.rst
View file

@ -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

18
Doc/library/collections.rst
View file

@ -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

2
Doc/library/concurrency.rst
View file

@ -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

55
Doc/library/concurrent.futures.rst
View file

@ -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

18
Doc/library/configparser.rst
View file

@ -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.

33
Doc/library/crypt.rst
View file

@ -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
--------

6
Doc/library/csv.rst
View file

@ -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)

8
Doc/library/curses.ascii.rst
View file

@ -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.

2
Doc/library/curses.panel.rst
View file

@ -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()

222
Doc/library/curses.rst
View file

@ -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 <window.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 <window.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.

98
Doc/library/datetime.rst
View file

@ -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

39
Doc/library/dis.rst
View file

@ -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

17
Doc/library/dummy_threading.rst
View file

@ -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.

3
Doc/library/ensurepip.rst
View file

@ -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
----------

2
Doc/library/fnmatch.rst
View file

@ -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'>
<re.Match object; span=(0, 10), match='foobar.txt'>
.. seealso::

133
Doc/library/functions.rst
View file

@ -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='')

4
Doc/library/functools.rst
View file

@ -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 <single
Transform a function into a :term:`single-dispatch <single
dispatch>` :term:`generic function`.
To define a generic function, decorate it with the ``@singledispatch``

27
Doc/library/gc.rst
View file

@ -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):

179
Doc/library/gettext.rst
View file

@ -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

21
Doc/library/hashlib.rst
View file

@ -267,7 +267,7 @@ include a `salt <https://en.wikipedia.org/wiki/Salt_%28cryptography%29>`_.
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

18
Doc/library/http.client.rst
View file

@ -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.

4
Doc/library/http.rst
View file

@ -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.

64
Doc/library/idle.rst
View file

@ -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.

12
Doc/library/importlib.rst
View file

@ -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 <http://legacy.python.org/doc/essays/packages.html>`__
`Packages specification <https://www.python.org/doc/essays/packages/>`__
Original specification of packages. Some semantics have changed since
the writing of this document (e.g. redirecting based on ``None``
in :data:`sys.modules`).
@ -1048,7 +1048,15 @@ find and load modules.
.. class:: ModuleSpec(name, loader, *, origin=None, loader_state=None, is_package=None)
A specification for a module's import-system-related state.
A specification for a module's import-system-related state. This is
typically exposed as the module's ``__spec__`` attribute. In the
descriptions below, the names in parentheses give the corresponding
attribute available directly on the module object.
E.g. ``module.__spec__.origin == module.__file__``. Note however that
while the *values* are usually equivalent, they can differ since there is
no synchronization between the two objects. Thus it is possible to update
the module's ``__path__`` at runtime, and this will not be automatically
reflected in ``__spec__.submodule_search_locations``.
.. versionadded:: 3.4

24
Doc/library/ipaddress.rst
View file

@ -543,6 +543,28 @@ so to avoid duplication they are only documented for :class:`IPv4Network`.
>>> ip_network('192.0.2.0/24').supernet(new_prefix=20)
IPv4Network('192.0.0.0/20')
.. method:: subnet_of(other)
Returns *True* if this network is a subnet of *other*.
>>> a = ip_network('192.168.1.0/24')
>>> b = ip_network('192.168.1.128/30')
>>> b.subnet_of(a)
True
.. versionadded:: 3.7
.. method:: supernet_of(other)
Returns *True* if this network is a supernet of *other*.
>>> a = ip_network('192.168.1.0/24')
>>> b = ip_network('192.168.1.128/30')
>>> a.supernet_of(b)
True
.. versionadded:: 3.7
.. method:: compare_networks(other)
Compare this network to *other*. In this comparison only the network
@ -621,6 +643,8 @@ so to avoid duplication they are only documented for :class:`IPv4Network`.
.. method:: address_exclude(network)
.. method:: subnets(prefixlen_diff=1, new_prefix=None)
.. method:: supernet(prefixlen_diff=1, new_prefix=None)
.. method:: subnet_of(other)
.. method:: supernet_of(other)
.. method:: compare_networks(other)
Refer to the corresponding attribute documentation in

46
Doc/library/itertools.rst
View file

@ -53,7 +53,7 @@ Iterator Arguments Results
:func:`compress` data, selectors (d[0] if s[0]), (d[1] if s[1]), ... ``compress('ABCDEF', [1,0,1,0,1,1]) --> A C E F``
:func:`dropwhile` pred, seq seq[n], seq[n+1], starting when pred fails ``dropwhile(lambda x: x<5, [1,4,6,4,1]) --> 6 4 1``
:func:`filterfalse` pred, seq elements of seq where pred(elem) is false ``filterfalse(lambda x: x%2, range(10)) --> 0 2 4 6 8``
:func:`groupby` iterable[, keyfunc] sub-iterators grouped by value of keyfunc(v)
:func:`groupby` iterable[, key] sub-iterators grouped by value of key(v)
:func:`islice` seq, [start,] stop [, step] elements from seq[start:stop:step] ``islice('ABCDEFG', 2, None) --> C D E F G``
:func:`starmap` func, seq func(\*seq[0]), func(\*seq[1]), ... ``starmap(pow, [(2,5), (3,2), (10,3)]) --> 32 9 1000``
:func:`takewhile` pred, seq seq[0], seq[1], until pred fails ``takewhile(lambda x: x<5, [1,4,6,4,1]) --> 1 4``
@ -401,13 +401,14 @@ loops that truncate the stream.
def __iter__(self):
return self
def __next__(self):
self.id = object()
while self.currkey == self.tgtkey:
self.currvalue = next(self.it) # Exit on StopIteration
self.currkey = self.keyfunc(self.currvalue)
self.tgtkey = self.currkey
return (self.currkey, self._grouper(self.tgtkey))
def _grouper(self, tgtkey):
while self.currkey == tgtkey:
return (self.currkey, self._grouper(self.tgtkey, self.id))
def _grouper(self, tgtkey, id):
while self.id is id and self.currkey == tgtkey:
yield self.currvalue
try:
self.currvalue = next(self.it)
@ -630,26 +631,25 @@ loops that truncate the stream.
iterables are of uneven length, missing values are filled-in with *fillvalue*.
Iteration continues until the longest iterable is exhausted. Roughly equivalent to::
class ZipExhausted(Exception):
pass
def zip_longest(*args, **kwds):
def zip_longest(*args, fillvalue=None):
# zip_longest('ABCD', 'xy', fillvalue='-') --> Ax By C- D-
fillvalue = kwds.get('fillvalue')
counter = len(args) - 1
def sentinel():
nonlocal counter
if not counter:
raise ZipExhausted
counter -= 1
yield fillvalue
fillers = repeat(fillvalue)
iterators = [chain(it, sentinel(), fillers) for it in args]
try:
while iterators:
yield tuple(map(next, iterators))
except ZipExhausted:
pass
iterators = [iter(it) for it in args]
num_active = len(iterators)
if not num_active:
return
while True:
values = []
for i, it in enumerate(iterators):
try:
value = next(it)
except StopIteration:
num_active -= 1
if not num_active:
return
iterators[i] = repeat(fillvalue)
value = fillvalue
values.append(value)
yield tuple(values)
If one of the iterables is potentially infinite, then the :func:`zip_longest`
function should be wrapped with something that limits the number of calls

2
Doc/library/json.rst
View file

@ -43,7 +43,7 @@ Encoding basic Python object hierarchies::
Compact encoding::
>>> import json
>>> json.dumps([1,2,3,{'4': 5, '6': 7}], separators=(',', ':'))
>>> json.dumps([1, 2, 3, {'4': 5, '6': 7}], separators=(',', ':'))
'[1,2,3,{"4":5,"6":7}]'
Pretty printing::

16
Doc/library/locale.rst
View file

@ -373,7 +373,7 @@ The :mod:`locale` module defines the following exception and functions:
Please note that this function works like :meth:`format_string` but will
only work for exactly one ``%char`` specifier. For example, ``'%f'`` and
``'%.0f'`` are both valid specifiers, but ``'%f kB'`` is not.
``'%.0f'`` are both valid specifiers, but ``'%f KiB'`` is not.
For whole format strings, use :func:`format_string`.
@ -551,17 +551,23 @@ library.
Access to message catalogs
--------------------------
.. function:: gettext(msg)
.. function:: dgettext(domain, msg)
.. function:: dcgettext(domain, msg, category)
.. function:: textdomain(domain)
.. function:: bindtextdomain(domain, dir)
The locale module exposes the C library's gettext interface on systems that
provide this interface. It consists of the functions :func:`gettext`,
:func:`dgettext`, :func:`dcgettext`, :func:`textdomain`, :func:`bindtextdomain`,
and :func:`bind_textdomain_codeset`. These are similar to the same functions in
provide this interface. It consists of the functions :func:`!gettext`,
:func:`!dgettext`, :func:`!dcgettext`, :func:`!textdomain`, :func:`!bindtextdomain`,
and :func:`!bind_textdomain_codeset`. These are similar to the same functions in
the :mod:`gettext` module, but use the C library's binary format for message
catalogs, and the C library's search algorithms for locating message catalogs.
Python applications should normally find no need to invoke these functions, and
should use :mod:`gettext` instead. A known exception to this rule are
applications that link with additional C libraries which internally invoke
:c:func:`gettext` or :func:`dcgettext`. For these applications, it may be
:c:func:`gettext` or :c:func:`dcgettext`. For these applications, it may be
necessary to bind the text domain, so that the libraries can properly locate
their message catalogs.

9
Doc/library/logging.config.rst
View file

@ -715,7 +715,12 @@ a corresponding section in the configuration file.
The ``args`` entry, when :func:`eval`\ uated in the context of the ``logging``
package's namespace, is the list of arguments to the constructor for the handler
class. Refer to the constructors for the relevant handlers, or to the examples
below, to see how typical entries are constructed.
below, to see how typical entries are constructed. If not provided, it defaults
to ``()``.
The optional ``kwargs`` entry, when :func:`eval`\ uated in the context of the
``logging`` package's namespace, is the keyword argument dict to the constructor
for the handler class. If not provided, it defaults to ``{}``.
.. code-block:: ini
@ -754,6 +759,7 @@ below, to see how typical entries are constructed.
level=WARN
formatter=form07
args=('localhost', 'from@abc', ['user1@abc', 'user2@xyz'], 'Logger Subject')
kwargs={'timeout': 10.0}
[handler_hand08]
class=handlers.MemoryHandler
@ -767,6 +773,7 @@ below, to see how typical entries are constructed.
level=NOTSET
formatter=form09
args=('localhost:9022', '/log', 'GET')
kwargs={'secure': True}
Sections which specify formatter configuration are typified by the following.

13
Doc/library/logging.handlers.rst
View file

@ -59,6 +59,18 @@ and :meth:`flush` methods).
:meth:`close` method is inherited from :class:`~logging.Handler` and so
does no output, so an explicit :meth:`flush` call may be needed at times.
.. method:: setStream(stream)
Sets the instance's stream to the specified value, if it is different.
The old stream is flushed before the new stream is set.
:param stream: The stream that the handler should use.
:return: the old stream, if the stream was changed, or *None* if it wasn't.
.. versionadded:: 3.7
.. versionchanged:: 3.2
The ``StreamHandler`` class now has a ``terminator`` attribute, default
value ``'\n'``, which is used as the terminator when writing a formatted
@ -66,6 +78,7 @@ and :meth:`flush` methods).
set the handler instance's ``terminator`` attribute to the empty string.
In earlier versions, the terminator was hardcoded as ``'\n'``.
.. _file-handler:
FileHandler

20
Doc/library/logging.rst
View file

@ -94,10 +94,14 @@ is the module's name in the Python package namespace.
.. method:: Logger.setLevel(lvl)
Sets the threshold for this logger to *lvl*. Logging messages which are less
severe than *lvl* will be ignored. When a logger is created, the level is set to
:const:`NOTSET` (which causes all messages to be processed when the logger is
the root logger, or delegation to the parent when the logger is a non-root
logger). Note that the root logger is created with level :const:`WARNING`.
severe than *lvl* will be ignored; logging messages which have severity *lvl*
or higher will be emitted by whichever handler or handlers service this logger,
unless a handler's level has been set to a higher severity level than *lvl*.
When a logger is created, the level is set to :const:`NOTSET` (which causes
all messages to be processed when the logger is the root logger, or delegation
to the parent when the logger is a non-root logger). Note that the root logger
is created with level :const:`WARNING`.
The term 'delegation to the parent' means that if a logger has a level of
NOTSET, its chain of ancestor loggers is traversed until either an ancestor with
@ -775,15 +779,15 @@ the options available to you.
| lineno | ``%(lineno)d`` | Source line number where the logging call was |
| | | issued (if available). |
+----------------+-------------------------+-----------------------------------------------+
| message | ``%(message)s`` | The logged message, computed as ``msg % |
| | | args``. This is set when |
| | | :meth:`Formatter.format` is invoked. |
+----------------+-------------------------+-----------------------------------------------+
| module | ``%(module)s`` | Module (name portion of ``filename``). |
+----------------+-------------------------+-----------------------------------------------+
| msecs | ``%(msecs)d`` | Millisecond portion of the time when the |
| | | :class:`LogRecord` was created. |
+----------------+-------------------------+-----------------------------------------------+
| message | ``%(message)s`` | The logged message, computed as ``msg % |
| | | args``. This is set when |
| | | :meth:`Formatter.format` is invoked. |
+----------------+-------------------------+-----------------------------------------------+
| msg | You shouldn't need to | The format string passed in the original |
| | format this yourself. | logging call. Merged with ``args`` to |
| | | produce ``message``, or an arbitrary object |

24
Doc/library/mmap.rst
View file

@ -29,16 +29,20 @@ still needs to be closed when done).
mapping.
For both the Unix and Windows versions of the constructor, *access* may be
specified as an optional keyword parameter. *access* accepts one of three
values: :const:`ACCESS_READ`, :const:`ACCESS_WRITE`, or :const:`ACCESS_COPY`
to specify read-only, write-through or copy-on-write memory respectively.
*access* can be used on both Unix and Windows. If *access* is not specified,
Windows mmap returns a write-through mapping. The initial memory values for
all three access types are taken from the specified file. Assignment to an
:const:`ACCESS_READ` memory map raises a :exc:`TypeError` exception.
Assignment to an :const:`ACCESS_WRITE` memory map affects both memory and the
underlying file. Assignment to an :const:`ACCESS_COPY` memory map affects
memory but does not update the underlying file.
specified as an optional keyword parameter. *access* accepts one of four
values: :const:`ACCESS_READ`, :const:`ACCESS_WRITE`, or :const:`ACCESS_COPY` to
specify read-only, write-through or copy-on-write memory respectively, or
:const:`ACCESS_DEFAULT` to defer to *prot*. *access* can be used on both Unix
and Windows. If *access* is not specified, Windows mmap returns a
write-through mapping. The initial memory values for all three access types
are taken from the specified file. Assignment to an :const:`ACCESS_READ`
memory map raises a :exc:`TypeError` exception. Assignment to an
:const:`ACCESS_WRITE` memory map affects both memory and the underlying file.
Assignment to an :const:`ACCESS_COPY` memory map affects memory but does not
update the underlying file.
.. versionchanged:: 3.7
Added :const:`ACCESS_DEFAULT` constant.
To map anonymous memory, -1 should be passed as the fileno along with the length.

74
Doc/library/msilib.rst
View file

@ -124,9 +124,9 @@ structures.
.. seealso::
`FCICreateFile <https://msdn.microsoft.com/library?url=/library/en-us/devnotes/winprog/fcicreate.asp>`_
`UuidCreate <https://msdn.microsoft.com/library?url=/library/en-us/rpc/rpc/uuidcreate.asp>`_
`UuidToString <https://msdn.microsoft.com/library?url=/library/en-us/rpc/rpc/uuidtostring.asp>`_
`FCICreate <https://msdn.microsoft.com/en-us/library/bb432265.aspx>`_
`UuidCreate <https://msdn.microsoft.com/en-us/library/windows/desktop/aa379205.aspx>`_
`UuidToString <https://msdn.microsoft.com/en-us/library/windows/desktop/aa379352.aspx>`_
.. _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 <https://msdn.microsoft.com/library?url=/library/en-us/msi/setup/msidatabaseopenview.asp>`_
`MSIDatabaseCommit <https://msdn.microsoft.com/library?url=/library/en-us/msi/setup/msidatabasecommit.asp>`_
`MSIGetSummaryInformation <https://msdn.microsoft.com/library?url=/library/en-us/msi/setup/msigetsummaryinformation.asp>`_
`MSIDatabaseOpenView <https://msdn.microsoft.com/en-us/library/windows/desktop/aa370082.aspx>`_
`MSIDatabaseCommit <https://msdn.microsoft.com/en-us/library/windows/desktop/aa370075.aspx>`_
`MSIGetSummaryInformation <https://msdn.microsoft.com/en-us/library/windows/desktop/aa370301.aspx>`_
`MsiCloseHandle <https://msdn.microsoft.com/en-us/library/windows/desktop/aa370067.aspx>`_
.. _view-objects:
@ -203,11 +209,11 @@ View Objects
.. seealso::
`MsiViewExecute <https://msdn.microsoft.com/library?url=/library/en-us/msi/setup/msiviewexecute.asp>`_
`MSIViewGetColumnInfo <https://msdn.microsoft.com/library?url=/library/en-us/msi/setup/msiviewgetcolumninfo.asp>`_
`MsiViewFetch <https://msdn.microsoft.com/library?url=/library/en-us/msi/setup/msiviewfetch.asp>`_
`MsiViewModify <https://msdn.microsoft.com/library?url=/library/en-us/msi/setup/msiviewmodify.asp>`_
`MsiViewClose <https://msdn.microsoft.com/library?url=/library/en-us/msi/setup/msiviewclose.asp>`_
`MsiViewExecute <https://msdn.microsoft.com/en-us/library/windows/desktop/aa370513.aspx>`_
`MSIViewGetColumnInfo <https://msdn.microsoft.com/en-us/library/windows/desktop/aa370516.aspx>`_
`MsiViewFetch <https://msdn.microsoft.com/en-us/library/windows/desktop/aa370514.aspx>`_
`MsiViewModify <https://msdn.microsoft.com/en-us/library/windows/desktop/aa370519.aspx>`_
`MsiViewClose <https://msdn.microsoft.com/en-us/library/windows/desktop/aa370510.aspx>`_
.. _summary-objects:
@ -247,10 +253,10 @@ Summary Information Objects
.. seealso::
`MsiSummaryInfoGetProperty <https://msdn.microsoft.com/library?url=/library/en-us/msi/setup/msisummaryinfogetproperty.asp>`_
`MsiSummaryInfoGetPropertyCount <https://msdn.microsoft.com/library?url=/library/en-us/msi/setup/msisummaryinfogetpropertycount.asp>`_
`MsiSummaryInfoSetProperty <https://msdn.microsoft.com/library?url=/library/en-us/msi/setup/msisummaryinfosetproperty.asp>`_
`MsiSummaryInfoPersist <https://msdn.microsoft.com/library?url=/library/en-us/msi/setup/msisummaryinfopersist.asp>`_
`MsiSummaryInfoGetProperty <https://msdn.microsoft.com/en-us/library/windows/desktop/aa370409.aspx>`_
`MsiSummaryInfoGetPropertyCount <https://msdn.microsoft.com/en-us/library/windows/desktop/aa370488.aspx>`_
`MsiSummaryInfoSetProperty <https://msdn.microsoft.com/en-us/library/windows/desktop/aa370491.aspx>`_
`MsiSummaryInfoPersist <https://msdn.microsoft.com/en-us/library/windows/desktop/aa370490.aspx>`_
.. _record-objects:
@ -301,18 +307,18 @@ Record Objects
.. seealso::
`MsiRecordGetFieldCount <https://msdn.microsoft.com/library?url=/library/en-us/msi/setup/msirecordgetfieldcount.asp>`_
`MsiRecordSetString <https://msdn.microsoft.com/library?url=/library/en-us/msi/setup/msirecordsetstring.asp>`_
`MsiRecordSetStream <https://msdn.microsoft.com/library?url=/library/en-us/msi/setup/msirecordsetstream.asp>`_
`MsiRecordSetInteger <https://msdn.microsoft.com/library?url=/library/en-us/msi/setup/msirecordsetinteger.asp>`_
`MsiRecordClear <https://msdn.microsoft.com/library?url=/library/en-us/msi/setup/msirecordclear.asp>`_
`MsiRecordGetFieldCount <https://msdn.microsoft.com/en-us/library/windows/desktop/aa370366.aspx>`_
`MsiRecordSetString <https://msdn.microsoft.com/en-us/library/windows/desktop/aa370373.aspx>`_
`MsiRecordSetStream <https://msdn.microsoft.com/en-us/library/windows/desktop/aa370372.aspx>`_
`MsiRecordSetInteger <https://msdn.microsoft.com/en-us/library/windows/desktop/aa370371.aspx>`_
`MsiRecordClearData <https://msdn.microsoft.com/en-us/library/windows/desktop/aa370364.aspx>`_
.. _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 <https://msdn.microsoft.com/library?url=/library/en-us/msi/setup/directory_table.asp>`_
`File Table <https://msdn.microsoft.com/library?url=/library/en-us/msi/setup/file_table.asp>`_
`Component Table <https://msdn.microsoft.com/library?url=/library/en-us/msi/setup/component_table.asp>`_
`FeatureComponents Table <https://msdn.microsoft.com/library?url=/library/en-us/msi/setup/featurecomponents_table.asp>`_
`Directory Table <https://msdn.microsoft.com/en-us/library/windows/desktop/aa368295.aspx>`_
`File Table <https://msdn.microsoft.com/en-us/library/windows/desktop/aa368596.aspx>`_
`Component Table <https://msdn.microsoft.com/en-us/library/windows/desktop/aa368007.aspx>`_
`FeatureComponents Table <https://msdn.microsoft.com/en-us/library/windows/desktop/aa368579.aspx>`_
.. _features:
@ -425,7 +431,7 @@ Features
.. seealso::
`Feature Table <https://msdn.microsoft.com/library?url=/library/en-us/msi/setup/feature_table.asp>`_
`Feature Table <https://msdn.microsoft.com/en-us/library/windows/desktop/aa368585.aspx>`_
.. _msi-gui:
@ -520,13 +526,13 @@ for installing Python packages.
.. seealso::
`Dialog Table <https://msdn.microsoft.com/library?url=/library/en-us/msi/setup/dialog_table.asp>`_
`Control Table <https://msdn.microsoft.com/library?url=/library/en-us/msi/setup/control_table.asp>`_
`Control Types <https://msdn.microsoft.com/library?url=/library/en-us/msi/setup/controls.asp>`_
`ControlCondition Table <https://msdn.microsoft.com/library?url=/library/en-us/msi/setup/controlcondition_table.asp>`_
`ControlEvent Table <https://msdn.microsoft.com/library?url=/library/en-us/msi/setup/controlevent_table.asp>`_
`EventMapping Table <https://msdn.microsoft.com/library?url=/library/en-us/msi/setup/eventmapping_table.asp>`_
`RadioButton Table <https://msdn.microsoft.com/library?url=/library/en-us/msi/setup/radiobutton_table.asp>`_
`Dialog Table <https://msdn.microsoft.com/en-us/library/windows/desktop/aa368286.aspx>`_
`Control Table <https://msdn.microsoft.com/en-us/library/windows/desktop/aa368044.aspx>`_
`Control Types <https://msdn.microsoft.com/en-us/library/windows/desktop/aa368039.aspx>`_
`ControlCondition Table <https://msdn.microsoft.com/en-us/library/windows/desktop/aa368035.aspx>`_
`ControlEvent Table <https://msdn.microsoft.com/en-us/library/windows/desktop/aa368037.aspx>`_
`EventMapping Table <https://msdn.microsoft.com/en-us/library/windows/desktop/aa368559.aspx>`_
`RadioButton Table <https://msdn.microsoft.com/en-us/library/windows/desktop/aa370962.aspx>`_
.. _msi-tables:

54
Doc/library/multiprocessing.rst
View file

@ -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()

10
Doc/library/operator.rst
View file

@ -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:

10
Doc/library/os.path.rst
View file

@ -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`.

29
Doc/library/os.rst
View file

@ -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

Some files were not shown because too many files have changed in this diff Show more