traverseda
/
cpython
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Merge remote-tracking branch 'upstream/master' into finalise-subinterps

This commit is contained in:
Lewis Gaul 2020-11-23 20:47:31 +00:00
parent c89c0e55c3 79d2e62c00
commit c285f52bbb
727 changed files with 40084 additions and 27057 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
.azure-pipelines/ci.yml
View File

@ -104,7 +104,7 @@ jobs:
matrix:
win32:
arch: win32
buildOpt:
buildOpt: '-p Win32'
testRunTitle: '$(Build.SourceBranchName)-win32'
testRunPlatform: win32
win64:

2
.azure-pipelines/pr.yml
View File

@ -104,7 +104,7 @@ jobs:
matrix:
win32:
arch: win32
buildOpt:
buildOpt: '-p Win32'
testRunTitle: '$(System.PullRequest.TargetBranch)-win32'
testRunPlatform: win32
win64:

3
.azure-pipelines/windows-release/stage-pack-msix.yml
View File

@ -120,10 +120,11 @@ jobs:
artifactName: unsigned_msix
downloadPath: $(Build.BinariesDirectory)
# MSIX must be signed and timestamped simultaneously
- powershell: |
$failed = $true
foreach ($retry in 1..3) {
signtool sign /a /n "$(SigningCertificate)" /fd sha256 /t http://timestamp.verisign.com/scripts/timestamp.dll /d "$(SigningDescription)" (gi *.msix)
signtool sign /a /n "$(SigningCertificate)" /fd sha256 /tr http://timestamp.digicert.com/ /td sha256 /d "$(SigningDescription)" (gi *.msix)
if ($?) {
$failed = $false
break

10
.azure-pipelines/windows-release/stage-pack-nuget.yml
View File

@ -4,7 +4,7 @@ jobs:
condition: and(succeeded(), eq(variables['DoNuget'], 'true'))
pool:
vmImage: windows-2019
name: 'Windows Release'
workspace:
clean: all
@ -36,6 +36,14 @@ jobs:
nuget pack "$(Build.BinariesDirectory)\layout\python.nuspec" -OutputDirectory $(Build.ArtifactStagingDirectory) -NoPackageAnalysis -NonInteractive
displayName: 'Create nuget package'
- powershell: |
gci *.nupkg | %{
nuget sign "$_" -CertificateSubjectName "$(SigningCertificate)" -Timestamper http://timestamp.digicert.com/ -Overwrite
}
displayName: 'Sign nuget package'
workingDirectory: $(Build.ArtifactStagingDirectory)
condition: and(succeeded(), variables['SigningCertificate'])
- task: PublishBuildArtifacts@1
displayName: 'Publish Artifact: nuget'
inputs:

2
.azure-pipelines/windows-release/stage-sign.yml
View File

@ -57,7 +57,7 @@ jobs:
$files = (gi ${{ parameters.Include }} -Exclude ${{ parameters.Exclude }})
$failed = $true
foreach ($retry in 1..10) {
signtool timestamp /t http://timestamp.verisign.com/scripts/timestamp.dll $files
signtool timestamp /tr http://timestamp.digicert.com/ /td sha256 $files
if ($?) {
$failed = $false
break

10
.gitattributes vendored
View File

@ -57,3 +57,13 @@ Doc/library/token-list.inc linguist-generated=true
Include/token.h linguist-generated=true
Lib/token.py linguist-generated=true
Parser/token.c linguist-generated=true
# Language aware diff headers
# https://tekin.co.uk/2020/10/better-git-diff-output-for-ruby-python-elixir-and-more
# https://gist.github.com/tekin/12500956bd56784728e490d8cef9cb81
*.c diff=cpp
*.h diff=cpp
*.css diff=css
*.html diff=html
*.py diff=python
*.md diff=markdown

11
.github/CODEOWNERS vendored
View File

@ -9,10 +9,16 @@
# Core
**/*context* @1st1
**/*genobject* @1st1
**/*genobject* @1st1 @markshannon
**/*hamt* @1st1
Objects/set* @rhettinger
Objects/dict* @methane
Objects/dict* @methane @markshannon
Objects/type* @markshannon
Objects/codeobject.c @markshannon
Objects/frameobject.c @markshannon
Objects/call.c @markshannon
Python/ceval.c @markshannon
Python/compile.c @markshannon
# Hashing
**/*hashlib* @python/crypto-team @tiran
@ -76,6 +82,7 @@ Include/pytime.h @pganssle @abalkin
/Parser/ @pablogsal @lysnikolaou
/Tools/peg_generator/ @pablogsal @lysnikolaou
/Lib/test/test_peg_generator/ @pablogsal @lysnikolaou
/Grammar/python.gram @pablogsal @lysnikolaou
# SQLite 3
**/*sqlite* @berkerpeksag

1
.github/FUNDING.yml vendored
View File

@ -1 +1,2 @@
custom: https://www.python.org/psf/donations/python-dev/
github: [python]

9
.github/dependabot.yml vendored Normal file
View File

@ -0,0 +1,9 @@
version: 2
updates:
- package-ecosystem: "github-actions"
directory: "/"
schedule:
interval: "monthly"
labels:
- "skip issue"
- "skip news"

34
.github/workflows/build.yml vendored
View File

@ -47,6 +47,34 @@ jobs:
# https://github.com/python/core-workflow/issues/373
git diff --name-only origin/$GITHUB_BASE_REF.. | grep -qvE '(\.rst$|^Doc|^Misc)' && echo '::set-output name=run_tests::true' || true
fi
check_generated_files:
name: 'Check if generated files are up to date'
runs-on: ubuntu-latest
needs: check_source
if: needs.check_source.outputs.run_tests == 'true'
steps:
- uses: actions/checkout@v2
- uses: actions/setup-python@v2
- name: Install Dependencies
run: sudo ./.github/workflows/posix-deps-apt.sh
- name: Build CPython
run: |
./configure --with-pydebug
make -j4 regen-all
- name: Check for changes
run: |
changes=$(git status --porcelain)
# Check for changes in regenerated files
if ! test -z "$changes"
then
echo "Generated files not up to date. Perhaps you forgot to run make regen-all ;)"
echo "$changes"
exit 1
fi
- name: Check exported libpython symbols
run: make smelly
build_win32:
name: 'Windows (x86)'
runs-on: windows-latest
@ -59,7 +87,7 @@ jobs:
- name: Display build info
run: .\python.bat -m test.pythoninfo
- name: Tests
run: .\PCbuild\rt.bat -q -uall -u-cpu -rwW --slowest --timeout=1200 -j0
run: .\PCbuild\rt.bat -p Win32 -q -uall -u-cpu -rwW --slowest --timeout=1200 -j0
build_win_amd64:
name: 'Windows (x64)'
@ -73,7 +101,7 @@ jobs:
- name: Display build info
run: .\python.bat -m test.pythoninfo
- name: Tests
run: .\PCbuild\rt.bat -x64 -q -uall -u-cpu -rwW --slowest --timeout=1200 -j0
run: .\PCbuild\rt.bat -p x64 -q -uall -u-cpu -rwW --slowest --timeout=1200 -j0
build_macos:
name: 'macOS'
@ -106,7 +134,7 @@ jobs:
run: sudo ./.github/workflows/posix-deps-apt.sh
- name: 'Restore OpenSSL build'
id: cache-openssl
uses: actions/cache@v1
uses: actions/cache@v2.1.2
with:
path: ./multissl/openssl/${{ env.OPENSSL_VER }}
key: ${{ runner.os }}-multissl-openssl-${{ env.OPENSSL_VER }}

2
.github/workflows/coverage.yml vendored
View File

@ -32,7 +32,7 @@ jobs:
run: sudo ./.github/workflows/posix-deps-apt.sh
- name: 'Restore OpenSSL build'
id: cache-openssl
uses: actions/cache@v1
uses: actions/cache@v2.1.2
with:
path: ./multissl/openssl/${{ env.OPENSSL_VER }}
key: ${{ runner.os }}-multissl-openssl-${{ env.OPENSSL_VER }}

2
.github/workflows/doc.yml vendored
View File

@ -38,7 +38,7 @@ jobs:
- name: 'Build documentation'
run: xvfb-run make -C Doc/ PYTHON=../python SPHINXOPTS="-q -W --keep-going -j4" doctest suspicious html
- name: 'Upload'
uses: actions/upload-artifact@v1
uses: actions/upload-artifact@v2.2.0
with:
name: doc-html
path: Doc/build/html

12
.github/workflows/posix-deps-apt.sh vendored
View File

@ -3,19 +3,19 @@ apt-get update
apt-get -yq install \
build-essential \
zlib1g-dev \
gdb \
lcov \
libbz2-dev \
libffi-dev \
libgdbm-dev \
liblzma-dev \
libncurses5-dev \
libreadline6-dev \
libsqlite3-dev \
libssl-dev \
libgdbm-dev \
tk-dev \
lzma \
lzma-dev \
liblzma-dev \
libffi-dev \
tk-dev \
uuid-dev \
xvfb \
lcov
zlib1g-dev

2
.gitignore vendored
View File

@ -103,6 +103,8 @@ Tools/unicode/data/
/config.status
/config.status.lineno
/platform
/profile-clean-stamp
/profile-run-stamp
/pybuilddir.txt
/pyconfig.h
/python-config

4
Doc/Makefile
View File

@ -215,12 +215,12 @@ serve:
# for development releases: always build
autobuild-dev:
make dist SPHINXOPTS='$(SPHINXOPTS) -Ea -A daily=1 -A switchers=1'
make dist SPHINXOPTS='$(SPHINXOPTS) -Ea -A daily=1'
-make suspicious
# for quick rebuilds (HTML only)
autobuild-dev-html:
make html SPHINXOPTS='$(SPHINXOPTS) -Ea -A daily=1 -A switchers=1'
make html SPHINXOPTS='$(SPHINXOPTS) -Ea -A daily=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

3
Doc/c-api/arg.rst
View File

@ -482,7 +482,8 @@ API Functions
*min* and no more than *max*; *min* and *max* may be equal. Additional
arguments must be passed to the function, each of which should be a pointer to a
:c:type:`PyObject*` variable; these will be filled in with the values from
*args*; they will contain borrowed references. The variables which correspond
*args*; they will contain :term:`borrowed references <borrowed reference>`.
The variables which correspond
to optional parameters not given by *args* will not be filled in; these should
be initialized by the caller. This function returns true on success and false if
*args* is not a tuple or contains the wrong number of elements; an exception

8
Doc/c-api/exceptions.rst
View File

@ -182,8 +182,8 @@ For convenience, some of these functions will always return a
.. c:function:: PyObject* PyErr_SetFromErrnoWithFilename(PyObject *type, const char *filename)
Similar to :c:func:`PyErr_SetFromErrnoWithFilenameObject`, but the filename
is given as a C string. *filename* is decoded from the filesystem encoding
(:func:`os.fsdecode`).
is given as a C string. *filename* is decoded from the :term:`filesystem
encoding and error handler`.
.. c:function:: PyObject* PyErr_SetFromWindowsErr(int ierr)
@ -266,7 +266,7 @@ For convenience, some of these functions will always return a
.. c:function:: void PyErr_SyntaxLocationEx(const char *filename, int lineno, int col_offset)
Like :c:func:`PyErr_SyntaxLocationObject`, but *filename* is a byte string
decoded from the filesystem encoding (:func:`os.fsdecode`).
decoded from the :term:`filesystem encoding and error handler`.
.. versionadded:: 3.2
@ -343,7 +343,7 @@ an error value).
Similar to :c:func:`PyErr_WarnExplicitObject` except that *message* and
*module* are UTF-8 encoded strings, and *filename* is decoded from the
filesystem encoding (:func:`os.fsdecode`).
:term:`filesystem encoding and error handler`.
.. c:function:: int PyErr_WarnFormat(PyObject *category, Py_ssize_t stack_level, const char *format, ...)

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

@ -82,6 +82,8 @@ the :mod:`io` APIs instead.
This function is safe to call before :c:func:`Py_Initialize`.
.. audit-event:: setopencodehook "" c.PyFile_SetOpenCodeHook
.. versionadded:: 3.8

43
Doc/c-api/init.rst
View File

@ -151,8 +151,9 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
.. c:var:: int Py_LegacyWindowsFSEncodingFlag
If the flag is non-zero, use the ``mbcs`` encoding instead of the UTF-8
encoding for the filesystem encoding.
If the flag is non-zero, use the ``mbcs`` encoding with ``replace`` error
handler, instead of the UTF-8 encoding with ``surrogatepass`` error handler,
for the :term:`filesystem encoding and error handler`.
Set to ``1`` if the :envvar:`PYTHONLEGACYWINDOWSFSENCODING` environment
variable is set to a non-empty string.
@ -377,6 +378,12 @@ Process-wide parameters
The returned string points into static storage; the caller should not modify its
value.
This function should not be called before :c:func:`Py_Initialize`, otherwise
it returns ``NULL``.
.. versionchanged:: 3.10
It now returns ``NULL`` if called before :c:func:`Py_Initialize`.
.. c:function:: wchar_t* Py_GetPrefix()
@ -390,6 +397,12 @@ Process-wide parameters
script at build time. The value is available to Python code as ``sys.prefix``.
It is only useful on Unix. See also the next function.
This function should not be called before :c:func:`Py_Initialize`, otherwise
it returns ``NULL``.
.. versionchanged:: 3.10
It now returns ``NULL`` if called before :c:func:`Py_Initialize`.
.. c:function:: wchar_t* Py_GetExecPrefix()
@ -425,6 +438,12 @@ Process-wide parameters
while having :file:`/usr/local/plat` be a different filesystem for each
platform.
This function should not be called before :c:func:`Py_Initialize`, otherwise
it returns ``NULL``.
.. versionchanged:: 3.10
It now returns ``NULL`` if called before :c:func:`Py_Initialize`.
.. c:function:: wchar_t* Py_GetProgramFullPath()
@ -438,6 +457,12 @@ Process-wide parameters
static storage; the caller should not modify its value. The value is available
to Python code as ``sys.executable``.
This function should not be called before :c:func:`Py_Initialize`, otherwise
it returns ``NULL``.
.. versionchanged:: 3.10
It now returns ``NULL`` if called before :c:func:`Py_Initialize`.
.. c:function:: wchar_t* Py_GetPath()
@ -456,8 +481,14 @@ Process-wide parameters
can be (and usually is) modified later to change the search path for loading
modules.
This function should not be called before :c:func:`Py_Initialize`, otherwise
it returns ``NULL``.
.. XXX should give the exact rules
.. versionchanged:: 3.10
It now returns ``NULL`` if called before :c:func:`Py_Initialize`.
.. c:function:: void Py_SetPath(const wchar_t *)
@ -639,6 +670,12 @@ Process-wide parameters
:c:func:`Py_SetPythonHome`, or the value of the :envvar:`PYTHONHOME`
environment variable if it is set.
This function should not be called before :c:func:`Py_Initialize`, otherwise
it returns ``NULL``.
.. versionchanged:: 3.10
It now returns ``NULL`` if called before :c:func:`Py_Initialize`.
.. _threads:
@ -1078,7 +1115,7 @@ All of the following functions must be called after :c:func:`Py_Initialize`.
Get the current frame of the Python thread state *tstate*.
Return a strong reference. Return ``NULL`` if no frame is currently
Return a :term:`strong reference`. Return ``NULL`` if no frame is currently
executing.
See also :c:func:`PyEval_GetFrame`.

827
Doc/c-api/init_config.rst
View File

File diff suppressed because it is too large Load Diff

2
Doc/c-api/intro.rst
View File

@ -326,7 +326,7 @@ when it's no longer needed---or passing on this responsibility (usually to its
caller). When a function passes ownership of a reference on to its caller, the
caller is said to receive a *new* reference. When no ownership is transferred,
the caller is said to *borrow* the reference. Nothing needs to be done for a
borrowed reference.
:term:`borrowed reference`.
Conversely, when a calling function passes in a reference to an object, there
are two possibilities: the function *steals* a reference to the object, or it

100
Doc/c-api/module.rst
View File

@ -264,7 +264,7 @@ of the following two module creation functions:
instead; only use this if you are sure you need it.
Before it is returned from in the initialization function, the resulting module
object is typically populated using functions like :c:func:`PyModule_AddObject`.
object is typically populated using functions like :c:func:`PyModule_AddObjectRef`.
.. _multi-phase-initialization:
@ -437,26 +437,102 @@ a function called from a module execution slot (if using multi-phase
initialization), can use the following functions to help initialize the module
state:
.. c:function:: int PyModule_AddObjectRef(PyObject *module, const char *name, PyObject *value)
Add an object to *module* as *name*. This is a convenience function which
can be used from the module's initialization function.
On success, return ``0``. On error, raise an exception and return ``-1``.
Return ``NULL`` if *value* is ``NULL``. It must be called with an exception
raised in this case.
Example usage::
static int
add_spam(PyObject *module, int value)
{
PyObject *obj = PyLong_FromLong(value);
if (obj == NULL) {
return -1;
}
int res = PyModule_AddObjectRef(module, "spam", obj);
Py_DECREF(obj);
return res;
}
The example can also be written without checking explicitly if *obj* is
``NULL``::
static int
add_spam(PyObject *module, int value)
{
PyObject *obj = PyLong_FromLong(value);
int res = PyModule_AddObjectRef(module, "spam", obj);
Py_XDECREF(obj);
return res;
}
Note that ``Py_XDECREF()`` should be used instead of ``Py_DECREF()`` in
this case, since *obj* can be ``NULL``.
.. versionadded:: 3.10
.. c:function:: int PyModule_AddObject(PyObject *module, const char *name, PyObject *value)
Add an object to *module* as *name*. This is a convenience function which can
be used from the module's initialization function. This steals a reference to
*value* on success. Return ``-1`` on error, ``0`` on success.
Similar to :c:func:`PyModule_AddObjectRef`, but steals a reference to
*value* on success (if it returns ``0``).
The new :c:func:`PyModule_AddObjectRef` function is recommended, since it is
easy to introduce reference leaks by misusing the
:c:func:`PyModule_AddObject` function.
.. note::
Unlike other functions that steal references, ``PyModule_AddObject()`` only
decrements the reference count of *value* **on success**.
Unlike other functions that steal references, ``PyModule_AddObject()``
only decrements the reference count of *value* **on success**.
This means that its return value must be checked, and calling code must
:c:func:`Py_DECREF` *value* manually on error. Example usage::
:c:func:`Py_DECREF` *value* manually on error.
Py_INCREF(spam);
if (PyModule_AddObject(module, "spam", spam) < 0) {
Py_DECREF(module);
Py_DECREF(spam);
return NULL;
Example usage::
static int
add_spam(PyObject *module, int value)
{
PyObject *obj = PyLong_FromLong(value);
if (obj == NULL) {
return -1;
}
if (PyModule_AddObject(module, "spam", obj) < 0) {
Py_DECREF(obj);
return -1;
}
// PyModule_AddObject() stole a reference to obj:
// Py_DECREF(obj) is not needed here
return 0;
}
The example can also be written without checking explicitly if *obj* is
``NULL``::
static int
add_spam(PyObject *module, int value)
{
PyObject *obj = PyLong_FromLong(value);
if (PyModule_AddObject(module, "spam", obj) < 0) {
Py_XDECREF(obj);
return -1;
}
// PyModule_AddObject() stole a reference to obj:
// Py_DECREF(obj) is not needed here
return 0;
}
Note that ``Py_XDECREF()`` should be used instead of ``Py_DECREF()`` in
this case, since *obj* can be ``NULL``.
.. c:function:: int PyModule_AddIntConstant(PyObject *module, const char *name, long value)

60
Doc/c-api/refcounting.rst
View File

@ -13,8 +13,14 @@ objects.
.. c:function:: void Py_INCREF(PyObject *o)
Increment the reference count for object *o*. The object must not be ``NULL``; if
you aren't sure that it isn't ``NULL``, use :c:func:`Py_XINCREF`.
Increment the reference count for object *o*.
This function is usually used to convert a :term:`borrowed reference` to a
:term:`strong reference` in-place. The :c:func:`Py_NewRef` function can be
used to create a new :term:`strong reference`.
The object must not be ``NULL``; if you aren't sure that it isn't
``NULL``, use :c:func:`Py_XINCREF`.
.. c:function:: void Py_XINCREF(PyObject *o)
@ -22,13 +28,55 @@ objects.
Increment the reference count for object *o*. The object may be ``NULL``, in
which case the macro has no effect.
See also :c:func:`Py_XNewRef`.
.. c:function:: PyObject* Py_NewRef(PyObject *o)
Create a new :term:`strong reference` to an object: increment the reference
count of the object *o* and return the object *o*.
When the :term:`strong reference` is no longer needed, :c:func:`Py_DECREF`
should be called on it to decrement the object reference count.
The object *o* must not be ``NULL``; use :c:func:`Py_XNewRef` if *o* can be
``NULL``.
For example::
Py_INCREF(obj);
self->attr = obj;
can be written as::
self->attr = Py_NewRef(obj);
See also :c:func:`Py_INCREF`.
.. versionadded:: 3.10
.. c:function:: PyObject* Py_XNewRef(PyObject *o)
Similar to :c:func:`Py_NewRef`, but the object *o* can be NULL.
If the object *o* is ``NULL``, the function just returns ``NULL``.
.. versionadded:: 3.10
.. c:function:: void Py_DECREF(PyObject *o)
Decrement the reference count for object *o*. The object must not be ``NULL``; if
you aren't sure that it isn't ``NULL``, use :c:func:`Py_XDECREF`. If the reference
count reaches zero, the object's type's deallocation function (which must not be
``NULL``) is invoked.
Decrement the reference count for object *o*.
If the reference count reaches zero, the object's type's deallocation
function (which must not be ``NULL``) is invoked.
This function is usually used to delete a :term:`strong reference` before
exiting its scope.
The object must not be ``NULL``; if you aren't sure that it isn't ``NULL``,
use :c:func:`Py_XDECREF`.
.. warning::

4
Doc/c-api/reflection.rst
View File

@ -35,7 +35,7 @@ Reflection
Get the *frame* next outer frame.
Return a strong reference, or ``NULL`` if *frame* has no outer frame.
Return a :term:`strong reference`, or ``NULL`` if *frame* has no outer frame.
*frame* must not be ``NULL``.
@ -46,7 +46,7 @@ Reflection
Get the *frame* code.
Return a strong reference.
Return a :term:`strong reference`.
*frame* must not be ``NULL``. The result (frame code) cannot be ``NULL``.

16
Doc/c-api/structures.rst
View File

@ -66,11 +66,9 @@ the definition of all other Python objects.
Get the type of the Python object *o*.
Return a borrowed reference.
Return a :term:`borrowed reference`.
.. versionchanged:: 3.10
:c:func:`Py_TYPE()` is changed to the inline static function.
Use :c:func:`Py_SET_TYPE()` to set an object type.
The :c:func:`Py_SET_TYPE` function must be used to set an object type.
.. c:function:: int Py_IS_TYPE(PyObject *o, PyTypeObject *type)
@ -108,9 +106,7 @@ the definition of all other Python objects.
Get the size of the Python object *o*.
.. versionchanged:: 3.10
:c:func:`Py_SIZE()` is changed to the inline static function.
Use :c:func:`Py_SET_SIZE()` to set an object size.
The :c:func:`Py_SET_SIZE` function must be used to set an object size.
.. c:function:: void Py_SET_SIZE(PyVarObject *o, Py_ssize_t size)
@ -263,10 +259,12 @@ There are these calling conventions:
of :c:type:`PyObject*` values indicating the arguments and the third
parameter is the number of arguments (the length of the array).
This is not part of the :ref:`limited API <stable>`.
.. versionadded:: 3.7
.. versionchanged:: 3.10
``METH_FASTCALL`` is now part of the stable ABI.
.. data:: METH_FASTCALL | METH_KEYWORDS

66
Doc/c-api/sys.rst
View File

@ -118,22 +118,21 @@ Operating System Utilities
.. c:function:: wchar_t* Py_DecodeLocale(const char* arg, size_t *size)
Decode a byte string from the locale encoding with the :ref:`surrogateescape
error handler <surrogateescape>`: undecodable bytes are decoded as
characters in range U+DC80..U+DCFF. If a byte sequence can be decoded as a
surrogate character, escape the bytes using the surrogateescape error
handler instead of decoding them.
.. warning::
This function should not be called directly: use the :c:type:`PyConfig`
API with the :c:func:`PyConfig_SetBytesString` function which ensures
that :ref:`Python is preinitialized <c-preinit>`.
Encoding, highest priority to lowest priority:
This function must not be called before :ref:`Python is preinitialized
<c-preinit>` and so that the LC_CTYPE locale is properly configured: see
the :c:func:`Py_PreInitialize` function.
* ``UTF-8`` on macOS, Android, and VxWorks;
* ``UTF-8`` on Windows if :c:data:`Py_LegacyWindowsFSEncodingFlag` is zero;
* ``UTF-8`` if the Python UTF-8 mode is enabled;
* ``ASCII`` if the ``LC_CTYPE`` locale is ``"C"``,
``nl_langinfo(CODESET)`` returns the ``ASCII`` encoding (or an alias),
and :c:func:`mbstowcs` and :c:func:`wcstombs` functions uses the
``ISO-8859-1`` encoding.
* the current locale encoding.
Decode a byte string from the :term:`filesystem encoding and error handler`.
If the error handler is :ref:`surrogateescape error handler
<surrogateescape>`, undecodable bytes are decoded as characters in range
U+DC80..U+DCFF; and if a byte sequence can be decoded as a surrogate
character, the bytes are escaped using the surrogateescape error handler
instead of decoding them.
Return a pointer to a newly allocated wide character string, use
:c:func:`PyMem_RawFree` to free the memory. If size is not ``NULL``, write
@ -143,6 +142,10 @@ Operating System Utilities
not ``NULL``, ``*size`` is set to ``(size_t)-1`` on memory error or set to
``(size_t)-2`` on decoding error.
The :term:`filesystem encoding and error handler` are selected by
:c:func:`PyConfig_Read`: see :c:member:`~PyConfig.filesystem_encoding` and
:c:member:`~PyConfig.filesystem_errors` members of :c:type:`PyConfig`.
Decoding errors should never happen, unless there is a bug in the C
library.
@ -157,7 +160,8 @@ Operating System Utilities
.. versionadded:: 3.5
.. versionchanged:: 3.7
The function now uses the UTF-8 encoding in the UTF-8 mode.
The function now uses the UTF-8 encoding in the :ref:`Python UTF-8 Mode
<utf8-mode>`.
.. versionchanged:: 3.8
The function now uses the UTF-8 encoding on Windows if
@ -166,22 +170,10 @@ Operating System Utilities
.. c:function:: char* Py_EncodeLocale(const wchar_t *text, size_t *error_pos)
Encode a wide character string to the locale encoding with the
:ref:`surrogateescape error handler <surrogateescape>`: surrogate characters
in the range U+DC80..U+DCFF are converted to bytes 0x80..0xFF.
Encoding, highest priority to lowest priority:
* ``UTF-8`` on macOS, Android, and VxWorks;
* ``UTF-8`` on Windows if :c:data:`Py_LegacyWindowsFSEncodingFlag` is zero;
* ``UTF-8`` if the Python UTF-8 mode is enabled;
* ``ASCII`` if the ``LC_CTYPE`` locale is ``"C"``,
``nl_langinfo(CODESET)`` returns the ``ASCII`` encoding (or an alias),
and :c:func:`mbstowcs` and :c:func:`wcstombs` functions uses the
``ISO-8859-1`` encoding.
* the current locale encoding.
The function uses the UTF-8 encoding in the Python UTF-8 mode.
Encode a wide character string to the :term:`filesystem encoding and error
handler`. If the error handler is :ref:`surrogateescape error handler
<surrogateescape>`, surrogate characters in the range U+DC80..U+DCFF are
converted to bytes 0x80..0xFF.
Return a pointer to a newly allocated byte string, use :c:func:`PyMem_Free`
to free the memory. Return ``NULL`` on encoding error or memory allocation
@ -190,9 +182,18 @@ Operating System Utilities
If error_pos is not ``NULL``, ``*error_pos`` is set to ``(size_t)-1`` on
success, or set to the index of the invalid character on encoding error.
The :term:`filesystem encoding and error handler` are selected by
:c:func:`PyConfig_Read`: see :c:member:`~PyConfig.filesystem_encoding` and
:c:member:`~PyConfig.filesystem_errors` members of :c:type:`PyConfig`.
Use the :c:func:`Py_DecodeLocale` function to decode the bytes string back
to a wide character string.
.. warning::
This function must not be called before :ref:`Python is preinitialized
<c-preinit>` and so that the LC_CTYPE locale is properly configured: see
the :c:func:`Py_PreInitialize` function.
.. seealso::
The :c:func:`PyUnicode_EncodeFSDefault` and
@ -201,7 +202,8 @@ Operating System Utilities
.. versionadded:: 3.5
.. versionchanged:: 3.7
The function now uses the UTF-8 encoding in the UTF-8 mode.
The function now uses the UTF-8 encoding in the :ref:`Python UTF-8 Mode
<utf8-mode>`.
.. versionchanged:: 3.8
The function now uses the UTF-8 encoding on Windows if

24
Doc/c-api/type.rst
View File

@ -105,10 +105,12 @@ Type Objects
See :c:member:`PyType_Slot.slot` for possible values of the *slot* argument.
An exception is raised if *type* is not a heap type.
.. versionadded:: 3.4
.. versionchanged:: 3.10
:c:func:`PyType_GetSlot` can now accept all types.
Previously, it was limited to heap types.
.. c:function:: PyObject* PyType_GetModule(PyTypeObject *type)
Return the module object associated with the given type when the type was
@ -152,10 +154,10 @@ The following functions and structs are used to create
Creates and returns a heap type object from the *spec*
(:const:`Py_TPFLAGS_HEAPTYPE`).
If *bases* is a tuple, the created heap type contains all types contained
in it as base types.
If *bases* is ``NULL``, the *Py_tp_base* slot is used instead.
The *bases* argument can be used to specify base classes; it can either
be only one class or a tuple of classes.
If *bases* is ``NULL``, the *Py_tp_bases* slot is used instead.
If that also is ``NULL``, the *Py_tp_base* slot is used instead.
If that also is ``NULL``, the new type derives from :class:`object`.
The *module* argument can be used to record the module in which the new
@ -169,6 +171,11 @@ The following functions and structs are used to create
.. versionadded:: 3.9
.. versionchanged:: 3.10
The function now accepts a single class as the *bases* argument and
``NULL`` as the ``tp_doc`` slot.
.. c:function:: PyObject* PyType_FromSpecWithBases(PyType_Spec *spec, PyObject *bases)
Equivalent to ``PyType_FromModuleAndSpec(NULL, spec, bases)``.
@ -247,7 +254,8 @@ The following functions and structs are used to create
* :c:member:`~PyBufferProcs.bf_getbuffer`
* :c:member:`~PyBufferProcs.bf_releasebuffer`
Setting :c:data:`Py_tp_bases` may be problematic on some platforms.
Setting :c:data:`Py_tp_bases` or :c:data:`Py_tp_base` may be
problematic on some platforms.
To avoid issues, use the *bases* argument of
:py:func:`PyType_FromSpecWithBases` instead.
@ -260,4 +268,4 @@ The following functions and structs are used to create
The desired value of the slot. In most cases, this is a pointer
to a function.
May not be ``NULL``.
Slots other than ``Py_tp_doc`` may not be ``NULL``.

29
Doc/c-api/typeobj.rst
View File

@ -199,6 +199,8 @@ sub-slots
+---------------------------------------------------------+-----------------------------------+--------------+
| :c:member:`~PyAsyncMethods.am_anext` | :c:type:`unaryfunc` | __anext__ |
+---------------------------------------------------------+-----------------------------------+--------------+
| :c:member:`~PyAsyncMethods.am_send` | :c:type:`sendfunc` | |
+---------------------------------------------------------+-----------------------------------+--------------+
| |
+---------------------------------------------------------+-----------------------------------+--------------+
| :c:member:`~PyNumberMethods.nb_add` | :c:type:`binaryfunc` | __add__ |
@ -1168,6 +1170,14 @@ and :c:type:`PyType_Type` effectively act as defaults.)
.. versionadded:: 3.9
.. data:: Py_TPFLAGS_HAVE_AM_SEND
This bit is set when the :c:member:`~PyAsyncMethods.am_send` entry is present in the
:c:member:`~PyTypeObject.tp_as_async` slot of type structure.
.. versionadded:: 3.10
.. c:member:: const char* PyTypeObject.tp_doc
An optional pointer to a NUL-terminated C string giving the docstring for this
@ -1213,8 +1223,9 @@ and :c:type:`PyType_Type` effectively act as defaults.)
:func:`~gc.get_referents` function will include it.
.. warning::
When implementing :c:member:`~PyTypeObject.tp_traverse`, only the members
that the instance *owns* (by having strong references to them) must be
When implementing :c:member:`~PyTypeObject.tp_traverse`, only the
members that the instance *owns* (by having :term:`strong references
<strong reference>` to them) must be
visited. For instance, if an object supports weak references via the
:c:member:`~PyTypeObject.tp_weaklist` slot, the pointer supporting
the linked list (what *tp_weaklist* points to) must **not** be
@ -2303,6 +2314,7 @@ Async Object Structures
unaryfunc am_await;
unaryfunc am_aiter;
unaryfunc am_anext;
sendfunc am_send;
} PyAsyncMethods;
.. c:member:: unaryfunc PyAsyncMethods.am_await
@ -2336,6 +2348,15 @@ Async Object Structures
Must return an :term:`awaitable` object. See :meth:`__anext__` for details.
This slot may be set to ``NULL``.
.. c:member:: sendfunc PyAsyncMethods.am_send
The signature of this function is::
PySendResult am_send(PyObject *self, PyObject *arg, PyObject **result);
See :c:func:`PyIter_Send` for details.
This slot may be set to ``NULL``.
.. _slot-typedefs:
@ -2431,6 +2452,10 @@ Slot Type typedefs
.. c:type:: PyObject *(*binaryfunc)(PyObject *, PyObject *)
.. c:type:: PySendResult (*sendfunc)(PyObject *, PyObject *, PyObject **)
See :c:member:`~PyAsyncMethods.am_send`.
.. c:type:: PyObject *(*ternaryfunc)(PyObject *, PyObject *, PyObject *)
.. c:type:: PyObject *(*ssizeargfunc)(PyObject *, Py_ssize_t)

