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

Merge branch 'master' into revert-23107-revert-13893-fix-issue-37193

This commit is contained in:
Jason R. Coombs 2020-12-27 12:46:59 -05:00
parent ec8e6895a3 bf64d9064a
commit a78f0158a2
811 changed files with 38188 additions and 20257 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:

6
.azure-pipelines/docs-steps.yml
View File

@ -12,11 +12,11 @@ steps:
inputs:
versionSpec: '>=3.6'
- script: python -m pip install sphinx==2.2.0 blurb python-docs-theme
- script: python -m pip install sphinx==3.2.1 blurb python-docs-theme
displayName: 'Install build dependencies'
- ${{ if ne(parameters.latex, 'true') }}:
- script: make check suspicious html PYTHON=python
- script: make check html PYTHON=python
workingDirectory: '$(build.sourcesDirectory)/Doc'
displayName: 'Build documentation'
@ -31,7 +31,7 @@ steps:
- ${{ if eq(parameters.upload, 'true') }}:
- task: PublishBuildArtifacts@1
displayName: 'Publish docs'
inputs:
PathToPublish: '$(build.sourcesDirectory)/Doc/build'
ArtifactName: docs

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

7
.github/CODEOWNERS vendored
View File

@ -19,6 +19,7 @@ Objects/frameobject.c @markshannon
Objects/call.c @markshannon
Python/ceval.c @markshannon
Python/compile.c @markshannon
Python/ast_opt.c @isidentical
# Hashing
**/*hashlib* @python/crypto-team @tiran
@ -84,6 +85,12 @@ Include/pytime.h @pganssle @abalkin
/Lib/test/test_peg_generator/ @pablogsal @lysnikolaou
/Grammar/python.gram @pablogsal @lysnikolaou
# AST
Python/ast.c @isidentical
Parser/asdl.py @isidentical
Parser/asdl_c.py @isidentical
Lib/ast.py @isidentical
# SQLite 3
**/*sqlite* @berkerpeksag

4
.github/dependabot.yml vendored
View File

@ -7,3 +7,7 @@ updates:
labels:
- "skip issue"
- "skip news"
target_branch:
- "master"
- "3.9"
- "3.8"

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

@ -47,6 +47,37 @@ 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: |
# Build Python with the libpython dynamic library
./configure --with-pydebug --enable-shared
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
- name: Check limited ABI symbols
run: make check-limited-abi
build_win32:
name: 'Windows (x86)'
runs-on: windows-latest
@ -59,7 +90,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 +104,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 +137,7 @@ jobs:
run: sudo ./.github/workflows/posix-deps-apt.sh
- name: 'Restore OpenSSL build'
id: cache-openssl
uses: actions/cache@v2.1.2
uses: actions/cache@v2.1.3
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@v2.1.2
uses: actions/cache@v2.1.3
with:
path: ./multissl/openssl/${{ env.OPENSSL_VER }}
key: ${{ runner.os }}-multissl-openssl-${{ env.OPENSSL_VER }}

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

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

19
.github/workflows/stale.yml vendored Normal file
View File

@ -0,0 +1,19 @@
name: Mark stale pull requests
on:
schedule:
- cron: "0 0 * * *"
jobs:
stale:
runs-on: ubuntu-latest
steps:
- uses: actions/stale@v3
with:
repo-token: ${{ secrets.GITHUB_TOKEN }}
stale-pr-message: 'This PR is stale because it has been open for 30 days with no activity.'
stale-pr-label: 'stale'
days-before-stale: 30
days-before-close: -1

4
.travis.yml
View File

@ -53,7 +53,7 @@ matrix:
- cd Doc
- make venv PYTHON=python
script:
- make check suspicious html SPHINXOPTS="-q -W -j4"
- make check html SPHINXOPTS="-q -W -j4"
- name: "Documentation tests"
os: linux
language: c
@ -192,6 +192,8 @@ script:
- if [[ "$TRAVIS_OS_NAME" == "linux" ]]; then ./python Tools/scripts/patchcheck.py --travis $TRAVIS_PULL_REQUEST; fi
# Check that all symbols exported by libpython start with "Py" or "_Py"
- make smelly
# Check that all symbols in the limited abi are present
- make check-limited-abi
# `-r -w` implicitly provided through `make buildbottest`.
- |
if [[ "$TRAVIS_OS_NAME" == "linux" ]]; then

6
Doc/Makefile
View File

@ -202,6 +202,7 @@ dist:
check:
$(PYTHON) tools/rstlint.py -i tools -i $(VENVDIR) -i README.rst
$(PYTHON) tools/rstlint.py ../Misc/NEWS.d/next/
serve:
$(PYTHON) ../Tools/scripts/serve.py build/html
@ -215,12 +216,11 @@ serve:
# for development releases: always build
autobuild-dev:
make dist SPHINXOPTS='$(SPHINXOPTS) -Ea -A daily=1 -A switchers=1'
-make suspicious
make dist SPHINXOPTS='$(SPHINXOPTS) -Ea -A daily=1'
# 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

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

@ -376,6 +376,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()
@ -389,6 +395,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()
@ -424,6 +436,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()
@ -437,6 +455,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()
@ -455,8 +479,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 *)
@ -638,6 +668,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:
@ -1077,7 +1113,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`.

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

@ -8,46 +8,24 @@ Python Initialization Configuration
.. versionadded:: 3.8
Structures:
Python can be initialized with :c:func:`Py_InitializeFromConfig` and the
:c:type:`PyConfig` structure. It can be preinitialized with
:c:func:`Py_PreInitialize` and the :c:type:`PyPreConfig` structure.
* :c:type:`PyConfig`
* :c:type:`PyPreConfig`
* :c:type:`PyStatus`
* :c:type:`PyWideStringList`
There are two kinds of configuration:
Functions:
* The :ref:`Python Configuration <init-python-config>` can be used to build a
customized Python which behaves as the regular Python. For example,
environments variables and command line arguments are used to configure
Python.
* :c:func:`PyConfig_Clear`
* :c:func:`PyConfig_InitIsolatedConfig`
* :c:func:`PyConfig_InitPythonConfig`
* :c:func:`PyConfig_Read`
* :c:func:`PyConfig_SetArgv`
* :c:func:`PyConfig_SetBytesArgv`
* :c:func:`PyConfig_SetBytesString`
* :c:func:`PyConfig_SetString`
* :c:func:`PyConfig_SetWideStringList`
* :c:func:`PyPreConfig_InitIsolatedConfig`
* :c:func:`PyPreConfig_InitPythonConfig`
* :c:func:`PyStatus_Error`
* :c:func:`PyStatus_Exception`
* :c:func:`PyStatus_Exit`
* :c:func:`PyStatus_IsError`
* :c:func:`PyStatus_IsExit`
* :c:func:`PyStatus_NoMemory`
* :c:func:`PyStatus_Ok`
* :c:func:`PyWideStringList_Append`
* :c:func:`PyWideStringList_Insert`
* :c:func:`Py_ExitStatusException`
* :c:func:`Py_InitializeFromConfig`
* :c:func:`Py_PreInitialize`
* :c:func:`Py_PreInitializeFromArgs`
* :c:func:`Py_PreInitializeFromBytesArgs`
* :c:func:`Py_RunMain`
* :c:func:`Py_GetArgcArgv`
* The :ref:`Isolated Configuration <init-isolated-conf>` can be used to embed
Python into an application. It isolates Python from the system. For example,
environments variables are ignored, the LC_CTYPE locale is left unchanged and
no signal handler is registred.
The preconfiguration (``PyPreConfig`` type) is stored in
``_PyRuntime.preconfig`` and the configuration (``PyConfig`` type) is stored in
``PyInterpreterState.config``.
The :c:func:`Py_RunMain` function can be used to write a customized Python
program.
See also :ref:`Initialization, Finalization, and Threads <initialization>`.
@ -55,8 +33,47 @@ See also :ref:`Initialization, Finalization, and Threads <initialization>`.
:pep:`587` "Python Initialization Configuration".
Example
=======
Example of customized Python always running in isolated mode::
int main(int argc, char **argv)
{
PyStatus status;
PyConfig config;
PyConfig_InitPythonConfig(&config);
config.isolated = 1;
/* Decode command line arguments.
Implicitly preinitialize Python (in isolated mode). */
status = PyConfig_SetBytesArgv(&config, argc, argv);
if (PyStatus_Exception(status)) {
goto exception;
}
status = Py_InitializeFromConfig(&config);
if (PyStatus_Exception(status)) {
goto exception;
}
PyConfig_Clear(&config);
return Py_RunMain();
exception:
PyConfig_Clear(&config);
if (PyStatus_IsExit(status)) {
return status.exitcode;
}
/* Display the error message and exit the process with
non-zero exit code */
Py_ExitStatusException(status);
}
PyWideStringList
----------------
================
.. c:type:: PyWideStringList
@ -95,7 +112,7 @@ PyWideStringList
List items.
PyStatus
--------
========
.. c:type:: PyStatus
@ -128,6 +145,8 @@ PyStatus
Initialization error with a message.
*err_msg* must not be ``NULL``.
.. c:function:: PyStatus PyStatus_NoMemory(void)
Memory allocation failure (out of memory).
@ -185,7 +204,7 @@ Example::
PyPreConfig
-----------
===========
.. c:type:: PyPreConfig
@ -315,7 +334,7 @@ PyPreConfig
.. _c-preinit:
Preinitialize Python with PyPreConfig
-------------------------------------
=====================================
The preinitialization of Python:
@ -324,12 +343,17 @@ The preinitialization of Python:
* Set the :ref:`Python UTF-8 Mode <utf8-mode>`
(:c:member:`PyPreConfig.utf8_mode`)
The current preconfiguration (``PyPreConfig`` type) is stored in
``_PyRuntime.preconfig``.
Functions to preinitialize Python:
.. c:function:: PyStatus Py_PreInitialize(const PyPreConfig *preconfig)
Preinitialize Python from *preconfig* preconfiguration.
*preconfig* must not be ``NULL``.
.. c:function:: PyStatus Py_PreInitializeFromBytesArgs(const PyPreConfig *preconfig, int argc, char * const *argv)
Preinitialize Python from *preconfig* preconfiguration.
@ -337,6 +361,8 @@ Functions to preinitialize Python:
Parse *argv* command line arguments (bytes strings) if
:c:member:`~PyPreConfig.parse_argv` of *preconfig* is non-zero.
*preconfig* must not be ``NULL``.
.. c:function:: PyStatus Py_PreInitializeFromArgs(const PyPreConfig *preconfig, int argc, wchar_t * const * argv)
Preinitialize Python from *preconfig* preconfiguration.
@ -344,6 +370,8 @@ Functions to preinitialize Python:
Parse *argv* command line arguments (wide strings) if
:c:member:`~PyPreConfig.parse_argv` of *preconfig* is non-zero.
*preconfig* must not be ``NULL``.
The caller is responsible to handle exceptions (error or exit) using
:c:func:`PyStatus_Exception` and :c:func:`Py_ExitStatusException`.
@ -386,7 +414,7 @@ the :ref:`Python UTF-8 Mode <utf8-mode>`::
PyConfig
--------
========
.. c:type:: PyConfig
@ -447,8 +475,20 @@ PyConfig
Fields which are already initialized are left unchanged.
The :c:func:`PyConfig_Read` function only parses
:c:member:`PyConfig.argv` arguments once: :c:member:`PyConfig.parse_argv`
is set to ``2`` after arguments are parsed. Since Python arguments are
strippped from :c:member:`PyConfig.argv`, parsing arguments twice would
parse the application options as Python options.
:ref:`Preinitialize Python <c-preinit>` if needed.
.. versionchanged:: 3.10
The :c:member:`PyConfig.argv` arguments are now only parsed once,
:c:member:`PyConfig.parse_argv` is set to ``2`` after arguments are
parsed, and arguments are only parsed if
:c:member:`PyConfig.parse_argv` equals ``1``.
.. c:function:: void PyConfig_Clear(PyConfig *config)
Release configuration memory.
@ -496,7 +536,7 @@ PyConfig
Default: ``NULL``.
Part of the :ref:`Path Configuration <init-path-config>` output.
Part of the :ref:`Python Path Configuration <init-path-config>` output.
.. c:member:: wchar_t* base_executable
@ -508,7 +548,7 @@ PyConfig
Default: ``NULL``.
Part of the :ref:`Path Configuration <init-path-config>` output.
Part of the :ref:`Python Path Configuration <init-path-config>` output.
.. c:member:: wchar_t* base_prefix
@ -516,7 +556,7 @@ PyConfig
Default: ``NULL``.
Part of the :ref:`Path Configuration <init-path-config>` output.
Part of the :ref:`Python Path Configuration <init-path-config>` output.
.. c:member:: int buffered_stdio
@ -598,7 +638,7 @@ PyConfig
Default: ``NULL``.
Part of the :ref:`Path Configuration <init-path-config>` output.
Part of the :ref:`Python Path Configuration <init-path-config>` output.
.. c:member:: wchar_t* executable
@ -607,7 +647,7 @@ PyConfig
Default: ``NULL``.
Part of the :ref:`Path Configuration <init-path-config>` output.
Part of the :ref:`Python Path Configuration <init-path-config>` output.
.. c:member:: int faulthandler
@ -690,7 +730,7 @@ PyConfig
Default: ``NULL``.
Part of the :ref:`Path Configuration <init-path-config>` input.
Part of the :ref:`Python Path Configuration <init-path-config>` input.
.. c:member:: int import_time
@ -781,7 +821,7 @@ PyConfig
Default: value of the ``PLATLIBDIR`` macro which is set at configure time
by ``--with-platlibdir`` (default: ``"lib"``).
Part of the :ref:`Path Configuration <init-path-config>` input.
Part of the :ref:`Python Path Configuration <init-path-config>` input.
.. versionadded:: 3.9
@ -794,7 +834,7 @@ PyConfig
Default: ``NULL``.
Part of the :ref:`Path Configuration <init-path-config>` input.
Part of the :ref:`Python Path Configuration <init-path-config>` input.
.. c:member:: PyWideStringList module_search_paths
.. c:member:: int module_search_paths_set
@ -802,14 +842,14 @@ PyConfig
Module search paths: :data:`sys.path`.
If :c:member:`~PyConfig.module_search_paths_set` is equal to 0, the
function calculating the :ref:`Path Configuration <init-path-config>`
function calculating the :ref:`Python Path Configuration <init-path-config>`
overrides the :c:member:`~PyConfig.module_search_paths` and sets
:c:member:`~PyConfig.module_search_paths_set` to ``1``.
Default: empty list (``module_search_paths``) and ``0``
(``module_search_paths_set``).
Part of the :ref:`Path Configuration <init-path-config>` output.
Part of the :ref:`Python Path Configuration <init-path-config>` output.
.. c:member:: int optimization_level
@ -831,7 +871,7 @@ PyConfig
If :c:member:`~PyConfig.orig_argv` list is empty and
:c:member:`~PyConfig.argv` is not a list only containing an empty
string, :c:func:`PyConfig_Read()` copies :c:member:`~PyConfig.argv` into
string, :c:func:`PyConfig_Read` copies :c:member:`~PyConfig.argv` into
:c:member:`~PyConfig.orig_argv` before modifying
:c:member:`~PyConfig.argv` (if :c:member:`~PyConfig.parse_argv` is
non-zero).
@ -847,12 +887,22 @@ PyConfig
Parse command line arguments?
If non-zero, parse :c:member:`~PyConfig.argv` the same way the regular
If equals to ``1``, parse :c:member:`~PyConfig.argv` the same way the regular
Python parses :ref:`command line arguments <using-on-cmdline>`, and strip
Python arguments from :c:member:`~PyConfig.argv`.
The :c:func:`PyConfig_Read` function only parses
:c:member:`PyConfig.argv` arguments once: :c:member:`PyConfig.parse_argv`
is set to ``2`` after arguments are parsed. Since Python arguments are
strippped from :c:member:`PyConfig.argv`, parsing arguments twice would
parse the application options as Python options.
Default: ``1`` in Python mode, ``0`` in isolated mode.
.. versionchanged:: 3.10
The :c:member:`PyConfig.argv` arguments are now only parsed if
:c:member:`PyConfig.parse_argv` equals to ``1``.
.. c:member:: int parser_debug
Parser debug mode. If greater than 0, turn on parser debugging output (for expert only, depending
@ -865,7 +915,7 @@ PyConfig
.. c:member:: int pathconfig_warnings
On Unix, if non-zero, calculating the :ref:`Path Configuration
On Unix, if non-zero, calculating the :ref:`Python Path Configuration
<init-path-config>` can log warnings into ``stderr``. If equals to 0,
suppress these warnings.
@ -873,7 +923,7 @@ PyConfig
Default: ``1`` in Python mode, ``0`` in isolated mode.
Part of the :ref:`Path Configuration <init-path-config>` input.
Part of the :ref:`Python Path Configuration <init-path-config>` input.
.. c:member:: wchar_t* prefix
@ -882,7 +932,7 @@ PyConfig
Default: ``NULL``.
Part of the :ref:`Path Configuration <init-path-config>` output.
Part of the :ref:`Python Path Configuration <init-path-config>` output.
.. c:member:: wchar_t* program_name
@ -900,7 +950,7 @@ PyConfig
Default: ``NULL``.
Part of the :ref:`Path Configuration <init-path-config>` input.
Part of the :ref:`Python Path Configuration <init-path-config>` input.
.. c:member:: wchar_t* pycache_prefix
@ -1106,7 +1156,7 @@ the :option:`-X` command line option.
Initialization with PyConfig
----------------------------
============================
Function to initialize Python:
@ -1121,6 +1171,9 @@ If :c:func:`PyImport_FrozenModules`, :c:func:`PyImport_AppendInittab` or
:c:func:`PyImport_ExtendInittab` are used, they must be set or called after
Python preinitialization and before the Python initialization.
The current configuration (``PyConfig`` type) is stored in
``PyInterpreterState.config``.
Example setting the program name::
void init_python(void)
@ -1134,17 +1187,17 @@ Example setting the program name::
status = PyConfig_SetString(&config, &config.program_name,
L"/path/to/my_program");
if (PyStatus_Exception(status)) {
goto fail;
goto exception;
}
status = Py_InitializeFromConfig(&config);
if (PyStatus_Exception(status)) {
goto fail;
goto exception;
}
PyConfig_Clear(&config);
return;
fail:
exception:
PyConfig_Clear(&config);
Py_ExitStatusException(status);
}
@ -1200,7 +1253,7 @@ configuration, and then override some parameters::
.. _init-isolated-conf:
Isolated Configuration
----------------------
======================
:c:func:`PyPreConfig_InitIsolatedConfig` and
:c:func:`PyConfig_InitIsolatedConfig` functions create a configuration to
@ -1213,7 +1266,7 @@ and user site directory. The C standard streams (ex: ``stdout``) and the
LC_CTYPE locale are left unchanged. Signal handlers are not installed.
Configuration files are still used with this configuration. Set the
:ref:`Path Configuration <init-path-config>` ("output fields") to ignore these
:ref:`Python Path Configuration <init-path-config>` ("output fields") to ignore these
configuration files and avoid the function computing the default path
configuration.
@ -1221,7 +1274,7 @@ configuration.
.. _init-python-config:
Python Configuration
--------------------
====================
:c:func:`PyPreConfig_InitPythonConfig` and :c:func:`PyConfig_InitPythonConfig`
functions create a configuration to build a customized Python which behaves as
@ -1235,46 +1288,11 @@ and :ref:`Python UTF-8 Mode <utf8-mode>`
(:pep:`540`) depending on the LC_CTYPE locale, :envvar:`PYTHONUTF8` and
:envvar:`PYTHONCOERCECLOCALE` environment variables.
Example of customized Python always running in isolated mode::
int main(int argc, char **argv)
{
PyStatus status;
PyConfig config;
PyConfig_InitPythonConfig(&config);
config.isolated = 1;
/* Decode command line arguments.
Implicitly preinitialize Python (in isolated mode). */
status = PyConfig_SetBytesArgv(&config, argc, argv);
if (PyStatus_Exception(status)) {
goto fail;
}
status = Py_InitializeFromConfig(&config);
if (PyStatus_Exception(status)) {
goto fail;
}
PyConfig_Clear(&config);
return Py_RunMain();
fail:
PyConfig_Clear(&config);
if (PyStatus_IsExit(status)) {
return status.exitcode;
}
/* Display the error message and exit the process with
non-zero exit code */
Py_ExitStatusException(status);
}
.. _init-path-config:
Path Configuration
------------------
Python Path Configuration
=========================
:c:type:`PyConfig` contains multiple fields for the path configuration:
@ -1354,7 +1372,7 @@ The ``__PYVENV_LAUNCHER__`` environment variable is used to set
Py_RunMain()
------------
============
.. c:function:: int Py_RunMain(void)
@ -1374,7 +1392,7 @@ customized Python always running in isolated mode using
Py_GetArgcArgv()
----------------
================
.. c:function:: void Py_GetArgcArgv(int *argc, wchar_t ***argv)
@ -1384,7 +1402,7 @@ Py_GetArgcArgv()
Multi-Phase Initialization Private Provisional API
--------------------------------------------------
==================================================
This section is a private provisional API introducing multi-phase
initialization, the core feature of the :pep:`432`:

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