14
Doc/c-api/unicode.rst
View File

@ -783,7 +783,7 @@ system.
:c:data:`Py_FileSystemDefaultEncoding` (the locale encoding read at
Python startup).
This function ignores the Python UTF-8 mode.
This function ignores the :ref:`Python UTF-8 Mode <utf8-mode>`.
.. seealso::
@ -819,7 +819,7 @@ system.
:c:data:`Py_FileSystemDefaultEncoding` (the locale encoding read at
Python startup).
This function ignores the Python UTF-8 mode.
This function ignores the :ref:`Python UTF-8 Mode <utf8-mode>`.
.. seealso::
@ -878,8 +878,7 @@ conversion function:
.. c:function:: PyObject* PyUnicode_DecodeFSDefaultAndSize(const char *s, Py_ssize_t size)
Decode a string using :c:data:`Py_FileSystemDefaultEncoding` and the
:c:data:`Py_FileSystemDefaultEncodeErrors` error handler.
Decode a string from the :term:`filesystem encoding and error handler`.
If :c:data:`Py_FileSystemDefaultEncoding` is not set, fall back to the
locale encoding.
@ -899,8 +898,8 @@ conversion function:
.. c:function:: PyObject* PyUnicode_DecodeFSDefault(const char *s)
Decode a null-terminated string using :c:data:`Py_FileSystemDefaultEncoding`
and the :c:data:`Py_FileSystemDefaultEncodeErrors` error handler.
Decode a null-terminated string from the :term:`filesystem encoding and
error handler`.
If :c:data:`Py_FileSystemDefaultEncoding` is not set, fall back to the
locale encoding.
@ -1098,6 +1097,9 @@ These are the UTF-8 codec APIs:
.. versionchanged:: 3.7
The return type is now ``const char *`` rather of ``char *``.
.. versionchanged:: 3.10
This function is a part of the :ref:`limited API <stable>`.
.. c:function:: const char* PyUnicode_AsUTF8(PyObject *unicode)

21
Doc/c-api/veryhigh.rst
View File

@ -112,9 +112,9 @@ the same library that the Python runtime is using.
Similar to :c:func:`PyRun_SimpleStringFlags`, but the Python source code is read
from *fp* instead of an in-memory string. *filename* should be the name of
the file, it is decoded from the filesystem encoding
(:func:`sys.getfilesystemencoding`). If *closeit* is true, the file is
closed before PyRun_SimpleFileExFlags returns.
the file, it is decoded from :term:`filesystem encoding and error handler`.
If *closeit* is true, the file is closed before
``PyRun_SimpleFileExFlags()`` returns.
.. note::
On Windows, *fp* should be opened as binary mode (e.g. ``fopen(filename, "rb")``).
@ -132,7 +132,7 @@ the same library that the Python runtime is using.
Read and execute a single statement from a file associated with an
interactive device according to the *flags* argument. The user will be
prompted using ``sys.ps1`` and ``sys.ps2``. *filename* is decoded from the
filesystem encoding (:func:`sys.getfilesystemencoding`).
:term:`filesystem encoding and error handler`.
Returns ``0`` when the input was
executed successfully, ``-1`` if there was an exception, or an error code
@ -151,9 +151,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 or a negative
number upon failure.
``sys.ps2``. *filename* is decoded from the :term:`filesystem encoding and
error handler`. Returns ``0`` at EOF or a negative number upon failure.
.. c:var:: int (*PyOS_InputHook)(void)
@ -206,8 +205,8 @@ the same library that the Python runtime is using.
Parse Python source code from *str* using the start token *start* according to
the *flags* argument. The result can be used to create a code object which can
be evaluated efficiently. This is useful if a code fragment must be evaluated
many times. *filename* is decoded from the filesystem encoding
(:func:`sys.getfilesystemencoding`).
many times. *filename* is decoded from the :term:`filesystem encoding and
error handler`.
.. c:function:: struct _node* PyParser_SimpleParseFile(FILE *fp, const char *filename, int start)
@ -262,7 +261,7 @@ the same library that the Python runtime is using.
Similar to :c:func:`PyRun_StringFlags`, but the Python source code is read from
*fp* instead of an in-memory string. *filename* should be the name of the file,
it is decoded from the filesystem encoding (:func:`sys.getfilesystemencoding`).
it is decoded from the :term:`filesystem encoding and error handler`.
If *closeit* is true, the file is closed before :c:func:`PyRun_FileExFlags`
returns.
@ -301,7 +300,7 @@ the same library that the Python runtime is using.
.. c:function:: PyObject* Py_CompileStringExFlags(const char *str, const char *filename, int start, PyCompilerFlags *flags, int optimize)
Like :c:func:`Py_CompileStringObject`, but *filename* is a byte string
decoded from the filesystem encoding (:func:`os.fsdecode`).
decoded from the :term:`filesystem encoding and error handler`.
.. versionadded:: 3.2

6
Doc/c-api/weakref.rst
View File

@ -57,10 +57,10 @@ as much as it can.
.. note::
This function returns a **borrowed reference** to the referenced object.
This function returns a :term:`borrowed reference` to the referenced object.
This means that you should always call :c:func:`Py_INCREF` on the object
except if you know that it cannot be destroyed while you are still
using it.
except when it cannot be destroyed before the last usage of the borrowed
reference.
.. c:function:: PyObject* PyWeakref_GET_OBJECT(PyObject *ref)

6
Doc/data/refcounts.dat
View File

@ -3007,6 +3007,9 @@ Py_GetVersion:const char*:::
Py_INCREF:void:::
Py_INCREF:PyObject*:o:+1:
Py_NewRef:void:::
Py_NewRef:PyObject*:o:+1:
Py_Initialize:void:::
Py_IsInitialized:int:::
@ -3028,6 +3031,9 @@ Py_XDECREF:PyObject*:o:-1:if o is not NULL
Py_XINCREF:void:::
Py_XINCREF:PyObject*:o:+1:if o is not NULL
Py_XNewRef:void:::
Py_XNewRef:PyObject*:o:+1:if o is not NULL
_PyImport_Fini:void:::
_PyObject_New:PyObject*::+1:

17
Doc/faq/programming.rst
View File

@ -1116,7 +1116,7 @@ trailing newline from a string.
How do I iterate over a sequence in reverse order?
--------------------------------------------------
Use the :func:`reversed` built-in function, which is new in Python 2.4::
Use the :func:`reversed` built-in function::
for x in reversed(sequence):
... # do something with x ...
@ -1124,11 +1124,6 @@ Use the :func:`reversed` built-in function, which is new in Python 2.4::
This won't touch your original sequence, but build a new copy with reversed
order to iterate over.
With Python 2.3, you can use an extended slice syntax::
for x in sequence[::-1]:
... # do something with x ...
How do you remove duplicates from a list?
-----------------------------------------
@ -1517,17 +1512,17 @@ order` (MRO) with ``type(self).__mro__``, and return the next in line after
How can I organize my code to make it easier to change the base class?
----------------------------------------------------------------------
You could define an alias for the base class, assign the real base class to it
before your class definition, and use the alias throughout your class. Then all
You could assign the base class to an alias and derive from the alias. Then all
you have to change is the value assigned to the alias. Incidentally, this trick
is also handy if you want to decide dynamically (e.g. depending on availability
of resources) which base class to use. Example::
BaseAlias = <real base class>
class Base:
...
BaseAlias = Base
class Derived(BaseAlias):
def meth(self):
BaseAlias.meth(self)
...

4
Doc/faq/windows.rst
View File

@ -140,7 +140,7 @@ offender.
How do I make an executable from a Python script?
-------------------------------------------------
See `cx_Freeze <https://anthony-tuininga.github.io/cx_Freeze/>`_ for a distutils extension
See `cx_Freeze <https://cx-freeze.readthedocs.io/en/latest/>`_ for a distutils extension
that allows you to create console and GUI executables from Python code.
`py2exe <http://www.py2exe.org/>`_, the most popular extension for building
Python 2.x-based executables, does not yet support Python 3 but a version that
@ -279,7 +279,7 @@ in batch mode.
How do I check for a keypress without blocking?
-----------------------------------------------
Use the msvcrt module. This is a standard Windows-specific extension module.
Use the :mod:`msvcrt` module. This is a standard Windows-specific extension module.
It defines a function ``kbhit()`` which checks whether a keyboard hit is
present, and ``getch()`` which gets one character without echoing it.

79
Doc/glossary.rst
View File

@ -158,6 +158,18 @@ Glossary
See also :term:`text file` for a file object able to read and write
:class:`str` objects.
borrowed reference
In Python's C API, a borrowed reference is a reference to an object.
It does not modify the object reference count. It becomes a dangling
pointer if the object is destroyed. For example, a garbage collection can
remove the last :term:`strong reference` to the object and so destroy it.
Calling :c:func:`Py_INCREF` on the :term:`borrowed reference` is
recommended to convert it to a :term:`strong reference` in-place, except
when the object cannot be destroyed before the last usage of the borrowed
reference. The :c:func:`Py_NewRef` function can be used to create a new
:term:`strong reference`.
bytes-like object
An object that supports the :ref:`bufferobjects` and can
export a C-:term:`contiguous` buffer. This includes all :class:`bytes`,
@ -301,13 +313,20 @@ Glossary
including functions, methods, properties, class methods, static methods,
and reference to super classes.
For more information about descriptors' methods, see :ref:`descriptors`.
For more information about descriptors' methods, see :ref:`descriptors`
or the :ref:`Descriptor How To Guide <descriptorhowto>`.
dictionary
An associative array, where arbitrary keys are mapped to values. The
keys can be any object with :meth:`__hash__` and :meth:`__eq__` methods.
Called a hash in Perl.
dictionary comprehension
A compact way to process all or part of the elements in an iterable and
return a dictionary with the results. ``results = {n: n ** 2 for n in
range(10)}`` generates a dictionary containing key ``n`` mapped to
value ``n ** 2``. See :ref:`comprehensions`.
dictionary view
The objects returned from :meth:`dict.keys`, :meth:`dict.values`, and
:meth:`dict.items` are called dictionary views. They provide a dynamic
@ -379,6 +398,25 @@ Glossary
file-like object
A synonym for :term:`file object`.
filesystem encoding and error handler
Encoding and error handler used by Python to decode bytes from the
operating system and encode Unicode to the operating system.
The filesystem encoding must guarantee to successfully decode all bytes
below 128. If the file system encoding fails to provide this guarantee,
API functions can raise :exc:`UnicodeError`.
The :func:`sys.getfilesystemencoding` and
:func:`sys.getfilesystemencodeerrors` functions can be used to get the
filesystem encoding and error handler.
The :term:`filesystem encoding and error handler` are configured at
Python startup by the :c:func:`PyConfig_Read` function: see
:c:member:`~PyConfig.filesystem_encoding` and
:c:member:`~PyConfig.filesystem_errors` members of :c:type:`PyConfig`.
See also the :term:`locale encoding`.
finder
An object that tries to find the :term:`loader` for a module that is
being imported.
@ -476,6 +514,13 @@ Glossary
See also the :term:`single dispatch` glossary entry, the
:func:`functools.singledispatch` decorator, and :pep:`443`.
generic type
A :term:`type` that can be parameterized; typically a container like
:class:`list`. Used for :term:`type hints <type hint>` and
:term:`annotations <annotation>`.
See :pep:`483` for more details, and :mod:`typing` or
:ref:`generic alias type <types-genericalias>` for its uses.
GIL
See :term:`global interpreter lock`.
@ -659,6 +704,18 @@ Glossary
thread removes *key* from *mapping* after the test, but before the lookup.
This issue can be solved with locks or by using the EAFP approach.
locale encoding
On Unix, it is the encoding of the LC_CTYPE locale. It can be set with
``locale.setlocale(locale.LC_CTYPE, new_locale)``.
On Windows, it is is the ANSI code page (ex: ``cp1252``).
``locale.getpreferredencoding(False)`` can be used to get the locale
encoding.
Python uses the :term:`filesystem encoding and error handler` to convert
between Unicode filenames and bytes filenames.
list
A built-in Python :term:`sequence`. Despite its name it is more akin
to an array in other languages than to a linked list since access to
@ -1024,7 +1081,13 @@ Glossary
:meth:`index`, :meth:`__contains__`, and
:meth:`__reversed__`. Types that implement this expanded
interface can be registered explicitly using
:func:`~abc.register`.
:func:`~abc.ABCMeta.register`.
set comprehension
A compact way to process all or part of the elements in an iterable and
return a set with the results. ``results = {c for c in 'abracadabra' if
c not in 'abc'}`` generates the set of strings ``{'r', 'd'}``. See
:ref:`comprehensions`.
single dispatch
A form of :term:`generic function` dispatch where the implementation is
@ -1049,6 +1112,18 @@ Glossary
an :term:`expression` or one of several constructs with a keyword, such
as :keyword:`if`, :keyword:`while` or :keyword:`for`.
strong reference
In Python's C API, a strong reference is a reference to an object
which increments the object's reference count when it is created and
decrements the object's reference count when it is deleted.
The :c:func:`Py_NewRef` function can be used to create a strong reference
to an object. Usually, the :c:func:`Py_DECREF` function must be called on
the strong reference before exiting the scope of the strong reference, to
avoid leaking one reference.
See also :term:`borrowed reference`.
text encoding
A codec which encodes Unicode strings to bytes.

1110
Doc/howto/descriptor.rst
View File

File diff suppressed because it is too large Load Diff

10
Doc/howto/unicode.rst
View File

@ -609,9 +609,9 @@ implemented by converting the Unicode string into some encoding that
varies depending on the system. Today Python is converging on using
UTF-8: Python on MacOS has used UTF-8 for several versions, and Python
3.6 switched to using UTF-8 on Windows as well. On Unix systems,
there will only be a filesystem encoding if you've set the ``LANG`` or
``LC_CTYPE`` environment variables; if you haven't, the default
encoding is again UTF-8.
there will only be a :term:`filesystem encoding <filesystem encoding and error
handler>`. if you've set the ``LANG`` or ``LC_CTYPE`` environment variables; if
you haven't, the default encoding is again UTF-8.
The :func:`sys.getfilesystemencoding` function returns the encoding to use on
your current system, in case you want to do the encoding manually, but there's
@ -633,8 +633,8 @@ provided the directory path as bytes or a Unicode string. If you pass a
Unicode string as the path, filenames will be decoded using the filesystem's
encoding and a list of Unicode strings will be returned, while passing a byte
path will return the filenames as bytes. For example,
assuming the default filesystem encoding is UTF-8, running the following
program::
assuming the default :term:`filesystem encoding <filesystem encoding and error
handler>` is UTF-8, running the following program::
fn = 'filename\u4500abc'
f = open(fn, 'w')

20
Doc/library/ast.rst
View File

@ -80,12 +80,13 @@ Node classes
end_col_offset
Instances of :class:`ast.expr` and :class:`ast.stmt` subclasses have
:attr:`lineno`, :attr:`col_offset`, :attr:`lineno`, and :attr:`col_offset`
attributes. The :attr:`lineno` and :attr:`end_lineno` are the first and
last line numbers of source text span (1-indexed so the first line is line 1)
and the :attr:`col_offset` and :attr:`end_col_offset` are the corresponding
UTF-8 byte offsets of the first and last tokens that generated the node.
The UTF-8 offset is recorded because the parser uses UTF-8 internally.
:attr:`lineno`, :attr:`col_offset`, :attr:`end_lineno`, and
:attr:`end_col_offset` attributes. The :attr:`lineno` and :attr:`end_lineno`
are the first and last line numbers of source text span (1-indexed so the
first line is line 1) and the :attr:`col_offset` and :attr:`end_col_offset`
are the corresponding UTF-8 byte offsets of the first and last tokens that
generated the node. The UTF-8 offset is recorded because the parser uses
UTF-8 internally.
Note that the end positions are not required by the compiler and are
therefore optional. The end offset is *after* the last symbol, for example
@ -1503,6 +1504,13 @@ Async and await
fields as :class:`For` and :class:`With`, respectively. Only valid in the
body of an :class:`AsyncFunctionDef`.
.. note::
When a string is parsed by :func:`ast.parse`, operator nodes (subclasses
of :class:`ast.operator`, :class:`ast.unaryop`, :class:`ast.cmpop`,
:class:`ast.boolop` and :class:`ast.expr_context`) on the returned tree
will be singletons. Changes to one will be reflected in all other
occurrences of the same value (e.g. :class:`ast.Add`).
:mod:`ast` Helpers
------------------

4
Doc/library/asyncio-policy.rst
View File

@ -209,7 +209,7 @@ implementation used by the asyncio event loop:
It works reliably even when the asyncio event loop is run in a non-main OS thread.
There is no noticeable overhead when handling a big number of children (*O(1)* each
time a child terminates), but stating a thread per process requires extra memory.
time a child terminates), but starting a thread per process requires extra memory.
This watcher is used by default.
@ -219,7 +219,7 @@ implementation used by the asyncio event loop:
This implementation registers a :py:data:`SIGCHLD` signal handler on
instantiation. That can break third-party code that installs a custom handler for
`SIGCHLD`. signal).
:py:data:`SIGCHLD` signal.
The watcher avoids disrupting other code spawning processes
by polling every process explicitly on a :py:data:`SIGCHLD` signal.

6
Doc/library/asyncio-subprocess.rst
View File

@ -110,10 +110,8 @@ Creating Subprocesses
.. note::
The default asyncio event loop implementation on **Windows** does not
support subprocesses. Subprocesses are available for Windows if a
:class:`ProactorEventLoop` is used.
See :ref:`Subprocess Support on Windows <asyncio-windows-subprocess>`
Subprocesses are available for Windows if a :class:`ProactorEventLoop` is
used. See :ref:`Subprocess Support on Windows <asyncio-windows-subprocess>`
for details.
.. seealso::

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

@ -504,10 +504,10 @@ Waiting Primitives
return_when=ALL_COMPLETED)
Run :ref:`awaitable objects <asyncio-awaitables>` in the *aws*
set concurrently and block until the condition specified
iterable concurrently and block until the condition specified
by *return_when*.
The *aws* set must not be empty.
The *aws* iterable must not be empty.
Returns two sets of Tasks/Futures: ``(done, pending)``.
@ -593,9 +593,9 @@ Waiting Primitives
.. function:: as_completed(aws, \*, loop=None, timeout=None)
Run :ref:`awaitable objects <asyncio-awaitables>` in the *aws*
set concurrently. Return an iterator of coroutines.
iterable concurrently. Return an iterator of coroutines.
Each coroutine returned can be awaited to get the earliest next
result from the set of the remaining awaitables.
result from the iterable of the remaining awaitables.
Raises :exc:`asyncio.TimeoutError` if the timeout occurs before
all Futures are done.

26
Doc/library/audit_events.rst
View File

@ -19,3 +19,29 @@ information on handling these events.
specific documentation for actual events raised.
.. audit-event-table::
The following events are raised internally and do not correspond to any
public API of CPython:
+--------------------------+-------------------------------------------+
| Audit event | Arguments |
+==========================+===========================================+
| _winapi.CreateFile | ``file_name``, ``desired_access``, |
| | ``share_mode``, ``creation_disposition``, |
| | ``flags_and_attributes`` |
+--------------------------+-------------------------------------------+
| _winapi.CreateJunction | ``src_path``, ``dst_path`` |
+--------------------------+-------------------------------------------+
| _winapi.CreateNamedPipe | ``name``, ``open_mode``, ``pipe_mode`` |
+--------------------------+-------------------------------------------+
| _winapi.CreatePipe | |
+--------------------------+-------------------------------------------+
| _winapi.CreateProcess | ``application_name``, ``command_line``, |
| | ``current_directory`` |
+--------------------------+-------------------------------------------+
| _winapi.OpenProcess | ``process_id``, ``desired_access`` |
+--------------------------+-------------------------------------------+
| _winapi.TerminateProcess | ``handle``, ``exit_code`` |
+--------------------------+-------------------------------------------+
| ctypes.PyObj_FromPtr | ``obj`` |
+--------------------------+-------------------------------------------+

104
Doc/library/bisect.rst
View File

@ -21,7 +21,7 @@ example of the algorithm (the boundary conditions are already right!).
The following functions are provided:
.. function:: bisect_left(a, x, lo=0, hi=len(a))
.. function:: bisect_left(a, x, lo=0, hi=len(a), *, key=None)
Locate the insertion point for *x* in *a* to maintain sorted order.
The parameters *lo* and *hi* may be used to specify a subset of the list
@ -34,7 +34,15 @@ The following functions are provided:
that ``all(val < x for val in a[lo : i])`` for the left side and
``all(val >= x for val in a[i : hi])`` for the right side.
.. function:: bisect_right(a, x, lo=0, hi=len(a))
*key* specifies a :term:`key function` of one argument that is used to
extract a comparison key from each input element. The default value is
``None`` (compare the elements directly).
.. versionchanged:: 3.10
Added the *key* parameter.
.. function:: bisect_right(a, x, lo=0, hi=len(a), *, key=None)
bisect(a, x, lo=0, hi=len(a))
Similar to :func:`bisect_left`, but returns an insertion point which comes
@ -44,23 +52,82 @@ The following functions are provided:
that ``all(val <= x for val in a[lo : i])`` for the left side and
``all(val > x for val in a[i : hi])`` for the right side.
.. function:: insort_left(a, x, lo=0, hi=len(a))
*key* specifies a :term:`key function` of one argument that is used to
extract a comparison key from each input element. The default value is
``None`` (compare the elements directly).
Insert *x* in *a* in sorted order. This is equivalent to
``a.insert(bisect.bisect_left(a, x, lo, hi), x)`` assuming that *a* is
already sorted. Keep in mind that the O(log n) search is dominated by
the slow O(n) insertion step.
.. versionchanged:: 3.10
Added the *key* parameter.
.. function:: insort_right(a, x, lo=0, hi=len(a))
.. function:: insort_left(a, x, lo=0, hi=len(a), *, key=None)
Insert *x* in *a* in sorted order.
*key* specifies a :term:`key function` of one argument that is used to
extract a comparison key from each input element. The default value is
``None`` (compare the elements directly).
This function first runs :func:`bisect_left` to locate an insertion point.
Next, it runs the :meth:`insert` method on *a* to insert *x* at the
appropriate position to maintain sort order.
Keep in mind that the ``O(log n)`` search is dominated by the slow O(n)
insertion step.
.. versionchanged:: 3.10
Added the *key* parameter.
.. function:: insort_right(a, x, lo=0, hi=len(a), *, key=None)
insort(a, x, lo=0, hi=len(a))
Similar to :func:`insort_left`, but inserting *x* in *a* after any existing
entries of *x*.
*key* specifies a :term:`key function` of one argument that is used to
extract a comparison key from each input element. The default value is
``None`` (compare the elements directly).
This function first runs :func:`bisect_right` to locate an insertion point.
Next, it runs the :meth:`insert` method on *a* to insert *x* at the
appropriate position to maintain sort order.
Keep in mind that the ``O(log n)`` search is dominated by the slow O(n)
insertion step.
.. versionchanged:: 3.10
Added the *key* parameter.
Performance Notes
-----------------
When writing time sensitive code using *bisect()* and *insort()*, keep these
thoughts in mind:
* Bisection is effective for searching ranges of values.
For locating specific values, dictionaries are more performant.
* The *insort()* functions are ``O(n)`` because the logarithmic search step
is dominated by the linear time insertion step.
* The search functions are stateless and discard key function results after
they are used. Consequently, if the search functions are used in a loop,
the key function may be called again and again on the same array elements.
If the key function isn't fast, consider wrapping it with
:func:`functools.cache` to avoid duplicate computations. Alternatively,
consider searching an array of precomputed keys to locate the insertion
point (as shown in the examples section below).
.. seealso::
`SortedCollection recipe
<https://code.activestate.com/recipes/577197-sortedcollection/>`_ that uses
* `Sorted Collections
<http://www.grantjenks.com/docs/sortedcollections/>`_ is a high performance
module that uses *bisect* to managed sorted collections of data.
* The `SortedCollection recipe
<https://code.activestate.com/recipes/577197-sortedcollection/>`_ uses
bisect to build a full-featured collection class with straight-forward search
methods and support for a key-function. The keys are precomputed to save
unnecessary calls to the key function during searches.
@ -110,8 +177,8 @@ lists::
raise ValueError
Other Examples
--------------
Examples
--------
.. _bisect-example:
@ -127,17 +194,12 @@ a 'B', and so on::
>>> [grade(score) for score in [33, 99, 77, 70, 89, 90, 100]]
['F', 'A', 'C', 'C', 'B', 'A', 'A']
Unlike the :func:`sorted` function, it does not make sense for the :func:`bisect`
functions to have *key* or *reversed* arguments because that would lead to an
inefficient design (successive calls to bisect functions would not "remember"
all of the previous key lookups).
Instead, it is better to search a list of precomputed keys to find the index
of the record in question::
One technique to avoid repeated calls to a key function is to search a list of
precomputed keys to find the index of a record::
>>> data = [('red', 5), ('blue', 1), ('yellow', 8), ('black', 0)]
>>> data.sort(key=lambda r: r[1])
>>> keys = [r[1] for r in data] # precomputed list of keys
>>> data.sort(key=lambda r: r[1]) # Or use operator.itemgetter(1).
>>> keys = [r[1] for r in data] # Precompute a list of keys.
>>> data[bisect_left(keys, 0)]
('black', 0)
>>> data[bisect_left(keys, 1)]

2
Doc/library/collections.abc.rst
View File

@ -291,7 +291,7 @@ Notes on using :class:`Set` and :class:`MutableSet` as a mixin:
:meth:`_from_iterable` which calls ``cls(iterable)`` to produce a new set.
If the :class:`Set` mixin is being used in a class with a different
constructor signature, you will need to override :meth:`_from_iterable`
with a classmethod that can construct new instances from
with a classmethod or regular method that can construct new instances from
an iterable argument.
(2)

3
Doc/library/collections.rst
View File

@ -862,6 +862,9 @@ they add the ability to access fields by name instead of position index.
Named tuple instances do not have per-instance dictionaries, so they are
lightweight and require no more memory than regular tuples.
To support pickling, the named tuple class should be assigned to a variable
that matches *typename*.
.. versionchanged:: 3.1
Added support for *rename*.

6
Doc/library/concurrent.futures.rst
View File

@ -236,9 +236,9 @@ to a :class:`ProcessPoolExecutor` will result in deadlock.
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`
If *max_workers* is less than or equal to ``0``, then a :exc:`ValueError`
will be raised.
On Windows, *max_workers* must be equal or lower than ``61``. If it is not
On Windows, *max_workers* must be less than or equal to ``61``. If it is not
then :exc:`ValueError` will be raised. If *max_workers* is ``None``, then
the default chosen will be at most ``61``, even if more processors are
available.
@ -250,7 +250,7 @@ to a :class:`ProcessPoolExecutor` will result in deadlock.
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.process.BrokenProcessPool`,
as well any attempt to submit more jobs to the pool.
as well as any attempt to submit more jobs to the pool.
.. versionchanged:: 3.3
When one of the worker processes terminates abruptly, a

115
Doc/library/contextlib.rst
View File

@ -126,6 +126,31 @@ Functions and classes provided:
.. versionadded:: 3.7
Context managers defined with :func:`asynccontextmanager` can be used
either as decorators or with :keyword:`async with` statements::
import time
async def timeit():
now = time.monotonic()
try:
yield
finally:
print(f'it took {time.monotonic() - now}s to run')
@timeit()
async def main():
# ... async code ...
When used as a decorator, a new generator instance is implicitly created on
each function call. This allows the otherwise "one-shot" context managers
created by :func:`asynccontextmanager` to meet the requirement that context
managers support multiple invocations in order to be used as decorators.
.. versionchanged:: 3.10
Async context managers created with :func:`asynccontextmanager` can
be used as decorators.
.. function:: closing(thing)
@ -154,6 +179,39 @@ Functions and classes provided:
``page.close()`` will be called when the :keyword:`with` block is exited.
.. class:: aclosing(thing)
Return an async context manager that calls the ``aclose()`` method of *thing*
upon completion of the block. This is basically equivalent to::
from contextlib import asynccontextmanager
@asynccontextmanager
async def aclosing(thing):
try:
yield thing
finally:
await thing.aclose()
Significantly, ``aclosing()`` supports deterministic cleanup of async
generators when they happen to exit early by :keyword:`break` or an
exception. For example::
from contextlib import aclosing
async with aclosing(my_generator()) as values:
async for value in values:
if value == 42:
break
This pattern ensures that the generator's async exit code is executed in
the same context as its iterations (so that exceptions and context
variables work as expected, and the exit code isn't run after the
lifetime of some task it depends on).
.. versionadded:: 3.10
.. _simplifying-support-for-single-optional-context-managers:
.. function:: nullcontext(enter_result=None)
@ -185,8 +243,26 @@ Functions and classes provided:
with cm as file:
# Perform processing on the file
It can also be used as a stand-in for
:ref:`asynchronous context managers <async-context-managers>`::
async def send_http(session=None):
if not session:
# If no http session, create it with aiohttp
cm = aiohttp.ClientSession()
else:
# Caller is responsible for closing the session
cm = nullcontext(session)
async with cm as session:
# Send http requests with session
.. versionadded:: 3.7
.. versionchanged:: 3.10
:term:`asynchronous context manager` support was added.
.. function:: suppress(*exceptions)
@ -351,6 +427,45 @@ Functions and classes provided:
.. versionadded:: 3.2
.. class:: AsyncContextDecorator
Similar to :class:`ContextDecorator` but only for asynchronous functions.
Example of ``AsyncContextDecorator``::
from asyncio import run
from contextlib import AsyncContextDecorator
class mycontext(AsyncContextDecorator):
async def __aenter__(self):
print('Starting')
return self
async def __aexit__(self, *exc):
print('Finishing')
return False
>>> @mycontext()
... async def function():
... print('The bit in the middle')
...
>>> run(function())
Starting
The bit in the middle
Finishing
>>> async def function():
... async with mycontext():
... print('The bit in the middle')
...
>>> run(function())
Starting
The bit in the middle
Finishing
.. versionadded:: 3.10
.. class:: ExitStack()
A context manager that is designed to make it easy to programmatically

18
Doc/library/ctypes.rst
View File

@ -1326,6 +1326,21 @@ way is to instantiate one of the following classes:
libraries use the standard C calling convention, and are assumed to return
:c:type:`int`.
On Windows creating a :class:`CDLL` instance may fail even if the DLL name
exists. When a dependent DLL of the loaded DLL is not found, a
:exc:`OSError` error is raised with the message *"[WinError 126] The
specified module could not be found".* This error message does not contain
the name of the missing DLL because the Windows API does not return this
information making this error hard to diagnose. To resolve this error and
determine which DLL is not found, you need to find the list of dependent
DLLs and determine which one is not found using Windows debugging and
tracing tools.
.. seealso::
`Microsoft DUMPBIN tool <https://docs.microsoft.com/cpp/build/reference/dependents>`_
-- A tool to find DLL dependents.
.. class:: OleDLL(name, mode=DEFAULT_MODE, handle=None, use_errno=False, use_last_error=False, winmode=0)
@ -1618,7 +1633,7 @@ They are instances of a private class:
``ctypes.seh_exception`` with argument ``code`` will be raised, allowing an
audit hook to replace the exception with its own.
.. audit-event:: ctypes.call_function func_pointer,arguments ctype-foreign-functions
.. audit-event:: ctypes.call_function func_pointer,arguments foreign-functions
Some ways to invoke foreign function calls may raise an auditing event
``ctypes.call_function`` with arguments ``function pointer`` and ``arguments``.
@ -2545,4 +2560,3 @@ Arrays and pointers
Returns the object to which to pointer points. Assigning to this
attribute changes the pointer to point to the assigned object.

3
Doc/library/devmode.rst
View File

@ -93,6 +93,9 @@ The Python Development Mode does not prevent the :option:`-O` command line
option from removing :keyword:`assert` statements nor from setting
:const:`__debug__` to ``False``.
The Python Development Mode can only be enabled at the Python startup. Its
value can be read from :data:`sys.flags.dev_mode <sys.flags>`.
.. versionchanged:: 3.8
The :class:`io.IOBase` destructor now logs ``close()`` exceptions.

3
Doc/library/email.errors.rst
View File

@ -112,3 +112,6 @@ All defect classes are subclassed from :class:`email.errors.MessageDefect`.
* :class:`InvalidBase64LengthDefect` -- When decoding a block of base64 encoded
bytes, the number of non-padding base64 characters was invalid (1 more than
a multiple of 4). The encoded block was kept as-is.
* :class:`InvalidDateDefect` -- When decoding an invalid or unparsable date field.
The original value is kept as-is.