102
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.
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``.
Py_INCREF(spam);
if (PyModule_AddObject(module, "spam", spam) < 0) {
Py_DECREF(module);
Py_DECREF(spam);
return 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

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

@ -57,7 +57,7 @@ Tuple Objects
.. c:function:: PyObject* PyTuple_GetItem(PyObject *p, Py_ssize_t pos)
Return the object at position *pos* in the tuple pointed to by *p*. If *pos* is
out of bounds, return ``NULL`` and set an :exc:`IndexError` exception.
negative or out of bounds, return ``NULL`` and set an :exc:`IndexError` exception.
.. c:function:: PyObject* PyTuple_GET_ITEM(PyObject *p, Py_ssize_t pos)

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)

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)

3
Doc/conf.py
View File

@ -15,8 +15,7 @@ sys.path.append(os.path.abspath('includes'))
extensions = ['sphinx.ext.coverage', 'sphinx.ext.doctest',
'pyspecific', 'c_annotations', 'escape4chm',
'asdl_highlight', 'peg_highlight']
'asdl_highlight', 'peg_highlight', 'glossary_search']
doctest_global_setup = '''
try:

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:

780
Doc/data/stable_abi.dat Normal file
View File

@ -0,0 +1,780 @@
# File generated by 'make regen-limited-abi'
# This is NOT an authoritative list of stable ABI symbols
PyArg_Parse
PyArg_ParseTuple
PyArg_ParseTupleAndKeywords
PyArg_UnpackTuple
PyArg_VaParse
PyArg_VaParseTupleAndKeywords
PyArg_ValidateKeywordArguments
PyBaseObject_Type
PyBool_FromLong
PyBool_Type
PyByteArrayIter_Type
PyByteArray_AsString
PyByteArray_Concat
PyByteArray_FromObject
PyByteArray_FromStringAndSize
PyByteArray_Resize
PyByteArray_Size
PyByteArray_Type
PyBytesIter_Type
PyBytes_AsString
PyBytes_AsStringAndSize
PyBytes_Concat
PyBytes_ConcatAndDel
PyBytes_DecodeEscape
PyBytes_FromFormat
PyBytes_FromFormatV
PyBytes_FromObject
PyBytes_FromString
PyBytes_FromStringAndSize
PyBytes_Repr
PyBytes_Size
PyBytes_Type
PyCFunction_Call
PyCFunction_GetFlags
PyCFunction_GetFunction
PyCFunction_GetSelf
PyCFunction_NewEx
PyCFunction_Type
PyCMethod_New
PyCallIter_New
PyCallIter_Type
PyCallable_Check
PyCapsule_GetContext
PyCapsule_GetDestructor
PyCapsule_GetName
PyCapsule_GetPointer
PyCapsule_Import
PyCapsule_IsValid
PyCapsule_New
PyCapsule_SetContext
PyCapsule_SetDestructor
PyCapsule_SetName
PyCapsule_SetPointer
PyCapsule_Type
PyClassMethodDescr_Type
PyCodec_BackslashReplaceErrors
PyCodec_Decode
PyCodec_Decoder
PyCodec_Encode
PyCodec_Encoder
PyCodec_IgnoreErrors
PyCodec_IncrementalDecoder
PyCodec_IncrementalEncoder
PyCodec_KnownEncoding
PyCodec_LookupError
PyCodec_NameReplaceErrors
PyCodec_Register
PyCodec_RegisterError
PyCodec_ReplaceErrors
PyCodec_StreamReader
PyCodec_StreamWriter
PyCodec_StrictErrors
PyCodec_Unregister
PyCodec_XMLCharRefReplaceErrors
PyComplex_FromDoubles
PyComplex_ImagAsDouble
PyComplex_RealAsDouble
PyComplex_Type
PyDescr_NewClassMethod
PyDescr_NewGetSet
PyDescr_NewMember
PyDescr_NewMethod
PyDictItems_Type
PyDictIterItem_Type
PyDictIterKey_Type
PyDictIterValue_Type
PyDictKeys_Type
PyDictProxy_New
PyDictProxy_Type
PyDictRevIterItem_Type
PyDictRevIterKey_Type
PyDictRevIterValue_Type
PyDictValues_Type
PyDict_Clear
PyDict_Contains
PyDict_Copy
PyDict_DelItem
PyDict_DelItemString
PyDict_GetItem
PyDict_GetItemString
PyDict_GetItemWithError
PyDict_Items
PyDict_Keys
PyDict_Merge
PyDict_MergeFromSeq2
PyDict_New
PyDict_Next
PyDict_SetItem
PyDict_SetItemString
PyDict_Size
PyDict_Type
PyDict_Update
PyDict_Values
PyEllipsis_Type
PyEnum_Type
PyErr_BadArgument
PyErr_BadInternalCall
PyErr_CheckSignals
PyErr_Clear
PyErr_Display
PyErr_ExceptionMatches
PyErr_Fetch
PyErr_Format
PyErr_FormatV
PyErr_GetExcInfo
PyErr_GivenExceptionMatches
PyErr_NewException
PyErr_NewExceptionWithDoc
PyErr_NoMemory
PyErr_NormalizeException
PyErr_Occurred
PyErr_Print
PyErr_PrintEx
PyErr_ProgramText
PyErr_ResourceWarning
PyErr_Restore
PyErr_SetExcInfo
PyErr_SetFromErrno
PyErr_SetFromErrnoWithFilename
PyErr_SetFromErrnoWithFilenameObject
PyErr_SetFromErrnoWithFilenameObjects
PyErr_SetImportError
PyErr_SetImportErrorSubclass
PyErr_SetInterrupt
PyErr_SetNone
PyErr_SetObject
PyErr_SetString
PyErr_SyntaxLocation
PyErr_SyntaxLocationEx
PyErr_WarnEx
PyErr_WarnExplicit
PyErr_WarnFormat
PyErr_WriteUnraisable
PyEval_AcquireLock
PyEval_AcquireThread
PyEval_CallFunction
PyEval_CallMethod
PyEval_CallObjectWithKeywords
PyEval_EvalCode
PyEval_EvalCodeEx
PyEval_EvalFrame
PyEval_EvalFrameEx
PyEval_GetBuiltins
PyEval_GetFrame
PyEval_GetFuncDesc
PyEval_GetFuncName
PyEval_GetGlobals
PyEval_GetLocals
PyEval_InitThreads
PyEval_ReleaseLock
PyEval_ReleaseThread
PyEval_RestoreThread
PyEval_SaveThread
PyEval_ThreadsInitialized
PyExc_ArithmeticError
PyExc_AssertionError
PyExc_AttributeError
PyExc_BaseException
PyExc_BlockingIOError
PyExc_BrokenPipeError
PyExc_BufferError
PyExc_BytesWarning
PyExc_ChildProcessError
PyExc_ConnectionAbortedError
PyExc_ConnectionError
PyExc_ConnectionRefusedError
PyExc_ConnectionResetError
PyExc_DeprecationWarning
PyExc_EOFError
PyExc_EnvironmentError
PyExc_Exception
PyExc_FileExistsError
PyExc_FileNotFoundError
PyExc_FloatingPointError
PyExc_FutureWarning
PyExc_GeneratorExit
PyExc_IOError
PyExc_ImportError
PyExc_ImportWarning
PyExc_IndentationError
PyExc_IndexError
PyExc_InterruptedError
PyExc_IsADirectoryError
PyExc_KeyError
PyExc_KeyboardInterrupt
PyExc_LookupError
PyExc_MemoryError
PyExc_ModuleNotFoundError
PyExc_NameError
PyExc_NotADirectoryError
PyExc_NotImplementedError
PyExc_OSError
PyExc_OverflowError
PyExc_PendingDeprecationWarning
PyExc_PermissionError
PyExc_ProcessLookupError
PyExc_RecursionError
PyExc_ReferenceError
PyExc_ResourceWarning
PyExc_RuntimeError
PyExc_RuntimeWarning
PyExc_StopAsyncIteration
PyExc_StopIteration
PyExc_SyntaxError
PyExc_SyntaxWarning
PyExc_SystemError
PyExc_SystemExit
PyExc_TabError
PyExc_TimeoutError
PyExc_TypeError
PyExc_UnboundLocalError
PyExc_UnicodeDecodeError
PyExc_UnicodeEncodeError
PyExc_UnicodeError
PyExc_UnicodeTranslateError
PyExc_UnicodeWarning
PyExc_UserWarning
PyExc_ValueError
PyExc_Warning
PyExc_ZeroDivisionError
PyExceptionClass_Name
PyException_GetCause
PyException_GetContext
PyException_GetTraceback
PyException_SetCause
PyException_SetContext
PyException_SetTraceback
PyFile_FromFd
PyFile_GetLine
PyFile_WriteObject
PyFile_WriteString
PyFilter_Type
PyFloat_AsDouble
PyFloat_FromDouble
PyFloat_FromString
PyFloat_GetInfo
PyFloat_GetMax
PyFloat_GetMin
PyFloat_Type
PyFrame_GetCode
PyFrame_GetLineNumber
PyFrozenSet_New
PyFrozenSet_Type
PyGC_Collect
PyGILState_Ensure
PyGILState_GetThisThreadState
PyGILState_Release
PyGetSetDescr_Type
PyImport_AddModule
PyImport_AddModuleObject
PyImport_AppendInittab
PyImport_ExecCodeModule
PyImport_ExecCodeModuleEx
PyImport_ExecCodeModuleObject
PyImport_ExecCodeModuleWithPathnames
PyImport_GetImporter
PyImport_GetMagicNumber
PyImport_GetMagicTag
PyImport_GetModule
PyImport_GetModuleDict
PyImport_Import
PyImport_ImportFrozenModule
PyImport_ImportFrozenModuleObject
PyImport_ImportModule
PyImport_ImportModuleLevel
PyImport_ImportModuleLevelObject
PyImport_ImportModuleNoBlock
PyImport_ReloadModule
PyIndex_Check
PyInterpreterState_Clear
PyInterpreterState_Delete
PyInterpreterState_Get
PyInterpreterState_GetDict
PyInterpreterState_GetID
PyInterpreterState_New
PyIter_Check
PyIter_Next
PyIter_Send
PyListIter_Type
PyListRevIter_Type
PyList_Append
PyList_AsTuple
PyList_GetItem
PyList_GetSlice
PyList_Insert
PyList_New
PyList_Reverse
PyList_SetItem
PyList_SetSlice
PyList_Size
PyList_Sort
PyList_Type
PyLongRangeIter_Type
PyLong_AsDouble
PyLong_AsLong
PyLong_AsLongAndOverflow
PyLong_AsLongLong
PyLong_AsLongLongAndOverflow
PyLong_AsSize_t
PyLong_AsSsize_t
PyLong_AsUnsignedLong
PyLong_AsUnsignedLongLong
PyLong_AsUnsignedLongLongMask
PyLong_AsUnsignedLongMask
PyLong_AsVoidPtr
PyLong_FromDouble
PyLong_FromLong
PyLong_FromLongLong
PyLong_FromSize_t
PyLong_FromSsize_t
PyLong_FromString
PyLong_FromUnsignedLong
PyLong_FromUnsignedLongLong
PyLong_FromVoidPtr
PyLong_GetInfo
PyLong_Type
PyMap_Type
PyMapping_Check
PyMapping_GetItemString
PyMapping_HasKey
PyMapping_HasKeyString
PyMapping_Items
PyMapping_Keys
PyMapping_Length
PyMapping_SetItemString
PyMapping_Size
PyMapping_Values
PyMarshal_ReadObjectFromString
PyMarshal_WriteLongToFile
PyMarshal_WriteObjectToFile
PyMarshal_WriteObjectToString
PyMem_Free
PyMem_Malloc
PyMem_Realloc
PyMemberDescr_Type
PyMember_GetOne
PyMember_SetOne
PyMemoryView_FromMemory
PyMemoryView_FromObject
PyMemoryView_GetContiguous
PyMemoryView_Type
PyMethodDescr_Type
PyModuleDef_Init
PyModuleDef_Type
PyModule_AddFunctions
PyModule_AddIntConstant
PyModule_AddObject
PyModule_AddObjectRef
PyModule_AddStringConstant
PyModule_AddType
PyModule_Create2
PyModule_ExecDef
PyModule_FromDefAndSpec2
PyModule_GetDef
PyModule_GetDict
PyModule_GetFilename
PyModule_GetFilenameObject
PyModule_GetName
PyModule_GetNameObject
PyModule_GetState
PyModule_New
PyModule_NewObject
PyModule_SetDocString
PyModule_Type
PyNumber_Absolute
PyNumber_Add
PyNumber_And
PyNumber_AsSsize_t
PyNumber_Check
PyNumber_Divmod
PyNumber_Float
PyNumber_FloorDivide
PyNumber_InPlaceAdd
PyNumber_InPlaceAnd
PyNumber_InPlaceFloorDivide
PyNumber_InPlaceLshift
PyNumber_InPlaceMatrixMultiply
PyNumber_InPlaceMultiply
PyNumber_InPlaceOr
PyNumber_InPlacePower
PyNumber_InPlaceRemainder
PyNumber_InPlaceRshift
PyNumber_InPlaceSubtract
PyNumber_InPlaceTrueDivide
PyNumber_InPlaceXor
PyNumber_Index
PyNumber_Invert
PyNumber_Long
PyNumber_Lshift
PyNumber_MatrixMultiply
PyNumber_Multiply
PyNumber_Negative
PyNumber_Or
PyNumber_Positive
PyNumber_Power
PyNumber_Remainder
PyNumber_Rshift
PyNumber_Subtract
PyNumber_ToBase
PyNumber_TrueDivide
PyNumber_Xor
PyOS_AfterFork
PyOS_AfterFork_Child
PyOS_AfterFork_Parent
PyOS_BeforeFork
PyOS_FSPath
PyOS_InterruptOccurred
PyOS_double_to_string
PyOS_getsig
PyOS_mystricmp
PyOS_mystrnicmp
PyOS_setsig
PyOS_snprintf
PyOS_string_to_double
PyOS_strtol
PyOS_strtoul
PyOS_vsnprintf
PyObject_ASCII
PyObject_AsFileDescriptor
PyObject_Bytes
PyObject_Call
PyObject_CallFunction
PyObject_CallFunctionObjArgs
PyObject_CallMethod
PyObject_CallMethodObjArgs
PyObject_CallNoArgs
PyObject_CallObject
PyObject_Calloc
PyObject_ClearWeakRefs
PyObject_DelItem
PyObject_DelItemString
PyObject_Dir
PyObject_Format
PyObject_Free
PyObject_GC_Del
PyObject_GC_IsFinalized
PyObject_GC_IsTracked
PyObject_GC_Track
PyObject_GC_UnTrack
PyObject_GenericGetAttr
PyObject_GenericGetDict
PyObject_GenericSetAttr
PyObject_GenericSetDict
PyObject_GetAttr
PyObject_GetAttrString
PyObject_GetItem
PyObject_GetIter
PyObject_HasAttr
PyObject_HasAttrString
PyObject_Hash
PyObject_HashNotImplemented
PyObject_Init
PyObject_InitVar
PyObject_IsInstance
PyObject_IsSubclass
PyObject_IsTrue
PyObject_Length
PyObject_Malloc
PyObject_Not
PyObject_Realloc
PyObject_Repr
PyObject_RichCompare
PyObject_RichCompareBool
PyObject_SelfIter
PyObject_SetAttr
PyObject_SetAttrString
PyObject_SetItem
PyObject_Size
PyObject_Str
PyObject_Type
PyProperty_Type
PyRangeIter_Type
PyRange_Type
PyReversed_Type
PySeqIter_New
PySeqIter_Type
PySequence_Check
PySequence_Concat
PySequence_Contains
PySequence_Count
PySequence_DelItem
PySequence_DelSlice
PySequence_Fast
PySequence_GetItem
PySequence_GetSlice
PySequence_In
PySequence_InPlaceConcat
PySequence_InPlaceRepeat
PySequence_Index
PySequence_Length
PySequence_List
PySequence_Repeat
PySequence_SetItem
PySequence_SetSlice
PySequence_Size
PySequence_Tuple
PySetIter_Type
PySet_Add
PySet_Clear
PySet_Contains
PySet_Discard
PySet_New
PySet_Pop
PySet_Size
PySet_Type
PySlice_AdjustIndices
PySlice_GetIndices
PySlice_GetIndicesEx
PySlice_New
PySlice_Type
PySlice_Unpack
PyState_AddModule
PyState_FindModule
PyState_RemoveModule
PyStructSequence_GetItem
PyStructSequence_New
PyStructSequence_NewType
PyStructSequence_SetItem
PySuper_Type
PySys_AddWarnOption
PySys_AddWarnOptionUnicode
PySys_AddXOption
PySys_FormatStderr
PySys_FormatStdout
PySys_GetObject
PySys_GetXOptions
PySys_HasWarnOptions
PySys_ResetWarnOptions
PySys_SetArgv
PySys_SetArgvEx
PySys_SetObject
PySys_SetPath
PySys_WriteStderr
PySys_WriteStdout
PyThreadState_Clear
PyThreadState_Delete
PyThreadState_Get
PyThreadState_GetDict
PyThreadState_GetFrame
PyThreadState_GetID
PyThreadState_GetInterpreter
PyThreadState_New
PyThreadState_SetAsyncExc
PyThreadState_Swap
PyThread_GetInfo
PyThread_ReInitTLS
PyThread_acquire_lock
PyThread_acquire_lock_timed
PyThread_allocate_lock
PyThread_create_key
PyThread_delete_key
PyThread_delete_key_value
PyThread_exit_thread
PyThread_free_lock
PyThread_get_key_value
PyThread_get_stacksize
PyThread_get_thread_ident
PyThread_get_thread_native_id
PyThread_init_thread
PyThread_release_lock
PyThread_set_key_value
PyThread_set_stacksize
PyThread_start_new_thread
PyThread_tss_alloc
PyThread_tss_create
PyThread_tss_delete
PyThread_tss_free
PyThread_tss_get
PyThread_tss_is_created
PyThread_tss_set
PyTraceBack_Here
PyTraceBack_Print
PyTraceBack_Type
PyTupleIter_Type
PyTuple_GetItem
PyTuple_GetSlice
PyTuple_New
PyTuple_Pack
PyTuple_SetItem
PyTuple_Size
PyTuple_Type
PyType_ClearCache
PyType_FromModuleAndSpec
PyType_FromSpec
PyType_FromSpecWithBases
PyType_GenericAlloc
PyType_GenericNew
PyType_GetFlags
PyType_GetModule
PyType_GetModuleState
PyType_GetSlot
PyType_IsSubtype
PyType_Modified
PyType_Ready
PyType_Type
PyUnicodeDecodeError_Create
PyUnicodeDecodeError_GetEncoding
PyUnicodeDecodeError_GetEnd
PyUnicodeDecodeError_GetObject
PyUnicodeDecodeError_GetReason
PyUnicodeDecodeError_GetStart
PyUnicodeDecodeError_SetEnd
PyUnicodeDecodeError_SetReason
PyUnicodeDecodeError_SetStart
PyUnicodeEncodeError_GetEncoding
PyUnicodeEncodeError_GetEnd
PyUnicodeEncodeError_GetObject
PyUnicodeEncodeError_GetReason
PyUnicodeEncodeError_GetStart
PyUnicodeEncodeError_SetEnd
PyUnicodeEncodeError_SetReason
PyUnicodeEncodeError_SetStart
PyUnicodeIter_Type
PyUnicodeTranslateError_GetEnd
PyUnicodeTranslateError_GetObject
PyUnicodeTranslateError_GetReason
PyUnicodeTranslateError_GetStart
PyUnicodeTranslateError_SetEnd
PyUnicodeTranslateError_SetReason
PyUnicodeTranslateError_SetStart
PyUnicode_Append
PyUnicode_AppendAndDel
PyUnicode_AsASCIIString
PyUnicode_AsCharmapString
PyUnicode_AsDecodedObject
PyUnicode_AsDecodedUnicode
PyUnicode_AsEncodedObject
PyUnicode_AsEncodedString
PyUnicode_AsEncodedUnicode
PyUnicode_AsLatin1String
PyUnicode_AsRawUnicodeEscapeString
PyUnicode_AsUCS4
PyUnicode_AsUCS4Copy
PyUnicode_AsUTF16String
PyUnicode_AsUTF32String
PyUnicode_AsUTF8AndSize
PyUnicode_AsUTF8String
PyUnicode_AsUnicodeEscapeString
PyUnicode_AsWideChar
PyUnicode_AsWideCharString
PyUnicode_BuildEncodingMap
PyUnicode_Compare
PyUnicode_CompareWithASCIIString
PyUnicode_Concat
PyUnicode_Contains
PyUnicode_Count
PyUnicode_Decode
PyUnicode_DecodeASCII
PyUnicode_DecodeCharmap
PyUnicode_DecodeFSDefault
PyUnicode_DecodeFSDefaultAndSize
PyUnicode_DecodeLatin1
PyUnicode_DecodeLocale
PyUnicode_DecodeLocaleAndSize
PyUnicode_DecodeRawUnicodeEscape
PyUnicode_DecodeUTF16
PyUnicode_DecodeUTF16Stateful
PyUnicode_DecodeUTF32
PyUnicode_DecodeUTF32Stateful
PyUnicode_DecodeUTF7
PyUnicode_DecodeUTF7Stateful
PyUnicode_DecodeUTF8
PyUnicode_DecodeUTF8Stateful
PyUnicode_DecodeUnicodeEscape
PyUnicode_EncodeFSDefault
PyUnicode_EncodeLocale
PyUnicode_FSConverter
PyUnicode_FSDecoder
PyUnicode_Find
PyUnicode_FindChar
PyUnicode_Format
PyUnicode_FromEncodedObject
PyUnicode_FromFormat
PyUnicode_FromFormatV
PyUnicode_FromObject
PyUnicode_FromOrdinal
PyUnicode_FromString
PyUnicode_FromStringAndSize
PyUnicode_FromWideChar
PyUnicode_GetDefaultEncoding
PyUnicode_GetLength
PyUnicode_GetSize
PyUnicode_InternFromString
PyUnicode_InternImmortal
PyUnicode_InternInPlace
PyUnicode_IsIdentifier
PyUnicode_Join
PyUnicode_Partition
PyUnicode_RPartition
PyUnicode_RSplit
PyUnicode_ReadChar
PyUnicode_Replace
PyUnicode_Resize
PyUnicode_RichCompare
PyUnicode_Split
PyUnicode_Splitlines
PyUnicode_Substring
PyUnicode_Tailmatch
PyUnicode_Translate
PyUnicode_Type
PyUnicode_WriteChar
PyWeakref_GetObject
PyWeakref_NewProxy
PyWeakref_NewRef
PyWrapperDescr_Type
PyWrapper_New
PyZip_Type
Py_AddPendingCall
Py_AtExit
Py_BuildValue
Py_BytesMain
Py_CompileString
Py_DecRef
Py_DecodeLocale
Py_EncodeLocale
Py_EndInterpreter
Py_EnterRecursiveCall
Py_Exit
Py_FatalError
Py_FileSystemDefaultEncodeErrors
Py_FileSystemDefaultEncoding
Py_Finalize
Py_FinalizeEx
Py_FrozenMain
Py_GenericAlias
Py_GenericAliasType
Py_GetBuildInfo
Py_GetCompiler
Py_GetCopyright
Py_GetExecPrefix
Py_GetPath
Py_GetPlatform
Py_GetPrefix
Py_GetProgramFullPath
Py_GetProgramName
Py_GetPythonHome
Py_GetRecursionLimit
Py_GetVersion
Py_HasFileSystemDefaultEncoding
Py_IncRef
Py_Initialize
Py_InitializeEx
Py_IsInitialized
Py_LeaveRecursiveCall
Py_Main
Py_MakePendingCalls
Py_NewInterpreter
Py_NewRef
Py_ReprEnter
Py_ReprLeave
Py_SetPath
Py_SetProgramName
Py_SetPythonHome
Py_SetRecursionLimit
Py_SymtableString
Py_UTF8Mode
Py_VaBuildValue
Py_XNewRef

24
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`,
@ -1100,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.

23
Doc/howto/argparse.rst
View File

@ -83,7 +83,7 @@ Following is a result of running the code:
$ python3 prog.py --help
usage: prog.py [-h]
optional arguments:
options:
-h, --help show this help message and exit
$ python3 prog.py --verbose
usage: prog.py [-h]
@ -130,7 +130,7 @@ And running the code:
positional arguments:
echo
optional arguments:
options:
-h, --help show this help message and exit
$ python3 prog.py foo
foo
@ -172,7 +172,7 @@ And we get:
positional arguments:
echo echo the string you use here
optional arguments:
options:
-h, --help show this help message and exit
Now, how about doing something even more useful::
@ -241,7 +241,7 @@ And the output:
$ python3 prog.py --help
usage: prog.py [-h] [--verbosity VERBOSITY]
optional arguments:
options:
-h, --help show this help message and exit
--verbosity VERBOSITY
increase output verbosity
@ -289,7 +289,7 @@ And the output:
$ python3 prog.py --help
usage: prog.py [-h] [--verbose]
optional arguments:
options:
-h, --help show this help message and exit
--verbose increase output verbosity
@ -332,7 +332,7 @@ And here goes:
$ python3 prog.py --help
usage: prog.py [-h] [-v]
optional arguments:
options:
-h, --help show this help message and exit
-v, --verbose increase output verbosity
@ -440,7 +440,7 @@ And the output:
positional arguments:
square display a square of a given number
optional arguments:
options:
-h, --help show this help message and exit
-v {0,1,2}, --verbosity {0,1,2}
increase output verbosity
@ -468,7 +468,8 @@ verbosity argument (check the output of ``python --help``)::
print(answer)
We have introduced another action, "count",
to count the number of occurrences of a specific optional arguments:
to count the number of occurrences of specific options.
.. code-block:: shell-session
@ -489,7 +490,7 @@ to count the number of occurrences of a specific optional arguments:
positional arguments:
square display a square of a given number
optional arguments:
options:
-h, --help show this help message and exit
-v, --verbosity increase output verbosity
$ python3 prog.py 4 -vvv
@ -626,7 +627,7 @@ Output:
x the base
y the exponent
optional arguments:
options:
-h, --help show this help message and exit
-v, --verbosity
$ python3 prog.py 4 2 -v
@ -750,7 +751,7 @@ but not both at the same time:
x the base
y the exponent
optional arguments:
options:
-h, --help show this help message and exit
-v, --verbose
-q, --quiet

655
Doc/howto/descriptor.rst
View File

File diff suppressed because it is too large Load Diff

3
Doc/library/abc.rst
View File

@ -336,6 +336,7 @@ The :mod:`abc` module also provides the following functions:
.. versionadded:: 3.4
.. function:: update_abstractmethods(cls)
A function to recalculate an abstract class's abstraction status. This
function should be called if a class's abstract methods have been
implemented or changed after it was created. Usually, this function should
@ -343,7 +344,7 @@ The :mod:`abc` module also provides the following functions:
Returns *cls*, to allow usage as a class decorator.
If *cls* is not an instance of ABCMeta, does nothing.
If *cls* is not an instance of :class:`ABCMeta`, does nothing.
.. note::

183
Doc/library/argparse.rst
View File

@ -57,7 +57,7 @@ be run at the command line and provides useful help messages:
positional arguments:
N an integer for the accumulator
optional arguments:
options:
-h, --help show this help message and exit
--sum sum the integers (default: find the max)
@ -217,14 +217,14 @@ The help for this program will display ``myprogram.py`` as the program name
$ python myprogram.py --help
usage: myprogram.py [-h] [--foo FOO]
optional arguments:
options:
-h, --help show this help message and exit
--foo FOO foo help
$ cd ..
$ python subdir/myprogram.py --help
usage: myprogram.py [-h] [--foo FOO]
optional arguments:
options:
-h, --help show this help message and exit
--foo FOO foo help
@ -235,7 +235,7 @@ To change this default behavior, another value can be supplied using the
>>> parser.print_help()
usage: myprogram [-h]
optional arguments:
options:
-h, --help show this help message and exit
Note that the program name, whether determined from ``sys.argv[0]`` or from the
@ -249,7 +249,7 @@ specifier.
>>> parser.print_help()
usage: myprogram [-h] [--foo FOO]
optional arguments:
options:
-h, --help show this help message and exit
--foo FOO foo of the myprogram program
@ -269,7 +269,7 @@ arguments it contains::
positional arguments:
bar bar help
optional arguments:
options:
-h, --help show this help message and exit
--foo [FOO] foo help
@ -284,7 +284,7 @@ The default message can be overridden with the ``usage=`` keyword argument::
positional arguments:
bar bar help
optional arguments:
options:
-h, --help show this help message and exit
--foo [FOO] foo help
@ -307,7 +307,7 @@ various arguments::
A foo that bars
optional arguments:
options:
-h, --help show this help message and exit
By default, the description will be line-wrapped so that it fits within the
@ -329,7 +329,7 @@ argument to :class:`ArgumentParser`::
A foo that bars
optional arguments:
options:
-h, --help show this help message and exit
And that's how you'd foo a bar
@ -403,7 +403,7 @@ epilog_ texts in command-line help messages::
this description was indented weird but that is okay
optional arguments:
options:
-h, --help show this help message and exit
likewise for this epilog whose whitespace will be cleaned up and whose words
@ -432,7 +432,7 @@ should not be line-wrapped::
exactly the way
I want it
optional arguments:
options:
-h, --help show this help message and exit
:class:`RawTextHelpFormatter` maintains whitespace for all sorts of help text,
@ -454,7 +454,7 @@ default values to each of the argument help messages::
positional arguments:
bar BAR! (default: [1, 2, 3])
optional arguments:
options:
-h, --help show this help message and exit
--foo FOO FOO! (default: 42)
@ -473,7 +473,7 @@ as the regular formatter does)::
positional arguments:
float
optional arguments:
options:
-h, --help show this help message and exit
--foo int
@ -592,7 +592,7 @@ older arguments with the same option string. To get this behavior, the value
>>> parser.print_help()
usage: PROG [-h] [-f FOO] [--foo FOO]
optional arguments:
options:
-h, --help show this help message and exit
-f FOO old foo help
--foo FOO new foo help
@ -623,7 +623,7 @@ help will be printed:
$ python myprogram.py --help
usage: myprogram.py [-h] [--foo FOO]
optional arguments:
options:
-h, --help show this help message and exit
--foo FOO foo help
@ -636,7 +636,7 @@ This can be achieved by passing ``False`` as the ``add_help=`` argument to
>>> parser.print_help()
usage: PROG [--foo FOO]
optional arguments:
options:
--foo FOO foo help
The help option is typically ``-h/--help``. The exception to this is
@ -649,7 +649,7 @@ the help options::
>>> parser.print_help()
usage: PROG [+h]
optional arguments:
options:
+h, ++help show this help message and exit
@ -696,7 +696,7 @@ The add_argument() method
* const_ - A constant value required by some action_ and nargs_ selections.
* default_ - The value produced if the argument is absent from the
command line.
command line and if it is absent from the namespace object.
* type_ - The type to which the command-line argument should be converted.
@ -1006,6 +1006,14 @@ was not present at the command line::
>>> parser.parse_args([])
Namespace(foo=42)
If the target namespace already has an attribute set, the action *default*
will not over write it::
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', default=42)
>>> parser.parse_args([], namespace=argparse.Namespace(foo=101))
Namespace(foo=101)
If the ``default`` value is a string, the parser parses the value as if it
were a command-line argument. In particular, the parser applies any type_
conversion argument, if provided, before setting the attribute on the
@ -1042,63 +1050,70 @@ command-line argument was not present::
type
^^^^
By default, :class:`ArgumentParser` objects read command-line arguments in as simple
By default, the parser reads command-line arguments in as simple
strings. However, quite often the command-line string should instead be
interpreted as another type, like a :class:`float` or :class:`int`. The
``type`` keyword argument of :meth:`~ArgumentParser.add_argument` allows any
necessary type-checking and type conversions to be performed. Common built-in
types and functions can be used directly as the value of the ``type`` argument::
interpreted as another type, such as a :class:`float` or :class:`int`. The
``type`` keyword for :meth:`~ArgumentParser.add_argument` allows any
necessary type-checking and type conversions to be performed.
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('foo', type=int)
>>> parser.add_argument('bar', type=open)
>>> parser.parse_args('2 temp.txt'.split())
Namespace(bar=<_io.TextIOWrapper name='temp.txt' encoding='UTF-8'>, foo=2)
If the type_ keyword is used with the default_ keyword, the type converter
is only applied if the default is a string.
See the section on the default_ keyword argument for information on when the
``type`` argument is applied to default arguments.
The argument to ``type`` can be any callable that accepts a single string.
If the function raises :exc:`ArgumentTypeError`, :exc:`TypeError`, or
:exc:`ValueError`, the exception is caught and a nicely formatted error
message is displayed. No other exception types are handled.
To ease the use of various types of files, the argparse module provides the
factory FileType which takes the ``mode=``, ``bufsize=``, ``encoding=`` and
``errors=`` arguments of the :func:`open` function. For example,
``FileType('w')`` can be used to create a writable file::
Common built-in types and functions can be used as type converters:
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('bar', type=argparse.FileType('w'))
>>> parser.parse_args(['out.txt'])
Namespace(bar=<_io.TextIOWrapper name='out.txt' encoding='UTF-8'>)
.. testcode::
``type=`` can take any callable that takes a single string argument and returns
the converted value::
import argparse
import pathlib
>>> def perfect_square(string):
... value = int(string)
... sqrt = math.sqrt(value)
... if sqrt != int(sqrt):
... msg = "%r is not a perfect square" % string
... raise argparse.ArgumentTypeError(msg)
... return value
parser = argparse.ArgumentParser()
parser.add_argument('count', type=int)
parser.add_argument('distance', type=float)
parser.add_argument('street', type=ascii)
parser.add_argument('code_point', type=ord)
parser.add_argument('source_file', type=open)
parser.add_argument('dest_file', type=argparse.FileType('w', encoding='latin-1'))
parser.add_argument('datapath', type=pathlib.Path)
User defined functions can be used as well:
.. doctest::
>>> def hyphenated(string):
... return '-'.join([word[:4] for word in string.casefold().split()])
...
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('foo', type=perfect_square)
>>> parser.parse_args(['9'])
Namespace(foo=9)
>>> parser.parse_args(['7'])
usage: PROG [-h] foo
PROG: error: argument foo: '7' is not a perfect square
>>> parser = argparse.ArgumentParser()
>>> _ = parser.add_argument('short_title', type=hyphenated)
>>> parser.parse_args(['"The Tale of Two Cities"'])
Namespace(short_title='"the-tale-of-two-citi')
The choices_ keyword argument may be more convenient for type checkers that
simply check against a range of values::
The :func:`bool` function is not recommended as a type converter. All it does
is convert empty strings to ``False`` and non-empty strings to ``True``.
This is usually not what is desired.
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('foo', type=int, choices=range(5, 10))
>>> parser.parse_args(['7'])
Namespace(foo=7)
>>> parser.parse_args(['11'])
usage: PROG [-h] {5,6,7,8,9}
PROG: error: argument foo: invalid choice: 11 (choose from 5, 6, 7, 8, 9)
In general, the ``type`` keyword is a convenience that should only be used for
simple conversions that can only raise one of the three supported exceptions.
Anything with more interesting error-handling or resource management should be
done downstream after the arguments are parsed.
See the choices_ section for more details.
For example, JSON or YAML conversions have complex error cases that require
better reporting than can be given by the ``type`` keyword. An
:exc:`~json.JSONDecodeError` would not be well formatted and a
:exc:`FileNotFound` exception would not be handled at all.
Even :class:`~argparse.FileType` has its limitations for use with the ``type``
keyword. If one argument uses *FileType* and then a subsequent argument fails,
an error is reported but the file is not automatically closed. In this case, it
would be better to wait until after the parser has run and then use the
:keyword:`with`-statement to manage the files.
For type checkers that simply check against a fixed set of values, consider
using the choices_ keyword instead.
choices
@ -1133,20 +1148,14 @@ container should match the type_ specified::
Any container can be passed as the *choices* value, so :class:`list` objects,
:class:`set` objects, and custom containers are all supported.
This includes :class:`enum.Enum`, which could be used to restrain
argument's choices; if we reuse previous rock/paper/scissors game example,
this could be as follows::
>>> from enum import Enum
>>> class GameMove(Enum):
... ROCK = 'rock'
... PAPER = 'paper'
... SCISSORS = 'scissors'
...
>>> parser = argparse.ArgumentParser(prog='game.py')
>>> parser.add_argument('move', type=GameMove, choices=GameMove)
>>> parser.parse_args(['rock'])
Namespace(move=<GameMove.ROCK: 'rock'>)
Use of :class:`enum.Enum` is not recommended because it is difficult to
control its appearance in usage, help, and error messages.
Formatted choices overrides the default *metavar* which is normally derived
from *dest*. This is usually what you want because the user never sees the
*dest* parameter. If this display isn't desirable (perhaps because there are
many choices), just specify an explicit metavar_.
required
@ -1194,7 +1203,7 @@ argument::
positional arguments:
bar one of the bars to be frobbled
optional arguments:
options:
-h, --help show this help message and exit
--foo foo the bars before frobbling
@ -1212,7 +1221,7 @@ specifiers include the program name, ``%(prog)s`` and most keyword arguments to
positional arguments:
bar the bar to frobble (default: 42)
optional arguments:
options:
-h, --help show this help message and exit
As the help string supports %-formatting, if you want a literal ``%`` to appear
@ -1226,7 +1235,7 @@ setting the ``help`` value to ``argparse.SUPPRESS``::
>>> parser.print_help()
usage: frobble [-h]
optional arguments:
options:
-h, --help show this help message and exit
@ -1253,7 +1262,7 @@ will be referred to as ``FOO``. An example::
positional arguments:
bar
optional arguments:
options:
-h, --help show this help message and exit
--foo FOO
@ -1270,7 +1279,7 @@ An alternative name can be specified with ``metavar``::
positional arguments:
XXX
optional arguments:
options:
-h, --help show this help message and exit
--foo YYY
@ -1288,7 +1297,7 @@ arguments::
>>> parser.print_help()
usage: PROG [-h] [-x X X] [--foo bar baz]
optional arguments:
options:
-h, --help show this help message and exit
-x X X
--foo bar baz
@ -1692,7 +1701,7 @@ Sub-commands
a a help
b b help
optional arguments:
options:
-h, --help show this help message and exit
--foo foo help
@ -1702,13 +1711,13 @@ Sub-commands
positional arguments:
bar bar help
optional arguments:
options:
-h, --help show this help message and exit
>>> parser.parse_args(['b', '--help'])
usage: PROG b [-h] [--baz {X,Y,Z}]
optional arguments:
options:
-h, --help show this help message and exit
--baz {X,Y,Z} baz help
@ -1725,7 +1734,7 @@ Sub-commands
>>> parser.parse_args(['-h'])
usage: [-h] {foo,bar} ...
optional arguments:
options:
-h, --help show this help message and exit
subcommands:

19
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
@ -1575,7 +1576,7 @@ and classes for traversing abstract syntax trees:
Safely evaluate an expression node or a string containing a Python literal or
container display. The string or node provided may only consist of the
following Python literal structures: strings, bytes, numbers, tuples, lists,
dicts, sets, booleans, and ``None``.
dicts, sets, booleans, ``None`` and ``Ellipsis``.
This can be used for safely evaluating strings containing Python values from
untrusted sources without the need to parse the values oneself. It is not
@ -1587,6 +1588,10 @@ and classes for traversing abstract syntax trees:
sufficiently large/complex string due to stack depth limitations
in Python's AST compiler.
It can raise :exc:`ValueError`, :exc:`TypeError`, :exc:`SyntaxError`,
:exc:`MemoryError` and :exc:`RecursionError` depending on the malformed
input.
.. versionchanged:: 3.2
Now allows bytes and set literals.

41
Doc/library/asyncio-eventloop.rst
View File

@ -321,7 +321,7 @@ Creating Futures and Tasks
.. versionadded:: 3.5.2
.. method:: loop.create_task(coro, \*, name=None)
.. method:: loop.create_task(coro, *, name=None)
Schedule the execution of a :ref:`coroutine`.
Return a :class:`Task` object.
@ -356,7 +356,7 @@ Opening network connections
^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. coroutinemethod:: loop.create_connection(protocol_factory, \
host=None, port=None, \*, ssl=None, \
host=None, port=None, *, ssl=None, \
family=0, proto=0, flags=0, sock=None, \
local_addr=None, server_hostname=None, \
ssl_handshake_timeout=None, \
@ -482,7 +482,7 @@ Opening network connections
that can be used directly in async/await code.
.. coroutinemethod:: loop.create_datagram_endpoint(protocol_factory, \
local_addr=None, remote_addr=None, \*, \
local_addr=None, remote_addr=None, *, \
family=0, proto=0, flags=0, \
reuse_address=None, reuse_port=None, \
allow_broadcast=None, sock=None)
@ -559,7 +559,7 @@ Opening network connections
Added support for Windows.
.. coroutinemethod:: loop.create_unix_connection(protocol_factory, \
path=None, \*, ssl=None, sock=None, \
path=None, *, ssl=None, sock=None, \
server_hostname=None, ssl_handshake_timeout=None)
Create a Unix connection.
@ -592,7 +592,7 @@ Creating network servers
^^^^^^^^^^^^^^^^^^^^^^^^
.. coroutinemethod:: loop.create_server(protocol_factory, \
host=None, port=None, \*, \
host=None, port=None, *, \
family=socket.AF_UNSPEC, \
flags=socket.AI_PASSIVE, \
sock=None, backlog=100, ssl=None, \
@ -683,7 +683,7 @@ Creating network servers
.. coroutinemethod:: loop.create_unix_server(protocol_factory, path=None, \
\*, sock=None, backlog=100, ssl=None, \
*, sock=None, backlog=100, ssl=None, \
ssl_handshake_timeout=None, start_serving=True)
Similar to :meth:`loop.create_server` but works with the
@ -708,7 +708,7 @@ Creating network servers
The *path* parameter can now be a :class:`~pathlib.Path` object.
.. coroutinemethod:: loop.connect_accepted_socket(protocol_factory, \
sock, \*, ssl=None, ssl_handshake_timeout=None)
sock, *, ssl=None, ssl_handshake_timeout=None)
Wrap an already accepted connection into a transport/protocol pair.
@ -773,7 +773,7 @@ TLS Upgrade
^^^^^^^^^^^
.. coroutinemethod:: loop.start_tls(transport, protocol, \
sslcontext, \*, server_side=False, \
sslcontext, *, server_side=False, \
server_hostname=None, ssl_handshake_timeout=None)
Upgrade an existing transport-based connection to TLS.
@ -806,7 +806,7 @@ TLS Upgrade
Watching file descriptors
^^^^^^^^^^^^^^^^^^^^^^^^^
.. method:: loop.add_reader(fd, callback, \*args)
.. method:: loop.add_reader(fd, callback, *args)
Start monitoring the *fd* file descriptor for read availability and
invoke *callback* with the specified arguments once *fd* is available for
@ -816,7 +816,7 @@ Watching file descriptors
Stop monitoring the *fd* file descriptor for read availability.
.. method:: loop.add_writer(fd, callback, \*args)
.. method:: loop.add_writer(fd, callback, *args)
Start monitoring the *fd* file descriptor for write availability and
invoke *callback* with the specified arguments once *fd* is available for
@ -930,7 +930,7 @@ convenient.
:meth:`loop.create_server` and :func:`start_server`.
.. coroutinemethod:: loop.sock_sendfile(sock, file, offset=0, count=None, \
\*, fallback=True)
*, fallback=True)
Send a file using high-performance :mod:`os.sendfile` if possible.
Return the total number of bytes sent.
@ -964,7 +964,7 @@ convenient.
DNS
^^^
.. coroutinemethod:: loop.getaddrinfo(host, port, \*, family=0, \
.. coroutinemethod:: loop.getaddrinfo(host, port, *, family=0, \
type=0, proto=0, flags=0)
Asynchronous version of :meth:`socket.getaddrinfo`.
@ -1029,7 +1029,7 @@ Working with pipes
Unix signals
^^^^^^^^^^^^
.. method:: loop.add_signal_handler(signum, callback, \*args)
.. method:: loop.add_signal_handler(signum, callback, *args)
Set *callback* as the handler for the *signum* signal.
@ -1064,7 +1064,7 @@ Unix signals
Executing code in thread or process pools
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. awaitablemethod:: loop.run_in_executor(executor, func, \*args)
.. awaitablemethod:: loop.run_in_executor(executor, func, *args)
Arrange for *func* to be called in the specified executor.
@ -1184,10 +1184,13 @@ Allows customizing how exceptions are handled in the event loop.
* 'message': Error message;
* 'exception' (optional): Exception object;
* 'future' (optional): :class:`asyncio.Future` instance;
* 'task' (optional): :class:`asyncio.Task` instance;
* 'handle' (optional): :class:`asyncio.Handle` instance;
* 'protocol' (optional): :ref:`Protocol <asyncio-protocol>` instance;
* 'transport' (optional): :ref:`Transport <asyncio-transport>` instance;
* 'socket' (optional): :class:`socket.socket` instance.
* 'socket' (optional): :class:`socket.socket` instance;
* 'asyncgen' (optional): Asynchronous generator that caused
the exception.
.. note::
@ -1234,9 +1237,9 @@ async/await code consider using the high-level
subprocesses. See :ref:`Subprocess Support on Windows
<asyncio-windows-subprocess>` for details.
.. coroutinemethod:: loop.subprocess_exec(protocol_factory, \*args, \
.. coroutinemethod:: loop.subprocess_exec(protocol_factory, *args, \
stdin=subprocess.PIPE, stdout=subprocess.PIPE, \
stderr=subprocess.PIPE, \*\*kwargs)
stderr=subprocess.PIPE, **kwargs)
Create a subprocess from one or more string arguments specified by
*args*.
@ -1316,9 +1319,9 @@ async/await code consider using the high-level
conforms to the :class:`asyncio.SubprocessTransport` base class and
*protocol* is an object instantiated by the *protocol_factory*.
.. coroutinemethod:: loop.subprocess_shell(protocol_factory, cmd, \*, \
.. coroutinemethod:: loop.subprocess_shell(protocol_factory, cmd, *, \
stdin=subprocess.PIPE, stdout=subprocess.PIPE, \
stderr=subprocess.PIPE, \*\*kwargs)
stderr=subprocess.PIPE, **kwargs)
Create a subprocess from *cmd*, which can be a :class:`str` or a
:class:`bytes` string encoded to the

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

@ -31,7 +31,7 @@ Future Functions
.. versionadded:: 3.5
.. function:: ensure_future(obj, \*, loop=None)
.. function:: ensure_future(obj, *, loop=None)
Return:
@ -58,7 +58,7 @@ Future Functions
The function accepts any :term:`awaitable` object.
.. function:: wrap_future(future, \*, loop=None)
.. function:: wrap_future(future, *, loop=None)
Wrap a :class:`concurrent.futures.Future` object in a
:class:`asyncio.Future` object.
@ -67,7 +67,7 @@ Future Functions
Future Object
=============
.. class:: Future(\*, loop=None)
.. class:: Future(*, loop=None)
A Future represents an eventual result of an asynchronous
operation. Not thread-safe.

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

@ -159,7 +159,7 @@ implementation used by the asyncio event loop:
.. class:: AbstractChildWatcher
.. method:: add_child_handler(pid, callback, \*args)
.. method:: add_child_handler(pid, callback, *args)
Register a new child handler.
@ -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.

5
Doc/library/asyncio-queue.rst
View File

@ -23,7 +23,7 @@ See also the `Examples`_ section below.
Queue
=====
.. class:: Queue(maxsize=0, \*, loop=None)
.. class:: Queue(maxsize=0)
A first in, first out (FIFO) queue.
@ -36,9 +36,6 @@ Queue
the queue is always known and can be returned by calling the
:meth:`qsize` method.
.. deprecated-removed:: 3.8 3.10
The *loop* parameter.
This class is :ref:`not thread safe <asyncio-multithreading>`.

27
Doc/library/asyncio-stream.rst
View File

@ -48,9 +48,9 @@ The following top-level asyncio functions can be used to create
and work with streams:
.. coroutinefunction:: open_connection(host=None, port=None, \*, \
loop=None, limit=None, ssl=None, family=0, \
proto=0, flags=0, sock=None, local_addr=None, \
.. coroutinefunction:: open_connection(host=None, port=None, *, \
limit=None, ssl=None, family=0, proto=0, \
flags=0, sock=None, local_addr=None, \
server_hostname=None, ssl_handshake_timeout=None)
Establish a network connection and return a pair of
@ -59,9 +59,6 @@ and work with streams:
The returned *reader* and *writer* objects are instances of
:class:`StreamReader` and :class:`StreamWriter` classes.
The *loop* argument is optional and can always be determined
automatically when this function is awaited from a coroutine.
*limit* determines the buffer size limit used by the
returned :class:`StreamReader` instance. By default the *limit*
is set to 64 KiB.
@ -74,7 +71,7 @@ and work with streams:
The *ssl_handshake_timeout* parameter.
.. coroutinefunction:: start_server(client_connected_cb, host=None, \
port=None, \*, loop=None, limit=None, \
port=None, *, limit=None, \
family=socket.AF_UNSPEC, \
flags=socket.AI_PASSIVE, sock=None, \
backlog=100, ssl=None, reuse_address=None, \
@ -92,9 +89,6 @@ and work with streams:
:ref:`coroutine function <coroutine>`; if it is a coroutine function,
it will be automatically scheduled as a :class:`Task`.
The *loop* argument is optional and can always be determined
automatically when this method is awaited from a coroutine.
*limit* determines the buffer size limit used by the
returned :class:`StreamReader` instance. By default the *limit*
is set to 64 KiB.
@ -109,9 +103,9 @@ and work with streams:
.. rubric:: Unix Sockets
.. coroutinefunction:: open_unix_connection(path=None, \*, loop=None, \
limit=None, ssl=None, sock=None, \
server_hostname=None, ssl_handshake_timeout=None)
.. coroutinefunction:: open_unix_connection(path=None, *, limit=None, \
ssl=None, sock=None, server_hostname=None, \
ssl_handshake_timeout=None)
Establish a Unix socket connection and return a pair of
``(reader, writer)``.
@ -132,9 +126,8 @@ and work with streams:
.. coroutinefunction:: start_unix_server(client_connected_cb, path=None, \
\*, loop=None, limit=None, sock=None, \
backlog=100, ssl=None, ssl_handshake_timeout=None, \
start_serving=True)
*, limit=None, sock=None, backlog=100, ssl=None, \
ssl_handshake_timeout=None, start_serving=True)
Start a Unix socket server.
@ -192,7 +185,7 @@ StreamReader
can be read. Use the :attr:`IncompleteReadError.partial`
attribute to get the partially read data.
.. coroutinemethod:: readuntil(separator=b'\\n')
.. coroutinemethod:: readuntil(separator=b'\n')
Read data from the stream until *separator* is found.

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

@ -61,9 +61,8 @@ See also the `Examples`_ subsection.
Creating Subprocesses
=====================
.. coroutinefunction:: create_subprocess_exec(program, \*args, stdin=None, \
stdout=None, stderr=None, loop=None, \
limit=None, \*\*kwds)
.. coroutinefunction:: create_subprocess_exec(program, *args, stdin=None, \
stdout=None, stderr=None, limit=None, **kwds)
Create a subprocess.
@ -76,13 +75,9 @@ Creating Subprocesses
See the documentation of :meth:`loop.subprocess_exec` for other
parameters.
.. deprecated-removed:: 3.8 3.10
The *loop* parameter.
.. coroutinefunction:: create_subprocess_shell(cmd, stdin=None, \
stdout=None, stderr=None, loop=None, \
limit=None, \*\*kwds)
stdout=None, stderr=None, limit=None, **kwds)
Run the *cmd* shell command.
@ -104,10 +99,6 @@ Creating Subprocesses
escape whitespace and special shell characters in strings that are going
to be used to construct shell commands.
.. deprecated-removed:: 3.8 3.10
The *loop* parameter.
.. note::
Subprocesses are available for Windows if a :class:`ProactorEventLoop` is

39
Doc/library/asyncio-sync.rst
View File

@ -36,7 +36,7 @@ asyncio has the following basic synchronization primitives:
Lock
====
.. class:: Lock(\*, loop=None)
.. class:: Lock()
Implements a mutex lock for asyncio tasks. Not thread-safe.
@ -63,9 +63,6 @@ Lock
finally:
lock.release()
.. deprecated-removed:: 3.8 3.10
The *loop* parameter.
.. coroutinemethod:: acquire()
Acquire the lock.
@ -96,7 +93,7 @@ Lock
Event
=====
.. class:: Event(\*, loop=None)
.. class:: Event()
An event object. Not thread-safe.
@ -104,14 +101,10 @@ Event
that some event has happened.
An Event object manages an internal flag that can be set to *true*
with the :meth:`set` method and reset to *false* with the
:meth:`clear` method. The :meth:`wait` method blocks until the
with the :meth:`~Event.set` method and reset to *false* with the
:meth:`clear` method. The :meth:`~Event.wait` method blocks until the
flag is set to *true*. The flag is set to *false* initially.
.. deprecated-removed:: 3.8 3.10
The *loop* parameter.
.. _asyncio_example_sync_event:
Example::
@ -142,7 +135,7 @@ Event
Wait until the event is set.
If the event is set, return ``True`` immediately.
Otherwise block until another task calls :meth:`set`.
Otherwise block until another task calls :meth:`~Event.set`.
.. method:: set()
@ -155,8 +148,8 @@ Event
Clear (unset) the event.
Tasks awaiting on :meth:`wait` will now block until the
:meth:`set` method is called again.
Tasks awaiting on :meth:`~Event.wait` will now block until the
:meth:`~Event.set` method is called again.
.. method:: is_set()
@ -166,7 +159,7 @@ Event
Condition
=========
.. class:: Condition(lock=None, \*, loop=None)
.. class:: Condition(lock=None)
A Condition object. Not thread-safe.
@ -184,10 +177,6 @@ Condition
``None``. In the latter case a new Lock object is created
automatically.
.. deprecated-removed:: 3.8 3.10
The *loop* parameter.
The preferred way to use a Condition is an :keyword:`async with`
statement::
@ -270,7 +259,7 @@ Condition
Semaphore
=========
.. class:: Semaphore(value=1, \*, loop=None)
.. class:: Semaphore(value=1)
A Semaphore object. Not thread-safe.
@ -284,10 +273,6 @@ Semaphore
internal counter (``1`` by default). If the given value is
less than ``0`` a :exc:`ValueError` is raised.
.. deprecated-removed:: 3.8 3.10
The *loop* parameter.
The preferred way to use a Semaphore is an :keyword:`async with`
statement::
@ -332,7 +317,7 @@ Semaphore
BoundedSemaphore
================
.. class:: BoundedSemaphore(value=1, \*, loop=None)
.. class:: BoundedSemaphore(value=1)
A bounded semaphore object. Not thread-safe.
@ -340,10 +325,6 @@ BoundedSemaphore
a :exc:`ValueError` in :meth:`~Semaphore.release` if it
increases the internal counter above the initial *value*.
.. deprecated-removed:: 3.8 3.10
The *loop* parameter.
---------

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

@ -210,7 +210,7 @@ is :meth:`loop.run_in_executor`.
Running an asyncio Program
==========================
.. function:: run(coro, \*, debug=False)
.. function:: run(coro, *, debug=False)
Execute the :term:`coroutine` *coro* and return the result.
@ -247,7 +247,7 @@ Running an asyncio Program
Creating Tasks
==============
.. function:: create_task(coro, \*, name=None)
.. function:: create_task(coro, *, name=None)
Wrap the *coro* :ref:`coroutine <coroutine>` into a :class:`Task`
and schedule its execution. Return the Task object.
@ -283,7 +283,7 @@ Creating Tasks
Sleeping
========
.. coroutinefunction:: sleep(delay, result=None, \*, loop=None)
.. coroutinefunction:: sleep(delay, result=None)
Block for *delay* seconds.
@ -293,9 +293,6 @@ Sleeping
``sleep()`` always suspends the current task, allowing other tasks
to run.
.. deprecated-removed:: 3.8 3.10
The *loop* parameter.
.. _asyncio_example_sleep:
Example of coroutine displaying the current date every second
@ -319,7 +316,7 @@ Sleeping
Running Tasks Concurrently
==========================
.. awaitablefunction:: gather(\*aws, loop=None, return_exceptions=False)
.. awaitablefunction:: gather(*aws, return_exceptions=False)
Run :ref:`awaitable objects <asyncio-awaitables>` in the *aws*
sequence *concurrently*.
@ -348,9 +345,6 @@ Running Tasks Concurrently
cancellation of one submitted Task/Future to cause other
Tasks/Futures to be cancelled.
.. deprecated-removed:: 3.8 3.10
The *loop* parameter.
.. _asyncio_example_gather:
Example::
@ -403,7 +397,7 @@ Running Tasks Concurrently
Shielding From Cancellation
===========================
.. awaitablefunction:: shield(aw, \*, loop=None)
.. awaitablefunction:: shield(aw)
Protect an :ref:`awaitable object <asyncio-awaitables>`
from being :meth:`cancelled <Task.cancel>`.
@ -436,14 +430,11 @@ Shielding From Cancellation
except CancelledError:
res = None
.. deprecated-removed:: 3.8 3.10
The *loop* parameter.
Timeouts
========
.. coroutinefunction:: wait_for(aw, timeout, \*, loop=None)
.. coroutinefunction:: wait_for(aw, timeout)
Wait for the *aw* :ref:`awaitable <asyncio-awaitables>`
to complete with a timeout.
@ -466,9 +457,6 @@ Timeouts
If the wait is cancelled, the future *aw* is also cancelled.
.. deprecated-removed:: 3.8 3.10
The *loop* parameter.
.. _asyncio_example_waitfor:
Example::
@ -500,8 +488,7 @@ Timeouts
Waiting Primitives
==================
.. coroutinefunction:: wait(aws, \*, loop=None, timeout=None,\
return_when=ALL_COMPLETED)
.. coroutinefunction:: wait(aws, *, timeout=None, return_when=ALL_COMPLETED)
Run :ref:`awaitable objects <asyncio-awaitables>` in the *aws*
iterable concurrently and block until the condition specified
@ -553,10 +540,6 @@ Waiting Primitives
``wait()`` directly is deprecated as it leads to
:ref:`confusing behavior <asyncio_example_wait_coroutine>`.
.. deprecated-removed:: 3.8 3.10
The *loop* parameter.
.. _asyncio_example_wait_coroutine:
.. note::
@ -590,7 +573,7 @@ Waiting Primitives
deprecated.
.. function:: as_completed(aws, \*, loop=None, timeout=None)
.. function:: as_completed(aws, *, timeout=None)
Run :ref:`awaitable objects <asyncio-awaitables>` in the *aws*
iterable concurrently. Return an iterator of coroutines.
@ -600,9 +583,6 @@ Waiting Primitives
Raises :exc:`asyncio.TimeoutError` if the timeout occurs before
all Futures are done.
.. deprecated-removed:: 3.8 3.10
The *loop* parameter.
Example::
for coro in as_completed(aws):
@ -613,12 +593,12 @@ Waiting Primitives
Running in Threads
==================
.. coroutinefunction:: to_thread(func, /, \*args, \*\*kwargs)
.. coroutinefunction:: to_thread(func, /, *args, **kwargs)
Asynchronously run function *func* in a separate thread.
Any \*args and \*\*kwargs supplied for this function are directly passed
to *func*. Also, the current :class:`contextvars.Context` is propogated,
to *func*. Also, the current :class:`contextvars.Context` is propagated,
allowing context variables from the event loop thread to be accessed in the
separate thread.
@ -743,7 +723,7 @@ Introspection
Task Object
===========
.. class:: Task(coro, \*, loop=None, name=None)
.. class:: Task(coro, *, loop=None, name=None)
A :class:`Future-like <Future>` object that runs a Python
:ref:`coroutine <coroutine>`. Not thread-safe.
@ -909,7 +889,7 @@ Task Object
See the documentation of :meth:`Future.remove_done_callback`
for more details.
.. method:: get_stack(\*, limit=None)
.. method:: get_stack(*, limit=None)
Return the list of stack frames for this Task.
@ -930,7 +910,7 @@ Task Object
stack are returned, but the oldest frames of a traceback are
returned. (This matches the behavior of the traceback module.)
.. method:: print_stack(\*, limit=None, file=None)
.. method:: print_stack(*, limit=None, file=None)
Print the stack or traceback for this Task.

2
Doc/library/base64.rst
View File

@ -199,7 +199,7 @@ The modern interface provides:
.. versionadded:: 3.4
.. function:: a85decode(b, *, foldspaces=False, adobe=False, ignorechars=b' \\t\\n\\r\\v')
.. function:: a85decode(b, *, foldspaces=False, adobe=False, ignorechars=b' \t\n\r\v')
Decode the Ascii85 encoded :term:`bytes-like object` or ASCII string *b* and
return the decoded :class:`bytes`.

8
Doc/library/bz2.rst
View File

@ -266,7 +266,6 @@ Below are some examples of typical usage of the :mod:`bz2` module.
Using :func:`compress` and :func:`decompress` to demonstrate round-trip compression:
>>> import bz2
>>> data = b"""\
... Donec rhoncus quis sapien sit amet molestie. Fusce scelerisque vel augue
... nec ullamcorper. Nam rutrum pretium placerat. Aliquam vel tristique lorem,
@ -275,11 +274,9 @@ Using :func:`compress` and :func:`decompress` to demonstrate round-trip compress
... Aliquam pharetra lacus non risus vehicula rutrum. Maecenas aliquam leo
... felis. Pellentesque semper nunc sit amet nibh ullamcorper, ac elementum
... dolor luctus. Curabitur lacinia mi ornare consectetur vestibulum."""
>>> c = bz2.compress(data)
>>> len(data) / len(c) # Data compression ratio
1.513595166163142
>>> d = bz2.decompress(c)
>>> data == d # Check equality to original object after round-trip
True
@ -287,7 +284,6 @@ Using :func:`compress` and :func:`decompress` to demonstrate round-trip compress
Using :class:`BZ2Compressor` for incremental compression:
>>> import bz2
>>> def gen_data(chunks=10, chunksize=1000):
... """Yield incremental blocks of chunksize bytes."""
... for _ in range(chunks):
@ -310,7 +306,6 @@ while ordered, repetitive data usually yields a high compression ratio.
Writing and reading a bzip2-compressed file in binary mode:
>>> import bz2
>>> data = b"""\
... Donec rhoncus quis sapien sit amet molestie. Fusce scelerisque vel augue
... nec ullamcorper. Nam rutrum pretium placerat. Aliquam vel tristique lorem,
@ -319,14 +314,11 @@ Writing and reading a bzip2-compressed file in binary mode:
... Aliquam pharetra lacus non risus vehicula rutrum. Maecenas aliquam leo
... felis. Pellentesque semper nunc sit amet nibh ullamcorper, ac elementum
... dolor luctus. Curabitur lacinia mi ornare consectetur vestibulum."""
>>> with bz2.open("myfile.bz2", "wb") as f:
... # Write compressed data to file
... unused = f.write(data)
>>> with bz2.open("myfile.bz2", "rb") as f:
... # Decompress data from file
... content = f.read()
>>> content == data # Check equality to original object after round-trip
True

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

4
Doc/library/compileall.rst
View File

@ -148,7 +148,7 @@ runtime.
Public functions
----------------
.. function:: compile_dir(dir, maxlevels=sys.getrecursionlimit(), ddir=None, force=False, rx=None, quiet=0, legacy=False, optimize=-1, workers=1, invalidation_mode=None, \*, stripdir=None, prependdir=None, limit_sl_dest=None, hardlink_dupes=False)
.. function:: compile_dir(dir, maxlevels=sys.getrecursionlimit(), ddir=None, force=False, rx=None, quiet=0, legacy=False, optimize=-1, workers=1, invalidation_mode=None, *, stripdir=None, prependdir=None, limit_sl_dest=None, hardlink_dupes=False)
Recursively descend the directory tree named by *dir*, compiling all :file:`.py`
files along the way. Return a true value if all the files compiled successfully,
@ -231,7 +231,7 @@ Public functions
Added *stripdir*, *prependdir*, *limit_sl_dest* and *hardlink_dupes* arguments.
Default value of *maxlevels* was changed from ``10`` to ``sys.getrecursionlimit()``
.. function:: compile_file(fullname, ddir=None, force=False, rx=None, quiet=0, legacy=False, optimize=-1, invalidation_mode=None, \*, stripdir=None, prependdir=None, limit_sl_dest=None, hardlink_dupes=False)
.. function:: compile_file(fullname, ddir=None, force=False, rx=None, quiet=0, legacy=False, optimize=-1, invalidation_mode=None, *, stripdir=None, prependdir=None, limit_sl_dest=None, hardlink_dupes=False)
Compile the file with path *fullname*. Return a true value if the file
compiled successfully, and a false value otherwise.

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

@ -67,7 +67,7 @@ Executor Objects
.. versionchanged:: 3.5
Added the *chunksize* argument.
.. method:: shutdown(wait=True, \*, cancel_futures=False)
.. method:: shutdown(wait=True, *, cancel_futures=False)
Signal the executor that it should free any resources that it is using
when the currently pending futures are done executing. Calls to
@ -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

82
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)
@ -218,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)
@ -384,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

4
Doc/library/contextvars.rst
View File

@ -26,7 +26,7 @@ See also :pep:`567` for additional details.
Context Variables
-----------------
.. class:: ContextVar(name, [\*, default])
.. class:: ContextVar(name, [*, default])
This class is used to declare a new Context Variable, e.g.::
@ -146,7 +146,7 @@ Manual Context Management
Context implements the :class:`collections.abc.Mapping` interface.
.. method:: run(callable, \*args, \*\*kwargs)
.. method:: run(callable, *args, **kwargs)
Execute ``callable(*args, **kwargs)`` code in the context object
the *run* method is called on. Return the result of the execution

2
Doc/library/ctypes.rst
View File

@ -2508,7 +2508,7 @@ other data types containing pointer type fields.
Arrays and pointers
^^^^^^^^^^^^^^^^^^^
.. class:: Array(\*args)
.. class:: Array(*args)
Abstract base class for arrays.

4
Doc/library/datetime.rst
View File

@ -1219,7 +1219,7 @@ Instance methods:
.. method:: datetime.replace(year=self.year, month=self.month, day=self.day, \
hour=self.hour, minute=self.minute, second=self.second, microsecond=self.microsecond, \
tzinfo=self.tzinfo, * fold=0)
tzinfo=self.tzinfo, *, fold=0)
Return a datetime with the same attributes, except for those attributes given
new values by whichever keyword arguments are specified. Note that
@ -1783,7 +1783,7 @@ Other constructor:
Instance methods:
.. method:: time.replace(hour=self.hour, minute=self.minute, second=self.second, \
microsecond=self.microsecond, tzinfo=self.tzinfo, * fold=0)
microsecond=self.microsecond, tzinfo=self.tzinfo, *, fold=0)
Return a :class:`.time` with the same value, except for those attributes given
new values by whichever keyword arguments are specified. Note that

2
Doc/library/dialog.rst
View File

@ -198,7 +198,7 @@ These do not emulate the native look-and-feel of the platform.
A subclass of FileDialog that creates a dialog window for selecting a
destination file.
.. method:: ok_command()
.. method:: ok_command()
Test whether or not the selection points to a valid file that is not a
directory. Confirmation is required if an already existing file is

6
Doc/library/difflib.rst
View File

@ -149,7 +149,7 @@ diffs. For comparing directories and files, see also, the :mod:`filecmp` module.
contains a good example of its use.
.. function:: context_diff(a, b, fromfile='', tofile='', fromfiledate='', tofiledate='', n=3, lineterm='\\n')
.. function:: context_diff(a, b, fromfile='', tofile='', fromfiledate='', tofiledate='', n=3, lineterm='\n')
Compare *a* and *b* (lists of strings); return a delta (a :term:`generator`
generating the delta lines) in context diff format.
@ -279,7 +279,7 @@ diffs. For comparing directories and files, see also, the :mod:`filecmp` module.
emu
.. function:: unified_diff(a, b, fromfile='', tofile='', fromfiledate='', tofiledate='', n=3, lineterm='\\n')
.. function:: unified_diff(a, b, fromfile='', tofile='', fromfiledate='', tofiledate='', n=3, lineterm='\n')
Compare *a* and *b* (lists of strings); return a delta (a :term:`generator`
generating the delta lines) in unified diff format.
@ -321,7 +321,7 @@ diffs. For comparing directories and files, see also, the :mod:`filecmp` module.
See :ref:`difflib-interface` for a more detailed example.
.. function:: diff_bytes(dfunc, a, b, fromfile=b'', tofile=b'', fromfiledate=b'', tofiledate=b'', n=3, lineterm=b'\\n')
.. function:: diff_bytes(dfunc, a, b, fromfile=b'', tofile=b'', fromfiledate=b'', tofiledate=b'', n=3, lineterm=b'\n')
Compare *a* and *b* (lists of bytes objects) using *dfunc*; yield a
sequence of delta lines (also bytes) in the format returned by *dfunc*.

19
Doc/library/dis.rst
View File

@ -708,7 +708,8 @@ iterations of the loop.
.. opcode:: RERAISE
Re-raises the exception currently on top of the stack.
Re-raises the exception currently on top of the stack. If oparg is non-zero,
restores ``f_lasti`` of the current frame to its value when the exception was raised.
.. versionadded:: 3.9
@ -861,7 +862,7 @@ All of the following opcodes use their arguments.
.. opcode:: LIST_TO_TUPLE
Pops a list from the stack and pushes a tuple containing the same values.
Pops a list from the stack and pushes a tuple containing the same values.
.. versionadded:: 3.9
@ -889,7 +890,7 @@ All of the following opcodes use their arguments.
.. opcode:: DICT_MERGE
Like :opcode:`DICT_UPDATE` but raises an exception for duplicate keys.
Like :opcode:`DICT_UPDATE` but raises an exception for duplicate keys.
.. versionadded:: 3.9
@ -907,14 +908,14 @@ All of the following opcodes use their arguments.
.. opcode:: IS_OP (invert)
Performs ``is`` comparison, or ``is not`` if ``invert`` is 1.
Performs ``is`` comparison, or ``is not`` if ``invert`` is 1.
.. versionadded:: 3.9
.. opcode:: CONTAINS_OP (invert)
Performs ``in`` comparison, or ``not in`` if ``invert`` is 1.
Performs ``in`` comparison, or ``not in`` if ``invert`` is 1.
.. versionadded:: 3.9
@ -955,8 +956,8 @@ All of the following opcodes use their arguments.
.. opcode:: JUMP_IF_NOT_EXC_MATCH (target)
Tests whether the second value on the stack is an exception matching TOS,
and jumps if it is not. Pops two values from the stack.
Tests whether the second value on the stack is an exception matching TOS,
and jumps if it is not. Pops two values from the stack.
.. versionadded:: 3.9
@ -1144,11 +1145,13 @@ All of the following opcodes use their arguments.
* ``0x01`` a tuple of default values for positional-only and
positional-or-keyword parameters in positional order
* ``0x02`` a dictionary of keyword-only parameters' default values
* ``0x04`` an annotation dictionary
* ``0x04`` a tuple of strings containing parameters' annotations
* ``0x08`` a tuple containing cells for free variables, making a closure
* the code associated with the function (at TOS1)
* the :term:`qualified name` of the function (at TOS)
.. versionchanged:: 3.10
Flag value ``0x04`` is a tuple of strings instead of dictionary
.. opcode:: BUILD_SLICE (argc)

54
Doc/library/doctest.rst
View File

@ -719,36 +719,51 @@ above.
An example's doctest directives modify doctest's behavior for that single
example. Use ``+`` to enable the named behavior, or ``-`` to disable it.
For example, this test passes::
For example, this test passes:
>>> print(list(range(20))) # doctest: +NORMALIZE_WHITESPACE
.. doctest::
:no-trim-doctest-flags:
>>> print(list(range(20))) # doctest: +NORMALIZE_WHITESPACE
[0, 1, 2, 3, 4, 5, 6, 7, 8, 9,
10, 11, 12, 13, 14, 15, 16, 17, 18, 19]
Without the directive it would fail, both because the actual output doesn't have
two blanks before the single-digit list elements, and because the actual output
is on a single line. This test also passes, and also requires a directive to do
so::
so:
>>> print(list(range(20))) # doctest: +ELLIPSIS
.. doctest::
:no-trim-doctest-flags:
>>> print(list(range(20))) # doctest: +ELLIPSIS
[0, 1, ..., 18, 19]
Multiple directives can be used on a single physical line, separated by
commas::
commas:
>>> print(list(range(20))) # doctest: +ELLIPSIS, +NORMALIZE_WHITESPACE
.. doctest::
:no-trim-doctest-flags:
>>> print(list(range(20))) # doctest: +ELLIPSIS, +NORMALIZE_WHITESPACE
[0, 1, ..., 18, 19]
If multiple directive comments are used for a single example, then they are
combined::
combined:
>>> print(list(range(20))) # doctest: +ELLIPSIS
... # doctest: +NORMALIZE_WHITESPACE
.. doctest::
:no-trim-doctest-flags:
>>> print(list(range(20))) # doctest: +ELLIPSIS
... # doctest: +NORMALIZE_WHITESPACE
[0, 1, ..., 18, 19]
As the previous example shows, you can add ``...`` lines to your example
containing only directives. This can be useful when an example is too long for
a directive to comfortably fit on the same line::
a directive to comfortably fit on the same line:
.. doctest::
:no-trim-doctest-flags:
>>> print(list(range(5)) + list(range(10, 20)) + list(range(30, 40)))
... # doctest: +ELLIPSIS
@ -793,18 +808,23 @@ instead. Another is to do ::
There are others, but you get the idea.
Another bad idea is to print things that embed an object address, like ::
Another bad idea is to print things that embed an object address, like
>>> id(1.0) # certain to fail some of the time
.. doctest::
>>> id(1.0) # certain to fail some of the time # doctest: +SKIP
7948648
>>> class C: pass
>>> C() # the default repr() for instances embeds an address
<__main__.C instance at 0x00AC18F0>
>>> C() # the default repr() for instances embeds an address # doctest: +SKIP
<C object at 0x00AC18F0>
The :const:`ELLIPSIS` directive gives a nice approach for the last example::
The :const:`ELLIPSIS` directive gives a nice approach for the last example:
>>> C() #doctest: +ELLIPSIS
<__main__.C instance at 0x...>
.. doctest::
:no-trim-doctest-flags:
>>> C() # doctest: +ELLIPSIS
<C object at 0x...>
Floating-point numbers are also subject to small output variations across
platforms, because Python defers to the platform C library for float formatting,

2
Doc/library/email.contentmanager.rst
View File

@ -116,7 +116,7 @@ Currently the email package provides only one concrete content manager,
decoding the payload to unicode. The default error handler is
``replace``.
.. method:: set_content(msg, <'str'>, subtype="plain", charset='utf-8' \
.. method:: set_content(msg, <'str'>, subtype="plain", charset='utf-8', \
cte=None, \
disposition=None, filename=None, cid=None, \
params=None, headers=None)

2
Doc/library/email.header.rst
View File

@ -116,7 +116,7 @@ Here is the :class:`Header` class description:
if *s* is a byte string.
.. method:: encode(splitchars=';, \\t', maxlinelen=None, linesep='\\n')
.. method:: encode(splitchars=';, \t', maxlinelen=None, linesep='\n')
Encode a message header into an RFC-compliant format, possibly wrapping
long lines and encapsulating non-ASCII parts in base64 or quoted-printable

2
Doc/library/email.policy.rst
View File

@ -210,7 +210,7 @@ added matters. To illustrate::
:meth:`register_defect` method.
.. attribute:: mangle_from\_
.. attribute:: mangle_from_
If :const:`True`, lines starting with *"From "* in the body are
escaped by putting a ``>`` in front of them. This parameter is used when

17
Doc/library/enum.rst
View File

@ -61,16 +61,18 @@ helper, :class:`auto`.
the bitwise operations without losing their :class:`Flag` membership.
.. function:: unique
:noindex:
:noindex:
Enum class decorator that ensures only one name is bound to any one value.
.. class:: auto
Instances are replaced with an appropriate value for Enum members. By default, the initial value starts at 1.
Instances are replaced with an appropriate value for Enum members.
:class:`StrEnum` defaults to the lower-cased version of the member name,
while other Enums default to 1 and increase from there.
.. versionadded:: 3.6 ``Flag``, ``IntFlag``, ``auto``
.. versionadded:: 3.10 ``StrEnum``
Creating an Enum
----------------
@ -1164,6 +1166,15 @@ and raise an error if the two do not match::
In Python 2 code the :attr:`_order_` attribute is necessary as definition
order is lost before it can be recorded.
_Private__names
"""""""""""""""
Private names are not converted to Enum members, but remain normal attributes.
.. versionchanged:: 3.10
``Enum`` member type
""""""""""""""""""""

9
Doc/library/exceptions.rst
View File

@ -90,8 +90,13 @@ The following exceptions are used mostly as base classes for other exceptions.
.. method:: with_traceback(tb)
This method sets *tb* as the new traceback for the exception and returns
the exception object. It is usually used in exception handling code like
this::
the exception object. It was more commonly used before the exception
chaining features of :pep:`3134` became available. The following example
shows how we can convert an instance of ``SomeException`` into an
instance of ``OtherException`` while preserving the traceback. Once
raised, the current frame is pushed onto the traceback of the
``OtherException``, as would have happened to the traceback of the
original ``SomeException`` had we allowed it to propagate to the caller.
try:
...

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

2
Doc/library/fnmatch.rst
View File

@ -75,7 +75,7 @@ patterns.
.. function:: filter(names, pattern)
Return the subset of the list of *names* that match *pattern*. It is the same as
Construct a list from those elements of the iterable *names* that match *pattern*. It is the same as
``[n for n in names if fnmatch(n, pattern)]``, but implemented more efficiently.

351
Doc/library/formatter.rst
View File

@ -1,351 +0,0 @@
:mod:`formatter` --- Generic output formatting
==============================================
.. module:: formatter
:synopsis: Generic output formatter and device interface.
:deprecated:
.. deprecated:: 3.4
Due to lack of usage, the formatter module has been deprecated.
--------------
This module supports two interface definitions, each with multiple
implementations: The *formatter* interface, and the *writer* interface which is
required by the formatter interface.
Formatter objects transform an abstract flow of formatting events into specific
output events on writer objects. Formatters manage several stack structures to
allow various properties of a writer object to be changed and restored; writers
need not be able to handle relative changes nor any sort of "change back"
operation. Specific writer properties which may be controlled via formatter
objects are horizontal alignment, font, and left margin indentations. A
mechanism is provided which supports providing arbitrary, non-exclusive style
settings to a writer as well. Additional interfaces facilitate formatting
events which are not reversible, such as paragraph separation.
Writer objects encapsulate device interfaces. Abstract devices, such as file
formats, are supported as well as physical devices. The provided
implementations all work with abstract devices. The interface makes available
mechanisms for setting the properties which formatter objects manage and
inserting data into the output.
.. _formatter-interface:
The Formatter Interface
-----------------------
Interfaces to create formatters are dependent on the specific formatter class
being instantiated. The interfaces described below are the required interfaces
which all formatters must support once initialized.
One data element is defined at the module level:
.. data:: AS_IS
Value which can be used in the font specification passed to the ``push_font()``
method described below, or as the new value to any other ``push_property()``
method. Pushing the ``AS_IS`` value allows the corresponding ``pop_property()``
method to be called without having to track whether the property was changed.
The following attributes are defined for formatter instance objects:
.. attribute:: formatter.writer
The writer instance with which the formatter interacts.
.. method:: formatter.end_paragraph(blanklines)
Close any open paragraphs and insert at least *blanklines* before the next
paragraph.
.. method:: formatter.add_line_break()
Add a hard line break if one does not already exist. This does not break the
logical paragraph.
.. method:: formatter.add_hor_rule(*args, **kw)
Insert a horizontal rule in the output. A hard break is inserted if there is
data in the current paragraph, but the logical paragraph is not broken. The
arguments and keywords are passed on to the writer's :meth:`send_line_break`
method.
.. method:: formatter.add_flowing_data(data)
Provide data which should be formatted with collapsed whitespace. Whitespace
from preceding and successive calls to :meth:`add_flowing_data` is considered as
well when the whitespace collapse is performed. The data which is passed to
this method is expected to be word-wrapped by the output device. Note that any
word-wrapping still must be performed by the writer object due to the need to
rely on device and font information.
.. method:: formatter.add_literal_data(data)
Provide data which should be passed to the writer unchanged. Whitespace,
including newline and tab characters, are considered legal in the value of
*data*.
.. method:: formatter.add_label_data(format, counter)
Insert a label which should be placed to the left of the current left margin.
This should be used for constructing bulleted or numbered lists. If the
*format* value is a string, it is interpreted as a format specification for
*counter*, which should be an integer. The result of this formatting becomes the
value of the label; if *format* is not a string it is used as the label value
directly. The label value is passed as the only argument to the writer's
:meth:`send_label_data` method. Interpretation of non-string label values is
dependent on the associated writer.
Format specifications are strings which, in combination with a counter value,
are used to compute label values. Each character in the format string is copied
to the label value, with some characters recognized to indicate a transform on
the counter value. Specifically, the character ``'1'`` represents the counter
value formatter as an Arabic number, the characters ``'A'`` and ``'a'``
represent alphabetic representations of the counter value in upper and lower
case, respectively, and ``'I'`` and ``'i'`` represent the counter value in Roman
numerals, in upper and lower case. Note that the alphabetic and roman
transforms require that the counter value be greater than zero.
.. method:: formatter.flush_softspace()
Send any pending whitespace buffered from a previous call to
:meth:`add_flowing_data` to the associated writer object. This should be called
before any direct manipulation of the writer object.
.. method:: formatter.push_alignment(align)
Push a new alignment setting onto the alignment stack. This may be
:const:`AS_IS` if no change is desired. If the alignment value is changed from
the previous setting, the writer's :meth:`new_alignment` method is called with
the *align* value.
.. method:: formatter.pop_alignment()
Restore the previous alignment.
.. method:: formatter.push_font((size, italic, bold, teletype))
Change some or all font properties of the writer object. Properties which are
not set to :const:`AS_IS` are set to the values passed in while others are
maintained at their current settings. The writer's :meth:`new_font` method is
called with the fully resolved font specification.
.. method:: formatter.pop_font()
Restore the previous font.
.. method:: formatter.push_margin(margin)
Increase the number of left margin indentations by one, associating the logical
tag *margin* with the new indentation. The initial margin level is ``0``.
Changed values of the logical tag must be true values; false values other than
:const:`AS_IS` are not sufficient to change the margin.
.. method:: formatter.pop_margin()
Restore the previous margin.
.. method:: formatter.push_style(*styles)
Push any number of arbitrary style specifications. All styles are pushed onto
the styles stack in order. A tuple representing the entire stack, including
:const:`AS_IS` values, is passed to the writer's :meth:`new_styles` method.
.. method:: formatter.pop_style(n=1)
Pop the last *n* style specifications passed to :meth:`push_style`. A tuple
representing the revised stack, including :const:`AS_IS` values, is passed to
the writer's :meth:`new_styles` method.
.. method:: formatter.set_spacing(spacing)
Set the spacing style for the writer.
.. method:: formatter.assert_line_data(flag=1)
Inform the formatter that data has been added to the current paragraph
out-of-band. This should be used when the writer has been manipulated
directly. The optional *flag* argument can be set to false if the writer
manipulations produced a hard line break at the end of the output.
.. _formatter-impls:
Formatter Implementations
-------------------------
Two implementations of formatter objects are provided by this module. Most
applications may use one of these classes without modification or subclassing.
.. class:: NullFormatter(writer=None)
A formatter which does nothing. If *writer* is omitted, a :class:`NullWriter`
instance is created. No methods of the writer are called by
:class:`NullFormatter` instances. Implementations should inherit from this
class if implementing a writer interface but don't need to inherit any
implementation.
.. class:: AbstractFormatter(writer)
The standard formatter. This implementation has demonstrated wide applicability
to many writers, and may be used directly in most circumstances. It has been
used to implement a full-featured World Wide Web browser.
.. _writer-interface:
The Writer Interface
--------------------
Interfaces to create writers are dependent on the specific writer class being
instantiated. The interfaces described below are the required interfaces which
all writers must support once initialized. Note that while most applications can
use the :class:`AbstractFormatter` class as a formatter, the writer must
typically be provided by the application.
.. method:: writer.flush()
Flush any buffered output or device control events.
.. method:: writer.new_alignment(align)
Set the alignment style. The *align* value can be any object, but by convention
is a string or ``None``, where ``None`` indicates that the writer's "preferred"
alignment should be used. Conventional *align* values are ``'left'``,
``'center'``, ``'right'``, and ``'justify'``.
.. method:: writer.new_font(font)
Set the font style. The value of *font* will be ``None``, indicating that the
device's default font should be used, or a tuple of the form ``(size,
italic, bold, teletype)``. Size will be a string indicating the size of
font that should be used; specific strings and their interpretation must be
defined by the application. The *italic*, *bold*, and *teletype* values are
Boolean values specifying which of those font attributes should be used.
.. method:: writer.new_margin(margin, level)
Set the margin level to the integer *level* and the logical tag to *margin*.
Interpretation of the logical tag is at the writer's discretion; the only
restriction on the value of the logical tag is that it not be a false value for
non-zero values of *level*.
.. method:: writer.new_spacing(spacing)
Set the spacing style to *spacing*.
.. method:: writer.new_styles(styles)
Set additional styles. The *styles* value is a tuple of arbitrary values; the
value :const:`AS_IS` should be ignored. The *styles* tuple may be interpreted
either as a set or as a stack depending on the requirements of the application
and writer implementation.
.. method:: writer.send_line_break()
Break the current line.
.. method:: writer.send_paragraph(blankline)
Produce a paragraph separation of at least *blankline* blank lines, or the
equivalent. The *blankline* value will be an integer. Note that the
implementation will receive a call to :meth:`send_line_break` before this call
if a line break is needed; this method should not include ending the last line
of the paragraph. It is only responsible for vertical spacing between
paragraphs.
.. method:: writer.send_hor_rule(*args, **kw)
Display a horizontal rule on the output device. The arguments to this method
are entirely application- and writer-specific, and should be interpreted with
care. The method implementation may assume that a line break has already been
issued via :meth:`send_line_break`.
.. method:: writer.send_flowing_data(data)
Output character data which may be word-wrapped and re-flowed as needed. Within
any sequence of calls to this method, the writer may assume that spans of
multiple whitespace characters have been collapsed to single space characters.
.. method:: writer.send_literal_data(data)
Output character data which has already been formatted for display. Generally,
this should be interpreted to mean that line breaks indicated by newline
characters should be preserved and no new line breaks should be introduced. The
data may contain embedded newline and tab characters, unlike data provided to
the :meth:`send_formatted_data` interface.
.. method:: writer.send_label_data(data)
Set *data* to the left of the current left margin, if possible. The value of
*data* is not restricted; treatment of non-string values is entirely
application- and writer-dependent. This method will only be called at the
beginning of a line.
.. _writer-impls:
Writer Implementations
----------------------
Three implementations of the writer object interface are provided as examples by
this module. Most applications will need to derive new writer classes from the
:class:`NullWriter` class.
.. class:: NullWriter()
A writer which only provides the interface definition; no actions are taken on
any methods. This should be the base class for all writers which do not need to
inherit any implementation methods.
.. class:: AbstractWriter()
A writer which can be used in debugging formatters, but not much else. Each
method simply announces itself by printing its name and arguments on standard
output.
.. class:: DumbWriter(file=None, maxcol=72)
Simple writer class which writes output on the :term:`file object` passed
in as *file* or, if *file* is omitted, on standard output. The output is
simply word-wrapped to the number of columns specified by *maxcol*. This
class is suitable for reflowing a sequence of paragraphs.

19
Doc/library/functions.rst
View File

@ -478,14 +478,15 @@ are always available. They are listed here in alphabetical order.
dictionaries as global and local namespace. If the *globals* dictionary is
present and does not contain a value for the key ``__builtins__``, a
reference to the dictionary of the built-in module :mod:`builtins` is
inserted under that key before *expression* is parsed. This means that
*expression* normally has full access to the standard :mod:`builtins`
module and restricted environments are propagated. If the *locals*
dictionary is omitted it defaults to the *globals* dictionary. If both
dictionaries are omitted, the expression is executed with the *globals* and
*locals* in the environment where :func:`eval` is called. Note, *eval()*
does not have access to the :term:`nested scopes <nested scope>` (non-locals) in the
enclosing environment.
inserted under that key before *expression* is parsed. That way you can
control what builtins are available to the executed code by inserting your
own ``__builtins__`` dictionary into *globals* before passing it to
:func:`eval`. If the *locals* dictionary is omitted it defaults to the
*globals* dictionary. If both dictionaries are omitted, the expression is
executed with the *globals* and *locals* in the environment where
:func:`eval` is called. Note, *eval()* does not have access to the
:term:`nested scopes <nested scope>` (non-locals) in the enclosing
environment.
The return value is the result of
the evaluated expression. Syntax errors are reported as exceptions. Example:
@ -1333,7 +1334,7 @@ are always available. They are listed here in alphabetical order.
supported.
.. function:: print(*objects, sep=' ', end='\\n', file=sys.stdout, flush=False)
.. function:: print(*objects, sep=' ', end='\n', file=sys.stdout, flush=False)
Print *objects* to the text stream *file*, separated by *sep* and followed
by *end*. *sep*, *end*, *file* and *flush*, if present, must be given as keyword

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

2
Doc/library/http.cookies.rst
View File

@ -93,7 +93,7 @@ Cookie Objects
:meth:`value_decode` are inverses on the range of *value_decode*.
.. method:: BaseCookie.output(attrs=None, header='Set-Cookie:', sep='\\r\\n')
.. method:: BaseCookie.output(attrs=None, header='Set-Cookie:', sep='\r\n')
Return a string representation suitable to be sent as HTTP headers. *attrs* and
*header* are sent to each :class:`Morsel`'s :meth:`output` method. *sep* is used

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:

4
Doc/library/importlib.rst
View File

@ -1138,7 +1138,7 @@ find and load modules.
directory for ``''`` (i.e. the empty string).
.. class:: FileFinder(path, \*loader_details)
.. class:: FileFinder(path, *loader_details)
A concrete implementation of :class:`importlib.abc.PathEntryFinder` which
caches results from the file system.
@ -1181,7 +1181,7 @@ find and load modules.
Clear out the internal cache.
.. classmethod:: path_hook(\*loader_details)
.. classmethod:: path_hook(*loader_details)
A class method which returns a closure for use on :attr:`sys.path_hooks`.
An instance of :class:`FileFinder` is returned by the closure using the

1
Doc/library/index.rst
View File

@ -72,7 +72,6 @@ the `Python Package Index <https://pypi.org>`_.
custominterp.rst
modules.rst
language.rst
misc.rst
windows.rst
unix.rst
superseded.rst

26
Doc/library/inspect.rst
View File

@ -556,7 +556,7 @@ The Signature object represents the call signature of a callable object and its
return annotation. To retrieve a Signature object, use the :func:`signature`
function.
.. function:: signature(callable, \*, follow_wrapped=True)
.. function:: signature(callable, *, follow_wrapped=True, globalns=None, localns=None)
Return a :class:`Signature` object for the given ``callable``::
@ -581,6 +581,9 @@ function.
Raises :exc:`ValueError` if no signature can be provided, and
:exc:`TypeError` if that type of object is not supported.
``globalns`` and ``localns`` are passed into
:func:`typing.get_type_hints` when resolving the annotations.
A slash(/) in the signature of a function denotes that the parameters prior
to it are positional-only. For more info, see
:ref:`the FAQ entry on positional-only parameters <faq-positional-only-arguments>`.
@ -590,14 +593,23 @@ function.
``callable`` specifically (``callable.__wrapped__`` will not be used to
unwrap decorated callables.)
.. versionadded:: 3.10
``globalns`` and ``localns`` parameters.
.. note::
Some callables may not be introspectable in certain implementations of
Python. For example, in CPython, some built-in functions defined in
C provide no metadata about their arguments.
.. note::
.. class:: Signature(parameters=None, \*, return_annotation=Signature.empty)
Will first try to resolve the annotations, but when it fails and
encounters with an error while that operation, the annotations will be
returned unchanged (as strings).
.. class:: Signature(parameters=None, *, return_annotation=Signature.empty)
A Signature object represents the call signature of a function and its return
annotation. For each parameter accepted by the function it stores a
@ -668,11 +680,12 @@ function.
>>> str(new_sig)
"(a, b) -> 'new return anno'"
.. classmethod:: Signature.from_callable(obj, \*, follow_wrapped=True)
.. classmethod:: Signature.from_callable(obj, *, follow_wrapped=True, globalns=None, localns=None)
Return a :class:`Signature` (or its subclass) object for a given callable
``obj``. Pass ``follow_wrapped=False`` to get a signature of ``obj``
without unwrapping its ``__wrapped__`` chain.
without unwrapping its ``__wrapped__`` chain. ``globalns`` and
``localns`` will be used as the namespaces when resolving annotations.
This method simplifies subclassing of :class:`Signature`::
@ -683,8 +696,11 @@ function.
.. versionadded:: 3.5
.. versionadded:: 3.10
``globalns`` and ``localns`` parameters.
.. class:: Parameter(name, kind, \*, default=Parameter.empty, annotation=Parameter.empty)
.. class:: Parameter(name, kind, *, default=Parameter.empty, annotation=Parameter.empty)
Parameter objects are *immutable*. Instead of modifying a Parameter object,
you can use :meth:`Parameter.replace` to create a modified copy.

2
Doc/library/io.rst
View File

@ -964,7 +964,7 @@ Text I/O
.. versionadded:: 3.7
.. class:: StringIO(initial_value='', newline='\\n')
.. class:: StringIO(initial_value='', newline='\n')
A text stream using an in-memory text buffer. It inherits
:class:`TextIOBase`.

47
Doc/library/itertools.rst
View File

@ -55,6 +55,7 @@ Iterator Arguments Results
:func:`filterfalse` pred, seq elements of seq where pred(elem) is false ``filterfalse(lambda x: x%2, range(10)) --> 0 2 4 6 8``
:func:`groupby` iterable[, key] sub-iterators grouped by value of key(v)
:func:`islice` seq, [start,] stop [, step] elements from seq[start:stop:step] ``islice('ABCDEFG', 2, None) --> C D E F G``
:func:`pairwise` iterable (p[0], p[1]), (p[1], p[2]) ``pairwise('ABCDEFG') --> AB BC CD DE EF FG``
:func:`starmap` func, seq func(\*seq[0]), func(\*seq[1]), ... ``starmap(pow, [(2,5), (3,2), (10,3)]) --> 32 9 1000``
:func:`takewhile` pred, seq seq[0], seq[1], until pred fails ``takewhile(lambda x: x<5, [1,4,6,4,1]) --> 1 4``
:func:`tee` it, n it1, it2, ... itn splits one iterator into n
@ -475,6 +476,22 @@ loops that truncate the stream.
If *start* is ``None``, then iteration starts at zero. If *step* is ``None``,
then the step defaults to one.
.. function:: pairwise(iterable)
Return successive overlapping pairs taken from the input *iterable*.
The number of 2-tuples in the output iterator will be one fewer than the
number of inputs. It will be empty if the input iterable has fewer than
two values.
Roughly equivalent to::
def pairwise(iterable):
# pairwise('ABCDEFG') --> AB BC CD DE EF FG
a, b = tee(iterable)
next(b, None)
return zip(a, b)
.. function:: permutations(iterable, r=None)
@ -565,7 +582,7 @@ loops that truncate the stream.
Before :func:`product` runs, it completely consumes the input iterables,
keeping pools of values in memory to generate the products. Accordingly,
it only useful with finite inputs.
it is only useful with finite inputs.
.. function:: repeat(object[, times])
@ -755,7 +772,7 @@ which incur interpreter overhead.
"Count how many times the predicate is true"
return sum(map(pred, iterable))
def padnone(iterable):
def pad_none(iterable):
"""Returns the sequence elements and then returns None indefinitely.
Useful for emulating the behavior of the built-in map() function.
@ -769,6 +786,18 @@ which incur interpreter overhead.
def dotproduct(vec1, vec2):
return sum(map(operator.mul, vec1, vec2))
def convolve(signal, kernel):
# See: https://betterexplained.com/articles/intuitive-convolution/
# convolve(data, [0.25, 0.25, 0.25, 0.25]) --> Moving average (blur)
# convolve(data, [1, -1]) --> 1st finite difference (1st derivative)
# convolve(data, [1, -2, 1]) --> 2nd finite difference (2nd derivative)
kernel = list(reversed(kernel))
n = len(kernel)
window = collections.deque([0] * n, maxlen=n)
for x in chain(signal, repeat(0, n-1)):
window.append(x)
yield sum(map(operator.mul, kernel, window))
def flatten(list_of_lists):
"Flatten one level of nesting"
return chain.from_iterable(list_of_lists)
@ -782,12 +811,6 @@ which incur interpreter overhead.
return starmap(func, repeat(args))
return starmap(func, repeat(args, times))
def pairwise(iterable):
"s -> (s0,s1), (s1,s2), (s2, s3), ..."
a, b = tee(iterable)
next(b, None)
return zip(a, b)
def grouper(iterable, n, fillvalue=None):
"Collect data into fixed-length chunks or blocks"
# grouper('ABCDEFG', 3, 'x') --> ABC DEF Gxx"
@ -809,7 +832,7 @@ which incur interpreter overhead.
nexts = cycle(islice(nexts, num_active))
def partition(pred, iterable):
'Use a predicate to partition entries into false entries and true entries'
"Use a predicate to partition entries into false entries and true entries"
# partition(is_odd, range(10)) --> 0 2 4 6 8 and 1 3 5 7 9
t1, t2 = tee(iterable)
return filterfalse(pred, t1), filter(pred, t2)
@ -881,7 +904,7 @@ which incur interpreter overhead.
def random_product(*args, repeat=1):
"Random selection from itertools.product(*args, **kwds)"
pools = [tuple(pool) for pool in args] * repeat
return tuple(random.choice(pool) for pool in pools)
return tuple(map(random.choice, pools))
def random_permutation(iterable, r=None):
"Random selection from itertools.permutations(iterable, r)"
@ -900,11 +923,11 @@ which incur interpreter overhead.
"Random selection from itertools.combinations_with_replacement(iterable, r)"
pool = tuple(iterable)
n = len(pool)
indices = sorted(random.randrange(n) for i in range(r))
indices = sorted(random.choices(range(n), k=r))
return tuple(pool[i] for i in indices)
def nth_combination(iterable, r, index):
'Equivalent to list(combinations(iterable, r))[index]'
"Equivalent to list(combinations(iterable, r))[index]"
pool = tuple(iterable)
n = len(pool)
if r < 0 or r > n:

66
Doc/library/logging.config.rst
View File

@ -35,45 +35,45 @@ in :mod:`logging` itself) and defining handlers which are declared either in
.. function:: dictConfig(config)
Takes the logging configuration from a dictionary. The contents of
this dictionary are described in :ref:`logging-config-dictschema`
below.
Takes the logging configuration from a dictionary. The contents of
this dictionary are described in :ref:`logging-config-dictschema`
below.
If an error is encountered during configuration, this function will
raise a :exc:`ValueError`, :exc:`TypeError`, :exc:`AttributeError`
or :exc:`ImportError` with a suitably descriptive message. The
following is a (possibly incomplete) list of conditions which will
raise an error:
If an error is encountered during configuration, this function will
raise a :exc:`ValueError`, :exc:`TypeError`, :exc:`AttributeError`
or :exc:`ImportError` with a suitably descriptive message. The
following is a (possibly incomplete) list of conditions which will
raise an error:
* A ``level`` which is not a string or which is a string not
corresponding to an actual logging level.
* A ``propagate`` value which is not a boolean.
* An id which does not have a corresponding destination.
* A non-existent handler id found during an incremental call.
* An invalid logger name.
* Inability to resolve to an internal or external object.
* A ``level`` which is not a string or which is a string not
corresponding to an actual logging level.
* A ``propagate`` value which is not a boolean.
* An id which does not have a corresponding destination.
* A non-existent handler id found during an incremental call.
* An invalid logger name.
* Inability to resolve to an internal or external object.
Parsing is performed by the :class:`DictConfigurator` class, whose
constructor is passed the dictionary used for configuration, and
has a :meth:`configure` method. The :mod:`logging.config` module
has a callable attribute :attr:`dictConfigClass`
which is initially set to :class:`DictConfigurator`.
You can replace the value of :attr:`dictConfigClass` with a
suitable implementation of your own.
Parsing is performed by the :class:`DictConfigurator` class, whose
constructor is passed the dictionary used for configuration, and
has a :meth:`configure` method. The :mod:`logging.config` module
has a callable attribute :attr:`dictConfigClass`
which is initially set to :class:`DictConfigurator`.
You can replace the value of :attr:`dictConfigClass` with a
suitable implementation of your own.
:func:`dictConfig` calls :attr:`dictConfigClass` passing
the specified dictionary, and then calls the :meth:`configure` method on
the returned object to put the configuration into effect::
:func:`dictConfig` calls :attr:`dictConfigClass` passing
the specified dictionary, and then calls the :meth:`configure` method on
the returned object to put the configuration into effect::
def dictConfig(config):
dictConfigClass(config).configure()
def dictConfig(config):
dictConfigClass(config).configure()
For example, a subclass of :class:`DictConfigurator` could call
``DictConfigurator.__init__()`` in its own :meth:`__init__()`, then
set up custom prefixes which would be usable in the subsequent
:meth:`configure` call. :attr:`dictConfigClass` would be bound to
this new subclass, and then :func:`dictConfig` could be called exactly as
in the default, uncustomized state.
For example, a subclass of :class:`DictConfigurator` could call
``DictConfigurator.__init__()`` in its own :meth:`__init__()`, then
set up custom prefixes which would be usable in the subsequent
:meth:`configure` call. :attr:`dictConfigClass` would be bound to
this new subclass, and then :func:`dictConfig` could be called exactly as
in the default, uncustomized state.
.. versionadded:: 3.2

8
Doc/library/logging.rst
View File

@ -1096,8 +1096,8 @@ functions.
suitable value.
.. versionchanged:: 3.7
The *level* parameter was defaulted to level ``CRITICAL``. See Issue
#28524 for more information about this change.
The *level* parameter was defaulted to level ``CRITICAL``. See
:issue:`28524` for more information about this change.
.. function:: addLevelName(level, levelName)
@ -1174,7 +1174,9 @@ functions.
| | to ``'a'``. |
+--------------+---------------------------------------------+
| *format* | Use the specified format string for the |
| | handler. |
| | handler. Defaults to attributes |
| | ``levelname``, ``name`` and ``message`` |
| | separated by colons. |
+--------------+---------------------------------------------+
| *datefmt* | Use the specified date/time format, as |
| | accepted by :func:`time.strftime`. |

4
Doc/library/lzma.rst
View File

@ -33,7 +33,7 @@ from multiple threads, it is necessary to protect it with a lock.
Reading and writing compressed files
------------------------------------
.. function:: open(filename, mode="rb", \*, format=None, check=-1, preset=None, filters=None, encoding=None, errors=None, newline=None)
.. function:: open(filename, mode="rb", *, format=None, check=-1, preset=None, filters=None, encoding=None, errors=None, newline=None)
Open an LZMA-compressed file in binary or text mode, returning a :term:`file
object`.
@ -69,7 +69,7 @@ Reading and writing compressed files
Accepts a :term:`path-like object`.
.. class:: LZMAFile(filename=None, mode="r", \*, format=None, check=-1, preset=None, filters=None)
.. class:: LZMAFile(filename=None, mode="r", *, format=None, check=-1, preset=None, filters=None)
Open an LZMA-compressed file in binary mode.

13
Doc/library/misc.rst
View File

@ -1,13 +0,0 @@
.. _misc:
**********************
Miscellaneous Services
**********************
The modules described in this chapter provide miscellaneous services that are
available in all Python versions. Here's an overview:
.. toctree::
formatter.rst

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.

48
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*.
@ -2569,9 +2569,9 @@ Address Formats
filesystem.
* An ``'AF_PIPE'`` address is a string of the form
:samp:`r'\\\\.\\pipe\\{PipeName}'`. To use :func:`Client` to connect to a named
pipe on a remote computer called *ServerName* one should use an address of the
form :samp:`r'\\\\{ServerName}\\pipe\\{PipeName}'` instead.
:samp:`r'\\\\.\\pipe\\{PipeName}'`. To use :func:`Client` to connect to a named
pipe on a remote computer called *ServerName* one should use an address of the
form :samp:`r'\\\\{ServerName}\\pipe\\{PipeName}'` instead.
Note that any string beginning with two backslashes is assumed by default to be
an ``'AF_PIPE'`` address rather than an ``'AF_UNIX'`` address.
@ -2661,6 +2661,46 @@ The :mod:`multiprocessing.dummy` module
:mod:`multiprocessing.dummy` replicates the API of :mod:`multiprocessing` but is
no more than a wrapper around the :mod:`threading` module.
.. currentmodule:: multiprocessing.pool
In particular, the ``Pool`` function provided by :mod:`multiprocessing.dummy`
returns an instance of :class:`ThreadPool`, which is a subclass of
:class:`Pool` that supports all the same method calls but uses a pool of
worker threads rather than worker processes.
.. class:: ThreadPool([processes[, initializer[, initargs]]])
A thread pool object which controls a pool of worker threads to which jobs
can be submitted. :class:`ThreadPool` instances are fully interface
compatible with :class:`Pool` instances, and their resources must also be
properly managed, either by using the pool as a context manager or by
calling :meth:`~multiprocessing.pool.Pool.close` and
:meth:`~multiprocessing.pool.Pool.terminate` manually.
*processes* is the number of worker threads to use. If *processes* is
``None`` then the number returned by :func:`os.cpu_count` is used.
If *initializer* is not ``None`` then each worker process will call
``initializer(*initargs)`` when it starts.
Unlike :class:`Pool`, *maxtasksperchild* and *context* cannot be provided.
.. note::
A :class:`ThreadPool` shares the same interface as :class:`Pool`, which
is designed around a pool of processes and predates the introduction of
the :class:`concurrent.futures` module. As such, it inherits some
operations that don't make sense for a pool backed by threads, and it
has its own type for representing the status of asynchronous jobs,
:class:`AsyncResult`, that is not understood by any other libraries.
Users should generally prefer to use
:class:`concurrent.futures.ThreadPoolExecutor`, which has a simpler
interface that was designed around threads from the start, and which
returns :class:`concurrent.futures.Future` instances that are
compatible with many other libraries, including :mod:`asyncio`.
.. _multiprocessing-programming:

161
Doc/library/os.rst
View File

@ -32,7 +32,7 @@ Notes on the availability of these functions:
objects, and result in an object of the same type, if a path or file name is
returned.
* On VxWorks, os.fork, os.execv and os.spawn*p* are not supported.
* On VxWorks, os.popen, os.fork, os.execv and os.spawn*p* are not supported.
.. note::
@ -113,6 +113,8 @@ of the UTF-8 encoding:
: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
@ -808,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)
@ -1315,12 +1323,12 @@ or `the MSDN <https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windo
.. data:: RWF_APPEND
Provide a per-write equivalent of the :data:`O_APPEND` :func:`os.open`
flag. This flag is meaningful only for :func:`os.pwritev`, and its
effect applies only to the data range written by the system call. The
*offset* argument does not affect the write operation; the data is always
appended to the end of the file. However, if the *offset* argument is
``-1``, the current file *offset* is updated.
Provide a per-write equivalent of the :data:`O_APPEND` :func:`os.open`
flag. This flag is meaningful only for :func:`os.pwritev`, and its
effect applies only to the data range written by the system call. The
*offset* argument does not affect the write operation; the data is always
appended to the end of the file. However, if the *offset* argument is
``-1``, the current file *offset* is updated.
.. availability:: Linux 4.16 and newer.
@ -1411,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
@ -1950,7 +1991,7 @@ features:
Accepts a :term:`path-like object`.
.. function:: lstat(path, \*, dir_fd=None)
.. function:: lstat(path, *, dir_fd=None)
Perform the equivalent of an :c:func:`lstat` system call on the given path.
Similar to :func:`~os.stat`, but does not follow symbolic links. Return a
@ -2457,7 +2498,7 @@ features:
On the first, uncached call, a system call is required on Windows but
not on Unix.
.. method:: is_dir(\*, follow_symlinks=True)
.. method:: is_dir(*, follow_symlinks=True)
Return ``True`` if this entry is a directory or a symbolic link pointing
to a directory; return ``False`` if the entry is or points to any other
@ -2481,7 +2522,7 @@ features:
This method can raise :exc:`OSError`, such as :exc:`PermissionError`,
but :exc:`FileNotFoundError` is caught and not raised.
.. method:: is_file(\*, follow_symlinks=True)
.. method:: is_file(*, follow_symlinks=True)
Return ``True`` if this entry is a file or a symbolic link pointing to a
file; return ``False`` if the entry is or points to a directory or other
@ -2511,7 +2552,7 @@ features:
This method can raise :exc:`OSError`, such as :exc:`PermissionError`,
but :exc:`FileNotFoundError` is caught and not raised.
.. method:: stat(\*, follow_symlinks=True)
.. method:: stat(*, follow_symlinks=True)
Return a :class:`stat_result` object for this entry. This method
follows symbolic links by default; to stat a symbolic link add the
@ -2543,7 +2584,7 @@ features:
for :class:`bytes` paths on Windows.
.. function:: stat(path, \*, dir_fd=None, follow_symlinks=True)
.. function:: stat(path, *, dir_fd=None, follow_symlinks=True)
Get the status of a file or a file descriptor. Perform the equivalent of a
:c:func:`stat` system call on the given path. *path* may be specified as
@ -3268,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
~~~~~~~~~~~~~~~~~~~~~~~~~

2
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

12
Doc/library/pickle.rst
View File

@ -213,7 +213,7 @@ The :mod:`pickle` module provides the following constants:
The :mod:`pickle` module provides the following functions to make the pickling
process more convenient:
.. function:: dump(obj, file, protocol=None, \*, fix_imports=True, buffer_callback=None)
.. function:: dump(obj, file, protocol=None, *, fix_imports=True, buffer_callback=None)
Write the pickled representation of the object *obj* to the open
:term:`file object` *file*. This is equivalent to
@ -225,7 +225,7 @@ process more convenient:
.. versionchanged:: 3.8
The *buffer_callback* argument was added.
.. function:: dumps(obj, protocol=None, \*, fix_imports=True, buffer_callback=None)
.. function:: dumps(obj, protocol=None, *, fix_imports=True, buffer_callback=None)
Return the pickled representation of the object *obj* as a :class:`bytes` object,
instead of writing it to a file.
@ -236,7 +236,7 @@ process more convenient:
.. versionchanged:: 3.8
The *buffer_callback* argument was added.
.. function:: load(file, \*, fix_imports=True, encoding="ASCII", errors="strict", buffers=None)
.. function:: load(file, *, fix_imports=True, encoding="ASCII", errors="strict", buffers=None)
Read the pickled representation of an object from the open :term:`file object`
*file* and return the reconstituted object hierarchy specified therein.
@ -252,7 +252,7 @@ process more convenient:
.. versionchanged:: 3.8
The *buffers* argument was added.
.. function:: loads(data, /, \*, fix_imports=True, encoding="ASCII", errors="strict", buffers=None)
.. function:: loads(data, /, *, fix_imports=True, encoding="ASCII", errors="strict", buffers=None)
Return the reconstituted object hierarchy of the pickled representation
*data* of an object. *data* must be a :term:`bytes-like object`.
@ -296,7 +296,7 @@ The :mod:`pickle` module defines three exceptions:
The :mod:`pickle` module exports three classes, :class:`Pickler`,
:class:`Unpickler` and :class:`PickleBuffer`:
.. class:: Pickler(file, protocol=None, \*, fix_imports=True, buffer_callback=None)
.. class:: Pickler(file, protocol=None, *, fix_imports=True, buffer_callback=None)
This takes a binary file for writing a pickle data stream.
@ -391,7 +391,7 @@ The :mod:`pickle` module exports three classes, :class:`Pickler`,
Use :func:`pickletools.optimize` if you need more compact pickles.
.. class:: Unpickler(file, \*, fix_imports=True, encoding="ASCII", errors="strict", buffers=None)
.. class:: Unpickler(file, *, fix_imports=True, encoding="ASCII", errors="strict", buffers=None)
This takes a binary file for reading a pickle data stream.

2
Doc/library/pipes.rst
View File

@ -17,6 +17,8 @@ The :mod:`pipes` module defines a class to abstract the concept of a *pipeline*
Because the module uses :program:`/bin/sh` command lines, a POSIX or compatible
shell for :func:`os.system` and :func:`os.popen` is required.
.. availability:: Unix. Not available on VxWorks.
The :mod:`pipes` module defines the following class:

45
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
@ -260,3 +253,41 @@ Unix Platforms
using :program:`gcc`.
The file is read and scanned in chunks of *chunksize* bytes.
Linux Platforms
---------------
.. function:: freedesktop_os_release()
Get operating system identification from ``os-release`` file and return
it as a dict. The ``os-release`` file is a `freedesktop.org standard
<https://www.freedesktop.org/software/systemd/man/os-release.html>`_ and
is available in most Linux distributions. A noticeable exception is
Android and Android-based distributions.
Raises :exc:`OSError` or subclass when neither ``/etc/os-release`` nor
``/usr/lib/os-release`` can be read.
On success, the function returns a dictionary where keys and values are
strings. Values have their special characters like ``"`` and ``$``
unquoted. The fields ``NAME``, ``ID``, and ``PRETTY_NAME`` are always
defined according to the standard. All other fields are optional. Vendors
may include additional fields.
Note that fields like ``NAME``, ``VERSION``, and ``VARIANT`` are strings
suitable for presentation to users. Programs should use fields like
``ID``, ``ID_LIKE``, ``VERSION_ID``, or ``VARIANT_ID`` to identify
Linux distributions.
Example::
def get_like_distro():
info = platform.freedesktop_os_release()
ids = [info["ID"]]
if "ID_LIKE" in info:
# ids are space separated and ordered by precedence
ids.extend(info["ID_LIKE"].split())
return ids
.. versionadded:: 3.10

8
Doc/library/plistlib.rst
View File

@ -52,7 +52,7 @@ or :class:`datetime.datetime` objects.
This module defines the following functions:
.. function:: load(fp, \*, fmt=None, dict_type=dict)
.. function:: load(fp, *, fmt=None, dict_type=dict)
Read a plist file. *fp* should be a readable and binary file object.
Return the unpacked root object (which usually is a
@ -80,7 +80,7 @@ This module defines the following functions:
.. versionadded:: 3.4
.. function:: loads(data, \*, fmt=None, dict_type=dict)
.. function:: loads(data, *, fmt=None, dict_type=dict)
Load a plist from a bytes object. See :func:`load` for an explanation of
the keyword arguments.
@ -88,7 +88,7 @@ This module defines the following functions:
.. versionadded:: 3.4
.. function:: dump(value, fp, \*, fmt=FMT_XML, sort_keys=True, skipkeys=False)
.. function:: dump(value, fp, *, fmt=FMT_XML, sort_keys=True, skipkeys=False)
Write *value* to a plist file. *Fp* should be a writable, binary
file object.
@ -116,7 +116,7 @@ This module defines the following functions:
.. versionadded:: 3.4
.. function:: dumps(value, \*, fmt=FMT_XML, sort_keys=True, skipkeys=False)
.. function:: dumps(value, *, fmt=FMT_XML, sort_keys=True, skipkeys=False)
Return *value* as a plist-formatted bytes object. See
the documentation for :func:`dump` for an explanation of the keyword

8
Doc/library/profile.rst
View File

@ -525,16 +525,16 @@ Analysis of the profiler data is done using the :class:`~pstats.Stats` class.
ordering are identical to the :meth:`~pstats.Stats.print_callers` method.
.. method:: get_stats_profile()
.. method:: get_stats_profile()
This method returns an instance of StatsProfile, which contains a mapping
of function names to instances of FunctionProfile. Each FunctionProfile
instance holds information related to the function's profile such as how
long the function took to run, how many times it was called, etc...
.. versionadded:: 3.9
Added the following dataclasses: StatsProfile, FunctionProfile.
Added the following function: get_stats_profile.
.. versionadded:: 3.9
Added the following dataclasses: StatsProfile, FunctionProfile.
Added the following function: get_stats_profile.
.. _deterministic-profiling:

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

9
Doc/library/random.rst
View File

@ -142,10 +142,11 @@ Functions for integers
.. function:: getrandbits(k)
Returns a Python integer with *k* random bits. This method is supplied with
the MersenneTwister generator and some other generators may also provide it
as an optional part of the API. When available, :meth:`getrandbits` enables
:meth:`randrange` to handle arbitrarily large ranges.
Returns a non-negative Python integer with *k* random bits. This method
is supplied with the MersenneTwister generator and some other generators
may also provide it as an optional part of the API. When available,
:meth:`getrandbits` enables :meth:`randrange` to handle arbitrarily large
ranges.
.. versionchanged:: 3.9
This method now accepts zero for *k*.

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/shutil.rst
View File

@ -218,7 +218,7 @@ Directory and files operations
copy the file more efficiently. See
:ref:`shutil-platform-dependent-efficient-copy-operations` section.
.. function:: ignore_patterns(\*patterns)
.. function:: ignore_patterns(*patterns)
This factory function creates a function that can be used as a callable for
:func:`copytree`\'s *ignore* argument, ignoring files and directories that

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

17
Doc/library/socket.rst
View File

@ -56,12 +56,12 @@ created. Socket addresses are represented as follows:
bytes-like object can be used for either type of address when
passing it as an argument.
.. versionchanged:: 3.3
Previously, :const:`AF_UNIX` socket paths were assumed to use UTF-8
encoding.
.. versionchanged:: 3.3
Previously, :const:`AF_UNIX` socket paths were assumed to use UTF-8
encoding.
.. versionchanged:: 3.5
Writable :term:`bytes-like object` is now accepted.
.. versionchanged:: 3.5
Writable :term:`bytes-like object` is now accepted.
.. _host_port:
@ -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
^^^^^^^^^
@ -1208,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

4
Doc/library/sqlite3.rst
View File

@ -198,7 +198,9 @@ Module functions and constants
*detect_types* defaults to 0 (i. e. off, no type detection), you can set it to
any combination of :const:`PARSE_DECLTYPES` and :const:`PARSE_COLNAMES` to turn
type detection on.
type detection on. Due to SQLite behaviour, types can't be detected for generated
fields (for example ``max(data)``), even when *detect_types* parameter is set. In
such case, the returned type is :class:`str`.
By default, *check_same_thread* is :const:`True` and only the creating thread may
use the connection. If set :const:`False`, the returned connection may be shared

21
Doc/library/statistics.rst
View File

@ -156,10 +156,11 @@ However, for reading convenience, most of the examples show sorted sequences.
.. versionadded:: 3.8
.. function:: harmonic_mean(data)
.. function:: harmonic_mean(data, weights=None)
Return the harmonic mean of *data*, a sequence or iterable of
real-valued numbers.
real-valued numbers. If *weights* is omitted or *None*, then
equal weighting is assumed.
The harmonic mean, sometimes called the subcontrary mean, is the
reciprocal of the arithmetic :func:`mean` of the reciprocals of the
@ -179,17 +180,17 @@ However, for reading convenience, most of the examples show sorted sequences.
>>> harmonic_mean([40, 60])
48.0
Suppose an investor purchases an equal value of shares in each of
three companies, with P/E (price/earning) ratios of 2.5, 3 and 10.
What is the average P/E ratio for the investor's portfolio?
Suppose a car travels 40 km/hr for 5 km, and when traffic clears,
speeds-up to 60 km/hr for the remaining 30 km of the journey. What
is the average speed?
.. doctest::
>>> harmonic_mean([2.5, 3, 10]) # For an equal investment portfolio.
3.6
>>> harmonic_mean([40, 60], weights=[5, 30])
56.0
:exc:`StatisticsError` is raised if *data* is empty, or any element
is less than zero.
:exc:`StatisticsError` is raised if *data* is empty, any element
is less than zero, or if the weighted sum isn't positive.
The current algorithm has an early-out when it encounters a zero
in the input. This means that the subsequent inputs are not tested
@ -197,6 +198,8 @@ However, for reading convenience, most of the examples show sorted sequences.
.. versionadded:: 3.6
.. versionchanged:: 3.8
Added support for *weights*.
.. function:: median(data)

10
Doc/library/stdtypes.rst
View File

@ -499,7 +499,7 @@ class`. In addition, it provides a few more methods:
.. versionadded:: 3.10
.. method:: int.to_bytes(length, byteorder, \*, signed=False)
.. method:: int.to_bytes(length, byteorder, *, signed=False)
Return an array of bytes representing an integer.
@ -531,7 +531,7 @@ class`. In addition, it provides a few more methods:
.. versionadded:: 3.2
.. classmethod:: int.from_bytes(bytes, byteorder, \*, signed=False)
.. classmethod:: int.from_bytes(bytes, byteorder, *, signed=False)
Return the integer represented by the given array of bytes.
@ -5065,7 +5065,7 @@ instantiated from the type::
>>> class M(type):
... def __or__(self, other):
... return "Hello"
... return "Hello"
...
>>> class C(metaclass=M):
... pass
@ -5353,8 +5353,8 @@ types, where they are relevant. Some of these are not reported by the
.. method:: class.__subclasses__
Each class keeps a list of weak references to its immediate subclasses. This
method returns a list of all those references still alive.
Example::
method returns a list of all those references still alive. The list is in
definition order. Example::
>>> int.__subclasses__()
[<class 'bool'>]

70
Doc/library/string.rst
View File

@ -384,10 +384,10 @@ following:
The ``'#'`` option causes the "alternate form" to be used for the
conversion. The alternate form is defined differently for different
types. This option is only valid for integer, float, complex and
Decimal types. For integers, when binary, octal, or hexadecimal output
types. This option is only valid for integer, float and complex
types. For integers, when binary, octal, or hexadecimal output
is used, this option adds the prefix respective ``'0b'``, ``'0o'``, or
``'0x'`` to the output value. For floats, complex and Decimal the
``'0x'`` to the output value. For float and complex the
alternate form causes the result of the conversion to always contain a
decimal-point character, even if no digits follow it. Normally, a
decimal-point character appears in the result of these conversions
@ -476,20 +476,36 @@ with the floating point presentation types listed below (except
``'n'`` and ``None``). When doing so, :func:`float` is used to convert the
integer to a floating point number before formatting.
The available presentation types for floating point and decimal values are:
The available presentation types for :class:`float` and
:class:`~decimal.Decimal` values are:
+---------+----------------------------------------------------------+
| Type | Meaning |
+=========+==========================================================+
| ``'e'`` | Exponent notation. Prints the number in scientific |
| | notation using the letter 'e' to indicate the exponent. |
| | The default precision is ``6``. |
| ``'e'`` | Scientific notation. For a given precision ``p``, |
| | formats the number in scientific notation with the |
| | letter 'e' separating the coefficient from the exponent. |
| | The coefficient has one digit before and ``p`` digits |
| | after the decimal point, for a total of ``p + 1`` |
| | significant digits. With no precision given, uses a |
| | precision of ``6`` digits after the decimal point for |
| | :class:`float`, and shows all coefficient digits |
| | for :class:`~decimal.Decimal`. If no digits follow the |
| | decimal point, the decimal point is also removed unless |
| | the ``#`` option is used. |
+---------+----------------------------------------------------------+
| ``'E'`` | Exponent notation. Same as ``'e'`` except it uses an |
| | upper case 'E' as the separator character. |
| ``'E'`` | Scientific notation. Same as ``'e'`` except it uses |
| | an upper case 'E' as the separator character. |
+---------+----------------------------------------------------------+
| ``'f'`` | Fixed-point notation. Displays the number as a |
| | fixed-point number. The default precision is ``6``. |
| ``'f'`` | Fixed-point notation. For a given precision ``p``, |
| | formats the number as a decimal number with exactly |
| | ``p`` digits following the decimal point. With no |
| | precision given, uses a precision of ``6`` digits after |
| | the decimal point for :class:`float`, and uses a |
| | precision large enough to show all coefficient digits |
| | for :class:`~decimal.Decimal`. If no digits follow the |
| | decimal point, the decimal point is also removed unless |
| | the ``#`` option is used. |
+---------+----------------------------------------------------------+
| ``'F'`` | Fixed-point notation. Same as ``'f'``, but converts |
| | ``nan`` to ``NAN`` and ``inf`` to ``INF``. |
@ -498,6 +514,8 @@ The available presentation types for floating point and decimal values are:
| | this rounds the number to ``p`` significant digits and |
| | then formats the result in either fixed-point format |
| | or in scientific notation, depending on its magnitude. |
| | A precision of ``0`` is treated as equivalent to a |
| | precision of ``1``. |
| | |
| | The precise rules are as follows: suppose that the |
| | result formatted with presentation type ``'e'`` and |
@ -512,13 +530,19 @@ The available presentation types for floating point and decimal values are:
| | removed if there are no remaining digits following it, |
| | unless the ``'#'`` option is used. |
| | |
| | With no precision given, uses a precision of ``6`` |
| | significant digits for :class:`float`. For |
| | :class:`~decimal.Decimal`, the coefficient of the result |
| | is formed from the coefficient digits of the value; |
| | scientific notation is used for values smaller than |
| | ``1e-6`` in absolute value and values where the place |
| | value of the least significant digit is larger than 1, |
| | and fixed-point notation is used otherwise. |
| | |
| | Positive and negative infinity, positive and negative |
| | zero, and nans, are formatted as ``inf``, ``-inf``, |
| | ``0``, ``-0`` and ``nan`` respectively, regardless of |
| | the precision. |
| | |
| | A precision of ``0`` is treated as equivalent to a |
| | precision of ``1``. The default precision is ``6``. |
+---------+----------------------------------------------------------+
| ``'G'`` | General format. Same as ``'g'`` except switches to |
| | ``'E'`` if the number gets too large. The |
@ -531,12 +555,18 @@ The available presentation types for floating point and decimal values are:
| ``'%'`` | Percentage. Multiplies the number by 100 and displays |
| | in fixed (``'f'``) format, followed by a percent sign. |
+---------+----------------------------------------------------------+
| None | Similar to ``'g'``, except that fixed-point notation, |
| | when used, has at least one digit past the decimal point.|
| | The default precision is as high as needed to represent |
| | the particular value. The overall effect is to match the |
| | output of :func:`str` as altered by the other format |
| | modifiers. |
| None | For :class:`float` this is the same as ``'g'``, except |
| | that when fixed-point notation is used to format the |
| | result, it always includes at least one digit past the |
| | decimal point. The precision used is as large as needed |
| | to represent the given value faithfully. |
| | |
| | For :class:`~decimal.Decimal`, this is the same as |
| | either ``'g'`` or ``'G'`` depending on the value of |
| | ``context.capitals`` for the current decimal context. |
| | |
| | The overall effect is to match the output of :func:`str` |
| | as altered by the other format modifiers. |
+---------+----------------------------------------------------------+

16
Doc/library/subprocess.rst
View File

@ -339,7 +339,7 @@ functions.
stderr=None, preexec_fn=None, close_fds=True, shell=False, \
cwd=None, env=None, universal_newlines=None, \
startupinfo=None, creationflags=0, restore_signals=True, \
start_new_session=False, pass_fds=(), \*, group=None, \
start_new_session=False, pass_fds=(), *, group=None, \
extra_groups=None, user=None, umask=-1, \
encoding=None, errors=None, text=None, pipesize=-1)
@ -718,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
@ -1190,8 +1187,9 @@ calls these functions.
The arguments shown above are merely some common ones.
The full function signature is largely the same as that of :func:`run` -
most arguments are passed directly through to that interface.
However, explicitly passing ``input=None`` to inherit the parent's
standard input file handle is not supported.
One API deviation from :func:`run` behavior exists: passing ``input=None``
will behave the same as ``input=b''`` (or ``input=''``, depending on other
arguments) rather than using the parent's standard input file handle.
By default, this function will return the data as encoded bytes. The actual
encoding of the output data may depend on the command being invoked, so the
@ -1284,7 +1282,7 @@ be used directly:
becomes::
output=check_output("dmesg | grep hda", shell=True)
output = check_output("dmesg | grep hda", shell=True)
Replacing :func:`os.system`

2
Doc/library/symtable.rst
View File

@ -156,7 +156,7 @@ Examining Symbol Tables
Return ``True`` if the symbol is local to its block.
.. method:: is_annotated()
.. method:: is_annotated()
Return ``True`` if the symbol is annotated.

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