6
Doc/library/email.utils.rst
View File

@ -124,8 +124,10 @@ of the new API.
.. function:: parsedate_to_datetime(date)
The inverse of :func:`format_datetime`. Performs the same function as
:func:`parsedate`, but on success returns a :mod:`~datetime.datetime`. If
the input date has a timezone of ``-0000``, the ``datetime`` will be a naive
:func:`parsedate`, but on success returns a :mod:`~datetime.datetime`;
otherwise ``ValueError`` is raised if *date* contains an invalid value such
as an hour greater than 23 or a timezone offset not between -24 and 24 hours.
If the input date has a timezone of ``-0000``, the ``datetime`` will be a naive
``datetime``, and if the date is conforming to the RFCs it will represent a
time in UTC but with no indication of the actual source timezone of the
message the date comes from. If the input date has any other valid timezone

4
Doc/library/exceptions.rst
View File

@ -313,8 +313,8 @@ The following exceptions are the exceptions that are usually raised.
.. versionchanged:: 3.4
The :attr:`filename` attribute is now the original file name passed to
the function, instead of the name encoded to or decoded from the
filesystem encoding. Also, the *filename2* constructor argument and
attribute was added.
:term:`filesystem encoding and error handler`. Also, the *filename2*
constructor argument and attribute was added.
.. exception:: OverflowError

5
Doc/library/fcntl.rst
View File

@ -39,6 +39,11 @@ descriptor.
On Linux(>=3.15), the fcntl module exposes the ``F_OFD_GETLK``, ``F_OFD_SETLK``
and ``F_OFD_SETLKW`` constants, which working with open file description locks.
.. versionchanged:: 3.10
On Linux >= 2.6.11, the fcntl module exposes the ``F_GETPIPE_SZ`` and
``F_SETPIPE_SZ`` constants, which allow to check and modify a pipe's size
respectively.
The module defines the following functions:

8
Doc/library/filecmp.rst
View File

@ -173,7 +173,13 @@ The :class:`dircmp` class
.. attribute:: subdirs
A dictionary mapping names in :attr:`common_dirs` to :class:`dircmp`
objects.
instances (or MyDirCmp instances if this instance is of type MyDirCmp, a
subclass of :class:`dircmp`).
.. versionchanged:: 3.10
Previously entries were always :class:`dircmp` instances. Now entries
are the same type as *self*, if *self* is a subclass of
:class:`dircmp`.
.. attribute:: DEFAULT_IGNORES

8
Doc/library/functions.rst
View File

@ -164,8 +164,8 @@ are always available. They are listed here in alphabetical order.
* If it is an *integer*, the array will have that size and will be
initialized with null bytes.
* If it is an object conforming to the *buffer* interface, a read-only buffer
of the object will be used to initialize the bytes array.
* If it is an object conforming to the :ref:`buffer interface <bufferobjects>`,
a read-only buffer of the object will be used to initialize the bytes array.
* If it is an *iterable*, it must be an iterable of integers in the range
``0 <= x < 256``, which are used as the initial contents of the array.
@ -259,7 +259,7 @@ are always available. They are listed here in alphabetical order.
interactive statement (in the latter case, expression statements that
evaluate to something other than ``None`` will be printed).
The optional argument *flags* and *dont_inherit* controls which
The optional arguments *flags* and *dont_inherit* control which
:ref:`compiler options <ast-compiler-flags>` should be activated
and which :ref:`future features <future>` should be allowed. If neither
is present (or both are zero) the code is compiled with the same flags that
@ -783,6 +783,8 @@ are always available. They are listed here in alphabetical order.
.. impl-detail:: This is the address of the object in memory.
.. audit-event:: builtins.id id id
.. function:: input([prompt])

23
Doc/library/functools.rst
View File

@ -73,17 +73,32 @@ The :mod:`functools` module defines the following functions:
def variance(self):
return statistics.variance(self._data)
.. versionadded:: 3.8
Note, this decorator interferes with the operation of :pep:`412`
key-sharing dictionaries. This means that instance dictionaries
can take more space than usual.
.. note::
This decorator requires that the ``__dict__`` attribute on each instance
Also, this decorator requires that the ``__dict__`` attribute on each instance
be a mutable mapping. This means it will not work with some types, such as
metaclasses (since the ``__dict__`` attributes on type instances are
read-only proxies for the class namespace), and those that specify
``__slots__`` without including ``__dict__`` as one of the defined slots
(as such classes don't provide a ``__dict__`` attribute at all).
If a mutable mapping is not available or if space-efficient key sharing
is desired, an effect similar to :func:`cached_property` can be achieved
by a stacking :func:`property` on top of :func:`cache`::
class DataSet:
def __init__(self, sequence_of_numbers):
self._data = sequence_of_numbers
@property
@cache
def stdev(self):
return statistics.stdev(self._data)
.. versionadded:: 3.8
.. function:: cmp_to_key(func)

5
Doc/library/http.client.rst
View File

@ -99,6 +99,11 @@ The module provides the following classes:
:attr:`ssl.SSLContext.post_handshake_auth` for the default *context* or
when *cert_file* is passed with a custom *context*.
.. versionchanged:: 3.10
This class now sends an ALPN extension with protocol indicator
``http/1.1`` when no *context* is given. Custom *context* should set
ALPN protocols with :meth:`~ssl.SSLContext.set_alpn_protocol`.
.. deprecated:: 3.6
*key_file* and *cert_file* are deprecated in favor of *context*.

6
Doc/library/imaplib.rst
View File

@ -174,9 +174,9 @@ example of usage.
.. seealso::
Documents describing the protocol, and sources and binaries for servers
implementing it, can all be found at the University of Washington's *IMAP
Information Center* (https://www.washington.edu/imap/).
Documents describing the protocol, sources for servers
implementing it, by the University of Washington's IMAP Information Center
can all be found at (**Source Code**) https://github.com/uw-imap/imap (**Not Maintained**).
.. _imap4-objects:

14
Doc/library/importlib.rst
View File

@ -438,8 +438,9 @@ ABC hierarchy::
package. This attribute is not set on modules.
- :attr:`__package__`
The parent package for the module/package. If the module is
top-level then it has a value of the empty string. The
The fully-qualified name of the package under which the module was
loaded as a submodule (or the empty string for top-level modules).
For packages, it is the same as :attr:`__name__`. The
:func:`importlib.util.module_for_loader` decorator can handle the
details for :attr:`__package__`.
@ -1347,8 +1348,8 @@ find and load modules.
(``__loader__``)
The loader to use for loading. For namespace packages this should be
set to ``None``.
The :term:`Loader <loader>` that should be used when loading
the module. :term:`Finders <finder>` should always set this.
.. attribute:: origin
@ -1381,8 +1382,9 @@ find and load modules.
(``__package__``)
(Read-only) Fully-qualified name of the package to which the module
belongs as a submodule (or ``None``).
(Read-only) The fully-qualified name of the package under which the module
should be loaded as a submodule (or the empty string for top-level modules).
For packages, it is the same as :attr:`__name__`.
.. attribute:: has_location

36
Doc/library/ipaddress.rst
View File

@ -202,6 +202,32 @@ write code that handles both IP versions correctly. Address objects are
.. _iana-ipv4-special-registry: https://www.iana.org/assignments/iana-ipv4-special-registry/iana-ipv4-special-registry.xhtml
.. _iana-ipv6-special-registry: https://www.iana.org/assignments/iana-ipv6-special-registry/iana-ipv6-special-registry.xhtml
.. method:: IPv4Address.__format__(fmt)
Returns a string representation of the IP address, controlled by
an explicit format string.
*fmt* can be one of the following: ``'s'``, the default option,
equivalent to :func:`str`, ``'b'`` for a zero-padded binary string,
``'X'`` or ``'x'`` for an uppercase or lowercase hexadecimal
representation, or ``'n'``, which is equivalent to ``'b'`` for IPv4
addresses and ``'x'`` for IPv6. For binary and hexadecimal
representations, the form specifier ``'#'`` and the grouping option
``'_'`` are available. ``__format__`` is used by ``format``, ``str.format``
and f-strings.
>>> format(ipaddress.IPv4Address('192.168.0.1'))
'192.168.0.1'
>>> '{:#b}'.format(ipaddress.IPv4Address('192.168.0.1'))
'0b11000000101010000000000000000001'
>>> f'{ipaddress.IPv6Address("2001:db8::1000"):s}'
'2001:db8::1000'
>>> format(ipaddress.IPv6Address('2001:db8::1000'), '_X')
'2001_0DB8_0000_0000_0000_0000_0000_1000'
>>> '{:#_n}'.format(ipaddress.IPv6Address('2001:db8::1000'))
'0x2001_0db8_0000_0000_0000_0000_0000_1000'
.. versionadded:: 3.9
.. class:: IPv6Address(address)
@ -246,8 +272,8 @@ write code that handles both IP versions correctly. Address objects are
groups consisting entirely of zeroes included.
For the following attributes, see the corresponding documentation of the
:class:`IPv4Address` class:
For the following attributes and methods, see the corresponding
documentation of the :class:`IPv4Address` class:
.. attribute:: packed
.. attribute:: reverse_pointer
@ -297,6 +323,12 @@ write code that handles both IP versions correctly. Address objects are
the embedded ``(server, client)`` IP address pair. For any other
address, this property will be ``None``.
.. method:: IPv6Address.__format__(fmt)
Refer to the corresponding method documentation in
:class:`IPv4Address`.
.. versionadded:: 3.9
Conversion to Strings and Integers
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

26
Doc/library/locale.rst
View File

@ -315,21 +315,25 @@ The :mod:`locale` module defines the following exception and functions:
.. function:: getpreferredencoding(do_setlocale=True)
Return the encoding used for text data, according to user preferences. User
preferences are expressed differently on different systems, and might not be
available programmatically on some systems, so this function only returns a
guess.
Return the :term:`locale encoding` used for text data, according to user
preferences. User preferences are expressed differently on different
systems, and might not be available programmatically on some systems, so
this function only returns a guess.
On some systems, it is necessary to invoke :func:`setlocale` to obtain the user
preferences, so this function is not thread-safe. If invoking setlocale is not
necessary or desired, *do_setlocale* should be set to ``False``.
On some systems, it is necessary to invoke :func:`setlocale` to obtain the
user preferences, so this function is not thread-safe. If invoking setlocale
is not necessary or desired, *do_setlocale* should be set to ``False``.
On Android or in the UTF-8 mode (:option:`-X` ``utf8`` option), always
return ``'UTF-8'``, the locale and the *do_setlocale* argument are ignored.
On Android or if the :ref:`Python UTF-8 Mode <utf8-mode>` is enabled, always
return ``'UTF-8'``, the :term:`locale encoding` and the *do_setlocale*
argument are ignored.
The :ref:`Python preinitialization <c-preinit>` configures the LC_CTYPE
locale. See also the :term:`filesystem encoding and error handler`.
.. versionchanged:: 3.7
The function now always returns ``UTF-8`` on Android or if the UTF-8 mode
is enabled.
The function now always returns ``UTF-8`` on Android or if the
:ref:`Python UTF-8 Mode <utf8-mode>` is enabled.
.. function:: normalize(localename)

14
Doc/library/mailbox.rst
View File

@ -426,17 +426,14 @@ Supported mailbox formats are Maildir, mbox, MH, Babyl, and MMDF.
.. seealso::
`maildir man page from qmail <http://www.qmail.org/man/man5/maildir.html>`_
The original specification of the format.
`maildir man page from Courier <http://www.courier-mta.org/maildir.html>`_
A specification of the format. Describes a common extension for
supporting folders.
`Using maildir format <https://cr.yp.to/proto/maildir.html>`_
Notes on Maildir by its inventor. Includes an updated name-creation scheme and
details on "info" semantics.
`maildir man page from Courier <http://www.courier-mta.org/maildir.html>`_
Another specification of the format. Describes a common extension for supporting
folders.
.. _mailbox-mbox:
@ -485,11 +482,8 @@ Supported mailbox formats are Maildir, mbox, MH, Babyl, and MMDF.
.. seealso::
`mbox man page from qmail <http://www.qmail.org/man/man5/mbox.html>`_
A specification of the format and its variations.
`mbox man page from tin <http://www.tin.org/bin/man.cgi?section=5&topic=mbox>`_
Another specification of the format, with details on locking.
A specification of the format, with details on locking.
`Configuring Netscape Mail on Unix: Why The Content-Length Format is Bad <https://www.jwz.org/doc/content-length.html>`_
An argument for using the original mbox format rather than a variation.

2
Doc/library/mmap.rst
View File

@ -337,6 +337,8 @@ MADV_* Constants
MADV_NOCORE
MADV_CORE
MADV_PROTECT
MADV_FREE_REUSABLE
MADV_FREE_REUSE
These options can be passed to :meth:`mmap.madvise`. Not every option will
be present on every system.

2
Doc/library/multiprocessing.rst
View File

@ -98,7 +98,7 @@ to start a process. These *start methods* are
*spawn*
The parent process starts a fresh python interpreter process. The
child process will only inherit those resources necessary to run
the process objects :meth:`~Process.run` method. In particular,
the process object's :meth:`~Process.run` method. In particular,
unnecessary file descriptors and handles from the parent process
will not be inherited. Starting a process using this method is
rather slow compared to using *fork* or *forkserver*.

227
Doc/library/os.rst
View File

@ -68,8 +68,13 @@ File Names, Command Line Arguments, and Environment Variables
In Python, file names, command line arguments, and environment variables are
represented using the string type. On some systems, decoding these strings to
and from bytes is necessary before passing them to the operating system. Python
uses the file system encoding to perform this conversion (see
:func:`sys.getfilesystemencoding`).
uses the :term:`filesystem encoding and error handler` to perform this
conversion (see :func:`sys.getfilesystemencoding`).
The :term:`filesystem encoding and error handler` are configured at Python
startup by the :c:func:`PyConfig_Read` function: see
:c:member:`~PyConfig.filesystem_encoding` and
:c:member:`~PyConfig.filesystem_errors` members of :c:type:`PyConfig`.
.. versionchanged:: 3.1
On some systems, conversion using the file system encoding may fail. In this
@ -79,9 +84,72 @@ uses the file system encoding to perform this conversion (see
original byte on encoding.
The file system encoding must guarantee to successfully decode all bytes
below 128. If the file system encoding fails to provide this guarantee, API
functions may raise UnicodeErrors.
The :term:`file system encoding <filesystem encoding and error handler>` must
guarantee to successfully decode all bytes below 128. If the file system
encoding fails to provide this guarantee, API functions can raise
:exc:`UnicodeError`.
See also the :term:`locale encoding`.
.. _utf8-mode:
Python UTF-8 Mode
-----------------
.. versionadded:: 3.7
See :pep:`540` for more details.
The Python UTF-8 Mode ignores the :term:`locale encoding` and forces the usage
of the UTF-8 encoding:
* Use UTF-8 as the :term:`filesystem encoding <filesystem encoding and error
handler>`.
* :func:`sys.getfilesystemencoding()` returns ``'UTF-8'``.
* :func:`locale.getpreferredencoding()` returns ``'UTF-8'`` (the *do_setlocale*
argument has no effect).
* :data:`sys.stdin`, :data:`sys.stdout`, and :data:`sys.stderr` all use
UTF-8 as their text encoding, with the ``surrogateescape``
:ref:`error handler <error-handlers>` being enabled for :data:`sys.stdin`
and :data:`sys.stdout` (:data:`sys.stderr` continues to use
``backslashreplace`` as it does in the default locale-aware mode)
* On Unix, :func:`os.device_encoding` returns ``'UTF-8'``. rather than the
device encoding.
Note that the standard stream settings in UTF-8 mode can be overridden by
:envvar:`PYTHONIOENCODING` (just as they can be in the default locale-aware
mode).
As a consequence of the changes in those lower level APIs, other higher
level APIs also exhibit different default behaviours:
* Command line arguments, environment variables and filenames are decoded
to text using the UTF-8 encoding.
* :func:`os.fsdecode()` and :func:`os.fsencode()` use the UTF-8 encoding.
* :func:`open()`, :func:`io.open()`, and :func:`codecs.open()` use the UTF-8
encoding by default. However, they still use the strict error handler by
default so that attempting to open a binary file in text mode is likely
to raise an exception rather than producing nonsense data.
The :ref:`Python UTF-8 Mode <utf8-mode>` is enabled if the LC_CTYPE locale is
``C`` or ``POSIX`` at Python startup (see the :c:func:`PyConfig_Read`
function).
It can be enabled or disabled using the :option:`-X utf8 <-X>` command line
option and the :envvar:`PYTHONUTF8` environment variable.
If the :envvar:`PYTHONUTF8` environment variable is not set at all, then the
interpreter defaults to using the current locale settings, *unless* the current
locale is identified as a legacy ASCII-based locale (as described for
:envvar:`PYTHONCOERCECLOCALE`), and locale coercion is either disabled or
fails. In such legacy locales, the interpreter will default to enabling UTF-8
mode unless explicitly instructed not to do so.
The Python UTF-8 Mode can only be enabled at the Python startup. Its value
can be read from :data:`sys.flags.utf8_mode <sys.flags>`.
See also the :ref:`UTF-8 mode on Windows <win-utf8-mode>`
and the :term:`filesystem encoding and error handler`.
.. _os-procinfo:
@ -165,9 +233,9 @@ process and user.
.. function:: fsencode(filename)
Encode :term:`path-like <path-like object>` *filename* to the filesystem
encoding with ``'surrogateescape'`` error handler, or ``'strict'`` on
Windows; return :class:`bytes` unchanged.
Encode :term:`path-like <path-like object>` *filename* to the
:term:`filesystem encoding and error handler`; return :class:`bytes`
unchanged.
:func:`fsdecode` is the reverse function.
@ -181,8 +249,8 @@ process and user.
.. function:: fsdecode(filename)
Decode the :term:`path-like <path-like object>` *filename* from the
filesystem encoding with ``'surrogateescape'`` error handler, or ``'strict'``
on Windows; return :class:`str` unchanged.
:term:`filesystem encoding and error handler`; return :class:`str`
unchanged.
:func:`fsencode` is the reverse function.
@ -742,6 +810,12 @@ as internal buffering of data.
Return a string describing the encoding of the device associated with *fd*
if it is connected to a terminal; else return :const:`None`.
On Unix, if the :ref:`Python UTF-8 Mode <utf8-mode>` is enabled, return
``'UTF-8'`` rather than the device encoding.
.. versionchanged:: 3.10
On Unix, the function now implements the Python UTF-8 Mode.
.. function:: dup(fd)
@ -1345,6 +1419,39 @@ or `the MSDN <https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windo
.. versionadded:: 3.3
.. function:: splice(src, dst, count, offset_src=None, offset_dst=None)
Transfer *count* bytes from file descriptor *src*, starting from offset
*offset_src*, to file descriptor *dst*, starting from offset *offset_dst*.
At least one of the file descriptors must refer to a pipe. If *offset_src*
is None, then *src* is read from the current position; respectively for
*offset_dst*. The offset associated to the file descriptor that refers to a
pipe must be ``None``. The files pointed by *src* and *dst* must reside in
the same filesystem, otherwise an :exc:`OSError` is raised with
:attr:`~OSError.errno` set to :data:`errno.EXDEV`.
This copy is done without the additional cost of transferring data
from the kernel to user space and then back into the kernel. Additionally,
some filesystems could implement extra optimizations. The copy is done as if
both files are opened as binary.
Upon successful completion, returns the number of bytes spliced to or from
the pipe. A return value of 0 means end of input. If *src* refers to a
pipe, then this means that there was no data to transfer, and it would not
make sense to block because there are no writers connected to the write end
of the pipe.
.. availability:: Linux kernel >= 2.6.17 and glibc >= 2.5
.. versionadded:: 3.10
.. data:: SPLICE_F_MOVE
SPLICE_F_NONBLOCK
SPLICE_F_MORE
.. versionadded:: 3.10
.. function:: readv(fd, buffers)
Read from a file descriptor *fd* into a number of mutable :term:`bytes-like
@ -3202,6 +3309,102 @@ features:
.. versionadded:: 3.8
.. function:: eventfd(initval[, flags=os.EFD_CLOEXEC])
Create and return an event file descriptor. The file descriptors supports
raw :func:`read` and :func:`write` with a buffer size of 8,
:func:`~select.select`, :func:`~select.poll` and similar. See man page
:manpage:`eventfd(2)` for more information. By default, the
new file descriptor is :ref:`non-inheritable <fd_inheritance>`.
*initval* is the initial value of the event counter. The initial value
must be an 32 bit unsigned integer. Please note that the initial value is
limited to a 32 bit unsigned int although the event counter is an unsigned
64 bit integer with a maximum value of 2\ :sup:`64`\ -\ 2.
*flags* can be constructed from :const:`EFD_CLOEXEC`,
:const:`EFD_NONBLOCK`, and :const:`EFD_SEMAPHORE`.
If :const:`EFD_SEMAPHORE` is specified and the event counter is non-zero,
:func:`eventfd_read` returns 1 and decrements the counter by one.
If :const:`EFD_SEMAPHORE` is not specified and the event counter is
non-zero, :func:`eventfd_read` returns the current event counter value and
resets the counter to zero.
If the event counter is zero and :const:`EFD_NONBLOCK` is not
specified, :func:`eventfd_read` blocks.
:func:`eventfd_write` increments the event counter. Write blocks if the
write operation would increment the counter to a value larger than
2\ :sup:`64`\ -\ 2.
Example::
import os
# semaphore with start value '1'
fd = os.eventfd(1, os.EFD_SEMAPHORE | os.EFC_CLOEXEC)
try:
# acquire semaphore
v = os.eventfd_read(fd)
try:
do_work()
finally:
# release semaphore
os.eventfd_write(fd, v)
finally:
os.close(fd)
.. availability:: Linux 2.6.27 or newer with glibc 2.8 or newer.
.. versionadded:: 3.10
.. function:: eventfd_read(fd)
Read value from an :func:`eventfd` file descriptor and return a 64 bit
unsigned int. The function does not verify that *fd* is an :func:`eventfd`.
.. availability:: See :func:`eventfd`
.. versionadded:: 3.10
.. function:: eventfd_write(fd, value)
Add value to an :func:`eventfd` file descriptor. *value* must be a 64 bit
unsigned int. The function does not verify that *fd* is an :func:`eventfd`.
.. availability:: See :func:`eventfd`
.. versionadded:: 3.10
.. data:: EFD_CLOEXEC
Set close-on-exec flag for new :func:`eventfd` file descriptor.
.. availability:: See :func:`eventfd`
.. versionadded:: 3.10
.. data:: EFD_NONBLOCK
Set :const:`O_NONBLOCK` status flag for new :func:`eventfd` file
descriptor.
.. availability:: See :func:`eventfd`
.. versionadded:: 3.10
.. data:: EFD_SEMAPHORE
Provide semaphore-like semantics for reads from a :func:`eventfd` file
descriptor. On read the internal counter is decremented by one.
.. availability:: Linux 2.6.30 or newer with glibc 2.8 or newer.
.. versionadded:: 3.10
Linux extended attributes
~~~~~~~~~~~~~~~~~~~~~~~~~
@ -3246,7 +3449,7 @@ These functions are all available on Linux only.
Removes the extended filesystem attribute *attribute* from *path*.
*attribute* should be bytes or str (directly or indirectly through the
:class:`PathLike` interface). If it is a string, it is encoded
with the filesystem encoding.
with the :term:`filesystem encoding and error handler`.
This function can support :ref:`specifying a file descriptor <path_fd>` and
:ref:`not following symlinks <follow_symlinks>`.
@ -3262,7 +3465,7 @@ These functions are all available on Linux only.
Set the extended filesystem attribute *attribute* on *path* to *value*.
*attribute* must be a bytes or str with no embedded NULs (directly or
indirectly through the :class:`PathLike` interface). If it is a str,
it is encoded with the filesystem encoding. *flags* may be
it is encoded with the :term:`filesystem encoding and error handler`. *flags* may be
:data:`XATTR_REPLACE` or :data:`XATTR_CREATE`. If :data:`XATTR_REPLACE` is
given and the attribute does not exist, ``EEXISTS`` will be raised.
If :data:`XATTR_CREATE` is given and the attribute already exists, the

7
Doc/library/pathlib.rst
View File

@ -336,6 +336,8 @@ Pure paths provide the following methods and properties:
>>> p.parents[2]
PureWindowsPath('c:/')
.. versionchanged:: 3.10
The parents sequence now supports :term:`slices <slice>` and negative index values.
.. data:: PurePath.parent
@ -1166,7 +1168,7 @@ call fails (for example because the path doesn't exist).
.. versionadded:: 3.5
.. method:: Path.write_text(data, encoding=None, errors=None)
.. method:: Path.write_text(data, encoding=None, errors=None, newline=None)
Open the file pointed to in text mode, write *data* to it, and close the
file::
@ -1182,6 +1184,9 @@ call fails (for example because the path doesn't exist).
.. versionadded:: 3.5
.. versionchanged:: 3.10
The *newline* parameter was added.
Correspondence to tools in the :mod:`os` module
-----------------------------------------------

7
Doc/library/platform.rst
View File

@ -209,13 +209,6 @@ Windows Platform
which means the OS version uses debugging code, i.e. code that checks arguments,
ranges, etc.
.. note::
This function works best with Mark Hammond's
:mod:`win32all` package installed, but also on Python 2.3 and
later (support for this was added in Python 2.6). It obviously
only runs on Win32 compatible platforms.
.. function:: win32_edition()
Returns a string representing the current Windows edition. Possible

2
Doc/library/poplib.rst
View File

@ -67,7 +67,7 @@ The :mod:`poplib` module provides two classes:
.. audit-event:: poplib.connect self,host,port poplib.POP3_SSL
.. audit-event:: poplib.putline self,line popplib.POP3_SSL
.. audit-event:: poplib.putline self,line poplib.POP3_SSL
All commands will raise an :ref:`auditing event <auditing>`
``poplib.putline`` with arguments ``self`` and ``line``,

6
Doc/library/posix.rst
View File

@ -37,7 +37,7 @@ Large File Support
.. sectionauthor:: Steve Clift <clift@mail.anacapa.net>
Several operating systems (including AIX, HP-UX, Irix and Solaris) provide
Several operating systems (including AIX, HP-UX and Solaris) provide
support for files that are larger than 2 GiB from a C programming model where
:c:type:`int` and :c:type:`long` are 32-bit values. This is typically accomplished
by defining the relevant size and offset types as 64-bit values. Such files are
@ -47,8 +47,8 @@ Large file support is enabled in Python when the size of an :c:type:`off_t` is
larger than a :c:type:`long` and the :c:type:`long long` is at least as large
as an :c:type:`off_t`.
It may be necessary to configure and compile Python with certain compiler flags
to enable this mode. For example, it is enabled by default with recent versions
of Irix, but with Solaris 2.6 and 2.7 you need to do something like::
to enable this mode. For example, with Solaris 2.6 and 2.7 you need to do
something like::
CFLAGS="`getconf LFS_CFLAGS`" OPT="-g -O2 $CFLAGS" \
./configure

7
Doc/library/pyclbr.rst
View File

@ -97,6 +97,13 @@ statements. They have the following attributes:
.. versionadded:: 3.7
.. attribute:: Function.is_async
``True`` for functions that are defined with the ``async`` prefix, ``False`` otherwise.
.. versionadded:: 3.10
.. _pyclbr-class-objects:
Class Objects

7
Doc/library/random.rst
View File

@ -319,6 +319,13 @@ be found in any statistics text.
deviation. This is slightly faster than the :func:`normalvariate` function
defined below.
Multithreading note: When two threads call this function
simultaneously, it is possible that they will receive the
same return value. This can be avoided in three ways.
1) Have each thread use a different instance of the random
number generator. 2) Put locks around all calls. 3) Use the
slower, but thread-safe :func:`normalvariate` function instead.
.. function:: lognormvariate(mu, sigma)

20
Doc/library/shelve.rst
View File

@ -25,8 +25,9 @@ lots of shared sub-objects. The keys are ordinary strings.
database file is opened for reading and writing. The optional *flag* parameter
has the same interpretation as the *flag* parameter of :func:`dbm.open`.
By default, version 3 pickles are used to serialize values. The version of the
pickle protocol can be specified with the *protocol* parameter.
By default, pickles created with :data:`pickle.DEFAULT_PROTOCOL` are used
to serialize values. The version of the pickle protocol can be specified
with the *protocol* parameter.
Because of Python semantics, a shelf cannot know when a mutable
persistent-dictionary entry is modified. By default modified objects are
@ -40,6 +41,10 @@ lots of shared sub-objects. The keys are ordinary strings.
determine which accessed entries are mutable, nor which ones were actually
mutated).
.. versionchanged:: 3.10
:data:`pickle.DEFAULT_PROTOCOL` is now used as the default pickle
protocol.
.. note::
Do not rely on the shelf being closed automatically; always call
@ -108,9 +113,10 @@ Restrictions
A subclass of :class:`collections.abc.MutableMapping` which stores pickled
values in the *dict* object.
By default, version 3 pickles are used to serialize values. The version of the
pickle protocol can be specified with the *protocol* parameter. See the
:mod:`pickle` documentation for a discussion of the pickle protocols.
By default, pickles created with :data:`pickle.DEFAULT_PROTOCOL` are used
to serialize values. The version of the pickle protocol can be specified
with the *protocol* parameter. See the :mod:`pickle` documentation for a
discussion of the pickle protocols.
If the *writeback* parameter is ``True``, the object will hold a cache of all
entries accessed and write them back to the *dict* at sync and close times.
@ -130,6 +136,10 @@ Restrictions
.. versionchanged:: 3.4
Added context manager support.
.. versionchanged:: 3.10
:data:`pickle.DEFAULT_PROTOCOL` is now used as the default pickle
protocol.
.. class:: BsdDbShelf(dict, protocol=None, writeback=False, keyencoding='utf-8')

14
Doc/library/shlex.rst
View File

@ -61,6 +61,20 @@ The :mod:`shlex` module defines the following functions:
string that can safely be used as one token in a shell command line, for
cases where you cannot use a list.
.. _shlex-quote-warning:
.. warning::
The ``shlex`` module is **only designed for Unix shells**.
The :func:`quote` function is not guaranteed to be correct on non-POSIX
compliant shells or shells from other operating systems such as Windows.
Executing commands quoted by this module on such shells can open up the
possibility of a command injection vulnerability.
Consider using functions that pass command arguments with lists such as
:func:`subprocess.run` with ``shell=False``.
This idiom would be unsafe:
>>> filename = 'somefile; rm -rf ~'

2
Doc/library/signal.rst
View File

@ -117,7 +117,7 @@ The variables defined in the :mod:`signal` module are:
Child process stopped or terminated.
.. availability:: Windows.
.. availability:: Unix.
.. data:: SIGCLD

4
Doc/library/smtplib.rst
View File

@ -32,7 +32,7 @@ Protocol) and :rfc:`1869` (SMTP Service Extensions).
than a success code, an :exc:`SMTPConnectError` is raised. The optional
*timeout* parameter specifies a timeout in seconds for blocking operations
like the connection attempt (if not specified, the global default timeout
setting will be used). If the timeout expires, :exc:`socket.timeout` is
setting will be used). If the timeout expires, :exc:`TimeoutError` is
raised. The optional source_address parameter allows binding
to some specific source address in a machine with multiple network
interfaces, and/or to some specific source TCP port. It takes a 2-tuple
@ -115,7 +115,7 @@ Protocol) and :rfc:`1869` (SMTP Service Extensions).
If the *timeout* parameter is set to be zero, it will raise a
:class:`ValueError` to prevent the creation of a non-blocking socket
.. class:: LMTP(host='', port=LMTP_PORT, local_hostname=None,
.. class:: LMTP(host='', port=LMTP_PORT, local_hostname=None, \
source_address=None[, timeout])
The LMTP protocol, which is very similar to ESMTP, is heavily based on the

26
Doc/library/socket.rst
View File

@ -283,6 +283,8 @@ Exceptions
.. exception:: timeout
A deprecated alias of :exc:`TimeoutError`.
A subclass of :exc:`OSError`, this exception is raised when a timeout
occurs on a socket which has had timeouts enabled via a prior call to
:meth:`~socket.settimeout` (or implicitly through
@ -292,6 +294,9 @@ Exceptions
.. versionchanged:: 3.3
This class was made a subclass of :exc:`OSError`.
.. versionchanged:: 3.10
This class was made an alias of :exc:`TimeoutError`.
Constants
^^^^^^^^^
@ -1091,6 +1096,19 @@ The :mod:`socket` module also offers various network-related services:
.. versionchanged:: 3.8
Windows support was added.
.. note::
On Windows network interfaces have different names in different contexts
(all names are examples):
* UUID: ``{FB605B73-AAC2-49A6-9A2F-25416AEA0573}``
* name: ``ethernet_32770``
* friendly name: ``vEthernet (nat)``
* description: ``Hyper-V Virtual Ethernet Adapter``
This function returns names of the second form from the list, ``ethernet_32770``
in this example case.
.. function:: if_nametoindex(if_name)
@ -1105,6 +1123,9 @@ The :mod:`socket` module also offers various network-related services:
.. versionchanged:: 3.8
Windows support was added.
.. seealso::
"Interface name" is a name as documented in :func:`if_nameindex`.
.. function:: if_indextoname(if_index)
@ -1119,6 +1140,9 @@ The :mod:`socket` module also offers various network-related services:
.. versionchanged:: 3.8
Windows support was added.
.. seealso::
"Interface name" is a name as documented in :func:`if_nameindex`.
.. _socket-objects:
@ -1189,7 +1213,7 @@ to sockets.
address family --- see above.)
If the connection is interrupted by a signal, the method waits until the
connection completes, or raise a :exc:`socket.timeout` on timeout, if the
connection completes, or raise a :exc:`TimeoutError` on timeout, if the
signal handler doesn't raise an exception and the socket is blocking or has
a timeout. For non-blocking sockets, the method raises an
:exc:`InterruptedError` exception if the connection is interrupted by a

260
Doc/library/stdtypes.rst
View File

@ -4140,6 +4140,12 @@ The constructors for both classes work the same:
objects. If *iterable* is not specified, a new empty set is
returned.
Sets can be created by several means:
* Use a comma-separated list of elements within braces: ``{'jack', 'sjoerd'}``
* Use a set comprehension: ``{c for c in 'abracadabra' if c not in 'abc'}``
* Use the type constructor: ``set()``, ``set('foobar')``, ``set(['a', 'b', 'foo'])``
Instances of :class:`set` and :class:`frozenset` provide the following
operations:
@ -4332,6 +4338,14 @@ pairs within braces, for example: ``{'jack': 4098, 'sjoerd': 4127}`` or ``{4098:
Return a new dictionary initialized from an optional positional argument
and a possibly empty set of keyword arguments.
Dictionaries can be created by several means:
* Use a comma-separated list of ``key: value`` pairs within braces:
``{'jack': 4098, 'sjoerd': 4127}`` or ``{4098: 'jack', 4127: 'sjoerd'}``
* Use a dict comprehension: ``{}``, ``{x: x ** 2 for x in range(10)}``
* Use the type constructor: ``dict()``,
``dict([('foo', 100), ('bar', 200)])``, ``dict(foo=100, bar=200)``
If no positional argument is given, an empty dictionary is created.
If a positional argument is given and it is a mapping object, a dictionary
is created with the same key-value pairs as the mapping object. Otherwise,
@ -4749,10 +4763,215 @@ define these methods must provide them as a normal Python accessible method.
Compared to the overhead of setting up the runtime context, the overhead of a
single class dictionary lookup is negligible.
Type Annotation Types --- :ref:`Generic Alias <types-genericalias>`, :ref:`Union <types-union>`
===============================================================================================
.. index::
single: annotation; type annotation; type hint
The core built-in types for :term:`type annotations <annotation>` are
:ref:`Generic Alias <types-genericalias>` and :ref:`Union <types-union>`.
.. _types-genericalias:
Generic Alias Type
------------------
.. index::
object: GenericAlias
pair: Generic; Alias
``GenericAlias`` objects are created by subscripting a class (usually a
container), such as ``list[int]``. They are intended primarily for
:term:`type annotations <annotation>`.
Usually, the :ref:`subscription <subscriptions>` of container objects calls the
method :meth:`__getitem__` of the object. However, the subscription of some
containers' classes may call the classmethod :meth:`__class_getitem__` of the
class instead. The classmethod :meth:`__class_getitem__` should return a
``GenericAlias`` object.
.. note::
If the :meth:`__getitem__` of the class' metaclass is present, it will take
precedence over the :meth:`__class_getitem__` defined in the class (see
:pep:`560` for more details).
The ``GenericAlias`` object acts as a proxy for :term:`generic types
<generic type>`, implementing *parameterized generics* - a specific instance
of a generic which provides the types for container elements.
The user-exposed type for the ``GenericAlias`` object can be accessed from
:class:`types.GenericAlias` and used for :func:`isinstance` checks. It can
also be used to create ``GenericAlias`` objects directly.
.. describe:: T[X, Y, ...]
Creates a ``GenericAlias`` representing a type ``T`` containing elements
of types *X*, *Y*, and more depending on the ``T`` used.
For example, a function expecting a :class:`list` containing
:class:`float` elements::
def average(values: list[float]) -> float:
return sum(values) / len(values)
Another example for :term:`mapping` objects, using a :class:`dict`, which
is a generic type expecting two type parameters representing the key type
and the value type. In this example, the function expects a ``dict`` with
keys of type :class:`str` and values of type :class:`int`::
def send_post_request(url: str, body: dict[str, int]) -> None:
...
The builtin functions :func:`isinstance` and :func:`issubclass` do not accept
``GenericAlias`` types for their second argument::
>>> isinstance([1, 2], list[str])
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
TypeError: isinstance() argument 2 cannot be a parameterized generic
The Python runtime does not enforce :term:`type annotations <annotation>`.
This extends to generic types and their type parameters. When creating
an object from a ``GenericAlias``, container elements are not checked
against their type. For example, the following code is discouraged, but will
run without errors::
>>> t = list[str]
>>> t([1, 2, 3])
[1, 2, 3]
Furthermore, parameterized generics erase type parameters during object
creation::
>>> t = list[str]
>>> type(t)
<class 'types.GenericAlias'>
>>> l = t()
>>> type(l)
<class 'list'>
Calling :func:`repr` or :func:`str` on a generic shows the parameterized type::
>>> repr(list[int])
'list[int]'
>>> str(list[int])
'list[int]'
The :meth:`__getitem__` method of generics will raise an exception to disallow
mistakes like ``dict[str][str]``::
>>> dict[str][str]
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
TypeError: There are no type variables left in dict[str]
However, such expressions are valid when :ref:`type variables <generics>` are
used. The index must have as many elements as there are type variable items
in the ``GenericAlias`` object's :attr:`__args__ <genericalias.__args__>`. ::
>>> from typing import TypeVar
>>> Y = TypeVar('Y')
>>> dict[str, Y][int]
dict[str, int]
Standard Generic Collections
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
These standard library collections support parameterized generics.
* :class:`tuple`
* :class:`list`
* :class:`dict`
* :class:`set`
* :class:`frozenset`
* :class:`type`
* :class:`collections.deque`
* :class:`collections.defaultdict`
* :class:`collections.OrderedDict`
* :class:`collections.Counter`
* :class:`collections.ChainMap`
* :class:`collections.abc.Awaitable`
* :class:`collections.abc.Coroutine`
* :class:`collections.abc.AsyncIterable`
* :class:`collections.abc.AsyncIterator`
* :class:`collections.abc.AsyncGenerator`
* :class:`collections.abc.Iterable`
* :class:`collections.abc.Iterator`
* :class:`collections.abc.Generator`
* :class:`collections.abc.Reversible`
* :class:`collections.abc.Container`
* :class:`collections.abc.Collection`
* :class:`collections.abc.Callable`
* :class:`collections.abc.Set`
* :class:`collections.abc.MutableSet`
* :class:`collections.abc.Mapping`
* :class:`collections.abc.MutableMapping`
* :class:`collections.abc.Sequence`
* :class:`collections.abc.MutableSequence`
* :class:`collections.abc.ByteString`
* :class:`collections.abc.MappingView`
* :class:`collections.abc.KeysView`
* :class:`collections.abc.ItemsView`
* :class:`collections.abc.ValuesView`
* :class:`contextlib.AbstractContextManager`
* :class:`contextlib.AbstractAsyncContextManager`
* :ref:`re.Pattern <re-objects>`
* :ref:`re.Match <match-objects>`
Special Attributes of Generic Alias
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
All parameterized generics implement special read-only attributes.
.. attribute:: genericalias.__origin__
This attribute points at the non-parameterized generic class::
>>> list[int].__origin__
<class 'list'>
.. attribute:: genericalias.__args__
This attribute is a :class:`tuple` (possibly of length 1) of generic
types passed to the original :meth:`__class_getitem__`
of the generic container::
>>> dict[str, list[int]].__args__
(<class 'str'>, list[int])
.. attribute:: genericalias.__parameters__
This attribute is a lazily computed tuple (possibly empty) of unique type
variables found in ``__args__``::
>>> from typing import TypeVar
>>> T = TypeVar('T')
>>> list[T].__parameters__
(~T,)
.. seealso::
* :pep:`585` -- "Type Hinting Generics In Standard Collections"
* :meth:`__class_getitem__` -- Used to implement parameterized generics.
* :ref:`generics` -- Generics in the :mod:`typing` module.
.. versionadded:: 3.9
.. _types-union:
Union Type
==========
----------
.. index::
object: Union
@ -4760,14 +4979,15 @@ Union Type
A union object holds the value of the ``|`` (bitwise or) operation on
multiple :ref:`type objects <bltin-type-objects>`. These types are intended
primarily for type annotations. The union type expression enables cleaner
type hinting syntax compared to :data:`typing.Union`.
primarily for :term:`type annotations <annotation>`. The union type expression
enables cleaner type hinting syntax compared to :data:`typing.Union`.
.. describe:: X | Y | ...
Defines a union object which holds types *X*, *Y*, and so forth. ``X | Y``
means either X or Y. It is equivalent to ``typing.Union[X, Y]``.
Example::
For example, the following function expects an argument of type
:class:`int` or :class:`float`::
def square(number: int | float) -> int | float:
return number ** 2
@ -4776,15 +4996,15 @@ type hinting syntax compared to :data:`typing.Union`.
Union objects can be tested for equality with other union objects. Details:
* Unions of unions are flattened, e.g.::
* Unions of unions are flattened::
(int | str) | float == int | str | float
* Redundant types are removed, e.g.::
* Redundant types are removed::
int | str | int == int | str
* When comparing unions, the order is ignored, e.g.::
* When comparing unions, the order is ignored::
int | str == str | int
@ -4798,19 +5018,13 @@ type hinting syntax compared to :data:`typing.Union`.
.. describe:: isinstance(obj, union_object)
Calls to :func:`isinstance` are also supported with a Union object::
Calls to :func:`isinstance` are also supported with a union object::
>>> isinstance("", int | str)
True
..
At the time of writing this, there is no documentation for parameterized
generics or PEP 585. Thus the link currently points to PEP 585 itself.
Please change the link for parameterized generics to reference the correct
documentation once documentation for PEP 585 becomes available.
However, union objects containing `parameterized generics
<https://www.python.org/dev/peps/pep-0585/>`_ cannot be used::
However, union objects containing :ref:`parameterized generics
<types-genericalias>` cannot be used::
>>> isinstance(1, int | list[int])
Traceback (most recent call last):
@ -4819,25 +5033,21 @@ type hinting syntax compared to :data:`typing.Union`.
.. describe:: issubclass(obj, union_object)
Calls to :func:`issubclass` are also supported with a Union Object.::
Calls to :func:`issubclass` are also supported with a union object::
>>> issubclass(bool, int | str)
True
..
Once again, please change the link below for parameterized generics to
reference the correct documentation once documentation for PEP 585
becomes available.
However, union objects containing `parameterized generics
<https://www.python.org/dev/peps/pep-0585/>`_ cannot be used::
However, union objects containing :ref:`parameterized generics
<types-genericalias>` cannot be used::
>>> issubclass(bool, bool | list[str])
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
TypeError: issubclass() argument 2 cannot contain a parameterized generic
The type for the Union object is :data:`types.Union`. An object cannot be
The user-exposed type for the union object can be accessed from
:data:`types.Union` and used for :func:`isinstance` checks. An object cannot be
instantiated from the type::
>>> import types

40
Doc/library/subprocess.rst
View File

@ -341,10 +341,10 @@ functions.
startupinfo=None, creationflags=0, restore_signals=True, \
start_new_session=False, pass_fds=(), \*, group=None, \
extra_groups=None, user=None, umask=-1, \
encoding=None, errors=None, text=None)
encoding=None, errors=None, text=None, pipesize=-1)
Execute a child program in a new process. On POSIX, the class uses
:meth:`os.execvp`-like behavior to execute the child program. On Windows,
:meth:`os.execvpe`-like behavior to execute the child program. On Windows,
the class uses the Windows ``CreateProcess()`` function. The arguments to
:class:`Popen` are as follows.
@ -356,6 +356,25 @@ functions.
arguments for additional differences from the default behavior. Unless
otherwise stated, it is recommended to pass *args* as a sequence.
.. warning::
For maximum reliability, use a fully-qualified path for the executable.
To search for an unqualified name on :envvar:`PATH`, use
:meth:`shutil.which`. On all platforms, passing :data:`sys.executable`
is the recommended way to launch the current Python interpreter again,
and use the ``-m`` command-line format to launch an installed module.
Resolving the path of *executable* (or the first item of *args*) is
platform dependent. For POSIX, see :meth:`os.execvpe`, and note that
when resolving or searching for the executable path, *cwd* overrides the
current working directory and *env* can override the ``PATH``
environment variable. For Windows, see the documentation of the
``lpApplicationName`` and ``lpCommandLine`` parameters of WinAPI
``CreateProcess``, and note that when resolving or searching for the
executable path with ``shell=False``, *cwd* does not override the
current working directory and *env* cannot override the ``PATH``
environment variable. Using a full path avoids all of these variations.
An example of passing some arguments to an external program
as a sequence is::
@ -524,7 +543,7 @@ functions.
If *cwd* is not ``None``, the function changes the working directory to
*cwd* before executing the child. *cwd* can be a string, bytes or
:term:`path-like <path-like object>` object. In particular, the function
:term:`path-like <path-like object>` object. In POSIX, the function
looks for *executable* (or for the first item in *args*) relative to *cwd*
if the executable path is a relative path.
@ -625,6 +644,14 @@ functions.
* :data:`CREATE_DEFAULT_ERROR_MODE`
* :data:`CREATE_BREAKAWAY_FROM_JOB`
*pipesize* can be used to change the size of the pipe when
:data:`PIPE` is used for *stdin*, *stdout* or *stderr*. The size of the pipe
is only changed on platforms that support this (only Linux at this time of
writing). Other platforms will ignore this parameter.
.. versionadded:: 3.10
The ``pipesize`` parameter was added.
Popen objects are supported as context managers via the :keyword:`with` statement:
on exit, standard file descriptors are closed, and the process is waited for.
::
@ -691,11 +718,8 @@ If the shell is invoked explicitly, via ``shell=True``, it is the application's
responsibility to ensure that all whitespace and metacharacters are
quoted appropriately to avoid
`shell injection <https://en.wikipedia.org/wiki/Shell_injection#Shell_injection>`_
vulnerabilities.
When using ``shell=True``, the :func:`shlex.quote` function can be
used to properly escape whitespace and shell metacharacters in strings
that are going to be used to construct shell commands.
vulnerabilities. On :ref:`some platforms <shlex-quote-warning>`, it is possible
to use :func:`shlex.quote` for this escaping.
Popen Objects

106
Doc/library/sys.rst
View File

@ -31,16 +31,22 @@ always available.
When an auditing event is raised through the :func:`sys.audit` function, each
hook will be called in the order it was added with the event name and the
tuple of arguments. Native hooks added by :c:func:`PySys_AddAuditHook` are
called first, followed by hooks added in the current interpreter.
called first, followed by hooks added in the current interpreter. Hooks
can then log the event, raise an exception to abort the operation,
or terminate the process entirely.
.. audit-event:: sys.addaudithook "" sys.addaudithook
Raise an auditing event ``sys.addaudithook`` with no arguments. If any
Calling :func:`sys.addaudithook` will itself raise an auditing event
named ``sys.addaudithook`` with no arguments. If any
existing hooks raise an exception derived from :class:`RuntimeError`, the
new hook will not be added and the exception suppressed. As a result,
callers cannot assume that their hook has been added unless they control
all existing hooks.
See the :ref:`audit events table <audit-events>` for all events raised by
CPython, and :pep:`578` for the original design discussion.
.. versionadded:: 3.8
.. versionchanged:: 3.8.1
@ -81,14 +87,23 @@ always available.
.. index:: single: auditing
Raise an auditing event with any active hooks. The event name is a string
identifying the event and its associated schema, which is the number and
types of arguments. The schema for a given event is considered public and
stable API and should not be modified between releases.
Raise an auditing event and trigger any active auditing hooks.
*event* is a string identifying the event, and *args* may contain
optional arguments with more information about the event. The
number and types of arguments for a given event are considered a
public and stable API and should not be modified between releases.
This function will raise the first exception raised by any hook. In general,
these errors should not be handled and should terminate the process as
quickly as possible.
For example, one auditing event is named ``os.chdir``. This event has
one argument called *path* that will contain the requested new
working directory.
:func:`sys.audit` will call the existing auditing hooks, passing
the event name and arguments, and will re-raise the first exception
from any hook. In general, if an exception is raised, it should not
be handled and the process should be terminated as quickly as
possible. This allows hook implementations to decide how to respond
to particular events: they can merely log the event or abort the
operation by raising an exception.
Hooks are added using the :func:`sys.addaudithook` or
:c:func:`PySys_AddAuditHook` functions.
@ -181,6 +196,18 @@ always available.
.. audit-event:: sys._current_frames "" sys._current_frames
.. function:: _current_exceptions()
Return a dictionary mapping each thread's identifier to the topmost exception
currently active in that thread at the time the function is called.
If a thread is not currently handling an exception, it is not included in
the result dictionary.
This is most useful for statistical profiling.
This function should be used for internal and specialized purposes only.
.. audit-event:: sys._current_exceptions "" sys._current_exceptions
.. function:: breakpointhook()
@ -600,30 +627,24 @@ always available.
.. function:: getfilesystemencoding()
Return the name of the encoding used to convert between Unicode
filenames and bytes filenames. For best compatibility, str should be
used for filenames in all cases, although representing filenames as bytes
is also supported. Functions accepting or returning filenames should support
either str or bytes and internally convert to the system's preferred
representation.
Get the :term:`filesystem encoding <filesystem encoding and error handler>`:
the encoding used with the :term:`filesystem error handler <filesystem
encoding and error handler>` to convert between Unicode filenames and bytes
filenames. The filesystem error handler is returned from
:func:`getfilesystemencoding`.
This encoding is always ASCII-compatible.
For best compatibility, str should be used for filenames in all cases,
although representing filenames as bytes is also supported. Functions
accepting or returning filenames should support either str or bytes and
internally convert to the system's preferred representation.
:func:`os.fsencode` and :func:`os.fsdecode` should be used to ensure that
the correct encoding and errors mode are used.
* In the UTF-8 mode, the encoding is ``utf-8`` on any platform.
* On macOS, the encoding is ``'utf-8'``.
* On Unix, the encoding is the locale encoding.
* On Windows, the encoding may be ``'utf-8'`` or ``'mbcs'``, depending
on user configuration.
* On Android, the encoding is ``'utf-8'``.
* On VxWorks, the encoding is ``'utf-8'``.
The :term:`filesystem encoding and error handler` are configured at Python
startup by the :c:func:`PyConfig_Read` function: see
:c:member:`~PyConfig.filesystem_encoding` and
:c:member:`~PyConfig.filesystem_errors` members of :c:type:`PyConfig`.
.. versionchanged:: 3.2
:func:`getfilesystemencoding` result cannot be ``None`` anymore.
@ -633,18 +654,26 @@ always available.
and :func:`_enablelegacywindowsfsencoding` for more information.
.. versionchanged:: 3.7
Return 'utf-8' in the UTF-8 mode.
Return ``'utf-8'`` if the :ref:`Python UTF-8 Mode <utf8-mode>` is
enabled.
.. function:: getfilesystemencodeerrors()
Return the name of the error mode used to convert between Unicode filenames
and bytes filenames. The encoding name is returned from
Get the :term:`filesystem error handler <filesystem encoding and error
handler>`: the error handler used with the :term:`filesystem encoding
<filesystem encoding and error handler>` to convert between Unicode
filenames and bytes filenames. The filesystem encoding is returned from
:func:`getfilesystemencoding`.
:func:`os.fsencode` and :func:`os.fsdecode` should be used to ensure that
the correct encoding and errors mode are used.
The :term:`filesystem encoding and error handler` are configured at Python
startup by the :c:func:`PyConfig_Read` function: see
:c:member:`~PyConfig.filesystem_encoding` and
:c:member:`~PyConfig.filesystem_errors` members of :c:type:`PyConfig`.
.. versionadded:: 3.6
.. function:: getrefcount(object)
@ -1436,12 +1465,16 @@ always available.
.. function:: _enablelegacywindowsfsencoding()
Changes the default filesystem encoding and errors mode to 'mbcs' and
'replace' respectively, for consistency with versions of Python prior to 3.6.
Changes the :term:`filesystem encoding and error handler` to 'mbcs' and
'replace' respectively, for consistency with versions of Python prior to
3.6.
This is equivalent to defining the :envvar:`PYTHONLEGACYWINDOWSFSENCODING`
environment variable before launching Python.
See also :func:`sys.getfilesystemencoding` and
:func:`sys.getfilesystemencodeerrors`.
.. availability:: Windows.
.. versionadded:: 3.6
@ -1464,9 +1497,8 @@ always available.
returned by the :func:`open` function. Their parameters are chosen as
follows:
* The character encoding is platform-dependent. Non-Windows
platforms use the locale encoding (see
:meth:`locale.getpreferredencoding()`).
* The encoding and error handling are is initialized from
:c:member:`PyConfig.stdio_encoding` and :c:member:`PyConfig.stdio_errors`.
On Windows, UTF-8 is used for the console device. Non-character
devices such as disk files and pipes use the system locale
@ -1474,7 +1506,7 @@ always available.
devices such as NUL (i.e. where ``isatty()`` returns ``True``) use the
value of the console input and output codepages at startup,
respectively for stdin and stdout/stderr. This defaults to the
system locale encoding if the process is not initially attached
system :term:`locale encoding` if the process is not initially attached
to a console.
The special behaviour of the console can be overridden

9
Doc/library/tarfile.rst
View File

@ -445,10 +445,11 @@ be finalized; only the internally used file object will be closed. See the
.. method:: TarFile.extractfile(member)
Extract a member from the archive as a file object. *member* may be a filename
or a :class:`TarInfo` object. If *member* is a regular file or a link, an
:class:`io.BufferedReader` object is returned. Otherwise, :const:`None` is
returned.
Extract a member from the archive as a file object. *member* may be
a filename or a :class:`TarInfo` object. If *member* is a regular file or
a link, an :class:`io.BufferedReader` object is returned. For all other
existing members, :const:`None` is returned. If *member* does not appear
in the archive, :exc:`KeyError` is raised.
.. versionchanged:: 3.3
Return an :class:`io.BufferedReader` object.

27
Doc/library/threading.rst
View File

@ -71,6 +71,13 @@ This module defines the following functions:
.. versionadded:: 3.8
.. data:: __excepthook__
Holds the original value of :func:`threading.excepthook`. It is saved so that the
original value can be restored in case they happen to get replaced with
broken or alternative objects.
.. versionadded:: 3.10
.. function:: get_ident()
@ -121,6 +128,17 @@ This module defines the following functions:
:meth:`~Thread.run` method is called.
.. function:: gettrace()
.. index::
single: trace function
single: debugger
Get the trace function as set by :func:`settrace`.
.. versionadded:: 3.10
.. function:: setprofile(func)
.. index:: single: profile function
@ -130,6 +148,15 @@ This module defines the following functions:
:meth:`~Thread.run` method is called.
.. function:: getprofile()
.. index:: single: profile function
Get the profiler function as set by :func:`setprofile`.
.. versionadded:: 3.10
.. function:: stack_size([size])
Return the thread stack size used when creating new threads. The optional

43
Doc/library/time.rst
View File

@ -166,6 +166,9 @@ Functions
Return the time of the specified clock *clk_id*. Refer to
:ref:`time-clock-id-constants` for a list of accepted values for *clk_id*.
Use :func:`clock_gettime_ns` to avoid the precision loss caused by the
:class:`float` type.
.. availability:: Unix.
.. versionadded:: 3.3
@ -185,6 +188,9 @@ Functions
Set the time of the specified clock *clk_id*. Currently,
:data:`CLOCK_REALTIME` is the only accepted value for *clk_id*.
Use :func:`clock_settime_ns` to avoid the precision loss caused by the
:class:`float` type.
.. availability:: Unix.
.. versionadded:: 3.3
@ -273,10 +279,17 @@ Functions
The reference point of the returned value is undefined, so that only the
difference between the results of consecutive calls is valid.
Use :func:`monotonic_ns` to avoid the precision loss caused by the
:class:`float` type.
.. versionadded:: 3.3
.. versionchanged:: 3.5
The function is now always available and always system-wide.
.. versionchanged:: 3.10
On macOS, the function is now system-wide.
.. function:: monotonic_ns() -> int
@ -295,8 +308,14 @@ Functions
point of the returned value is undefined, so that only the difference between
the results of consecutive calls is valid.
Use :func:`perf_counter_ns` to avoid the precision loss caused by the
:class:`float` type.
.. versionadded:: 3.3
.. versionchanged:: 3.10
On Windows, the function is now system-wide.
.. function:: perf_counter_ns() -> int
Similar to :func:`perf_counter`, but return time as nanoseconds.
@ -317,6 +336,9 @@ Functions
returned value is undefined, so that only the difference between the results
of consecutive calls is valid.
Use :func:`process_time_ns` to avoid the precision loss caused by the
:class:`float` type.
.. versionadded:: 3.3
.. function:: process_time_ns() -> int
@ -581,6 +603,17 @@ Functions
:class:`struct_time` object is returned, from which the components
of the calendar date may be accessed as attributes.
Use :func:`time_ns` to avoid the precision loss caused by the :class:`float`
type.
.. function:: time_ns() -> int
Similar to :func:`~time.time` but returns time as an integer number of nanoseconds
since the epoch_.
.. versionadded:: 3.7
.. function:: thread_time() -> float
@ -595,6 +628,9 @@ Functions
returned value is undefined, so that only the difference between the results
of consecutive calls in the same thread is valid.
Use :func:`thread_time_ns` to avoid the precision loss caused by the
:class:`float` type.
.. availability:: Windows, Linux, Unix systems supporting
``CLOCK_THREAD_CPUTIME_ID``.
@ -608,13 +644,6 @@ Functions
.. versionadded:: 3.7
.. function:: time_ns() -> int
Similar to :func:`~time.time` but returns time as an integer number of nanoseconds
since the epoch_.
.. versionadded:: 3.7
.. function:: tzset()
Reset the time conversion rules used by the library routines. The environment

43
Doc/library/traceback.rst
View File

@ -36,7 +36,8 @@ The module defines the following functions:
Added negative *limit* support.
.. function:: print_exception(etype, value, tb, limit=None, file=None, chain=True)
.. function:: print_exception(exc, /[, value, tb], limit=None, \
file=None, chain=True)
Print exception information and stack trace entries from traceback object
*tb* to *file*. This differs from :func:`print_tb` in the following
@ -45,7 +46,7 @@ The module defines the following functions:
* if *tb* is not ``None``, it prints a header ``Traceback (most recent
call last):``
* it prints the exception *etype* and *value* after the stack trace
* it prints the exception type and *value* after the stack trace
.. index:: single: ^ (caret); marker
@ -53,6 +54,10 @@ The module defines the following functions:
format, it prints the line where the syntax error occurred with a caret
indicating the approximate position of the error.
Since Python 3.10, instead of passing *value* and *tb*, an exception object
can be passed as the first argument. If *value* and *tb* are provided, the
first argument is ignored in order to provide backwards compatibility.
The optional *limit* argument has the same meaning as for :func:`print_tb`.
If *chain* is true (the default), then chained exceptions (the
:attr:`__cause__` or :attr:`__context__` attributes of the exception) will be
@ -62,6 +67,10 @@ The module defines the following functions:
.. versionchanged:: 3.5
The *etype* argument is ignored and inferred from the type of *value*.
.. versionchanged:: 3.10
The *etype* parameter has been renamed to *exc* and is now
positional-only.
.. function:: print_exc(limit=None, file=None, chain=True)
@ -121,18 +130,26 @@ The module defines the following functions:
text line is not ``None``.
.. function:: format_exception_only(etype, value)
.. function:: format_exception_only(exc, /[, value])
Format the exception part of a traceback. The arguments are the exception
type and value such as given by ``sys.last_type`` and ``sys.last_value``.
The return value is a list of strings, each ending in a newline. Normally,
the list contains a single string; however, for :exc:`SyntaxError`
exceptions, it contains several lines that (when printed) display detailed
information about where the syntax error occurred. The message indicating
which exception occurred is the always last string in the list.
Format the exception part of a traceback using an exception value such as
given by ``sys.last_value``. The return value is a list of strings, each
ending in a newline. Normally, the list contains a single string; however,
for :exc:`SyntaxError` exceptions, it contains several lines that (when
printed) display detailed information about where the syntax error occurred.
The message indicating which exception occurred is the always last string in
the list.
Since Python 3.10, instead of passing *value*, an exception object
can be passed as the first argument. If *value* is provided, the first
argument is ignored in order to provide backwards compatibility.
.. versionchanged:: 3.10
The *etype* parameter has been renamed to *exc* and is now
positional-only.
.. function:: format_exception(etype, value, tb, limit=None, chain=True)
.. function:: format_exception(exc, /[, value, tb], limit=None, chain=True)
Format a stack trace and the exception information. The arguments have the
same meaning as the corresponding arguments to :func:`print_exception`. The
@ -143,6 +160,10 @@ The module defines the following functions:
.. versionchanged:: 3.5
The *etype* argument is ignored and inferred from the type of *value*.
.. versionchanged:: 3.10
This function's behavior and signature were modified to match
:func:`print_exception`.
.. function:: format_exc(limit=None, chain=True)

30
Doc/library/types.rst
View File

@ -116,6 +116,11 @@ Standard names are defined for the following types:
The type of user-defined functions and functions created by
:keyword:`lambda` expressions.
.. audit-event:: function.__new__ code types.FunctionType
The audit event only occurs for direct instantiation of function objects,
and is not raised for normal compilation.
.. data:: GeneratorType
@ -145,10 +150,11 @@ Standard names are defined for the following types:
The type for code objects such as returned by :func:`compile`.
.. audit-event:: code.__new__ code,filename,name,argcount,posonlyargcount,kwonlyargcount,nlocals,stacksize,flags CodeType
.. audit-event:: code.__new__ code,filename,name,argcount,posonlyargcount,kwonlyargcount,nlocals,stacksize,flags types.CodeType
Note that the audited arguments may not match the names or positions
required by the initializer.
required by the initializer. The audit event only occurs for direct
instantiation of code objects, and is not raised for normal compilation.
.. method:: CodeType.replace(**kwargs)
@ -256,6 +262,24 @@ Standard names are defined for the following types:
.. versionadded:: 3.10
.. class:: GenericAlias(t_origin, t_args)
The type of :ref:`parameterized generics <types-genericalias>` such as
``list[int]``.
``t_origin`` should be a non-parameterized generic class, such as ``list``,
``tuple`` or ``dict``. ``t_args`` should be a :class:`tuple` (possibly of
length 1) of types which parameterize ``t_origin``::
>>> from types import GenericAlias
>>> list[int] == GenericAlias(list, (int,))
True
>>> dict[str, int] == GenericAlias(dict, (str, int))
True
.. versionadded:: 3.9
.. data:: Union
The type of :ref:`union type expressions<types-union>`.
@ -385,7 +409,9 @@ Additional Utility Classes and Functions
return "{}({})".format(type(self).__name__, ", ".join(items))
def __eq__(self, other):
if isinstance(self, SimpleNamespace) and isinstance(other, SimpleNamespace):
return self.__dict__ == other.__dict__
return NotImplemented
``SimpleNamespace`` may be useful as a replacement for ``class NS: pass``.
However, for a structured record type use :func:`~collections.namedtuple`

122
Doc/library/typing.rst
View File

@ -524,7 +524,8 @@ These can be used as types in annotations using ``[]``, each having a unique syn
is equivalent to ``Tuple[Any, ...]``, and in turn to :class:`tuple`.
.. deprecated:: 3.9
:class:`builtins.tuple <tuple>` now supports ``[]``. See :pep:`585`.
:class:`builtins.tuple <tuple>` now supports ``[]``. See :pep:`585` and
:ref:`types-genericalias`.
.. data:: Union
@ -602,7 +603,8 @@ These can be used as types in annotations using ``[]``, each having a unique syn
:class:`collections.abc.Callable`.
.. deprecated:: 3.9
:class:`collections.abc.Callable` now supports ``[]``. See :pep:`585`.
:class:`collections.abc.Callable` now supports ``[]``. See :pep:`585` and
:ref:`types-genericalias`.
.. class:: Type(Generic[CT_co])
@ -639,7 +641,7 @@ These can be used as types in annotations using ``[]``, each having a unique syn
:ref:`type variables <generics>`, and unions of any of these types.
For example::
def new_non_team_user(user_class: Type[Union[BaseUser, ProUser]]): ...
def new_non_team_user(user_class: Type[Union[BasicUser, ProUser]]): ...
``Type[Any]`` is equivalent to ``Type`` which in turn is equivalent
to ``type``, which is the root of Python's metaclass hierarchy.
@ -647,7 +649,8 @@ These can be used as types in annotations using ``[]``, each having a unique syn
.. versionadded:: 3.5.2
.. deprecated:: 3.9
:class:`builtins.type <type>` now supports ``[]``. See :pep:`585`.
:class:`builtins.type <type>` now supports ``[]``. See :pep:`585` and
:ref:`types-genericalias`.
.. data:: Literal
@ -671,6 +674,12 @@ These can be used as types in annotations using ``[]``, each having a unique syn
.. versionadded:: 3.8
.. versionchanged:: 3.9.1
``Literal`` now de-duplicates parameters. Equality comparison of
``Literal`` objects are no longer order dependent. ``Literal`` objects
will now raise a :exc:`TypeError` exception during equality comparisons
if one of their parameters are not :term:`immutable`.
.. data:: ClassVar
Special type construct to mark class variables.
@ -1079,7 +1088,8 @@ Corresponding to built-in types
...
.. deprecated:: 3.9
:class:`builtins.dict <dict>` now supports ``[]``. See :pep:`585`.
:class:`builtins.dict <dict>` now supports ``[]``. See :pep:`585` and
:ref:`types-genericalias`.
.. class:: List(list, MutableSequence[T])
@ -1099,7 +1109,8 @@ Corresponding to built-in types
return [item for item in vector if item > 0]
.. deprecated:: 3.9
:class:`builtins.list <list>` now supports ``[]``. See :pep:`585`.
:class:`builtins.list <list>` now supports ``[]``. See :pep:`585` and
:ref:`types-genericalias`.
.. class:: Set(set, MutableSet[T])
@ -1108,14 +1119,16 @@ Corresponding to built-in types
to use an abstract collection type such as :class:`AbstractSet`.
.. deprecated:: 3.9
:class:`builtins.set <set>` now supports ``[]``. See :pep:`585`.
:class:`builtins.set <set>` now supports ``[]``. See :pep:`585` and
:ref:`types-genericalias`.
.. class:: FrozenSet(frozenset, AbstractSet[T_co])
A generic version of :class:`builtins.frozenset <frozenset>`.
.. deprecated:: 3.9
:class:`builtins.frozenset <frozenset>` now supports ``[]``. See :pep:`585`.
:class:`builtins.frozenset <frozenset>` now supports ``[]``. See
:pep:`585` and :ref:`types-genericalias`.
.. note:: :data:`Tuple` is a special form.
@ -1129,7 +1142,8 @@ Corresponding to types in :mod:`collections`
.. versionadded:: 3.5.2
.. deprecated:: 3.9
:class:`collections.defaultdict` now supports ``[]``. See :pep:`585`.
:class:`collections.defaultdict` now supports ``[]``. See :pep:`585` and
:ref:`types-genericalias`.
.. class:: OrderedDict(collections.OrderedDict, MutableMapping[KT, VT])
@ -1138,7 +1152,8 @@ Corresponding to types in :mod:`collections`
.. versionadded:: 3.7.2
.. deprecated:: 3.9
:class:`collections.OrderedDict` now supports ``[]``. See :pep:`585`.
:class:`collections.OrderedDict` now supports ``[]``. See :pep:`585` and
:ref:`types-genericalias`.
.. class:: ChainMap(collections.ChainMap, MutableMapping[KT, VT])
@ -1148,7 +1163,8 @@ Corresponding to types in :mod:`collections`
.. versionadded:: 3.6.1
.. deprecated:: 3.9
:class:`collections.ChainMap` now supports ``[]``. See :pep:`585`.
:class:`collections.ChainMap` now supports ``[]``. See :pep:`585` and
:ref:`types-genericalias`.
.. class:: Counter(collections.Counter, Dict[T, int])
@ -1158,7 +1174,8 @@ Corresponding to types in :mod:`collections`
.. versionadded:: 3.6.1
.. deprecated:: 3.9
:class:`collections.Counter` now supports ``[]``. See :pep:`585`.
:class:`collections.Counter` now supports ``[]``. See :pep:`585` and
:ref:`types-genericalias`.
.. class:: Deque(deque, MutableSequence[T])
@ -1168,7 +1185,8 @@ Corresponding to types in :mod:`collections`
.. versionadded:: 3.6.1
.. deprecated:: 3.9
:class:`collections.deque` now supports ``[]``. See :pep:`585`.
:class:`collections.deque` now supports ``[]``. See :pep:`585` and
:ref:`types-genericalias`.
Other concrete types
""""""""""""""""""""
@ -1193,7 +1211,8 @@ Other concrete types
``Match[bytes]``. These types are also in the ``typing.re`` namespace.
.. deprecated:: 3.9
Classes ``Pattern`` and ``Match`` from :mod:`re` now support ``[]``. See :pep:`585`.
Classes ``Pattern`` and ``Match`` from :mod:`re` now support ``[]``.
See :pep:`585` and :ref:`types-genericalias`.
.. class:: Text
@ -1220,7 +1239,8 @@ Corresponding to collections in :mod:`collections.abc`
A generic version of :class:`collections.abc.Set`.
.. deprecated:: 3.9
:class:`collections.abc.Set` now supports ``[]``. See :pep:`585`.
:class:`collections.abc.Set` now supports ``[]``. See :pep:`585` and
:ref:`types-genericalias`.
.. class:: ByteString(Sequence[int])
@ -1233,7 +1253,8 @@ Corresponding to collections in :mod:`collections.abc`
annotate arguments of any of the types mentioned above.
.. deprecated:: 3.9
:class:`collections.abc.ByteString` now supports ``[]``. See :pep:`585`.
:class:`collections.abc.ByteString` now supports ``[]``. See :pep:`585`
and :ref:`types-genericalias`.
.. class:: Collection(Sized, Iterable[T_co], Container[T_co])
@ -1242,28 +1263,32 @@ Corresponding to collections in :mod:`collections.abc`
.. versionadded:: 3.6.0
.. deprecated:: 3.9
:class:`collections.abc.Collection` now supports ``[]``. See :pep:`585`.
:class:`collections.abc.Collection` now supports ``[]``. See :pep:`585`
and :ref:`types-genericalias`.
.. class:: Container(Generic[T_co])
A generic version of :class:`collections.abc.Container`.
.. deprecated:: 3.9
:class:`collections.abc.Container` now supports ``[]``. See :pep:`585`.
:class:`collections.abc.Container` now supports ``[]``. See :pep:`585`
and :ref:`types-genericalias`.
.. class:: ItemsView(MappingView, Generic[KT_co, VT_co])
A generic version of :class:`collections.abc.ItemsView`.
.. deprecated:: 3.9
:class:`collections.abc.ItemsView` now supports ``[]``. See :pep:`585`.
:class:`collections.abc.ItemsView` now supports ``[]``. See :pep:`585`
and :ref:`types-genericalias`.
.. class:: KeysView(MappingView[KT_co], AbstractSet[KT_co])
A generic version of :class:`collections.abc.KeysView`.
.. deprecated:: 3.9
:class:`collections.abc.KeysView` now supports ``[]``. See :pep:`585`.
:class:`collections.abc.KeysView` now supports ``[]``. See :pep:`585`
and :ref:`types-genericalias`.
.. class:: Mapping(Sized, Collection[KT], Generic[VT_co])
@ -1274,49 +1299,56 @@ Corresponding to collections in :mod:`collections.abc`
return word_list[word]
.. deprecated:: 3.9
:class:`collections.abc.Mapping` now supports ``[]``. See :pep:`585`.
:class:`collections.abc.Mapping` now supports ``[]``. See :pep:`585`
and :ref:`types-genericalias`.
.. class:: MappingView(Sized, Iterable[T_co])
A generic version of :class:`collections.abc.MappingView`.
.. deprecated:: 3.9
:class:`collections.abc.MappingView` now supports ``[]``. See :pep:`585`.
:class:`collections.abc.MappingView` now supports ``[]``. See :pep:`585`
and :ref:`types-genericalias`.
.. class:: MutableMapping(Mapping[KT, VT])
A generic version of :class:`collections.abc.MutableMapping`.
.. deprecated:: 3.9
:class:`collections.abc.MutableMapping` now supports ``[]``. See :pep:`585`.
:class:`collections.abc.MutableMapping` now supports ``[]``. See
:pep:`585` and :ref:`types-genericalias`.
.. class:: MutableSequence(Sequence[T])
A generic version of :class:`collections.abc.MutableSequence`.
.. deprecated:: 3.9
:class:`collections.abc.MutableSequence` now supports ``[]``. See :pep:`585`.
:class:`collections.abc.MutableSequence` now supports ``[]``. See
:pep:`585` and :ref:`types-genericalias`.
.. class:: MutableSet(AbstractSet[T])
A generic version of :class:`collections.abc.MutableSet`.
.. deprecated:: 3.9
:class:`collections.abc.MutableSet` now supports ``[]``. See :pep:`585`.
:class:`collections.abc.MutableSet` now supports ``[]``. See :pep:`585`
and :ref:`types-genericalias`.
.. class:: Sequence(Reversible[T_co], Collection[T_co])
A generic version of :class:`collections.abc.Sequence`.
.. deprecated:: 3.9
:class:`collections.abc.Sequence` now supports ``[]``. See :pep:`585`.
:class:`collections.abc.Sequence` now supports ``[]``. See :pep:`585`
and :ref:`types-genericalias`.
.. class:: ValuesView(MappingView[VT_co])
A generic version of :class:`collections.abc.ValuesView`.
.. deprecated:: 3.9
:class:`collections.abc.ValuesView` now supports ``[]``. See :pep:`585`.
:class:`collections.abc.ValuesView` now supports ``[]``. See :pep:`585`
and :ref:`types-genericalias`.
Corresponding to other types in :mod:`collections.abc`
""""""""""""""""""""""""""""""""""""""""""""""""""""""
@ -1326,14 +1358,16 @@ Corresponding to other types in :mod:`collections.abc`
A generic version of :class:`collections.abc.Iterable`.
.. deprecated:: 3.9
:class:`collections.abc.Iterable` now supports ``[]``. See :pep:`585`.
:class:`collections.abc.Iterable` now supports ``[]``. See :pep:`585`
and :ref:`types-genericalias`.
.. class:: Iterator(Iterable[T_co])
A generic version of :class:`collections.abc.Iterator`.
.. deprecated:: 3.9
:class:`collections.abc.Iterator` now supports ``[]``. See :pep:`585`.
:class:`collections.abc.Iterator` now supports ``[]``. See :pep:`585`
and :ref:`types-genericalias`.
.. class:: Generator(Iterator[T_co], Generic[T_co, T_contra, V_co])
@ -1367,7 +1401,8 @@ Corresponding to other types in :mod:`collections.abc`
start += 1
.. deprecated:: 3.9
:class:`collections.abc.Generator` now supports ``[]``. See :pep:`585`.
:class:`collections.abc.Generator` now supports ``[]``. See :pep:`585`
and :ref:`types-genericalias`.
.. class:: Hashable
@ -1378,7 +1413,8 @@ Corresponding to other types in :mod:`collections.abc`
A generic version of :class:`collections.abc.Reversible`.
.. deprecated:: 3.9
:class:`collections.abc.Reversible` now supports ``[]``. See :pep:`585`.
:class:`collections.abc.Reversible` now supports ``[]``. See :pep:`585`
and :ref:`types-genericalias`.
.. class:: Sized
@ -1403,7 +1439,8 @@ Asynchronous programming
.. versionadded:: 3.5.3
.. deprecated:: 3.9
:class:`collections.abc.Coroutine` now supports ``[]``. See :pep:`585`.
:class:`collections.abc.Coroutine` now supports ``[]``. See :pep:`585`
and :ref:`types-genericalias`.
.. class:: AsyncGenerator(AsyncIterator[T_co], Generic[T_co, T_contra])
@ -1439,7 +1476,8 @@ Asynchronous programming
.. versionadded:: 3.6.1
.. deprecated:: 3.9
:class:`collections.abc.AsyncGenerator` now supports ``[]``. See :pep:`585`.
:class:`collections.abc.AsyncGenerator` now supports ``[]``. See
:pep:`585` and :ref:`types-genericalias`.
.. class:: AsyncIterable(Generic[T_co])
@ -1448,7 +1486,8 @@ Asynchronous programming
.. versionadded:: 3.5.2
.. deprecated:: 3.9
:class:`collections.abc.AsyncIterable` now supports ``[]``. See :pep:`585`.
:class:`collections.abc.AsyncIterable` now supports ``[]``. See :pep:`585`
and :ref:`types-genericalias`.
.. class:: AsyncIterator(AsyncIterable[T_co])
@ -1457,7 +1496,8 @@ Asynchronous programming
.. versionadded:: 3.5.2
.. deprecated:: 3.9
:class:`collections.abc.AsyncIterator` now supports ``[]``. See :pep:`585`.
:class:`collections.abc.AsyncIterator` now supports ``[]``. See :pep:`585`
and :ref:`types-genericalias`.
.. class:: Awaitable(Generic[T_co])
@ -1466,7 +1506,8 @@ Asynchronous programming
.. versionadded:: 3.5.2
.. deprecated:: 3.9
:class:`collections.abc.Awaitable` now supports ``[]``. See :pep:`585`.
:class:`collections.abc.Awaitable` now supports ``[]``. See :pep:`585`
and :ref:`types-genericalias`.
Context manager types
@ -1480,7 +1521,8 @@ Context manager types
.. versionadded:: 3.6.0
.. deprecated:: 3.9
:class:`contextlib.AbstractContextManager` now supports ``[]``. See :pep:`585`.
:class:`contextlib.AbstractContextManager` now supports ``[]``. See
:pep:`585` and :ref:`types-genericalias`.
.. class:: AsyncContextManager(Generic[T_co])
@ -1490,7 +1532,8 @@ Context manager types
.. versionadded:: 3.6.2
.. deprecated:: 3.9
:class:`contextlib.AbstractAsyncContextManager` now supports ``[]``. See :pep:`585`.
:class:`contextlib.AbstractAsyncContextManager` now supports ``[]``. See
:pep:`585` and :ref:`types-genericalias`.
Protocols
---------
@ -1669,6 +1712,9 @@ Introspection helpers
For a typing object of the form ``X[Y, Z, ...]`` these functions return
``X`` and ``(Y, Z, ...)``. If ``X`` is a generic alias for a builtin or
:mod:`collections` class, it gets normalized to the original class.
If ``X`` is a :class:`Union` or :class:`Literal` contained in another
generic type, the order of ``(Y, Z, ...)`` may be different from the order
of the original arguments ``[Y, Z, ...]`` due to type caching.
For unsupported objects return ``None`` and ``()`` correspondingly.
Examples::

14
Doc/library/unittest.rst
View File

@ -593,8 +593,9 @@ The following decorators and exception implement test skipping and expected fail
.. decorator:: expectedFailure
Mark the test as an expected failure. If the test fails it will be
considered a success. If the test passes, it will be considered a failure.
Mark the test as an expected failure or error. If the test fails or errors
it will be considered a success. If the test passes, it will be considered
a failure.
.. exception:: SkipTest(reason)
@ -896,8 +897,7 @@ Test cases
.. method:: assertIs(first, second, msg=None)
assertIsNot(first, second, msg=None)
Test that *first* and *second* evaluate (or don't evaluate) to the
same object.
Test that *first* and *second* are (or are not) the same object.
.. versionadded:: 3.1
@ -1967,7 +1967,7 @@ Loading and running tests
A list containing 2-tuples of :class:`TestCase` instances and strings
holding formatted tracebacks. Each tuple represents an expected failure
of the test case.
or error of the test case.
.. attribute:: unexpectedSuccesses
@ -2093,8 +2093,8 @@ Loading and running tests
.. method:: addExpectedFailure(test, err)
Called when the test case *test* fails, but was marked with the
:func:`expectedFailure` decorator.
Called when the test case *test* fails or errors, but was marked with
the :func:`expectedFailure` decorator.
The default implementation appends a tuple ``(test, formatted_err)`` to
the instance's :attr:`expectedFailures` attribute, where *formatted_err*

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

@ -109,6 +109,11 @@ The :mod:`urllib.request` module defines the following functions:
.. versionchanged:: 3.4.3
*context* was added.
.. versionchanged:: 3.10
HTTPS connection now send an ALPN extension with protocol indicator
``http/1.1`` when no *context* is given. Custom *context* should set
ALPN protocols with :meth:`~ssl.SSLContext.set_alpn_protocol`.
.. deprecated:: 3.6
*cafile*, *capath* and *cadefault* are deprecated in favor of *context*.

4
Doc/library/xml.dom.minidom.rst
View File

@ -132,7 +132,7 @@ module documentation. This section lists the differences between the API and
... # Work with dom.
.. method:: Node.writexml(writer, indent="", addindent="", newl="",
.. method:: Node.writexml(writer, indent="", addindent="", newl="", \
encoding=None, standalone=None)
Write XML to the writer object. The writer receives texts but not bytes as input,
@ -174,7 +174,7 @@ module documentation. This section lists the differences between the API and
The :meth:`toxml` method now preserves the attribute order specified
by the user.
.. method:: Node.toprettyxml(indent="\\t", newl="\\n", encoding=None,
.. method:: Node.toprettyxml(indent="\\t", newl="\\n", encoding=None, \
standalone=None)
Return a pretty-printed version of the document. *indent* specifies the

18
Doc/library/xml.etree.elementtree.rst
View File

@ -455,6 +455,12 @@ Supported XPath syntax
| | has the given value. The value cannot contain |
| | quotes. |
+-----------------------+------------------------------------------------------+
| ``[@attrib!='value']``| Selects all elements for which the given attribute |
| | does not have the given value. The value cannot |
| | contain quotes. |
| | |
| | .. versionadded:: 3.10 |
+-----------------------+------------------------------------------------------+
| ``[tag]`` | Selects all elements that have a child named |
| | ``tag``. Only immediate children are supported. |
+-----------------------+------------------------------------------------------+
@ -463,10 +469,22 @@ Supported XPath syntax
| | |
| | .. versionadded:: 3.7 |
+-----------------------+------------------------------------------------------+
| ``[.!='text']`` | Selects all elements whose complete text content, |
| | including descendants, does not equal the given |
| | ``text``. |
| | |
| | .. versionadded:: 3.10 |
+-----------------------+------------------------------------------------------+
| ``[tag='text']`` | Selects all elements that have a child named |
| | ``tag`` whose complete text content, including |
| | descendants, equals the given ``text``. |
+-----------------------+------------------------------------------------------+
| ``[tag!='text']`` | Selects all elements that have a child named |
| | ``tag`` whose complete text content, including |
| | descendants, does not equal the given ``text``. |
| | |
| | .. versionadded:: 3.10 |
+-----------------------+------------------------------------------------------+
| ``[position]`` | Selects all elements that are located at the given |
| | position. The position can be either an integer |
| | (1 is the first position), the expression ``last()`` |

46
Doc/library/zipimport.rst
View File

@ -44,8 +44,9 @@ doesn't contain :file:`.pyc` files, importing may be rather slow.
follows the specification in :pep:`273`, but uses an implementation written by Just
van Rossum that uses the import hooks described in :pep:`302`.
:pep:`302` - New Import Hooks
The PEP to add the import hooks that help this module work.
:mod:`importlib` - The implementation of the import machinery
Package providing the relevant protocols for all importers to
implement.
This module defines an exception:
@ -73,7 +74,31 @@ zipimporter Objects
:exc:`ZipImportError` is raised if *archivepath* doesn't point to a valid ZIP
archive.
.. method:: find_module(fullname[, path])
.. method:: create_module(spec)
Implementation of :meth:`importlib.abc.Loader.create_module` that returns
:const:`None` to explicitly request the default semantics.
.. versionadded:: 3.10
.. method:: exec_module(module)
Implementation of :meth:`importlib.abc.Loader.exec_module`.
.. versionadded:: 3.10
.. method:: find_loader(fullname, path=None)
An implementation of :meth:`importlib.abc.PathEntryFinder.find_loader`.
.. deprecated:: 3.10
Use :meth:`find_spec` instead.
.. method:: find_module(fullname, path=None)
Search for a module specified by *fullname*. *fullname* must be the fully
qualified (dotted) module name. It returns the zipimporter instance itself
@ -81,6 +106,17 @@ zipimporter Objects
*path* argument is ignored---it's there for compatibility with the
importer protocol.
.. deprecated:: 3.10
Use :meth:`find_spec` instead.
.. method:: find_spec(fullname, target=None)
An implementation of :meth:`importlib.abc.PathEntryFinder.find_spec`.
.. versionadded:: 3.10
.. method:: get_code(fullname)
@ -126,6 +162,10 @@ zipimporter Objects
qualified (dotted) module name. It returns the imported module, or raises
:exc:`ZipImportError` if it wasn't found.
.. deprecated:: 3.10
Use :meth:`exec_module` instead.
.. attribute:: archive

52
Doc/reference/datamodel.rst
View File

@ -187,6 +187,24 @@ Ellipsis
related to mathematical numbers, but subject to the limitations of numerical
representation in computers.
The string representations of the numeric classes, computed by
:meth:`__repr__` and :meth:`__str__`, have the following
properties:
* They are valid numeric literals which, when passed to their
class constructor, produce an object having the value of the
original numeric.
* The representation is in base 10, when possible.
* Leading zeros, possibly excepting a single zero before a
decimal point, are not shown.
* Trailing zeros, possibly excepting a single zero after a
decimal point, are not shown.
* A sign is shown only when the number is negative.
Python distinguishes between integers, floating point numbers, and complex
numbers:
@ -1377,12 +1395,14 @@ Basic customization
context (e.g., in the condition of an ``if`` statement), Python will call
:func:`bool` on the value to determine if the result is true or false.
By default, :meth:`__ne__` delegates to :meth:`__eq__` and
inverts the result unless it is ``NotImplemented``. There are no other
implied relationships among the comparison operators, for example,
the truth of ``(x<y or x==y)`` does not imply ``x<=y``.
To automatically generate ordering operations from a single root operation,
see :func:`functools.total_ordering`.
By default, ``object`` implements :meth:`__eq__` by using ``is``, returning
``NotImplemented`` in the case of a false comparison:
``True if x is y else NotImplemented``. For :meth:`__ne__`, by default it
delegates to :meth:`__eq__` and inverts the result unless it is
``NotImplemented``. There are no other implied relationships among the
comparison operators or default implementations; for example, the truth of
``(x<y or x==y)`` does not imply ``x<=y``. To automatically generate ordering
operations from a single root operation, see :func:`functools.total_ordering`.
See the paragraph on :meth:`__hash__` for
some important notes on creating :term:`hashable` objects which support
@ -1540,6 +1560,12 @@ access (use of, assignment to, or deletion of ``x.name``) for class instances.
result of implicit invocation via language syntax or built-in functions.
See :ref:`special-lookup`.
.. audit-event:: object.__getattr__ obj,name object.__getattribute__
For certain sensitive attribute accesses, raises an
:ref:`auditing event <auditing>` ``object.__getattr__`` with arguments
``obj`` and ``name``.
.. method:: object.__setattr__(self, name, value)
@ -1551,12 +1577,24 @@ access (use of, assignment to, or deletion of ``x.name``) for class instances.
call the base class method with the same name, for example,
``object.__setattr__(self, name, value)``.
.. audit-event:: object.__setattr__ obj,name,value object.__setattr__
For certain sensitive attribute assignments, raises an
:ref:`auditing event <auditing>` ``object.__setattr__`` with arguments
``obj``, ``name``, ``value``.
.. method:: object.__delattr__(self, name)
Like :meth:`__setattr__` but for attribute deletion instead of assignment. This
should only be implemented if ``del obj.name`` is meaningful for the object.
.. audit-event:: object.__delattr__ obj,name object.__delattr__
For certain sensitive attribute deletions, raises an
:ref:`auditing event <auditing>` ``object.__delattr__`` with arguments
``obj`` and ``name``.
.. method:: object.__dir__(self)
@ -2130,7 +2168,7 @@ Emulating callable objects
.. index:: pair: call; instance
Called when the instance is "called" as a function; if this method is defined,
``x(arg1, arg2, ...)`` is a shorthand for ``x.__call__(arg1, arg2, ...)``.
``x(arg1, arg2, ...)`` roughly translates to ``type(x).__call__(x, arg1, ...)``.
.. _sequence-types:

29
Doc/reference/expressions.rst
View File

@ -162,6 +162,8 @@ ambiguities and allow common typos to pass uncaught.
Displays for lists, sets and dictionaries
-----------------------------------------
.. index:: single: comprehensions
For constructing a list, a set or a dictionary Python provides special syntax
called "displays", each of them in two flavors:
@ -260,6 +262,7 @@ Set displays
.. index::
pair: set; display
pair: set; comprehensions
object: set
single: {} (curly brackets); set expression
single: , (comma); expression list
@ -287,6 +290,7 @@ Dictionary displays
.. index::
pair: dictionary; display
pair: dictionary; comprehensions
key, datum, key/datum pair
object: dictionary
single: {} (curly brackets); dictionary expression
@ -639,6 +643,16 @@ after resuming depends on the method which resumed the execution. If
:meth:`~agen.asend` is used, then the result will be the value passed in to
that method.
If an asynchronous generator happens to exit early by :keyword:`break`, the caller
task being cancelled, or other exceptions, the generator's async cleanup code
will run and possibly raise exceptions or access context variables in an
unexpected context--perhaps after the lifetime of tasks it depends, or
during the event loop shutdown when the async-generator garbage collection hook
is called.
To prevent this, the caller must explicitly close the async generator by calling
:meth:`~agen.aclose` method to finalize the generator and ultimately detach it
from the event loop.
In an asynchronous generator function, yield expressions are allowed anywhere
in a :keyword:`try` construct. However, if an asynchronous generator is not
resumed before it is finalized (by reaching a zero reference count or by
@ -650,9 +664,9 @@ generator-iterator's :meth:`~agen.aclose` method and run the resulting
coroutine object, thus allowing any pending :keyword:`!finally` clauses
to execute.
To take care of finalization, an event loop should define
a *finalizer* function which takes an asynchronous generator-iterator
and presumably calls :meth:`~agen.aclose` and executes the coroutine.
To take care of finalization upon event loop termination, an event loop should
define a *finalizer* function which takes an asynchronous generator-iterator and
presumably calls :meth:`~agen.aclose` and executes the coroutine.
This *finalizer* may be registered by calling :func:`sys.set_asyncgen_hooks`.
When first iterated over, an asynchronous generator-iterator will store the
registered *finalizer* to be called upon finalization. For a reference example
@ -796,8 +810,8 @@ Subscriptions
object: dictionary
pair: sequence; item
A subscription selects an item of a sequence (string, tuple or list) or mapping
(dictionary) object:
Subscription of a sequence (string, tuple or list) or mapping (dictionary)
object usually selects an item from the collection:
.. productionlist:: python-grammar
subscription: `primary` "[" `expression_list` "]"
@ -833,6 +847,11 @@ this method will need to explicitly add that support.
A string's items are characters. A character is not a separate data type but a
string of exactly one character.
Subscription of certain :term:`classes <class>` or :term:`types <type>`
creates a :ref:`generic alias <types-genericalias>`.
In this case, user-defined classes can support subscription by providing a
:meth:`__class_getitem__` classmethod.
.. _slicings:

20
Doc/reference/import.rst
View File

@ -680,7 +680,7 @@ Here are the exact rules used:
Cached bytecode invalidation
----------------------------
Before Python loads cached bytecode from ``.pyc`` file, it checks whether the
Before Python loads cached bytecode from a ``.pyc`` file, it checks whether the
cache is up-to-date with the source ``.py`` file. By default, Python does this
by storing the source's last-modified timestamp and size in the cache file when
writing it. At runtime, the import system then validates the cache file by
@ -857,9 +857,8 @@ module. ``find_spec()`` returns a fully populated spec for the module.
This spec will always have "loader" set (with one exception).
To indicate to the import machinery that the spec represents a namespace
:term:`portion`, the path entry finder sets "loader" on the spec to
``None`` and "submodule_search_locations" to a list containing the
portion.
:term:`portion`, the path entry finder sets "submodule_search_locations" to
a list containing the portion.
.. versionchanged:: 3.4
:meth:`~importlib.abc.PathEntryFinder.find_spec` replaced
@ -875,18 +874,7 @@ portion.
:meth:`~importlib.abc.PathEntryFinder.find_loader` takes one argument, the
fully qualified name of the module being imported. ``find_loader()``
returns a 2-tuple where the first item is the loader and the second item
is a namespace :term:`portion`. When the first item (i.e. the loader) is
``None``, this means that while the path entry finder does not have a
loader for the named module, it knows that the path entry contributes to
a namespace portion for the named module. This will almost always be the
case where Python is asked to import a namespace package that has no
physical presence on the file system. When a path entry finder returns
``None`` for the loader, the second item of the 2-tuple return value must
be a sequence, although it can be empty.
If ``find_loader()`` returns a non-``None`` loader value, the portion is
ignored and the loader is returned from the path based finder, terminating
the search through the path entries.
is a namespace :term:`portion`.
For backwards compatibility with other implementations of the import
protocol, many path entry finders also support the same,

4
Doc/reference/simple_stmts.rst
View File

@ -874,8 +874,8 @@ can appear before a future statement are:
* blank lines, and
* other future statements.
The only feature in Python 3.7 that requires using the future statement is
``annotations``.
The only feature that requires using the future statement is
``annotations`` (see :pep:`563`).
All historical features enabled by the future statement are still recognized
by Python 3. The list includes ``absolute_import``, ``division``,

4
Doc/tools/extensions/c_annotations.py
View File

@ -79,9 +79,9 @@ class Annotations(dict):
classes=['stableabi']))
if par['objtype'] != 'function':
continue
if not par[0].has_key('names') or not par[0]['names']:
if not par[0].has_key('ids') or not par[0]['ids']:
continue
name = par[0]['names'][0]
name = par[0]['ids'][0]
if name.startswith("c."):
name = name[2:]
entry = self.get(name)

157
Doc/tools/static/switchers.js
View File

@ -1,157 +0,0 @@
(function() {
'use strict';
// Parses versions in URL segments like:
// "3", "dev", "release/2.7" or "3.6rc2"
var version_regexs = [
'(?:\\d)',
'(?:\\d\\.\\d[\\w\\d\\.]*)',
'(?:dev)',
'(?:release/\\d.\\d[\\x\\d\\.]*)'];
var all_versions = {
'3.10': 'dev (3.10)',
'3.9': 'pre (3.9)',
'3.8': '3.8',
'3.7': '3.7',
'3.6': '3.6',
'3.5': '3.5',
'2.7': '2.7',
};
var all_languages = {
'en': 'English',
'fr': 'French',
'ja': 'Japanese',
'ko': 'Korean',
'pt-br': 'Brazilian Portuguese',
'zh-cn': 'Simplified Chinese',
};
function build_version_select(current_version, current_release) {
var buf = ['<select>'];
$.each(all_versions, function(version, title) {
buf.push('<option value="' + version + '"');
if (version == current_version)
buf.push(' selected="selected">' + current_release + '</option>');
else
buf.push('>' + title + '</option>');
});
buf.push('</select>');
return buf.join('');
}
function build_language_select(current_language) {
var buf = ['<select>'];
$.each(all_languages, function(language, title) {
if (language == current_language)
buf.push('<option value="' + language + '" selected="selected">' +
all_languages[current_language] + '</option>');
else
buf.push('<option value="' + language + '">' + title + '</option>');
});
if (!(current_language in all_languages)) {
// In case we're browsing a language that is not yet in all_languages.
buf.push('<option value="' + current_language + '" selected="selected">' +
current_language + '</option>');
all_languages[current_language] = current_language;
}
buf.push('</select>');
return buf.join('');
}
function navigate_to_first_existing(urls) {
// Navigate to the first existing URL in urls.
var url = urls.shift();
if (urls.length == 0) {
window.location.href = url;
return;
}
$.ajax({
url: url,
success: function() {
window.location.href = url;
},
error: function() {
navigate_to_first_existing(urls);
}
});
}
function on_version_switch() {
var selected_version = $(this).children('option:selected').attr('value') + '/';
var url = window.location.href;
var current_language = language_segment_from_url(url);
var current_version = version_segment_in_url(url);
var new_url = url.replace('.org/' + current_language + current_version,
'.org/' + current_language + selected_version);
if (new_url != url) {
navigate_to_first_existing([
new_url,
url.replace('.org/' + current_language + current_version,
'.org/' + selected_version),
'https://docs.python.org/' + current_language + selected_version,
'https://docs.python.org/' + selected_version,
'https://docs.python.org/'
]);
}
}
function on_language_switch() {
var selected_language = $(this).children('option:selected').attr('value') + '/';
var url = window.location.href;
var current_language = language_segment_from_url(url);
var current_version = version_segment_in_url(url);
if (selected_language == 'en/') // Special 'default' case for english.
selected_language = '';
var new_url = url.replace('.org/' + current_language + current_version,
'.org/' + selected_language + current_version);
if (new_url != url) {
navigate_to_first_existing([
new_url,
'https://docs.python.org/'
]);
}
}
// Returns the path segment of the language as a string, like 'fr/'
// or '' if not found.
function language_segment_from_url(url) {
var language_regexp = '\.org/([a-z]{2}(?:-[a-z]{2})?/)';
var match = url.match(language_regexp);
if (match !== null)
return match[1];
return '';
}
// Returns the path segment of the version as a string, like '3.6/'
// or '' if not found.
function version_segment_in_url(url) {
var language_segment = '(?:[a-z]{2}(?:-[a-z]{2})?/)';
var version_segment = '(?:(?:' + version_regexs.join('|') + ')/)';
var version_regexp = '\\.org/' + language_segment + '?(' + version_segment + ')';
var match = url.match(version_regexp);
if (match !== null)
return match[1];
return ''
}
$(document).ready(function() {
var release = DOCUMENTATION_OPTIONS.VERSION;
var language_segment = language_segment_from_url(window.location.href);
var current_language = language_segment.replace(/\/+$/g, '') || 'en';
var version = release.substr(0, 3);
var version_select = build_version_select(version, release);
$('.version_switcher_placeholder').html(version_select);
$('.version_switcher_placeholder select').bind('change', on_version_switch);
var language_select = build_language_select(current_language);
$('.language_switcher_placeholder').html(language_select);
$('.language_switcher_placeholder select').bind('change', on_language_switch);
});
})();

14
Doc/tools/susp-ignored.csv
View File

@ -5,14 +5,13 @@ c-api/sequence,,:i2,o[i1:i2]
c-api/tuple,,:high,p[low:high]
c-api/unicode,,:end,str[start:end]
c-api/unicode,,:start,unicode[start:start+length]
distutils/examples,267,`,This is the description of the ``foobar`` package.
distutils/examples,,`,This is the description of the ``foobar`` package.
distutils/setupscript,,::,
extending/embedding,,:numargs,"if(!PyArg_ParseTuple(args, "":numargs""))"
extending/extending,,:myfunction,"PyArg_ParseTuple(args, ""D:myfunction"", &c);"
extending/extending,,:set,"if (PyArg_ParseTuple(args, ""O:set_callback"", &temp)) {"
extending/newtypes,,:call,"if (!PyArg_ParseTuple(args, ""sss:call"", &arg1, &arg2, &arg3)) {"
faq/programming,,:chr,">=4.0) or 1+f(xc,yc,x*x-y*y+xc,2.0*x*y+yc,k-1,f):f(xc,yc,x,y,k,f):chr("
faq/programming,,::,for x in sequence[::-1]:
faq/programming,,:reduce,"print((lambda Ru,Ro,Iu,Io,IM,Sx,Sy:reduce(lambda x,y:x+y,map(lambda y,"
faq/programming,,:reduce,"Sx=Sx,Sy=Sy:reduce(lambda x,y:x+y,map(lambda x,xc=Ru,yc=yc,Ru=Ru,Ro=Ro,"
faq/windows,,:d48eceb,"Python 3.6.4 (v3.6.4:d48eceb, Dec 19 2017, 06:04:45) [MSC v.1900 32 bit (Intel)] on win32"
@ -24,6 +23,9 @@ howto/curses,,:blue,"2:green, 3:yellow, 4:blue, 5:magenta, 6:cyan, and 7:white.
howto/curses,,:magenta,"2:green, 3:yellow, 4:blue, 5:magenta, 6:cyan, and 7:white. The"
howto/curses,,:cyan,"2:green, 3:yellow, 4:blue, 5:magenta, 6:cyan, and 7:white. The"
howto/curses,,:white,"2:green, 3:yellow, 4:blue, 5:magenta, 6:cyan, and 7:white. The"
howto/descriptor,,:root,"INFO:root"
howto/descriptor,,:Updating,"root:Updating"
howto/descriptor,,:Accessing,"root:Accessing"
howto/instrumentation,,::,python$target:::function-entry
howto/instrumentation,,:function,python$target:::function-entry
howto/instrumentation,,::,python$target:::function-return
@ -111,8 +113,6 @@ howto/urllib2,,:password,"""joe:password@example.com"""
library/ast,,:upper,lower:upper
library/ast,,:step,lower:upper:step
library/audioop,,:ipos,"# factor = audioop.findfactor(in_test[ipos*2:ipos*2+len(out_test)],"
library/bisect,32,:hi,all(val >= x for val in a[i:hi])
library/bisect,42,:hi,all(val > x for val in a[i:hi])
library/configparser,,:home,my_dir: ${Common:home_dir}/twosheds
library/configparser,,:option,${section:option}
library/configparser,,:path,python_dir: ${Frameworks:path}/Python/Versions/${Frameworks:Python}
@ -147,8 +147,10 @@ library/ipaddress,,:db8,IPv6Address('2001:db8::')
library/ipaddress,,::,IPv6Address('2001:db8::')
library/ipaddress,,:db8,>>> ipaddress.IPv6Address('2001:db8::1000')
library/ipaddress,,::,>>> ipaddress.IPv6Address('2001:db8::1000')
library/ipaddress,,:db8,IPv6Address('2001:db8::1000')
library/ipaddress,,::,IPv6Address('2001:db8::1000')
library/ipaddress,,:db8,'2001:db8::1000'
library/ipaddress,,::,'2001:db8::1000'
library/ipaddress,231,:db8,">>> f'{ipaddress.IPv6Address(""2001:db8::1000""):s}'"
library/ipaddress,231,::,">>> f'{ipaddress.IPv6Address(""2001:db8::1000""):s}'"
library/ipaddress,,::,IPv6Address('ff02::5678%1')
library/ipaddress,,::,fe80::1234
library/ipaddress,,:db8,">>> ipaddress.ip_address(""2001:db8::1"").reverse_pointer"

1 c-api/arg :ref PyArg_ParseTuple(args, "O|O:ref", &object, &callback)
5 c-api/tuple :high p[low:high]
6 c-api/unicode :end str[start:end]
7 c-api/unicode :start unicode[start:start+length]
8 distutils/examples 267 ` This is the description of the ``foobar`` package.
9 distutils/setupscript ::
10 extending/embedding :numargs if(!PyArg_ParseTuple(args, ":numargs"))
11 extending/extending :myfunction PyArg_ParseTuple(args, "D:myfunction", &c);
12 extending/extending :set if (PyArg_ParseTuple(args, "O:set_callback", &temp)) {
13 extending/newtypes :call if (!PyArg_ParseTuple(args, "sss:call", &arg1, &arg2, &arg3)) {
14 faq/programming :chr >=4.0) or 1+f(xc,yc,x*x-y*y+xc,2.0*x*y+yc,k-1,f):f(xc,yc,x,y,k,f):chr(
faq/programming :: for x in sequence[::-1]:
15 faq/programming :reduce print((lambda Ru,Ro,Iu,Io,IM,Sx,Sy:reduce(lambda x,y:x+y,map(lambda y,
16 faq/programming :reduce Sx=Sx,Sy=Sy:reduce(lambda x,y:x+y,map(lambda x,xc=Ru,yc=yc,Ru=Ru,Ro=Ro,
17 faq/windows :d48eceb Python 3.6.4 (v3.6.4:d48eceb, Dec 19 2017, 06:04:45) [MSC v.1900 32 bit (Intel)] on win32
23 howto/curses :magenta 2:green, 3:yellow, 4:blue, 5:magenta, 6:cyan, and 7:white. The
24 howto/curses :cyan 2:green, 3:yellow, 4:blue, 5:magenta, 6:cyan, and 7:white. The
25 howto/curses :white 2:green, 3:yellow, 4:blue, 5:magenta, 6:cyan, and 7:white. The
26 howto/descriptor :root INFO:root
27 howto/descriptor :Updating root:Updating
28 howto/descriptor :Accessing root:Accessing
29 howto/instrumentation :: python$target:::function-entry
30 howto/instrumentation :function python$target:::function-entry
31 howto/instrumentation :: python$target:::function-return
113 library/ast :upper lower:upper
114 library/ast :step lower:upper:step
115 library/audioop :ipos # factor = audioop.findfactor(in_test[ipos*2:ipos*2+len(out_test)],
library/bisect 32 :hi all(val >= x for val in a[i:hi])
library/bisect 42 :hi all(val > x for val in a[i:hi])
116 library/configparser :home my_dir: ${Common:home_dir}/twosheds
117 library/configparser :option ${section:option}
118 library/configparser :path python_dir: ${Frameworks:path}/Python/Versions/${Frameworks:Python}
147 library/ipaddress :: IPv6Address('2001:db8::')
148 library/ipaddress :db8 >>> ipaddress.IPv6Address('2001:db8::1000')
149 library/ipaddress :: >>> ipaddress.IPv6Address('2001:db8::1000')
150 library/ipaddress :db8 IPv6Address('2001:db8::1000') '2001:db8::1000'
151 library/ipaddress :: IPv6Address('2001:db8::1000') '2001:db8::1000'
152 library/ipaddress 231 :db8 >>> f'{ipaddress.IPv6Address("2001:db8::1000"):s}'
153 library/ipaddress 231 :: >>> f'{ipaddress.IPv6Address("2001:db8::1000"):s}'
154 library/ipaddress :: IPv6Address('ff02::5678%1')
155 library/ipaddress :: fe80::1234
156 library/ipaddress :db8 >>> ipaddress.ip_address("2001:db8::1").reverse_pointer

9
Doc/tools/templates/dummy.html
View File

@ -6,3 +6,12 @@ In extensions/pyspecific.py:
{% trans %}CPython implementation detail:{% endtrans %}
{% trans %}Deprecated since version {deprecated}, will be removed in version {removed}{% endtrans %}
{% trans %}Deprecated since version {deprecated}, removed in version {removed}{% endtrans %}
In docsbuild-scripts, when rewriting indexsidebar.html with actual versions:
{% trans %}in development{% endtrans %}
{% trans %}pre-release{% endtrans %}
{% trans %}stable{% endtrans %}
{% trans %}security-fixes{% endtrans %}
{% trans %}EOL{% endtrans %}

9
Doc/tools/templates/indexsidebar.html
View File

@ -2,13 +2,8 @@
<p><a href="{{ pathto('download') }}">{% trans %}Download these documents{% endtrans %}</a></p>
<h3>{% trans %}Docs by version{% endtrans %}</h3>
<ul>
<li><a href="https://docs.python.org/3.10/">{% trans %}Python 3.10 (in development){% endtrans %}</a></li>
<li><a href="https://docs.python.org/3.9/">{% trans %}Python 3.9 (pre-release){% endtrans %}</a></li>
<li><a href="https://docs.python.org/3.8/">{% trans %}Python 3.8 (stable){% endtrans %}</a></li>
<li><a href="https://docs.python.org/3.7/">{% trans %}Python 3.7 (stable){% endtrans %}</a></li>
<li><a href="https://docs.python.org/3.6/">{% trans %}Python 3.6 (security-fixes){% endtrans %}</a></li>
<li><a href="https://docs.python.org/3.5/">{% trans %}Python 3.5 (security-fixes){% endtrans %}</a></li>
<li><a href="https://docs.python.org/2.7/">{% trans %}Python 2.7 (EOL){% endtrans %}</a></li>
<li><a href="https://docs.python.org/">{% trans %}Stable{% endtrans %}</a></li>
<li><a href="https://docs.python.org/dev/">{% trans %}In development{% endtrans %}</a></li>
<li><a href="https://www.python.org/doc/versions/">{% trans %}All versions{% endtrans %}</a></li>
</ul>

10
Doc/tools/templates/layout.html
View File

@ -12,22 +12,14 @@
{% block rootrellink %}
{{ super() }}
<li>
{%- if switchers is defined %}
<span class="language_switcher_placeholder">{{ language or 'en' }}</span>
<span class="version_switcher_placeholder">{{ release }}</span>
<a href="{{ pathto('index') }}">{% trans %}Documentation {% endtrans %}</a>{{ reldelim1 }}
{%- else %}
<li id="cpython-language-and-version">
<a href="{{ pathto('index') }}">{{ shorttitle }}</a>{{ reldelim1 }}
{%- endif %}
</li>
{% endblock %}
{% block extrahead %}
<link rel="canonical" href="https://docs.python.org/3/{{pagename}}.html" />
{% if builder != "htmlhelp" %}
{% if switchers is defined and not embedded %}
<script type="text/javascript" src="{{ pathto('_static/switchers.js', 1) }}"></script>{% endif %}
{% if pagename == 'whatsnew/changelog' and not embedded %}
<script type="text/javascript" src="{{ pathto('_static/changelog_search.js', 1) }}"></script>{% endif %}
{% endif %}

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