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

Merge branch 'master' into bpo-40937-collections

This commit is contained in:
Serhiy Storchaka 2020-12-29 22:38:11 +02:00 committed by GitHub
parent d0679a00dc 2edfc86f69
commit 581b845599
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1664 changed files with 117702 additions and 92872 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

51
.azure-pipelines/ci.yml
View File

@ -1,18 +1,14 @@
variables:
manylinux: false
coverage: false
resources:
containers:
- container: manylinux1
image: pyca/cryptography-manylinux1:x86_64
trigger: ['master', '3.9', '3.8', '3.7']
jobs:
- job: Prebuild
displayName: Pre-build checks
pool:
vmImage: ubuntu-16.04
vmImage: ubuntu-18.04
steps:
- template: ./prebuild-checks.yml
@ -24,7 +20,7 @@ jobs:
condition: and(succeeded(), eq(dependencies.Prebuild.outputs['docs.run'], 'true'))
pool:
vmImage: ubuntu-16.04
vmImage: ubuntu-18.04
steps:
- template: ./docs-steps.yml
@ -56,12 +52,12 @@ jobs:
condition: and(succeeded(), eq(dependencies.Prebuild.outputs['tests.run'], 'true'))
pool:
vmImage: ubuntu-16.04
vmImage: ubuntu-18.04
variables:
testRunTitle: '$(build.sourceBranchName)-linux'
testRunPlatform: linux
openssl_version: 1.1.1f
openssl_version: 1.1.1g
steps:
- template: ./posix-steps.yml
@ -69,37 +65,6 @@ jobs:
dependencies: apt
- job: ManyLinux1_CI_Tests
displayName: ManyLinux1 CI Tests
dependsOn: Prebuild
condition: |
and(
and(
succeeded(),
eq(variables['manylinux'], 'true')
),
eq(dependencies.Prebuild.outputs['tests.run'], 'true')
)
pool:
vmImage: ubuntu-16.04
container: manylinux1
variables:
testRunTitle: '$(build.sourceBranchName)-manylinux1'
testRunPlatform: manylinux1
openssl_version: ''
steps:
- template: ./posix-steps.yml
parameters:
dependencies: yum
sudo_dependencies: ''
xvfb: false
patchcheck: false
- job: Ubuntu_Coverage_CI_Tests
displayName: Ubuntu CI Tests (coverage)
dependsOn: Prebuild
@ -113,12 +78,12 @@ jobs:
)
pool:
vmImage: ubuntu-16.04
vmImage: ubuntu-18.04
variables:
testRunTitle: '$(Build.SourceBranchName)-linux-coverage'
testRunPlatform: linux-coverage
openssl_version: 1.1.1f
openssl_version: 1.1.1g
steps:
- template: ./posix-steps.yml
@ -139,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

51
.azure-pipelines/pr.yml
View File

@ -1,18 +1,14 @@
variables:
manylinux: false
coverage: false
resources:
containers:
- container: manylinux1
image: pyca/cryptography-manylinux1:x86_64
pr: ['master', '3.9', '3.8', '3.7']
jobs:
- job: Prebuild
displayName: Pre-build checks
pool:
vmImage: ubuntu-16.04
vmImage: ubuntu-18.04
steps:
- template: ./prebuild-checks.yml
@ -24,7 +20,7 @@ jobs:
condition: and(succeeded(), eq(dependencies.Prebuild.outputs['docs.run'], 'true'))
pool:
vmImage: ubuntu-16.04
vmImage: ubuntu-18.04
steps:
- template: ./docs-steps.yml
@ -56,12 +52,12 @@ jobs:
condition: and(succeeded(), eq(dependencies.Prebuild.outputs['tests.run'], 'true'))
pool:
vmImage: ubuntu-16.04
vmImage: ubuntu-18.04
variables:
testRunTitle: '$(system.pullRequest.TargetBranch)-linux'
testRunPlatform: linux
openssl_version: 1.1.1f
openssl_version: 1.1.1g
steps:
- template: ./posix-steps.yml
@ -69,37 +65,6 @@ jobs:
dependencies: apt
- job: ManyLinux1_PR_Tests
displayName: ManyLinux1 PR Tests
dependsOn: Prebuild
condition: |
and(
and(
succeeded(),
eq(variables['manylinux'], 'true')
),
eq(dependencies.Prebuild.outputs['tests.run'], 'true')
)
pool:
vmImage: ubuntu-16.04
container: manylinux1
variables:
testRunTitle: '$(system.pullRequest.TargetBranch)-manylinux1'
testRunPlatform: manylinux1
openssl_version: ''
steps:
- template: ./posix-steps.yml
parameters:
dependencies: yum
sudo_dependencies: ''
xvfb: false
patchcheck: false
- job: Ubuntu_Coverage_PR_Tests
displayName: Ubuntu PR Tests (coverage)
dependsOn: Prebuild
@ -113,12 +78,12 @@ jobs:
)
pool:
vmImage: ubuntu-16.04
vmImage: ubuntu-18.04
variables:
testRunTitle: '$(Build.SourceBranchName)-linux-coverage'
testRunPlatform: linux-coverage
openssl_version: 1.1.1f
openssl_version: 1.1.1g
steps:
- template: ./posix-steps.yml
@ -139,7 +104,7 @@ jobs:
matrix:
win32:
arch: win32
buildOpt:
buildOpt: '-p Win32'
testRunTitle: '$(System.PullRequest.TargetBranch)-win32'
testRunPlatform: win32
win64:

6
.azure-pipelines/windows-release/msi-steps.yml
View File

@ -1,6 +1,12 @@
steps:
- template: ./checkout.yml
- powershell: |
$d = (.\PCbuild\build.bat -V) | %{ if($_ -match '\s+(\w+):\s*(.+)\s*$') { @{$Matches[1] = $Matches[2];} }};
Write-Host "##vso[task.setvariable variable=SigningDescription]Python $($d.PythonVersion)"
displayName: 'Update signing description'
condition: and(succeeded(), not(variables['SigningDescription']))
- task: DownloadPipelineArtifact@1
displayName: 'Download artifact: doc'
inputs:

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

@ -105,19 +105,26 @@ jobs:
clean: all
steps:
- checkout: none
- template: ./checkout.yml
- template: ./find-sdk.yml
- powershell: |
$d = (.\PCbuild\build.bat -V) | %{ if($_ -match '\s+(\w+):\s*(.+)\s*$') { @{$Matches[1] = $Matches[2];} }};
Write-Host "##vso[task.setvariable variable=SigningDescription]Python $($d.PythonVersion)"
displayName: 'Update signing description'
condition: and(succeeded(), not(variables['SigningDescription']))
- task: DownloadBuildArtifacts@0
displayName: 'Download Artifact: unsigned_msix'
inputs:
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:

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

@ -26,6 +26,12 @@ jobs:
- template: ./checkout.yml
- template: ./find-sdk.yml
- powershell: |
$d = (.\PCbuild\build.bat -V) | %{ if($_ -match '\s+(\w+):\s*(.+)\s*$') { @{$Matches[1] = $Matches[2];} }};
Write-Host "##vso[task.setvariable variable=SigningDescription]Python $($d.PythonVersion)"
displayName: 'Update signing description'
condition: and(succeeded(), not(variables['SigningDescription']))
- powershell: |
Write-Host "##vso[build.addbuildtag]signed"
displayName: 'Add build tags'
@ -51,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

12
.gitattributes vendored
View File

@ -41,8 +41,6 @@ PC/readme.txt text eol=crlf
# Generated files
# https://github.com/github/linguist#generated-code
Include/graminit.h linguist-generated=true
Python/graminit.h linguist-generated=true
Modules/clinic/*.h linguist-generated=true
Objects/clinic/*.h linguist-generated=true
PC/clinic/*.h linguist-generated=true
@ -59,3 +57,13 @@ Doc/library/token-list.inc linguist-generated=true
Include/token.h linguist-generated=true
Lib/token.py linguist-generated=true
Parser/token.c linguist-generated=true
# Language aware diff headers
# https://tekin.co.uk/2020/10/better-git-diff-output-for-ruby-python-elixir-and-more
# https://gist.github.com/tekin/12500956bd56784728e490d8cef9cb81
*.c diff=cpp
*.h diff=cpp
*.css diff=css
*.html diff=html
*.py diff=python
*.md diff=markdown

26
.github/CODEOWNERS vendored
View File

@ -9,10 +9,17 @@
# Core
**/*context* @1st1
**/*genobject* @1st1
**/*genobject* @1st1 @markshannon
**/*hamt* @1st1
Objects/set* @rhettinger
Objects/dict* @methane
Objects/dict* @methane @markshannon
Objects/type* @markshannon
Objects/codeobject.c @markshannon
Objects/frameobject.c @markshannon
Objects/call.c @markshannon
Python/ceval.c @markshannon
Python/compile.c @markshannon
Python/ast_opt.c @isidentical
# Hashing
**/*hashlib* @python/crypto-team @tiran
@ -72,10 +79,17 @@ Include/pytime.h @pganssle @abalkin
/Modules/gcmodule.c @pablogsal
/Doc/library/gc.rst @pablogsal
# Parser/Pgen
/Parser/pgen/ @pablogsal
/Parser/pegen/ @pablogsal
/Tools/peg_generator/ @pablogsal
# Parser
/Parser/ @pablogsal @lysnikolaou
/Tools/peg_generator/ @pablogsal @lysnikolaou
/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

1
.github/FUNDING.yml vendored
View File

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

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

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

19
.github/problem-matchers/msvc.json vendored Normal file
View File

@ -0,0 +1,19 @@
{
"__comment": "Taken from vscode's vs/workbench/contrib/tasks/common/problemMatcher.ts msCompile rule",
"problemMatcher": [
{
"owner": "msvc-problem-matcher",
"pattern": [
{
"regexp": "^(?:\\s+\\d+\\>)?([^\\s].*)\\((\\d+),?(\\d+)?(?:,\\d+,\\d+)?\\)\\s*:\\s+(error|warning|info)\\s+(\\w{1,2}\\d+)\\s*:\\s*(.*)$",
"file": 1,
"line": 2,
"column": 3,
"severity": 4,
"code": 5,
"message": 6
}
]
}
]
}

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

@ -32,8 +32,52 @@ jobs:
echo '::set-output name=run_tests::true'
else
git fetch origin $GITHUB_BASE_REF --depth=1
git diff --name-only origin/$GITHUB_BASE_REF... | grep -qvE '(\.rst$|^Doc|^Misc)' && echo '::set-output name=run_tests::true' || true
# git diff "origin/$GITHUB_BASE_REF..." (3 dots) may be more
# reliable than git diff "origin/$GITHUB_BASE_REF.." (2 dots),
# but it requires to download more commits (this job uses
# "git fetch --depth=1").
#
# git diff "origin/$GITHUB_BASE_REF..." (3 dots) works with Git
# 2.26, but Git 2.28 is stricter and fails with "no merge base".
#
# git diff "origin/$GITHUB_BASE_REF.." (2 dots) should be enough on
# GitHub, since GitHub starts by merging origin/$GITHUB_BASE_REF
# into the PR branch anyway.
#
# 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
@ -46,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)'
@ -55,12 +99,14 @@ jobs:
if: needs.check_source.outputs.run_tests == 'true'
steps:
- uses: actions/checkout@v2
- name: Register MSVC problem matcher
run: echo "::add-matcher::.github/problem-matchers/msvc.json"
- name: Build CPython
run: .\PCbuild\build.bat -e -p x64
- 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'
@ -93,7 +139,7 @@ jobs:
run: sudo ./.github/workflows/posix-deps-apt.sh
- name: 'Restore OpenSSL build'
id: cache-openssl
uses: actions/cache@v1
uses: actions/cache@v2.1.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@v1
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@v1
uses: actions/upload-artifact@v2.2.1
with:
name: doc-html
path: Doc/build/html

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

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

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

2
.gitignore vendored
View File

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

21
.travis.yml
View File

@ -51,12 +51,9 @@ matrix:
env: TESTING=docs
before_script:
- cd Doc
# Sphinx is pinned so that new versions that introduce new warnings won't suddenly cause build failures.
# (Updating the version is fine as long as no warnings are raised by doing so.)
# The theme used by the docs is stored separately, so we need to install that as well.
- python -m pip install sphinx==2.2.0 blurb python-docs-theme
- 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
@ -82,6 +79,12 @@ matrix:
packages:
- xvfb
before_script:
- |
if [[ "$TRAVIS_PULL_REQUEST" != "false" ]]
then
echo "Don't run Python coverage on pull requests."
exit
fi
- ./configure
- make -j4
# Need a venv that can parse covered code.
@ -109,6 +112,12 @@ matrix:
- lcov
- xvfb
before_script:
- |
if [[ "$TRAVIS_PULL_REQUEST" != "false" ]]
then
echo "Don't run C coverage on pull requests."
exit
fi
- ./configure
script:
- xvfb-run make -j4 coverage-report
@ -183,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

8
Doc/Makefile
View File

@ -143,7 +143,7 @@ clean:
venv:
$(PYTHON) -m venv $(VENVDIR)
$(VENVDIR)/bin/python3 -m pip install -U pip setuptools
$(VENVDIR)/bin/python3 -m pip install -U Sphinx==2.2.0 blurb python-docs-theme
$(VENVDIR)/bin/python3 -m pip install -r requirements.txt
@echo "The venv has been created in the $(VENVDIR) directory"
dist:
@ -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

1
Doc/c-api/abstract.rst
View File

@ -24,4 +24,3 @@ but whose items have not been set to some non-\ ``NULL`` value yet.
mapping.rst
iter.rst
buffer.rst
objbuffer.rst

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

@ -55,13 +55,11 @@ which disallows mutable objects such as :class:`bytearray`.
.. note::
For all ``#`` variants of formats (``s#``, ``y#``, etc.), the type of
the length argument (int or :c:type:`Py_ssize_t`) is controlled by
defining the macro :c:macro:`PY_SSIZE_T_CLEAN` before including
:file:`Python.h`. If the macro was defined, length is a
:c:type:`Py_ssize_t` rather than an :c:type:`int`. This behavior will change
in a future Python version to only support :c:type:`Py_ssize_t` and
drop :c:type:`int` support. It is best to always define :c:macro:`PY_SSIZE_T_CLEAN`.
For all ``#`` variants of formats (``s#``, ``y#``, etc.), the macro
:c:macro:`PY_SSIZE_T_CLEAN` must be defined before including
:file:`Python.h`. On Python 3.9 and older, the type of the length argument
is :c:type:`Py_ssize_t` if the :c:macro:`PY_SSIZE_T_CLEAN` macro is defined,
or int otherwise.
``s`` (:class:`str`) [const char \*]
@ -90,7 +88,7 @@ which disallows mutable objects such as :class:`bytearray`.
In this case the resulting C string may contain embedded NUL bytes.
Unicode objects are converted to C strings using ``'utf-8'`` encoding.
``s#`` (:class:`str`, read-only :term:`bytes-like object`) [const char \*, int or :c:type:`Py_ssize_t`]
``s#`` (:class:`str`, read-only :term:`bytes-like object`) [const char \*, :c:type:`Py_ssize_t`]
Like ``s*``, except that it doesn't accept mutable objects.
The result is stored into two C variables,
the first one a pointer to a C string, the second one its length.
@ -105,7 +103,7 @@ which disallows mutable objects such as :class:`bytearray`.
Like ``s*``, but the Python object may also be ``None``, in which case the
``buf`` member of the :c:type:`Py_buffer` structure is set to ``NULL``.
``z#`` (:class:`str`, read-only :term:`bytes-like object` or ``None``) [const char \*, int or :c:type:`Py_ssize_t`]
``z#`` (:class:`str`, read-only :term:`bytes-like object` or ``None``) [const char \*, :c:type:`Py_ssize_t`]
Like ``s#``, but the Python object may also be ``None``, in which case the C
pointer is set to ``NULL``.
@ -124,19 +122,19 @@ which disallows mutable objects such as :class:`bytearray`.
bytes-like objects. **This is the recommended way to accept
binary data.**
``y#`` (read-only :term:`bytes-like object`) [const char \*, int or :c:type:`Py_ssize_t`]
``y#`` (read-only :term:`bytes-like object`) [const char \*, :c:type:`Py_ssize_t`]
This variant on ``s#`` doesn't accept Unicode objects, only bytes-like
objects.
``S`` (:class:`bytes`) [PyBytesObject \*]
Requires that the Python object is a :class:`bytes` object, without
attempting any conversion. Raises :exc:`TypeError` if the object is not
a bytes object. The C variable may also be declared as :c:type:`PyObject\*`.
a bytes object. The C variable may also be declared as :c:type:`PyObject*`.
``Y`` (:class:`bytearray`) [PyByteArrayObject \*]
Requires that the Python object is a :class:`bytearray` object, without
attempting any conversion. Raises :exc:`TypeError` if the object is not
a :class:`bytearray` object. The C variable may also be declared as :c:type:`PyObject\*`.
a :class:`bytearray` object. The C variable may also be declared as :c:type:`PyObject*`.
``u`` (:class:`str`) [const Py_UNICODE \*]
Convert a Python Unicode object to a C pointer to a NUL-terminated buffer of
@ -155,7 +153,7 @@ which disallows mutable objects such as :class:`bytearray`.
Part of the old-style :c:type:`Py_UNICODE` API; please migrate to using
:c:func:`PyUnicode_AsWideCharString`.
``u#`` (:class:`str`) [const Py_UNICODE \*, int or :c:type:`Py_ssize_t`]
``u#`` (:class:`str`) [const Py_UNICODE \*, :c:type:`Py_ssize_t`]
This variant on ``u`` stores into two C variables, the first one a pointer to a
Unicode data buffer, the second one its length. This variant allows
null code points.
@ -172,7 +170,7 @@ which disallows mutable objects such as :class:`bytearray`.
Part of the old-style :c:type:`Py_UNICODE` API; please migrate to using
:c:func:`PyUnicode_AsWideCharString`.
``Z#`` (:class:`str` or ``None``) [const Py_UNICODE \*, int or :c:type:`Py_ssize_t`]
``Z#`` (:class:`str` or ``None``) [const Py_UNICODE \*, :c:type:`Py_ssize_t`]
Like ``u#``, but the Python object may also be ``None``, in which case the
:c:type:`Py_UNICODE` pointer is set to ``NULL``.
@ -183,7 +181,7 @@ which disallows mutable objects such as :class:`bytearray`.
``U`` (:class:`str`) [PyObject \*]
Requires that the Python object is a Unicode object, without attempting
any conversion. Raises :exc:`TypeError` if the object is not a Unicode
object. The C variable may also be declared as :c:type:`PyObject\*`.
object. The C variable may also be declared as :c:type:`PyObject*`.
``w*`` (read-write :term:`bytes-like object`) [Py_buffer]
This format accepts any object which implements the read-write buffer
@ -196,10 +194,10 @@ which disallows mutable objects such as :class:`bytearray`.
It only works for encoded data without embedded NUL bytes.
This format requires two arguments. The first is only used as input, and
must be a :c:type:`const char\*` which points to the name of an encoding as a
must be a :c:type:`const char*` which points to the name of an encoding as a
NUL-terminated string, or ``NULL``, in which case ``'utf-8'`` encoding is used.
An exception is raised if the named encoding is not known to Python. The
second argument must be a :c:type:`char\*\*`; the value of the pointer it
second argument must be a :c:type:`char**`; the value of the pointer it
references will be set to a buffer with the contents of the argument text.
The text will be encoded in the encoding specified by the first argument.
@ -213,16 +211,16 @@ which disallows mutable objects such as :class:`bytearray`.
recoding them. Instead, the implementation assumes that the byte string object uses
the encoding passed in as parameter.
``es#`` (:class:`str`) [const char \*encoding, char \*\*buffer, int or :c:type:`Py_ssize_t` \*buffer_length]
``es#`` (:class:`str`) [const char \*encoding, char \*\*buffer, :c:type:`Py_ssize_t` \*buffer_length]
This variant on ``s#`` is used for encoding Unicode into a character buffer.
Unlike the ``es`` format, this variant allows input data which contains NUL
characters.
It requires three arguments. The first is only used as input, and must be a
:c:type:`const char\*` which points to the name of an encoding as a
:c:type:`const char*` which points to the name of an encoding as a
NUL-terminated string, or ``NULL``, in which case ``'utf-8'`` encoding is used.
An exception is raised if the named encoding is not known to Python. The
second argument must be a :c:type:`char\*\*`; the value of the pointer it
second argument must be a :c:type:`char**`; the value of the pointer it
references will be set to a buffer with the contents of the argument text.
The text will be encoded in the encoding specified by the first argument.
The third argument must be a pointer to an integer; the referenced integer
@ -244,7 +242,7 @@ which disallows mutable objects such as :class:`bytearray`.
In both cases, *\*buffer_length* is set to the length of the encoded data
without the trailing NUL byte.
``et#`` (:class:`str`, :class:`bytes` or :class:`bytearray`) [const char \*encoding, char \*\*buffer, int or :c:type:`Py_ssize_t` \*buffer_length]
``et#`` (:class:`str`, :class:`bytes` or :class:`bytearray`) [const char \*encoding, char \*\*buffer, :c:type:`Py_ssize_t` \*buffer_length]
Same as ``es#`` except that byte string objects are passed through without recoding
them. Instead, the implementation assumes that the byte string object uses the
encoding passed in as parameter.
@ -322,7 +320,7 @@ Other objects
``O!`` (object) [*typeobject*, PyObject \*]
Store a Python object in a C object pointer. This is similar to ``O``, but
takes two C arguments: the first is the address of a Python type object, the
second is the address of the C variable (of type :c:type:`PyObject\*`) into which
second is the address of the C variable (of type :c:type:`PyObject*`) into which
the object pointer is stored. If the Python object does not have the required
type, :exc:`TypeError` is raised.
@ -331,13 +329,13 @@ Other objects
``O&`` (object) [*converter*, *anything*]
Convert a Python object to a C variable through a *converter* function. This
takes two arguments: the first is a function, the second is the address of a C
variable (of arbitrary type), converted to :c:type:`void \*`. The *converter*
variable (of arbitrary type), converted to :c:type:`void *`. The *converter*
function in turn is called as follows::
status = converter(object, address);
where *object* is the Python object to be converted and *address* is the
:c:type:`void\*` argument that was passed to the :c:func:`PyArg_Parse\*` function.
:c:type:`void*` argument that was passed to the :c:func:`PyArg_Parse\*` function.
The returned *status* should be ``1`` for a successful conversion and ``0`` if
the conversion has failed. When the conversion fails, the *converter* function
should raise an exception and leave the content of *address* unmodified.
@ -483,8 +481,9 @@ API Functions
*args*; it must actually be a tuple. The length of the tuple must be at least
*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
:c:type:`PyObject*` variable; these will be filled in with the values from
*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
@ -549,7 +548,7 @@ Building values
Convert a null-terminated C string to a Python :class:`str` object using ``'utf-8'``
encoding. If the C string pointer is ``NULL``, ``None`` is used.
``s#`` (:class:`str` or ``None``) [const char \*, int or :c:type:`Py_ssize_t`]
``s#`` (:class:`str` or ``None``) [const char \*, :c:type:`Py_ssize_t`]
Convert a C string and its length to a Python :class:`str` object using ``'utf-8'``
encoding. If the C string pointer is ``NULL``, the length is ignored and
``None`` is returned.
@ -558,14 +557,14 @@ Building values
This converts a C string to a Python :class:`bytes` object. If the C
string pointer is ``NULL``, ``None`` is returned.
``y#`` (:class:`bytes`) [const char \*, int or :c:type:`Py_ssize_t`]
``y#`` (:class:`bytes`) [const char \*, :c:type:`Py_ssize_t`]
This converts a C string and its lengths to a Python object. If the C
string pointer is ``NULL``, ``None`` is returned.
``z`` (:class:`str` or ``None``) [const char \*]
Same as ``s``.
``z#`` (:class:`str` or ``None``) [const char \*, int or :c:type:`Py_ssize_t`]
``z#`` (:class:`str` or ``None``) [const char \*, :c:type:`Py_ssize_t`]
Same as ``s#``.
``u`` (:class:`str`) [const wchar_t \*]
@ -573,7 +572,7 @@ Building values
data to a Python Unicode object. If the Unicode buffer pointer is ``NULL``,
``None`` is returned.
``u#`` (:class:`str`) [const wchar_t \*, int or :c:type:`Py_ssize_t`]
``u#`` (:class:`str`) [const wchar_t \*, :c:type:`Py_ssize_t`]
Convert a Unicode (UTF-16 or UCS-4) data buffer and its length to a Python
Unicode object. If the Unicode buffer pointer is ``NULL``, the length is ignored
and ``None`` is returned.
@ -581,7 +580,7 @@ Building values
``U`` (:class:`str` or ``None``) [const char \*]
Same as ``s``.
``U#`` (:class:`str` or ``None``) [const char \*, int or :c:type:`Py_ssize_t`]
``U#`` (:class:`str` or ``None``) [const char \*, :c:type:`Py_ssize_t`]
Same as ``s#``.
``i`` (:class:`int`) [int]
@ -652,8 +651,8 @@ Building values
``O&`` (object) [*converter*, *anything*]
Convert *anything* to a Python object through a *converter* function. The
function is called with *anything* (which should be compatible with :c:type:`void
\*`) as its argument and should return a "new" Python object, or ``NULL`` if an
function is called with *anything* (which should be compatible with :c:type:`void*`)
as its argument and should return a "new" Python object, or ``NULL`` if an
error occurred.
``(items)`` (:class:`tuple`) [*matching-items*]

28
Doc/c-api/buffer.rst
View File

@ -89,7 +89,7 @@ a buffer, see :c:func:`PyObject_GetBuffer`.
.. c:type:: Py_buffer
.. c:member:: void \*buf
.. c:member:: void *buf
A pointer to the start of the logical structure described by the buffer
fields. This can be any location within the underlying physical memory
@ -99,7 +99,7 @@ a buffer, see :c:func:`PyObject_GetBuffer`.
For :term:`contiguous` arrays, the value points to the beginning of
the memory block.
.. c:member:: void \*obj
.. c:member:: void *obj
A new reference to the exporting object. The reference is owned by
the consumer and automatically decremented and set to ``NULL`` by
@ -145,7 +145,7 @@ a buffer, see :c:func:`PyObject_GetBuffer`.
or a :c:macro:`PyBUF_WRITABLE` request, the consumer must disregard
:c:member:`~Py_buffer.itemsize` and assume ``itemsize == 1``.
.. c:member:: const char \*format
.. c:member:: const char *format
A *NUL* terminated string in :mod:`struct` module style syntax describing
the contents of a single item. If this is ``NULL``, ``"B"`` (unsigned bytes)
@ -164,7 +164,7 @@ a buffer, see :c:func:`PyObject_GetBuffer`.
to 64. Exporters MUST respect this limit, consumers of multi-dimensional
buffers SHOULD be able to handle up to :c:macro:`PyBUF_MAX_NDIM` dimensions.
.. c:member:: Py_ssize_t \*shape
.. c:member:: Py_ssize_t *shape
An array of :c:type:`Py_ssize_t` of length :c:member:`~Py_buffer.ndim`
indicating the shape of the memory as an n-dimensional array. Note that
@ -177,7 +177,7 @@ a buffer, see :c:func:`PyObject_GetBuffer`.
The shape array is read-only for the consumer.
.. c:member:: Py_ssize_t \*strides
.. c:member:: Py_ssize_t *strides
An array of :c:type:`Py_ssize_t` of length :c:member:`~Py_buffer.ndim`
giving the number of bytes to skip to get to a new element in each
@ -189,7 +189,7 @@ a buffer, see :c:func:`PyObject_GetBuffer`.
The strides array is read-only for the consumer.
.. c:member:: Py_ssize_t \*suboffsets
.. c:member:: Py_ssize_t *suboffsets
An array of :c:type:`Py_ssize_t` of length :c:member:`~Py_buffer.ndim`.
If ``suboffsets[n] >= 0``, the values stored along the nth dimension are
@ -207,7 +207,7 @@ a buffer, see :c:func:`PyObject_GetBuffer`.
The suboffsets array is read-only for the consumer.
.. c:member:: void \*internal
.. c:member:: void *internal
This is for use internally by the exporting object. For example, this
might be re-cast as an integer by the exporter and used to store flags
@ -301,7 +301,7 @@ must be C-contiguous.
+-----------------------------------+-------+---------+------------+--------+
| .. c:macro:: PyBUF_ANY_CONTIGUOUS | yes | yes | NULL | C or F |
+-----------------------------------+-------+---------+------------+--------+
| .. c:macro:: PyBUF_ND | yes | NULL | NULL | C |
| :c:macro:`PyBUF_ND` | yes | NULL | NULL | C |
+-----------------------------------+-------+---------+------------+--------+
@ -438,12 +438,12 @@ Buffer-related functions
Send a request to *exporter* to fill in *view* as specified by *flags*.
If the exporter cannot provide a buffer of the exact type, it MUST raise
:c:data:`PyExc_BufferError`, set :c:member:`view->obj` to ``NULL`` and
:c:data:`PyExc_BufferError`, set ``view->obj`` to ``NULL`` and
return ``-1``.
On success, fill in *view*, set :c:member:`view->obj` to a new reference
On success, fill in *view*, set ``view->obj`` to a new reference
to *exporter* and return 0. In the case of chained buffer providers
that redirect requests to a single object, :c:member:`view->obj` MAY
that redirect requests to a single object, ``view->obj`` MAY
refer to this object instead of *exporter* (See :ref:`Buffer Object Structures <buffer-structs>`).
Successful calls to :c:func:`PyObject_GetBuffer` must be paired with calls
@ -455,7 +455,7 @@ Buffer-related functions
.. c:function:: void PyBuffer_Release(Py_buffer *view)
Release the buffer *view* and decrement the reference count for
:c:member:`view->obj`. This function MUST be called when the buffer
``view->obj``. This function MUST be called when the buffer
is no longer being used, otherwise reference leaks may occur.
It is an error to call this function on a buffer that was not obtained via
@ -516,9 +516,9 @@ Buffer-related functions
*view* as specified by flags, unless *buf* has been designated as read-only
and :c:macro:`PyBUF_WRITABLE` is set in *flags*.
On success, set :c:member:`view->obj` to a new reference to *exporter* and
On success, set ``view->obj`` to a new reference to *exporter* and
return 0. Otherwise, raise :c:data:`PyExc_BufferError`, set
:c:member:`view->obj` to ``NULL`` and return ``-1``;
``view->obj`` to ``NULL`` and return ``-1``;
If this function is used as part of a :ref:`getbufferproc <buffer-structs>`,
*exporter* MUST be set to the exporting object and *flags* must be passed

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

@ -84,7 +84,7 @@ This is a pointer to a function with the following signature:
and they must be unique.
If there are no keyword arguments, then *kwnames* can instead be *NULL*.
.. c:var:: PY_VECTORCALL_ARGUMENTS_OFFSET
.. c:macro:: PY_VECTORCALL_ARGUMENTS_OFFSET
If this flag is set in a vectorcall *nargsf* argument, the callee is allowed
to temporarily change ``args[-1]``. In other words, *args* points to
@ -283,7 +283,7 @@ please see individual documentation for details.
This is the equivalent of the Python expression: ``callable(*args)``.
Note that if you only pass :c:type:`PyObject \*` args,
Note that if you only pass :c:type:`PyObject *` args,
:c:func:`PyObject_CallFunctionObjArgs` is a faster alternative.
.. versionchanged:: 3.4
@ -304,17 +304,17 @@ please see individual documentation for details.
This is the equivalent of the Python expression:
``obj.name(arg1, arg2, ...)``.
Note that if you only pass :c:type:`PyObject \*` args,
Note that if you only pass :c:type:`PyObject *` args,
:c:func:`PyObject_CallMethodObjArgs` is a faster alternative.
.. versionchanged:: 3.4
The types of *name* and *format* were changed from ``char *``.
.. c:function:: PyObject* PyObject_CallFunctionObjArgs(PyObject *callable, ..., NULL)
.. c:function:: PyObject* PyObject_CallFunctionObjArgs(PyObject *callable, ...)
Call a callable Python object *callable*, with a variable number of
:c:type:`PyObject \*` arguments. The arguments are provided as a variable number
:c:type:`PyObject *` arguments. The arguments are provided as a variable number
of parameters followed by *NULL*.
Return the result of the call on success, or raise an exception and return
@ -324,11 +324,11 @@ please see individual documentation for details.
``callable(arg1, arg2, ...)``.
.. c:function:: PyObject* PyObject_CallMethodObjArgs(PyObject *obj, PyObject *name, ..., NULL)
.. c:function:: PyObject* PyObject_CallMethodObjArgs(PyObject *obj, PyObject *name, ...)
Call a method of the Python object *obj*, where the name of the method is given as a
Python string object in *name*. It is called with a variable number of
:c:type:`PyObject \*` arguments. The arguments are provided as a variable number
:c:type:`PyObject *` arguments. The arguments are provided as a variable number
of parameters followed by *NULL*.
Return the result of the call on success, or raise an exception and return

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

@ -15,7 +15,7 @@ Refer to :ref:`using-capsules` for more information on using these objects.
.. c:type:: PyCapsule
This subtype of :c:type:`PyObject` represents an opaque value, useful for C
extension modules who need to pass an opaque value (as a :c:type:`void\*`
extension modules who need to pass an opaque value (as a :c:type:`void*`
pointer) through Python code to other C code. It is often used to make a C
function pointer defined in one module available to other modules, so the
regular import mechanism can be used to access C APIs defined in dynamically

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

@ -10,6 +10,14 @@ Codec registry and support functions
As side effect, this tries to load the :mod:`encodings` package, if not yet
done, to make sure that it is always first in the list of search functions.
.. c:function:: int PyCodec_Unregister(PyObject *search_function)
Unregister a codec search function and clear the registry's cache.
If the search function is not registered, do nothing.
Return 0 on success. Raise an exception and return -1 on error.
.. versionadded:: 3.10
.. c:function:: int PyCodec_KnownEncoding(const char *encoding)
Return ``1`` or ``0`` depending on whether there is a registered codec for

1
Doc/c-api/concrete.rst
View File

@ -115,3 +115,4 @@ Other Objects
coro.rst
contextvars.rst
datetime.rst
decimal.rst

10
Doc/c-api/conversion.rst
View File

@ -27,12 +27,8 @@ not.
The wrappers ensure that *str*[*size*-1] is always ``'\0'`` upon return. They
never write more than *size* bytes (including the trailing ``'\0'``) into str.
Both functions require that ``str != NULL``, ``size > 0`` and ``format !=
NULL``.
If the platform doesn't have :c:func:`vsnprintf` and the buffer size needed to
avoid truncation exceeds *size* by more than 512 bytes, Python aborts with a
:c:func:`Py_FatalError`.
Both functions require that ``str != NULL``, ``size > 0``, ``format != NULL``
and ``size < INT_MAX``.
The return value (*rv*) for these functions should be interpreted as follows:
@ -48,8 +44,8 @@ The return value (*rv*) for these functions should be interpreted as follows:
this case too, but the rest of *str* is undefined. The exact cause of the error
depends on the underlying platform.
The following functions provide locale-independent string to number conversions.
The following functions provide locale-independent string to number conversions.
.. c:function:: double PyOS_string_to_double(const char *s, char **endptr, PyObject *overflow_exception)

11
Doc/c-api/datetime.rst
View File

@ -185,6 +185,11 @@ must not be ``NULL``, and the type is not checked:
Return the microsecond, as an int from 0 through 999999.
.. c:function:: PyObject* PyDateTime_DATE_GET_TZINFO(PyDateTime_DateTime *o)
Return the tzinfo (which may be ``None``).
.. versionadded:: 3.10
Macros to extract fields from time objects. The argument must be an instance of
:c:data:`PyDateTime_Time`, including subclasses. The argument must not be ``NULL``,
@ -209,6 +214,12 @@ and the type is not checked:
Return the microsecond, as an int from 0 through 999999.
.. c:function:: PyObject* PyDateTime_TIME_GET_TZINFO(PyDateTime_Time *o)
Return the tzinfo (which may be ``None``).
.. versionadded:: 3.10
Macros to extract fields from time delta objects. The argument must be an
instance of :c:data:`PyDateTime_Delta`, including subclasses. The argument must

231
Doc/c-api/decimal.rst Normal file
View File

@ -0,0 +1,231 @@
.. sectionauthor:: Stefan Krah
.. highlight:: c
Decimal capsule API
===================
Capsule API functions can be used in the same manner as regular library
functions, provided that the API has been initialized.
Initialize
----------
Typically, a C extension module that uses the decimal API will do these
steps in its init function:
.. code-block:: c
#include "pydecimal.h"
static int decimal_initialized = 0;
if (!decimal_initialized) {
if (import_decimal() < 0) {
return NULL;
}
decimal_initialized = 1;
}
Type checking, predicates, accessors
------------------------------------
.. c:function:: int PyDec_TypeCheck(const PyObject *dec)
Return 1 if ``dec`` is a Decimal, 0 otherwise. This function does not set
any exceptions.
.. c:function:: int PyDec_IsSpecial(const PyObject *dec)
Return 1 if ``dec`` is ``NaN``, ``sNaN`` or ``Infinity``, 0 otherwise.
Set TypeError and return -1 if ``dec`` is not a Decimal. It is guaranteed that
this is the only failure mode, so if ``dec`` has already been type-checked, no
errors can occur and the function can be treated as a simple predicate.
.. c:function:: int PyDec_IsNaN(const PyObject *dec)
Return 1 if ``dec`` is ``NaN`` or ``sNaN``, 0 otherwise.
Set TypeError and return -1 if ``dec`` is not a Decimal. It is guaranteed that
this is the only failure mode, so if ``dec`` has already been type-checked, no
errors can occur and the function can be treated as a simple predicate.
.. c:function:: int PyDec_IsInfinite(const PyObject *dec)
Return 1 if ``dec`` is ``Infinity``, 0 otherwise.
Set TypeError and return -1 if ``dec`` is not a Decimal. It is guaranteed that
this is the only failure mode, so if ``dec`` has already been type-checked, no
errors can occur and the function can be treated as a simple predicate.
.. c:function:: int64_t PyDec_GetDigits(const PyObject *dec)
Return the number of digits in the coefficient. For ``Infinity``, the
number of digits is always zero. Typically, the same applies to ``NaN``
and ``sNaN``, but both of these can have a payload that is equivalent to
a coefficient. Therefore, ``NaNs`` can have a nonzero return value.
Set TypeError and return -1 if ``dec`` is not a Decimal. It is guaranteed that
this is the only failure mode, so if ``dec`` has already been type-checked, no
errors can occur and the function can be treated as a simple accessor.
Exact conversions between decimals and primitive C types
--------------------------------------------------------
This API supports conversions for decimals with a coefficient up to 38 digits.
Data structures
~~~~~~~~~~~~~~~
The conversion functions use the following status codes and data structures:
.. code-block:: c
/* status cases for getting a triple */
enum mpd_triple_class {
MPD_TRIPLE_NORMAL,
MPD_TRIPLE_INF,
MPD_TRIPLE_QNAN,
MPD_TRIPLE_SNAN,
MPD_TRIPLE_ERROR,
};
typedef struct {
enum mpd_triple_class tag;
uint8_t sign;
uint64_t hi;
uint64_t lo;
int64_t exp;
} mpd_uint128_triple_t;
The status cases are explained below. ``sign`` is 0 for positive and 1 for negative.
``((uint128_t)hi << 64) + lo`` is the coefficient, ``exp`` is the exponent.
The data structure is called "triple" because the decimal triple (sign, coeff, exp)
is an established term and (``hi``, ``lo``) represents a single ``uint128_t`` coefficient.
Functions
~~~~~~~~~
.. c:function:: mpd_uint128_triple_t PyDec_AsUint128Triple(const PyObject *dec)
Convert a decimal to a triple. As above, it is guaranteed that the only
Python failure mode is a TypeError, checks can be omitted if the type is
known.
For simplicity, the usage of the function and all special cases are
explained in code form and comments:
.. code-block:: c
triple = PyDec_AsUint128Triple(dec);
switch (triple.tag) {
case MPD_TRIPLE_QNAN:
/*
* Success: handle a quiet NaN.
* 1) triple.sign is 0 or 1.
* 2) triple.exp is always 0.
* 3) If triple.hi or triple.lo are nonzero, the NaN has a payload.
*/
break;
case MPD_TRIPLE_SNAN:
/*
* Success: handle a signaling NaN.
* 1) triple.sign is 0 or 1.
* 2) triple.exp is always 0.
* 3) If triple.hi or triple.lo are nonzero, the sNaN has a payload.
*/
break;
case MPD_TRIPLE_INF:
/*
* Success: handle Infinity.
* 1) triple.sign is 0 or 1.
* 2) triple.exp is always 0.
* 3) triple.hi and triple.lo are always zero.
*/
break;
case MPD_TRIPLE_NORMAL:
/* Success: handle a finite value. */
break;
case MPD_TRIPLE_ERROR:
/* TypeError check: can be omitted if the type of dec is known. */
if (PyErr_Occurred()) {
return NULL;
}
/* Too large for conversion. PyDec_AsUint128Triple() does not set an
exception so applications can choose themselves. Typically this
would be a ValueError. */
PyErr_SetString(PyExc_ValueError,
"value out of bounds for a uint128 triple");
return NULL;
}
.. c:function:: PyObject *PyDec_FromUint128Triple(const mpd_uint128_triple_t *triple)
Create a decimal from a triple. The following rules must be observed for
initializing the triple:
1) ``triple.sign`` must always be 0 (for positive) or 1 (for negative).
2) ``MPD_TRIPLE_QNAN``: ``triple.exp`` must be 0. If ``triple.hi`` or ``triple.lo``
are nonzero, create a ``NaN`` with a payload.
3) ``MPD_TRIPLE_SNAN``: ``triple.exp`` must be 0. If ``triple.hi`` or ``triple.lo``
are nonzero, create an ``sNaN`` with a payload.
4) ``MPD_TRIPLE_INF``: ``triple.exp``, ``triple.hi`` and ``triple.lo`` must be zero.
5) ``MPD_TRIPLE_NORMAL``: ``MPD_MIN_ETINY + 38 < triple.exp < MPD_MAX_EMAX - 38``.
``triple.hi`` and ``triple.lo`` can be chosen freely.
6) ``MPD_TRIPLE_ERROR``: It is always an error to set this tag.
If one of the above conditions is not met, the function returns ``NaN`` if
the ``InvalidOperation`` trap is not set in the thread local context. Otherwise,
it sets the ``InvalidOperation`` exception and returns NULL.
Additionally, though extremely unlikely give the small allocation sizes,
the function can set ``MemoryError`` and return ``NULL``.
Advanced API
------------
This API enables the use of ``libmpdec`` functions. Since Python is compiled with
hidden symbols, the API requires an external libmpdec and the ``mpdecimal.h``
header.
Functions
~~~~~~~~~
.. c:function:: PyObject *PyDec_Alloc(void)
Return a new decimal that can be used in the ``result`` position of ``libmpdec``
functions.
.. c:function:: mpd_t *PyDec_Get(PyObject *v)
Get a pointer to the internal ``mpd_t`` of the decimal. Decimals are immutable,
so this function must only be used on a new Decimal that has been created by
PyDec_Alloc().
.. c:function:: const mpd_t *PyDec_GetConst(const PyObject *v)
Get a pointer to the constant internal ``mpd_t`` of the decimal.

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

@ -73,7 +73,7 @@ Dictionary Objects
.. index:: single: PyUnicode_FromString()
Insert *val* into the dictionary *p* using *key* as a key. *key* should
be a :c:type:`const char\*`. The key object is created using
be a :c:type:`const char*`. The key object is created using
``PyUnicode_FromString(key)``. Return ``0`` on success or ``-1`` on
failure. This function *does not* steal a reference to *val*.
@ -81,14 +81,16 @@ Dictionary Objects
.. c:function:: int PyDict_DelItem(PyObject *p, PyObject *key)
Remove the entry in dictionary *p* with key *key*. *key* must be hashable;
if it isn't, :exc:`TypeError` is raised. Return ``0`` on success or ``-1``
on failure.
if it isn't, :exc:`TypeError` is raised.
If *key* is not in the dictionary, :exc:`KeyError` is raised.
Return ``0`` on success or ``-1`` on failure.
.. c:function:: int PyDict_DelItemString(PyObject *p, const char *key)
Remove the entry in dictionary *p* which has a key specified by the string
*key*. Return ``0`` on success or ``-1`` on failure.
Remove the entry in dictionary *p* which has a key specified by the string *key*.
If *key* is not in the dictionary, :exc:`KeyError` is raised.
Return ``0`` on success or ``-1`` on failure.
.. c:function:: PyObject* PyDict_GetItem(PyObject *p, PyObject *key)
@ -116,7 +118,7 @@ Dictionary Objects
.. c:function:: PyObject* PyDict_GetItemString(PyObject *p, const char *key)
This is the same as :c:func:`PyDict_GetItem`, but *key* is specified as a
:c:type:`const char\*`, rather than a :c:type:`PyObject\*`.
:c:type:`const char*`, rather than a :c:type:`PyObject*`.
Note that exceptions which occur while calling :meth:`__hash__` and
:meth:`__eq__` methods and creating a temporary string object
@ -165,7 +167,7 @@ Dictionary Objects
prior to the first call to this function to start the iteration; the
function returns true for each pair in the dictionary, and false once all
pairs have been reported. The parameters *pkey* and *pvalue* should either
point to :c:type:`PyObject\*` variables that will be filled in with each key
point to :c:type:`PyObject*` variables that will be filled in with each key
and value, respectively, or may be ``NULL``. Any references returned through
them are borrowed. *ppos* should not be altered during iteration. Its
value represents offsets within the internal dictionary structure, and

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

@ -182,8 +182,8 @@ For convenience, some of these functions will always return a
.. c:function:: PyObject* PyErr_SetFromErrnoWithFilename(PyObject *type, const char *filename)
Similar to :c:func:`PyErr_SetFromErrnoWithFilenameObject`, but the filename
is given as a C string. *filename* is decoded from the filesystem encoding
(:func:`os.fsdecode`).
is given as a C string. *filename* is decoded from the :term:`filesystem
encoding and error handler`.
.. c:function:: PyObject* PyErr_SetFromWindowsErr(int ierr)
@ -266,7 +266,7 @@ For convenience, some of these functions will always return a
.. c:function:: void PyErr_SyntaxLocationEx(const char *filename, int lineno, int col_offset)
Like :c:func:`PyErr_SyntaxLocationObject`, but *filename* is a byte string
decoded from the filesystem encoding (:func:`os.fsdecode`).
decoded from the :term:`filesystem encoding and error handler`.
.. versionadded:: 3.2
@ -343,7 +343,7 @@ an error value).
Similar to :c:func:`PyErr_WarnExplicitObject` except that *message* and
*module* are UTF-8 encoded strings, and *filename* is decoded from the
filesystem encoding (:func:`os.fsdecode`).
:term:`filesystem encoding and error handler`.
.. c:function:: int PyErr_WarnFormat(PyObject *category, Py_ssize_t stack_level, const char *format, ...)
@ -637,11 +637,21 @@ The following functions are used to create and modify Unicode exceptions from C.
*object*, *length*, *start*, *end* and *reason*. *encoding* and *reason* are
UTF-8 encoded strings.
.. deprecated:: 3.3 3.11
``Py_UNICODE`` is deprecated since Python 3.3. Please migrate to
``PyObject_CallFunction(PyExc_UnicodeEncodeError, "sOnns", ...)``.
.. c:function:: PyObject* PyUnicodeTranslateError_Create(const Py_UNICODE *object, Py_ssize_t length, Py_ssize_t start, Py_ssize_t end, const char *reason)
Create a :class:`UnicodeTranslateError` object with the attributes *object*,
*length*, *start*, *end* and *reason*. *reason* is a UTF-8 encoded string.
.. deprecated:: 3.3 3.11
``Py_UNICODE`` is deprecated since Python 3.3. Please migrate to
``PyObject_CallFunction(PyExc_UnicodeTranslateError, "Onns", ...)``.
.. c:function:: PyObject* PyUnicodeDecodeError_GetEncoding(PyObject *exc)
PyObject* PyUnicodeEncodeError_GetEncoding(PyObject *exc)
@ -773,7 +783,7 @@ Standard Exceptions
All standard Python exceptions are available as global variables whose names are
``PyExc_`` followed by the Python exception name. These have the type
:c:type:`PyObject\*`; they are all class objects. For completeness, here are all
:c:type:`PyObject*`; they are all class objects. For completeness, here are all
the variables:
.. index::
@ -993,7 +1003,7 @@ Standard Warning Categories
All standard Python warning categories are available as global variables whose
names are ``PyExc_`` followed by the Python exception name. These have the type
:c:type:`PyObject\*`; they are all class objects. For completeness, here are all
:c:type:`PyObject*`; they are all class objects. For completeness, here are all
the variables:
.. index::

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

@ -8,7 +8,7 @@ File Objects
.. index:: object: file
These APIs are a minimal emulation of the Python 2 C API for built-in file
objects, which used to rely on the buffered I/O (:c:type:`FILE\*`) support
objects, which used to rely on the buffered I/O (:c:type:`FILE*`) support
from the C standard library. In Python 3, files and streams use the new
:mod:`io` module, which defines several layers over the low-level unbuffered
I/O of the operating system. The functions described below are
@ -17,7 +17,7 @@ error reporting in the interpreter; third-party code is advised to access
the :mod:`io` APIs instead.
.. c:function:: PyFile_FromFd(int fd, const char *name, const char *mode, int buffering, const char *encoding, const char *errors, const char *newline, int closefd)
.. c:function:: PyObject* PyFile_FromFd(int fd, const char *name, const char *mode, int buffering, const char *encoding, const char *errors, const char *newline, int closefd)
Create a Python file object from the file descriptor of an already
opened file *fd*. The arguments *name*, *encoding*, *errors* and *newline*
@ -82,6 +82,8 @@ the :mod:`io` APIs instead.
This function is safe to call before :c:func:`Py_Initialize`.
.. audit-event:: setopencodehook "" c.PyFile_SetOpenCodeHook
.. versionadded:: 3.8

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

@ -81,7 +81,7 @@ When a flag is set by an option, the value of the flag is the number of times
that the option was set. For example, ``-b`` sets :c:data:`Py_BytesWarningFlag`
to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
.. c:var:: Py_BytesWarningFlag
.. c:var:: int Py_BytesWarningFlag
Issue a warning when comparing :class:`bytes` or :class:`bytearray` with
:class:`str` or :class:`bytes` with :class:`int`. Issue an error if greater
@ -89,7 +89,7 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
Set by the :option:`-b` option.
.. c:var:: Py_DebugFlag
.. c:var:: int Py_DebugFlag
Turn on parser debugging output (for expert only, depending on compilation
options).
@ -97,7 +97,7 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
Set by the :option:`-d` option and the :envvar:`PYTHONDEBUG` environment
variable.
.. c:var:: Py_DontWriteBytecodeFlag
.. c:var:: int Py_DontWriteBytecodeFlag
If set to non-zero, Python won't try to write ``.pyc`` files on the
import of source modules.
@ -105,14 +105,14 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
Set by the :option:`-B` option and the :envvar:`PYTHONDONTWRITEBYTECODE`
environment variable.
.. c:var:: Py_FrozenFlag
.. c:var:: int Py_FrozenFlag
Suppress error messages when calculating the module search path in
:c:func:`Py_GetPath`.
Private flag used by ``_freeze_importlib`` and ``frozenmain`` programs.
.. c:var:: Py_HashRandomizationFlag
.. c:var:: int Py_HashRandomizationFlag
Set to ``1`` if the :envvar:`PYTHONHASHSEED` environment variable is set to
a non-empty string.
@ -120,14 +120,14 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
If the flag is non-zero, read the :envvar:`PYTHONHASHSEED` environment
variable to initialize the secret hash seed.
.. c:var:: Py_IgnoreEnvironmentFlag
.. c:var:: int Py_IgnoreEnvironmentFlag
Ignore all :envvar:`PYTHON*` environment variables, e.g.
:envvar:`PYTHONPATH` and :envvar:`PYTHONHOME`, that might be set.
Set by the :option:`-E` and :option:`-I` options.
.. c:var:: Py_InspectFlag
.. c:var:: int Py_InspectFlag
When a script is passed as first argument or the :option:`-c` option is used,
enter interactive mode after executing the script or the command, even when
@ -136,11 +136,11 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
Set by the :option:`-i` option and the :envvar:`PYTHONINSPECT` environment
variable.
.. c:var:: Py_InteractiveFlag
.. c:var:: int Py_InteractiveFlag
Set by the :option:`-i` option.
.. c:var:: Py_IsolatedFlag
.. c:var:: int Py_IsolatedFlag
Run Python in isolated mode. In isolated mode :data:`sys.path` contains
neither the script's directory nor the user's site-packages directory.
@ -149,10 +149,11 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
.. versionadded:: 3.4
.. c:var:: Py_LegacyWindowsFSEncodingFlag
.. c:var:: int Py_LegacyWindowsFSEncodingFlag
If the flag is non-zero, use the ``mbcs`` encoding instead of the UTF-8
encoding for the filesystem encoding.
If the flag is non-zero, use the ``mbcs`` encoding with ``replace`` error
handler, instead of the UTF-8 encoding with ``surrogatepass`` error handler,
for the :term:`filesystem encoding and error handler`.
Set to ``1`` if the :envvar:`PYTHONLEGACYWINDOWSFSENCODING` environment
variable is set to a non-empty string.
@ -161,7 +162,7 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
.. availability:: Windows.
.. c:var:: Py_LegacyWindowsStdioFlag
.. c:var:: int Py_LegacyWindowsStdioFlag
If the flag is non-zero, use :class:`io.FileIO` instead of
:class:`WindowsConsoleIO` for :mod:`sys` standard streams.
@ -173,7 +174,7 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
.. availability:: Windows.
.. c:var:: Py_NoSiteFlag
.. c:var:: int Py_NoSiteFlag
Disable the import of the module :mod:`site` and the site-dependent
manipulations of :data:`sys.path` that it entails. Also disable these
@ -182,7 +183,7 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
Set by the :option:`-S` option.
.. c:var:: Py_NoUserSiteDirectory
.. c:var:: int Py_NoUserSiteDirectory
Don't add the :data:`user site-packages directory <site.USER_SITE>` to
:data:`sys.path`.
@ -190,12 +191,12 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
Set by the :option:`-s` and :option:`-I` options, and the
:envvar:`PYTHONNOUSERSITE` environment variable.
.. c:var:: Py_OptimizeFlag
.. c:var:: int Py_OptimizeFlag
Set by the :option:`-O` option and the :envvar:`PYTHONOPTIMIZE` environment
variable.
.. c:var:: Py_QuietFlag
.. c:var:: int Py_QuietFlag
Don't display the copyright and version messages even in interactive mode.
@ -203,14 +204,14 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
.. versionadded:: 3.2
.. c:var:: Py_UnbufferedStdioFlag
.. c:var:: int Py_UnbufferedStdioFlag
Force the stdout and stderr streams to be unbuffered.
Set by the :option:`-u` option and the :envvar:`PYTHONUNBUFFERED`
environment variable.
.. c:var:: Py_VerboseFlag
.. c:var:: int Py_VerboseFlag
Print a message each time a module is initialized, showing the place
(filename or built-in module) from which it is loaded. If greater or equal
@ -375,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()
@ -388,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()
@ -423,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()
@ -436,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()
@ -454,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 *)
@ -637,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:
@ -830,7 +867,7 @@ code, or when embedding the Python interpreter:
.. c:type:: PyThreadState
This data structure represents the state of a single thread. The only public
data member is :c:type:`PyInterpreterState \*`:attr:`interp`, which points to
data member is :attr:`interp` (:c:type:`PyInterpreterState *`), which points to
this thread's interpreter state.
@ -1076,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`.
@ -1619,7 +1656,7 @@ The Python interpreter provides low-level support for thread-local storage
(TLS) which wraps the underlying native TLS implementation to support the
Python-level thread local storage API (:class:`threading.local`). The
CPython C level APIs are similar to those offered by pthreads and Windows:
use a thread key and functions to associate a :c:type:`void\*` value per
use a thread key and functions to associate a :c:type:`void*` value per
thread.
The GIL does *not* need to be held when calling these functions; they supply
@ -1630,8 +1667,8 @@ you need to include :file:`pythread.h` to use thread-local storage.
.. note::
None of these API functions handle memory management on behalf of the
:c:type:`void\*` values. You need to allocate and deallocate them yourself.
If the :c:type:`void\*` values happen to be :c:type:`PyObject\*`, these
:c:type:`void*` values. You need to allocate and deallocate them yourself.
If the :c:type:`void*` values happen to be :c:type:`PyObject*`, these
functions don't do refcount operations on them either.
.. _thread-specific-storage-api:
@ -1727,14 +1764,14 @@ undefined if the given :c:type:`Py_tss_t` has not been initialized by
.. c:function:: int PyThread_tss_set(Py_tss_t *key, void *value)
Return a zero value to indicate successfully associating a :c:type:`void\*`
Return a zero value to indicate successfully associating a :c:type:`void*`
value with a TSS key in the current thread. Each thread has a distinct
mapping of the key to a :c:type:`void\*` value.
mapping of the key to a :c:type:`void*` value.
.. c:function:: void* PyThread_tss_get(Py_tss_t *key)
Return the :c:type:`void\*` value associated with a TSS key in the current
Return the :c:type:`void*` value associated with a TSS key in the current
thread. This returns ``NULL`` if no value is associated with the key in the
current thread.

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

File diff suppressed because it is too large Load Diff

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

@ -229,13 +229,13 @@ Objects, Types and Reference Counts
.. index:: object: type
Most Python/C API functions have one or more arguments as well as a return value
of type :c:type:`PyObject\*`. This type is a pointer to an opaque data type
of type :c:type:`PyObject*`. This type is a pointer to an opaque data type
representing an arbitrary Python object. Since all Python object types are
treated the same way by the Python language in most situations (e.g.,
assignments, scope rules, and argument passing), it is only fitting that they
should be represented by a single C type. Almost all Python objects live on the
heap: you never declare an automatic or static variable of type
:c:type:`PyObject`, only pointer variables of type :c:type:`PyObject\*` can be
:c:type:`PyObject`, only pointer variables of type :c:type:`PyObject*` can be
declared. The sole exception are the type objects; since these must never be
deallocated, they are typically static :c:type:`PyTypeObject` objects.
@ -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
@ -496,7 +496,7 @@ Types
There are few other data types that play a significant role in the Python/C
API; most are simple C types such as :c:type:`int`, :c:type:`long`,
:c:type:`double` and :c:type:`char\*`. A few structure types are used to
:c:type:`double` and :c:type:`char*`. A few structure types are used to
describe static tables used to list the functions exported by a module or the
data attributes of a new object type, and another is used to describe the value
of a complex number. These will be discussed together with the functions that

18
Doc/c-api/iter.rst
View File

@ -44,3 +44,21 @@ something like this::
else {
/* continue doing useful work */
}
.. c:type:: PySendResult
The enum value used to represent different results of :c:func:`PyIter_Send`.
.. versionadded:: 3.10
.. c:function:: PySendResult PyIter_Send(PyObject *iter, PyObject *arg, PyObject **presult)
Sends the *arg* value into the iterator *iter*. Returns:
- ``PYGEN_RETURN`` if iterator returns. Return value is returned via *presult*.
- ``PYGEN_NEXT`` if iterator yields. Yielded value is returned via *presult*.
- ``PYGEN_ERROR`` if iterator has raised and exception. *presult* is set to ``NULL``.
.. versionadded:: 3.10

15
Doc/c-api/long.rst
View File

@ -94,23 +94,10 @@ distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate.
are no digits, :exc:`ValueError` will be raised.
.. c:function:: PyObject* PyLong_FromUnicode(Py_UNICODE *u, Py_ssize_t length, int base)
Convert a sequence of Unicode digits to a Python integer value. The Unicode
string is first encoded to a byte string using :c:func:`PyUnicode_EncodeDecimal`
and then converted using :c:func:`PyLong_FromString`.
.. deprecated-removed:: 3.3 4.0
Part of the old-style :c:type:`Py_UNICODE` API; please migrate to using
:c:func:`PyLong_FromUnicodeObject`.
.. c:function:: PyObject* PyLong_FromUnicodeObject(PyObject *u, int base)
Convert a sequence of Unicode digits in the string *u* to a Python integer
value. The Unicode string is first encoded to a byte string using
:c:func:`PyUnicode_EncodeDecimal` and then converted using
:c:func:`PyLong_FromString`.
value.
.. versionadded:: 3.3

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

@ -43,7 +43,7 @@ The following functions allow marshalled values to be read back in.
.. c:function:: long PyMarshal_ReadLongFromFile(FILE *file)
Return a C :c:type:`long` from the data stream in a :c:type:`FILE\*` opened
Return a C :c:type:`long` from the data stream in a :c:type:`FILE*` opened
for reading. Only a 32-bit value can be read in using this function,
regardless of the native size of :c:type:`long`.
@ -53,7 +53,7 @@ The following functions allow marshalled values to be read back in.
.. c:function:: int PyMarshal_ReadShortFromFile(FILE *file)
Return a C :c:type:`short` from the data stream in a :c:type:`FILE\*` opened
Return a C :c:type:`short` from the data stream in a :c:type:`FILE*` opened
for reading. Only a 16-bit value can be read in using this function,
regardless of the native size of :c:type:`short`.
@ -63,7 +63,7 @@ The following functions allow marshalled values to be read back in.
.. c:function:: PyObject* PyMarshal_ReadObjectFromFile(FILE *file)
Return a Python object from the data stream in a :c:type:`FILE\*` opened for
Return a Python object from the data stream in a :c:type:`FILE*` opened for
reading.
On error, sets the appropriate exception (:exc:`EOFError`, :exc:`ValueError`
@ -72,7 +72,7 @@ The following functions allow marshalled values to be read back in.
.. c:function:: PyObject* PyMarshal_ReadLastObjectFromFile(FILE *file)
Return a Python object from the data stream in a :c:type:`FILE\*` opened for
Return a Python object from the data stream in a :c:type:`FILE*` opened for
reading. Unlike :c:func:`PyMarshal_ReadObjectFromFile`, this function
assumes that no further objects will be read from the file, allowing it to
aggressively load file data into memory so that the de-serialization can

26
Doc/c-api/memory.rst
View File

@ -109,7 +109,7 @@ zero bytes.
.. c:function:: void* PyMem_RawMalloc(size_t n)
Allocates *n* bytes and returns a pointer of type :c:type:`void\*` to the
Allocates *n* bytes and returns a pointer of type :c:type:`void*` to the
allocated memory, or ``NULL`` if the request fails.
Requesting zero bytes returns a distinct non-``NULL`` pointer if possible, as
@ -120,7 +120,7 @@ zero bytes.
.. c:function:: void* PyMem_RawCalloc(size_t nelem, size_t elsize)
Allocates *nelem* elements each whose size in bytes is *elsize* and returns
a pointer of type :c:type:`void\*` to the allocated memory, or ``NULL`` if the
a pointer of type :c:type:`void*` to the allocated memory, or ``NULL`` if the
request fails. The memory is initialized to zeros.
Requesting zero elements or elements of size zero bytes returns a distinct
@ -180,7 +180,7 @@ The :ref:`default memory allocator <default-memory-allocators>` uses the
.. c:function:: void* PyMem_Malloc(size_t n)
Allocates *n* bytes and returns a pointer of type :c:type:`void\*` to the
Allocates *n* bytes and returns a pointer of type :c:type:`void*` to the
allocated memory, or ``NULL`` if the request fails.
Requesting zero bytes returns a distinct non-``NULL`` pointer if possible, as
@ -191,7 +191,7 @@ The :ref:`default memory allocator <default-memory-allocators>` uses the
.. c:function:: void* PyMem_Calloc(size_t nelem, size_t elsize)
Allocates *nelem* elements each whose size in bytes is *elsize* and returns
a pointer of type :c:type:`void\*` to the allocated memory, or ``NULL`` if the
a pointer of type :c:type:`void*` to the allocated memory, or ``NULL`` if the
request fails. The memory is initialized to zeros.
Requesting zero elements or elements of size zero bytes returns a distinct
@ -233,14 +233,14 @@ The following type-oriented macros are provided for convenience. Note that
.. c:function:: TYPE* PyMem_New(TYPE, size_t n)
Same as :c:func:`PyMem_Malloc`, but allocates ``(n * sizeof(TYPE))`` bytes of
memory. Returns a pointer cast to :c:type:`TYPE\*`. The memory will not have
memory. Returns a pointer cast to :c:type:`TYPE*`. The memory will not have
been initialized in any way.
.. c:function:: TYPE* PyMem_Resize(void *p, TYPE, size_t n)
Same as :c:func:`PyMem_Realloc`, but the memory block is resized to ``(n *
sizeof(TYPE))`` bytes. Returns a pointer cast to :c:type:`TYPE\*`. On return,
sizeof(TYPE))`` bytes. Returns a pointer cast to :c:type:`TYPE*`. On return,
*p* will be a pointer to the new memory area, or ``NULL`` in the event of
failure.
@ -282,7 +282,7 @@ The :ref:`default object allocator <default-memory-allocators>` uses the
.. c:function:: void* PyObject_Malloc(size_t n)
Allocates *n* bytes and returns a pointer of type :c:type:`void\*` to the
Allocates *n* bytes and returns a pointer of type :c:type:`void*` to the
allocated memory, or ``NULL`` if the request fails.
Requesting zero bytes returns a distinct non-``NULL`` pointer if possible, as
@ -293,7 +293,7 @@ The :ref:`default object allocator <default-memory-allocators>` uses the
.. c:function:: void* PyObject_Calloc(size_t nelem, size_t elsize)
Allocates *nelem* elements each whose size in bytes is *elsize* and returns
a pointer of type :c:type:`void\*` to the allocated memory, or ``NULL`` if the
a pointer of type :c:type:`void*` to the allocated memory, or ``NULL`` if the
request fails. The memory is initialized to zeros.
Requesting zero elements or elements of size zero bytes returns a distinct
@ -388,7 +388,7 @@ Customize Memory Allocators
Enum used to identify an allocator domain. Domains:
.. c:var:: PYMEM_DOMAIN_RAW
.. c:macro:: PYMEM_DOMAIN_RAW
Functions:
@ -397,7 +397,7 @@ Customize Memory Allocators
* :c:func:`PyMem_RawCalloc`
* :c:func:`PyMem_RawFree`
.. c:var:: PYMEM_DOMAIN_MEM
.. c:macro:: PYMEM_DOMAIN_MEM
Functions:
@ -406,7 +406,7 @@ Customize Memory Allocators
* :c:func:`PyMem_Calloc`
* :c:func:`PyMem_Free`
.. c:var:: PYMEM_DOMAIN_OBJ
.. c:macro:: PYMEM_DOMAIN_OBJ
Functions:
@ -519,11 +519,11 @@ Customize pymalloc Arena Allocator
| ``void free(void *ctx, size_t size, void *ptr)`` | free an arena |
+--------------------------------------------------+---------------------------------------+
.. c:function:: PyObject_GetArenaAllocator(PyObjectArenaAllocator *allocator)
.. c:function:: void PyObject_GetArenaAllocator(PyObjectArenaAllocator *allocator)
Get the arena allocator.
.. c:function:: PyObject_SetArenaAllocator(PyObjectArenaAllocator *allocator)
.. c:function:: void PyObject_SetArenaAllocator(PyObjectArenaAllocator *allocator)
Set the arena allocator.

106
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:
@ -325,7 +325,7 @@ The *m_slots* array must be terminated by a slot with id 0.
The available slot types are:
.. c:var:: Py_mod_create
.. c:macro:: Py_mod_create
Specifies a function that is called to create the module object itself.
The *value* pointer of this slot must point to a function of the signature:
@ -357,7 +357,7 @@ The available slot types are:
``PyModuleDef`` has non-``NULL`` ``m_traverse``, ``m_clear``,
``m_free``; non-zero ``m_size``; or slots other than ``Py_mod_create``.
.. c:var:: Py_mod_exec
.. c:macro:: Py_mod_exec
Specifies a function that is called to *execute* the module.
This is equivalent to executing the code of a Python module: typically,
@ -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)

55
Doc/c-api/objbuffer.rst
View File

@ -1,55 +0,0 @@
.. highlight:: c
Old Buffer Protocol
-------------------
.. deprecated:: 3.0
These functions were part of the "old buffer protocol" API in Python 2.
In Python 3, this protocol doesn't exist anymore but the functions are still
exposed to ease porting 2.x code. They act as a compatibility wrapper
around the :ref:`new buffer protocol <bufferobjects>`, but they don't give
you control over the lifetime of the resources acquired when a buffer is
exported.
Therefore, it is recommended that you call :c:func:`PyObject_GetBuffer`
(or the ``y*`` or ``w*`` :ref:`format codes <arg-parsing>` with the
:c:func:`PyArg_ParseTuple` family of functions) to get a buffer view over
an object, and :c:func:`PyBuffer_Release` when the buffer view can be released.
.. c:function:: int PyObject_AsCharBuffer(PyObject *obj, const char **buffer, Py_ssize_t *buffer_len)
Returns a pointer to a read-only memory location usable as character-based
input. The *obj* argument must support the single-segment character buffer
interface. On success, returns ``0``, sets *buffer* to the memory location
and *buffer_len* to the buffer length. Returns ``-1`` and sets a
:exc:`TypeError` on error.
.. c:function:: int PyObject_AsReadBuffer(PyObject *obj, const void **buffer, Py_ssize_t *buffer_len)
Returns a pointer to a read-only memory location containing arbitrary data.
The *obj* argument must support the single-segment readable buffer
interface. On success, returns ``0``, sets *buffer* to the memory location
and *buffer_len* to the buffer length. Returns ``-1`` and sets a
:exc:`TypeError` on error.
.. c:function:: int PyObject_CheckReadBuffer(PyObject *o)
Returns ``1`` if *o* supports the single-segment readable buffer interface.
Otherwise returns ``0``. This function always succeeds.
Note that this function tries to get and release a buffer, and exceptions
which occur while calling corresponding functions will get suppressed.
To get error reporting use :c:func:`PyObject_GetBuffer()` instead.
.. c:function:: int PyObject_AsWriteBuffer(PyObject *obj, void **buffer, Py_ssize_t *buffer_len)
Returns a pointer to a writable memory location. The *obj* argument must
support the single-segment, character buffer interface. On success,
returns ``0``, sets *buffer* to the memory location and *buffer_len* to the
buffer length. Returns ``-1`` and sets a :exc:`TypeError` on error.

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

@ -291,7 +291,7 @@ Object Protocol
is equivalent to the Python expression ``type(o)``. This function increments the
reference count of the return value. There's really no reason to use this
function instead of the common expression ``o->ob_type``, which returns a
pointer of type :c:type:`PyTypeObject\*`, except when the incremented reference
pointer of type :c:type:`PyTypeObject*`, except when the incremented reference
count is needed.

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

34
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)
@ -145,7 +141,7 @@ Implementing functions and methods
.. c:type:: PyCFunction
Type of the functions used to implement most Python callables in C.
Functions of this type take two :c:type:`PyObject\*` parameters and return
Functions of this type take two :c:type:`PyObject*` parameters and return
one such value. If the return value is ``NULL``, an exception shall have
been set. If not ``NULL``, the return value is interpreted as the return
value of the function as exposed in Python. The function must return a new
@ -224,10 +220,10 @@ Implementing functions and methods
+------------------+---------------+-------------------------------+
The :attr:`ml_meth` is a C function pointer. The functions may be of different
types, but they always return :c:type:`PyObject\*`. If the function is not of
types, but they always return :c:type:`PyObject*`. If the function is not of
the :c:type:`PyCFunction`, the compiler will require a cast in the method table.
Even though :c:type:`PyCFunction` defines the first parameter as
:c:type:`PyObject\*`, it is common that the method implementation uses the
:c:type:`PyObject*`, it is common that the method implementation uses the
specific C type of the *self* object.
The :attr:`ml_flags` field is a bitfield which can include the following flags.
@ -239,7 +235,7 @@ There are these calling conventions:
.. data:: METH_VARARGS
This is the typical calling convention, where the methods have the type
:c:type:`PyCFunction`. The function expects two :c:type:`PyObject\*` values.
:c:type:`PyCFunction`. The function expects two :c:type:`PyObject*` values.
The first one is the *self* object for methods; for module functions, it is
the module object. The second parameter (often called *args*) is a tuple
object representing all arguments. This parameter is typically processed
@ -260,13 +256,15 @@ There are these calling conventions:
Fast calling convention supporting only positional arguments.
The methods have the type :c:type:`_PyCFunctionFast`.
The first parameter is *self*, the second parameter is a C array
of :c:type:`PyObject\*` values indicating the arguments and the third
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
@ -274,7 +272,7 @@ There are these calling conventions:
with methods of type :c:type:`_PyCFunctionFastWithKeywords`.
Keyword arguments are passed the same way as in the
:ref:`vectorcall protocol <vectorcall>`:
there is an additional fourth :c:type:`PyObject\*` parameter
there is an additional fourth :c:type:`PyObject*` parameter
which is a tuple representing the names of the keyword arguments
(which are guaranteed to be strings)
or possibly ``NULL`` if there are no keywords. The values of the keyword
@ -312,7 +310,7 @@ There are these calling conventions:
Methods with a single object argument can be listed with the :const:`METH_O`
flag, instead of invoking :c:func:`PyArg_ParseTuple` with a ``"O"`` argument.
They have the type :c:type:`PyCFunction`, with the *self* parameter, and a
:c:type:`PyObject\*` parameter representing the single argument.
:c:type:`PyObject*` parameter representing the single argument.
These two constants are not used to indicate the calling convention but the
@ -463,7 +461,7 @@ Accessing attributes of extension types
| | | getter and setter |
+-------------+------------------+-----------------------------------+
The ``get`` function takes one :c:type:`PyObject\*` parameter (the
The ``get`` function takes one :c:type:`PyObject*` parameter (the
instance) and a function pointer (the associated ``closure``)::
typedef PyObject *(*getter)(PyObject *, void *);
@ -471,7 +469,7 @@ Accessing attributes of extension types
It should return a new reference on success or ``NULL`` with a set exception
on failure.
``set`` functions take two :c:type:`PyObject\*` parameters (the instance and
``set`` functions take two :c:type:`PyObject*` parameters (the instance and
the value to be set) and a function pointer (the associated ``closure``)::
typedef int (*setter)(PyObject *, PyObject *, void *);

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

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

4
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)
@ -161,7 +161,7 @@ type.
.. c:type:: PyStructSequence_Field
Describes a field of a struct sequence. As a struct sequence is modeled as a
tuple, all fields are typed as :c:type:`PyObject\*`. The index in the
tuple, all fields are typed as :c:type:`PyObject*`. The index in the
:attr:`fields` array of the :c:type:`PyStructSequence_Desc` determines which
field of the struct sequence is described.

47
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
@ -117,6 +119,13 @@ Type Objects
If no module is associated with the given type, sets :py:class:`TypeError`
and returns ``NULL``.
This function is usually used to get the module in which a method is defined.
Note that in such a method, ``PyType_GetModule(Py_TYPE(self))``
may not return the intended result.
``Py_TYPE(self)`` may be a *subclass* of the intended class, and subclasses
are not necessarily defined in the same module as their superclass.
See :c:type:`PyCMethod` to get the class that defines the method.
.. versionadded:: 3.9
.. c:function:: void* PyType_GetModuleState(PyTypeObject *type)
@ -145,20 +154,28 @@ 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* must be a module object or ``NULL``.
The *module* argument can be used to record the module in which the new
class is defined. It must be a module object or ``NULL``.
If not ``NULL``, the module is associated with the new type and can later be
retreived with :c:func:`PyType_GetModule`.
The associated module is not inherited by subclasses; it must be specified
for each class individually.
This function calls :c:func:`PyType_Ready` on the new type.
.. 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)``.
@ -215,7 +232,8 @@ The following functions and structs are used to create
* ``Py_nb_add`` to set :c:member:`PyNumberMethods.nb_add`
* ``Py_sq_length`` to set :c:member:`PySequenceMethods.sq_length`
The following fields cannot be set using :c:type:`PyType_Spec` and :c:type:`PyType_Slot`:
The following fields cannot be set at all using :c:type:`PyType_Spec` and
:c:type:`PyType_Slot`:
* :c:member:`~PyTypeObject.tp_dict`
* :c:member:`~PyTypeObject.tp_mro`
@ -229,16 +247,25 @@ The following functions and structs are used to create
(see :ref:`PyMemberDef <pymemberdef-offsets>`)
* :c:member:`~PyTypeObject.tp_vectorcall_offset`
(see :ref:`PyMemberDef <pymemberdef-offsets>`)
The following fields cannot be set using :c:type:`PyType_Spec` and
:c:type:`PyType_Slot` under the limited API:
* :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.
.. versionchanged:: 3.9
Slots in :c:type:`PyBufferProcs` in may be set in the unlimited API.
.. c:member:: void *PyType_Slot.pfunc
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``.

33
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
@ -1348,7 +1359,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
The following macro is defined to ease writing rich comparison functions:
.. c:function:: PyObject \*Py_RETURN_RICHCOMPARE(VAL_A, VAL_B, int op)
.. c:macro:: Py_RETURN_RICHCOMPARE(VAL_A, VAL_B, op)
Return ``Py_True`` or ``Py_False`` from the function, depending on the
result of a comparison.
@ -1386,7 +1397,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
than zero and contains the offset in the instance structure of the weak
reference list head (ignoring the GC header, if present); this offset is used by
:c:func:`PyObject_ClearWeakRefs` and the :c:func:`PyWeakref_\*` functions. The
instance structure needs to include a field of type :c:type:`PyObject\*` which is
instance structure needs to include a field of type :c:type:`PyObject*` which is
initialized to ``NULL``.
Do not confuse this field with :c:member:`~PyTypeObject.tp_weaklist`; that is the list head for
@ -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)

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

@ -34,6 +34,11 @@ can internally be in two states depending on how they were created:
:c:type:`Py_UNICODE*` representation; you will have to call
:c:func:`PyUnicode_READY` on them before calling any other API.
.. note::
The "legacy" Unicode object will be removed in Python 3.12 with deprecated
APIs. All Unicode objects will be "canonical" since then. See :pep:`623`
for more information.
Unicode Type
""""""""""""
@ -107,6 +112,9 @@ access internal read-only data of Unicode objects:
.. versionadded:: 3.3
.. deprecated-removed:: 3.10 3.12
This API will be removed with :c:func:`PyUnicode_FromUnicode`.
.. c:function:: Py_ssize_t PyUnicode_GET_LENGTH(PyObject *o)
@ -138,6 +146,9 @@ access internal read-only data of Unicode objects:
.. versionadded:: 3.3
.. deprecated-removed:: 3.10 3.12
``PyUnicode_WCHAR_KIND`` is deprecated.
.. c:function:: int PyUnicode_KIND(PyObject *o)
@ -188,7 +199,7 @@ access internal read-only data of Unicode objects:
.. versionadded:: 3.3
.. c:function:: PyUnicode_MAX_CHAR_VALUE(PyObject *o)
.. c:macro:: PyUnicode_MAX_CHAR_VALUE(o)
Return the maximum code point that is suitable for creating another string
based on *o*, which must be in the "canonical" representation. This is
@ -203,7 +214,7 @@ access internal read-only data of Unicode objects:
code units (this includes surrogate pairs as 2 units). *o* has to be a
Unicode object (not checked).
.. deprecated-removed:: 3.3 4.0
.. deprecated-removed:: 3.3 3.12
Part of the old-style Unicode API, please migrate to using
:c:func:`PyUnicode_GET_LENGTH`.
@ -213,7 +224,7 @@ access internal read-only data of Unicode objects:
Return the size of the deprecated :c:type:`Py_UNICODE` representation in
bytes. *o* has to be a Unicode object (not checked).
.. deprecated-removed:: 3.3 4.0
.. deprecated-removed:: 3.3 3.12
Part of the old-style Unicode API, please migrate to using
:c:func:`PyUnicode_GET_LENGTH`.
@ -235,7 +246,7 @@ access internal read-only data of Unicode objects:
code to use the new :c:func:`PyUnicode_nBYTE_DATA` macros or use
:c:func:`PyUnicode_WRITE` or :c:func:`PyUnicode_READ`.
.. deprecated-removed:: 3.3 4.0
.. deprecated-removed:: 3.3 3.12
Part of the old-style Unicode API, please migrate to using the
:c:func:`PyUnicode_nBYTE_DATA` family of macros.
@ -687,8 +698,10 @@ Extension modules can continue using them, as they will not be removed in Python
string content has been filled before using any of the access macros such as
:c:func:`PyUnicode_KIND`.
Please migrate to using :c:func:`PyUnicode_FromKindAndData`,
:c:func:`PyUnicode_FromWideChar` or :c:func:`PyUnicode_New`.
.. deprecated-removed:: 3.3 3.12
Part of the old-style Unicode API, please migrate to using
:c:func:`PyUnicode_FromKindAndData`, :c:func:`PyUnicode_FromWideChar`, or
:c:func:`PyUnicode_New`.
.. c:function:: Py_UNICODE* PyUnicode_AsUnicode(PyObject *unicode)
@ -701,9 +714,10 @@ Extension modules can continue using them, as they will not be removed in Python
embedded null code points, which would cause the string to be truncated when
used in most C functions.
Please migrate to using :c:func:`PyUnicode_AsUCS4`,
:c:func:`PyUnicode_AsWideChar`, :c:func:`PyUnicode_ReadChar` or similar new
APIs.
.. deprecated-removed:: 3.3 3.12
Part of the old-style Unicode API, please migrate to using
:c:func:`PyUnicode_AsUCS4`, :c:func:`PyUnicode_AsWideChar`,
:c:func:`PyUnicode_ReadChar` or similar new APIs.
.. c:function:: PyObject* PyUnicode_TransformDecimalToASCII(Py_UNICODE *s, Py_ssize_t size)
@ -723,19 +737,10 @@ Extension modules can continue using them, as they will not be removed in Python
.. versionadded:: 3.3
.. c:function:: Py_UNICODE* PyUnicode_AsUnicodeCopy(PyObject *unicode)
Create a copy of a Unicode string ending with a null code point. Return ``NULL``
and raise a :exc:`MemoryError` exception on memory allocation failure,
otherwise return a new allocated buffer (use :c:func:`PyMem_Free` to free
the buffer). Note that the resulting :c:type:`Py_UNICODE*` string may
contain embedded null code points, which would cause the string to be
truncated when used in most C functions.
.. versionadded:: 3.2
Please migrate to using :c:func:`PyUnicode_AsUCS4Copy` or similar new APIs.
.. deprecated-removed:: 3.3 3.12
Part of the old-style Unicode API, please migrate to using
:c:func:`PyUnicode_AsUCS4`, :c:func:`PyUnicode_AsWideChar`,
:c:func:`PyUnicode_ReadChar` or similar new APIs.
.. c:function:: Py_ssize_t PyUnicode_GetSize(PyObject *unicode)
@ -743,7 +748,9 @@ Extension modules can continue using them, as they will not be removed in Python
Return the size of the deprecated :c:type:`Py_UNICODE` representation, in
code units (this includes surrogate pairs as 2 units).
Please migrate to using :c:func:`PyUnicode_GetLength`.
.. deprecated-removed:: 3.3 3.12
Part of the old-style Unicode API, please migrate to using
:c:func:`PyUnicode_GET_LENGTH`.
.. c:function:: PyObject* PyUnicode_FromObject(PyObject *obj)
@ -776,7 +783,7 @@ system.
:c:data:`Py_FileSystemDefaultEncoding` (the locale encoding read at
Python startup).
This function ignores the Python UTF-8 mode.
This function ignores the :ref:`Python UTF-8 Mode <utf8-mode>`.
.. seealso::
@ -812,7 +819,7 @@ system.
:c:data:`Py_FileSystemDefaultEncoding` (the locale encoding read at
Python startup).
This function ignores the Python UTF-8 mode.
This function ignores the :ref:`Python UTF-8 Mode <utf8-mode>`.
.. seealso::
@ -871,8 +878,7 @@ conversion function:
.. c:function:: PyObject* PyUnicode_DecodeFSDefaultAndSize(const char *s, Py_ssize_t size)
Decode a string using :c:data:`Py_FileSystemDefaultEncoding` and the
:c:data:`Py_FileSystemDefaultEncodeErrors` error handler.
Decode a string from the :term:`filesystem encoding and error handler`.
If :c:data:`Py_FileSystemDefaultEncoding` is not set, fall back to the
locale encoding.
@ -892,8 +898,8 @@ conversion function:
.. c:function:: PyObject* PyUnicode_DecodeFSDefault(const char *s)
Decode a null-terminated string using :c:data:`Py_FileSystemDefaultEncoding`
and the :c:data:`Py_FileSystemDefaultEncodeErrors` error handler.
Decode a null-terminated string from the :term:`filesystem encoding and
error handler`.
If :c:data:`Py_FileSystemDefaultEncoding` is not set, fall back to the
locale encoding.
@ -1091,6 +1097,9 @@ These are the UTF-8 codec APIs:
.. versionchanged:: 3.7
The return type is now ``const char *`` rather of ``char *``.
.. versionchanged:: 3.10
This function is a part of the :ref:`limited API <stable>`.
.. c:function:: const char* PyUnicode_AsUTF8(PyObject *unicode)
@ -1480,17 +1489,21 @@ These are the mapping codec APIs:
The following codec API is special in that maps Unicode to Unicode.
.. c:function:: PyObject* PyUnicode_Translate(PyObject *unicode, \
PyObject *mapping, const char *errors)
.. c:function:: PyObject* PyUnicode_Translate(PyObject *str, PyObject *table, const char *errors)
Translate a Unicode object using the given *mapping* object and return the
resulting Unicode object. Return ``NULL`` if an exception was raised by the
Translate a string by applying a character mapping table to it and return the
resulting Unicode object. Return ``NULL`` if an exception was raised by the
codec.
The *mapping* object must map Unicode ordinal integers to Unicode strings,
integers (which are then interpreted as Unicode ordinals) or ``None``
(causing deletion of the character). Unmapped character ordinals (ones
which cause a :exc:`LookupError`) are left untouched and are copied as-is.
The mapping table must map Unicode ordinal integers to Unicode ordinal integers
or ``None`` (causing deletion of the character).
Mapping tables need only provide the :meth:`__getitem__` interface; dictionaries
and sequences work well. Unmapped character ordinals (ones which cause a
:exc:`LookupError`) are left untouched and are copied as-is.
*errors* has the usual meaning for codecs. It may be ``NULL`` which indicates to
use the default error handling.
.. c:function:: PyObject* PyUnicode_TranslateCharmap(const Py_UNICODE *s, Py_ssize_t size, \
@ -1593,23 +1606,6 @@ They all return ``NULL`` or ``-1`` if an exception occurs.
characters are not included in the resulting strings.
.. c:function:: PyObject* PyUnicode_Translate(PyObject *str, PyObject *table, \
const char *errors)
Translate a string by applying a character mapping table to it and return the
resulting Unicode object.
The mapping table must map Unicode ordinal integers to Unicode ordinal integers
or ``None`` (causing deletion of the character).
Mapping tables need only provide the :meth:`__getitem__` interface; dictionaries
and sequences work well. Unmapped character ordinals (ones which cause a
:exc:`LookupError`) are left untouched and are copied as-is.
*errors* has the usual meaning for codecs. It may be ``NULL`` which indicates to
use the default error handling.
.. c:function:: PyObject* PyUnicode_Join(PyObject *separator, PyObject *seq)
Join a sequence of strings using the given *separator* and return the resulting

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

@ -16,11 +16,11 @@ parameter. The available start symbols are :const:`Py_eval_input`,
:const:`Py_file_input`, and :const:`Py_single_input`. These are described
following the functions which accept them as parameters.
Note also that several of these functions take :c:type:`FILE\*` parameters. One
Note also that several of these functions take :c:type:`FILE*` parameters. One
particular issue which needs to be handled carefully is that the :c:type:`FILE`
structure for different C libraries can be different and incompatible. Under
Windows (at least), it is possible for dynamically linked extensions to actually
use different libraries, so care should be taken that :c:type:`FILE\*` parameters
use different libraries, so care should be taken that :c:type:`FILE*` parameters
are only passed to these functions if it is certain that they were created by
the same library that the Python runtime is using.
@ -112,9 +112,9 @@ the same library that the Python runtime is using.
Similar to :c:func:`PyRun_SimpleStringFlags`, but the Python source code is read
from *fp* instead of an in-memory string. *filename* should be the name of
the file, it is decoded from the filesystem encoding
(:func:`sys.getfilesystemencoding`). If *closeit* is true, the file is
closed before PyRun_SimpleFileExFlags returns.
the file, it is decoded from :term:`filesystem encoding and error handler`.
If *closeit* is true, the file is closed before
``PyRun_SimpleFileExFlags()`` returns.
.. note::
On Windows, *fp* should be opened as binary mode (e.g. ``fopen(filename, "rb")``).
@ -132,7 +132,7 @@ the same library that the Python runtime is using.
Read and execute a single statement from a file associated with an
interactive device according to the *flags* argument. The user will be
prompted using ``sys.ps1`` and ``sys.ps2``. *filename* is decoded from the
filesystem encoding (:func:`sys.getfilesystemencoding`).
:term:`filesystem encoding and error handler`.
Returns ``0`` when the input was
executed successfully, ``-1`` if there was an exception, or an error code
@ -151,9 +151,8 @@ the same library that the Python runtime is using.
Read and execute statements from a file associated with an interactive device
until EOF is reached. The user will be prompted using ``sys.ps1`` and
``sys.ps2``. *filename* is decoded from the filesystem encoding
(:func:`sys.getfilesystemencoding`). Returns ``0`` at EOF or a negative
number upon failure.
``sys.ps2``. *filename* is decoded from the :term:`filesystem encoding and
error handler`. Returns ``0`` at EOF or a negative number upon failure.
.. c:var:: int (*PyOS_InputHook)(void)
@ -206,8 +205,8 @@ the same library that the Python runtime is using.
Parse Python source code from *str* using the start token *start* according to
the *flags* argument. The result can be used to create a code object which can
be evaluated efficiently. This is useful if a code fragment must be evaluated
many times. *filename* is decoded from the filesystem encoding
(:func:`sys.getfilesystemencoding`).
many times. *filename* is decoded from the :term:`filesystem encoding and
error handler`.
.. c:function:: struct _node* PyParser_SimpleParseFile(FILE *fp, const char *filename, int start)
@ -262,7 +261,7 @@ the same library that the Python runtime is using.
Similar to :c:func:`PyRun_StringFlags`, but the Python source code is read from
*fp* instead of an in-memory string. *filename* should be the name of the file,
it is decoded from the filesystem encoding (:func:`sys.getfilesystemencoding`).
it is decoded from the :term:`filesystem encoding and error handler`.
If *closeit* is true, the file is closed before :c:func:`PyRun_FileExFlags`
returns.
@ -301,7 +300,7 @@ the same library that the Python runtime is using.
.. c:function:: PyObject* Py_CompileStringExFlags(const char *str, const char *filename, int start, PyCompilerFlags *flags, int optimize)
Like :c:func:`Py_CompileStringObject`, but *filename* is a byte string
decoded from the filesystem encoding (:func:`os.fsdecode`).
decoded from the :term:`filesystem encoding and error handler`.
.. versionadded:: 3.2

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

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

13
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']
'asdl_highlight', 'peg_highlight', 'glossary_search']
doctest_global_setup = '''
try:
@ -228,3 +227,13 @@ linkcheck_ignore = [r'https://bugs.python.org/(issue)?\d+',
# Relative filename of the reference count data file.
refcount_file = 'data/refcounts.dat'
# Sphinx 2 and Sphinx 3 compatibility
# -----------------------------------
# bpo-40204: Allow Sphinx 2 syntax in the C domain
c_allow_pre_v3 = True
# bpo-40204: Disable warnings on Sphinx 2 syntax of the C domain since the
# documentation is built with -W (warnings treated as errors).
c_warn_on_allowed_pre_v3 = False

42
Doc/data/refcounts.dat
View File

@ -1076,6 +1076,11 @@ PyIter_Check:PyObject*:o:0:
PyIter_Next:PyObject*::+1:
PyIter_Next:PyObject*:o:0:
PyIter_Send:int:::
PyIter_Send:PyObject*:iter:0:
PyIter_Send:PyObject*:arg:0:
PyIter_Send:PyObject**:presult:+1:
PyList_Append:int:::
PyList_Append:PyObject*:list:0:
PyList_Append:PyObject*:item:+1:
@ -1205,11 +1210,6 @@ PyLong_FromString:const char*:str::
PyLong_FromString:char**:pend::
PyLong_FromString:int:base::
PyLong_FromUnicode:PyObject*::+1:
PyLong_FromUnicode:Py_UNICODE*:u::
PyLong_FromUnicode:Py_ssize_t:length::
PyLong_FromUnicode:int:base::
PyLong_FromUnicodeObject:PyObject*::+1:
PyLong_FromUnicodeObject:PyObject*:u:0:
PyLong_FromUnicodeObject:int:base::
@ -1568,21 +1568,6 @@ PyOS_FSPath:PyObject*:path:0:
PyObject_ASCII:PyObject*::+1:
PyObject_ASCII:PyObject*:o:0:
PyObject_AsCharBuffer:int:::
PyObject_AsCharBuffer:PyObject*:obj:0:
PyObject_AsCharBuffer:const char**:buffer::
PyObject_AsCharBuffer:Py_ssize_t*:buffer_len::
PyObject_AsReadBuffer:int:::
PyObject_AsReadBuffer:PyObject*:obj:0:
PyObject_AsReadBuffer:const void**:buffer::
PyObject_AsReadBuffer:Py_ssize_t*:buffer_len::
PyObject_AsWriteBuffer:int:::
PyObject_AsWriteBuffer:PyObject*:obj:0:
PyObject_AsWriteBuffer:void**:buffer::
PyObject_AsWriteBuffer:Py_ssize_t*:buffer_len::
PyObject_Bytes:PyObject*::+1:
PyObject_Bytes:PyObject*:o:0:
@ -1618,9 +1603,6 @@ PyObject_CallObject:PyObject*:args:0:
PyObject_CheckBuffer:int:::
PyObject_CheckBuffer:PyObject*:obj:0:
PyObject_CheckReadBuffer:int:::
PyObject_CheckReadBuffer:PyObject*:o:0:
PyObject_DelAttr:int:::
PyObject_DelAttr:PyObject*:o:0:
PyObject_DelAttr:PyObject*:attr_name:0:
@ -2306,6 +2288,11 @@ PyType_CheckExact:PyObject*:o:0:
PyType_FromSpec:PyObject*::+1:
PyType_FromSpec:PyType_Spec*:spec::
PyType_FromModuleAndSpec:PyObject*::+1:
PyType_FromModuleAndSpec:PyObject*:module:+1:
PyType_FromModuleAndSpec:PyType_Spec*:spec::
PyType_FromModuleAndSpec:PyObject*:bases:0:
PyType_FromSpecWithBases:PyObject*::+1:
PyType_FromSpecWithBases:PyType_Spec*:spec::
PyType_FromSpecWithBases:PyObject*:bases:0:
@ -2442,9 +2429,6 @@ PyUnicode_AsUnicodeAndSize:Py_UNICODE*:::
PyUnicode_AsUnicodeAndSize:PyObject*:unicode:0:
PyUnicode_AsUnicodeAndSize:Py_ssize_t*:size::
PyUnicode_AsUnicodeCopy:Py_UNICODE*:::
PyUnicode_AsUnicodeCopy:PyObject*:unicode:0:
PyUnicode_GetSize:Py_ssize_t:::
PyUnicode_GetSize:PyObject*:unicode:0:
@ -3023,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:::
@ -3044,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

3
Doc/distributing/index.rst
View File

@ -128,6 +128,7 @@ involved in creating and publishing a project:
* `Project structure`_
* `Building and packaging the project`_
* `Uploading the project to the Python Packaging Index`_
* `The .pypirc file`_
.. _Project structure: \
https://packaging.python.org/tutorials/distributing-packages/
@ -135,6 +136,8 @@ involved in creating and publishing a project:
https://packaging.python.org/tutorials/distributing-packages/#packaging-your-project
.. _Uploading the project to the Python Packaging Index: \
https://packaging.python.org/tutorials/distributing-packages/#uploading-your-project-to-pypi
.. _The .pypirc file: \
https://packaging.python.org/specifications/pypirc/
How do I...?

2
Doc/extending/newtypes_tutorial.rst
View File

@ -416,7 +416,7 @@ But this would be risky. Our type doesn't restrict the type of the
``first`` member, so it could be any kind of object. It could have a
destructor that causes code to be executed that tries to access the
``first`` member; or that destructor could release the
:term:`Global interpreter Lock` and let arbitrary code run in other
:term:`Global interpreter Lock <GIL>` and let arbitrary code run in other
threads that accesses and modifies our object.
To be paranoid and protect ourselves against this possibility, we almost

3
Doc/faq/design.rst
View File

@ -573,8 +573,7 @@ whether an instance or a class implements a particular ABC. The
:class:`~collections.abc.MutableMapping`.
For Python, many of the advantages of interface specifications can be obtained
by an appropriate test discipline for components. There is also a tool,
PyChecker, which can be used to find problems due to subclassing.
by an appropriate test discipline for components.
A good test suite for a module can both provide a regression test and serve as a
module interface specification and a set of examples. Many Python modules can

16
Doc/faq/general.rst
View File

@ -142,9 +142,9 @@ to fix critical bugs.
Alpha, beta and release candidate versions have an additional suffix. The
suffix for an alpha version is "aN" for some small number N, the suffix for a
beta version is "bN" for some small number N, and the suffix for a release
candidate version is "cN" for some small number N. In other words, all versions
candidate version is "rcN" for some small number N. In other words, all versions
labeled 2.0aN precede the versions labeled 2.0bN, which precede versions labeled
2.0cN, and *those* precede 2.0.
2.0rcN, and *those* precede 2.0.
You may also find version numbers with a "+" suffix, e.g. "2.2+". These are
unreleased versions, built directly from the CPython development repository. In
@ -296,8 +296,8 @@ How stable is Python?
---------------------
Very stable. New, stable releases have been coming out roughly every 6 to 18
months since 1991, and this seems likely to continue. Currently there are
usually around 18 months between major releases.
months since 1991, and this seems likely to continue. As of version 3.9,
Python will have a major new release every 12 months (:pep:`602`).
The developers issue "bugfix" releases of older versions, so the stability of
existing releases gradually improves. Bugfix releases, indicated by a third
@ -309,14 +309,14 @@ releases.
The latest stable releases can always be found on the `Python download page
<https://www.python.org/downloads/>`_. There are two production-ready versions
of Python: 2.x and 3.x. The recommended version is 3.x, which is supported by
most widely used libraries. Although 2.x is still widely used, `it will not
be maintained after January 1, 2020 <https://www.python.org/dev/peps/pep-0373/>`_.
most widely used libraries. Although 2.x is still widely used, `it is not
maintained anymore <https://www.python.org/dev/peps/pep-0373/>`_.
How many people are using Python?
---------------------------------
There are probably tens of thousands of users, though it's difficult to obtain
an exact count.
There are probably millions of users, though it's difficult to obtain an exact
count.
Python is available for free download, so there are no sales figures, and it's
available from many different sites and packaged with many Linux distributions,

166
Doc/faq/programming.rst
View File

@ -35,12 +35,6 @@ for Windows Extensions <https://sourceforge.net/projects/pywin32/>`__ project an
as a part of the ActivePython distribution (see
https://www.activestate.com/activepython\ ).
`Boa Constructor <http://boa-constructor.sourceforge.net/>`_ is an IDE and GUI
builder that uses wxWidgets. It offers visual frame creation and manipulation,
an object inspector, many views on the source like object browsers, inheritance
hierarchies, doc string generated html documentation, an advanced debugger,
integrated help, and Zope support.
`Eric <http://eric-ide.python-projects.org/>`_ is an IDE built on PyQt
and the Scintilla editing component.
@ -57,22 +51,14 @@ They include:
* PyCharm (https://www.jetbrains.com/pycharm/)
Is there a tool to help find bugs or perform static analysis?
Are there tools to help find bugs or perform static analysis?
-------------------------------------------------------------
Yes.
PyChecker is a static analysis tool that finds bugs in Python source code and
warns about code complexity and style. You can get PyChecker from
http://pychecker.sourceforge.net/.
`Pylint <https://www.pylint.org/>`_ is another tool that checks
if a module satisfies a coding standard, and also makes it possible to write
plug-ins to add a custom feature. In addition to the bug checking that
PyChecker performs, Pylint offers some additional features such as checking line
length, whether variable names are well-formed according to your coding
standard, whether declared interfaces are fully implemented, and more.
https://docs.pylint.org/ provides a full list of Pylint's features.
`Pylint <https://www.pylint.org/>`_ and
`Pyflakes <https://github.com/PyCQA/pyflakes>`_ do basic checking that will
help you catch bugs sooner.
Static type checkers such as `Mypy <http://mypy-lang.org/>`_,
`Pyre <https://pyre-check.org/>`_, and
@ -518,14 +504,14 @@ desired effect in a number of ways.
1) By returning a tuple of the results::
def func2(a, b):
a = 'new-value' # a and b are local names
b = b + 1 # assigned to new objects
return a, b # return new values
x, y = 'old-value', 99
x, y = func2(x, y)
print(x, y) # output: new-value 100
>>> def func1(a, b):
... a = 'new-value' # a and b are local names
... b = b + 1 # assigned to new objects
... return a, b # return new values
...
>>> x, y = 'old-value', 99
>>> func1(x, y)
('new-value', 100)
This is almost always the clearest solution.
@ -533,38 +519,41 @@ desired effect in a number of ways.
3) By passing a mutable (changeable in-place) object::
def func1(a):
a[0] = 'new-value' # 'a' references a mutable list
a[1] = a[1] + 1 # changes a shared object
args = ['old-value', 99]
func1(args)
print(args[0], args[1]) # output: new-value 100
>>> def func2(a):
... a[0] = 'new-value' # 'a' references a mutable list
... a[1] = a[1] + 1 # changes a shared object
...
>>> args = ['old-value', 99]
>>> func2(args)
>>> args
['new-value', 100]
4) By passing in a dictionary that gets mutated::
def func3(args):
args['a'] = 'new-value' # args is a mutable dictionary
args['b'] = args['b'] + 1 # change it in-place
args = {'a': 'old-value', 'b': 99}
func3(args)
print(args['a'], args['b'])
>>> def func3(args):
... args['a'] = 'new-value' # args is a mutable dictionary
... args['b'] = args['b'] + 1 # change it in-place
...
>>> args = {'a': 'old-value', 'b': 99}
>>> func3(args)
>>> args
{'a': 'new-value', 'b': 100}
5) Or bundle up values in a class instance::
class callByRef:
def __init__(self, /, **args):
for key, value in args.items():
setattr(self, key, value)
def func4(args):
args.a = 'new-value' # args is a mutable callByRef
args.b = args.b + 1 # change object in-place
args = callByRef(a='old-value', b=99)
func4(args)
print(args.a, args.b)
>>> class Namespace:
... def __init__(self, /, **args):
... for key, value in args.items():
... setattr(self, key, value)
...
>>> def func4(args):
... args.a = 'new-value' # args is a mutable Namespace
... args.b = args.b + 1 # change object in-place
...
>>> args = Namespace(a='old-value', b=99)
>>> func4(args)
>>> vars(args)
{'a': 'new-value', 'b': 100}
There's almost never a good reason to get this complicated.
@ -953,7 +942,7 @@ There are various techniques.
f()
* Use :func:`locals` or :func:`eval` to resolve the function name::
* Use :func:`locals` to resolve the function name::
def myFunc():
print("hello")
@ -963,12 +952,6 @@ There are various techniques.
f = locals()[fname]
f()
f = eval(fname)
f()
Note: Using :func:`eval` is slow and dangerous. If you don't have absolute
control over the contents of the string, someone could pass a string that
resulted in an arbitrary function being executed.
Is there an equivalent to Perl's chomp() for removing trailing newlines from strings?
-------------------------------------------------------------------------------------
@ -1133,7 +1116,7 @@ trailing newline from a string.
How do I iterate over a sequence in reverse order?
--------------------------------------------------
Use the :func:`reversed` built-in function, which is new in Python 2.4::
Use the :func:`reversed` built-in function::
for x in reversed(sequence):
... # do something with x ...
@ -1141,11 +1124,6 @@ Use the :func:`reversed` built-in function, which is new in Python 2.4::
This won't touch your original sequence, but build a new copy with reversed
order to iterate over.
With Python 2.3, you can use an extended slice syntax::
for x in sequence[::-1]:
... # do something with x ...
How do you remove duplicates from a list?
-----------------------------------------
@ -1175,6 +1153,21 @@ This converts the list into a set, thereby removing duplicates, and then back
into a list.
How do you remove multiple items from a list
--------------------------------------------
As with removing duplicates, explicitly iterating in reverse with a
delete condition is one possibility. However, it is easier and faster
to use slice replacement with an implicit or explicit forward iteration.
Here are three variations.::
mylist[:] = filter(keep_function, mylist)
mylist[:] = (x for x in mylist if keep_condition)
mylist[:] = [x for x in mylist if keep_condition]
The list comprehension may be fastest.
How do you make an array in Python?
-----------------------------------
@ -1187,7 +1180,7 @@ difference is that a Python list can contain objects of many different types.
The ``array`` module also provides methods for creating arrays of fixed types
with compact representations, but they are slower to index than lists. Also
note that the Numeric extensions and others define array-like structures with
note that NumPy and other third party packages define array-like structures with
various characteristics as well.
To get Lisp-style linked lists, you can emulate cons cells using tuples::
@ -1377,20 +1370,6 @@ out the element you want. ::
['else', 'sort', 'to', 'something']
An alternative for the last step is::
>>> result = []
>>> for p in pairs: result.append(p[1])
If you find this more legible, you might prefer to use this instead of the final
list comprehension. However, it is almost twice as slow for long lists. Why?
First, the ``append()`` operation has to reallocate memory, and while it uses
some tricks to avoid doing that each time, it still has to do it occasionally,
and that costs quite a bit. Second, the expression "result.append" requires an
extra attribute lookup, and third, there's a speed reduction from having to make
all those function calls.
Objects
=======
@ -1515,37 +1494,36 @@ Most :meth:`__setattr__` implementations must modify ``self.__dict__`` to store
local state for self without causing an infinite recursion.
How do I call a method defined in a base class from a derived class that overrides it?
--------------------------------------------------------------------------------------
How do I call a method defined in a base class from a derived class that extends it?
------------------------------------------------------------------------------------
Use the built-in :func:`super` function::
class Derived(Base):
def meth(self):
super(Derived, self).meth()
super().meth() # calls Base.meth
For version prior to 3.0, you may be using classic classes: For a class
definition such as ``class Derived(Base): ...`` you can call method ``meth()``
defined in ``Base`` (or one of ``Base``'s base classes) as ``Base.meth(self,
arguments...)``. Here, ``Base.meth`` is an unbound method, so you need to
provide the ``self`` argument.
In the example, :func:`super` will automatically determine the instance from
which it was called (the ``self`` value), look up the :term:`method resolution
order` (MRO) with ``type(self).__mro__``, and return the next in line after
``Derived`` in the MRO: ``Base``.
How can I organize my code to make it easier to change the base class?
----------------------------------------------------------------------
You could define an alias for the base class, assign the real base class to it
before your class definition, and use the alias throughout your class. Then all
You could assign the base class to an alias and derive from the alias. Then all
you have to change is the value assigned to the alias. Incidentally, this trick
is also handy if you want to decide dynamically (e.g. depending on availability
of resources) which base class to use. Example::
BaseAlias = <real base class>
class Base:
...
BaseAlias = Base
class Derived(BaseAlias):
def meth(self):
BaseAlias.meth(self)
...
...
How do I create static class data and static class methods?

4
Doc/faq/windows.rst
View File

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

95
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`,
@ -189,6 +201,10 @@ Glossary
A list of bytecode instructions can be found in the documentation for
:ref:`the dis module <bytecodes>`.
callback
A subroutine function which is passed as an argument to be executed at
some point in the future.
class
A template for creating user-defined objects. Class definitions
normally contain method definitions which operate on instances of the
@ -297,13 +313,20 @@ Glossary
including functions, methods, properties, class methods, static methods,
and reference to super classes.
For more information about descriptors' methods, see :ref:`descriptors`.
For more information about descriptors' methods, see :ref:`descriptors`
or the :ref:`Descriptor How To Guide <descriptorhowto>`.
dictionary
An associative array, where arbitrary keys are mapped to values. The
keys can be any object with :meth:`__hash__` and :meth:`__eq__` methods.
Called a hash in Perl.
dictionary comprehension
A compact way to process all or part of the elements in an iterable and
return a dictionary with the results. ``results = {n: n ** 2 for n in
range(10)}`` generates a dictionary containing key ``n`` mapped to
value ``n ** 2``. See :ref:`comprehensions`.
dictionary view
The objects returned from :meth:`dict.keys`, :meth:`dict.values`, and
:meth:`dict.items` are called dictionary views. They provide a dynamic
@ -375,6 +398,25 @@ Glossary
file-like object
A synonym for :term:`file object`.
filesystem encoding and error handler
Encoding and error handler used by Python to decode bytes from the
operating system and encode Unicode to the operating system.
The filesystem encoding must guarantee to successfully decode all bytes
below 128. If the file system encoding fails to provide this guarantee,
API functions can raise :exc:`UnicodeError`.
The :func:`sys.getfilesystemencoding` and
:func:`sys.getfilesystemencodeerrors` functions can be used to get the
filesystem encoding and error handler.
The :term:`filesystem encoding and error handler` are configured at
Python startup by the :c:func:`PyConfig_Read` function: see
:c:member:`~PyConfig.filesystem_encoding` and
:c:member:`~PyConfig.filesystem_errors` members of :c:type:`PyConfig`.
See also the :term:`locale encoding`.
finder
An object that tries to find the :term:`loader` for a module that is
being imported.
@ -472,6 +514,13 @@ Glossary
See also the :term:`single dispatch` glossary entry, the
:func:`functools.singledispatch` decorator, and :pep:`443`.
generic type
A :term:`type` that can be parameterized; typically a container like
:class:`list`. Used for :term:`type hints <type hint>` and
:term:`annotations <annotation>`.
See :pep:`483` for more details, and :mod:`typing` or
:ref:`generic alias type <types-genericalias>` for its uses.
GIL
See :term:`global interpreter lock`.
@ -583,7 +632,7 @@ Glossary
and :class:`tuple`) and some non-sequence types like :class:`dict`,
:term:`file objects <file object>`, and objects of any classes you define
with an :meth:`__iter__` method or with a :meth:`__getitem__` method
that implements :term:`Sequence` semantics.
that implements :term:`Sequence <sequence>` semantics.
Iterables can be
used in a :keyword:`for` loop and in many other places where a sequence is
@ -655,6 +704,18 @@ Glossary
thread removes *key* from *mapping* after the test, but before the lookup.
This issue can be solved with locks or by using the EAFP approach.
locale encoding
On Unix, it is the encoding of the LC_CTYPE locale. It can be set with
``locale.setlocale(locale.LC_CTYPE, new_locale)``.
On Windows, it is is the ANSI code page (ex: ``cp1252``).
``locale.getpreferredencoding(False)`` can be used to get the locale
encoding.
Python uses the :term:`filesystem encoding and error handler` to convert
between Unicode filenames and bytes filenames.
list
A built-in Python :term:`sequence`. Despite its name it is more akin
to an array in other languages than to a linked list since access to
@ -1020,7 +1081,13 @@ Glossary
:meth:`index`, :meth:`__contains__`, and
:meth:`__reversed__`. Types that implement this expanded
interface can be registered explicitly using
:func:`~abc.register`.
:func:`~abc.ABCMeta.register`.
set comprehension
A compact way to process all or part of the elements in an iterable and
return a set with the results. ``results = {c for c in 'abracadabra' if
c not in 'abc'}`` generates the set of strings ``{'r', 'd'}``. See
:ref:`comprehensions`.
single dispatch
A form of :term:`generic function` dispatch where the implementation is
@ -1045,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.
@ -1080,19 +1159,15 @@ Glossary
Type aliases are useful for simplifying :term:`type hints <type hint>`.
For example::
from typing import List, Tuple
def remove_gray_shades(
colors: List[Tuple[int, int, int]]) -> List[Tuple[int, int, int]]:
colors: list[tuple[int, int, int]]) -> list[tuple[int, int, int]]:
pass
could be made more readable like this::
from typing import List, Tuple
Color = tuple[int, int, int]
Color = Tuple[int, int, int]
def remove_gray_shades(colors: List[Color]) -> List[Color]:
def remove_gray_shades(colors: list[Color]) -> list[Color]:
pass
See :mod:`typing` and :pep:`484`, which describe this functionality.

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

1499
Doc/howto/descriptor.rst
View File

File diff suppressed because it is too large Load Diff

24
Doc/howto/instrumentation.rst
View File

@ -272,9 +272,7 @@ should instead read:
Available static markers
------------------------
.. I'm reusing the "c:function" type for markers
.. c:function:: function__entry(str filename, str funcname, int lineno)
.. object:: function__entry(str filename, str funcname, int lineno)
This marker indicates that execution of a Python function has begun.
It is only triggered for pure-Python (bytecode) functions.
@ -290,7 +288,7 @@ Available static markers
* ``$arg3`` : ``int`` line number
.. c:function:: function__return(str filename, str funcname, int lineno)
.. object:: function__return(str filename, str funcname, int lineno)
This marker is the converse of :c:func:`function__entry`, and indicates that
execution of a Python function has ended (either via ``return``, or via an
@ -298,7 +296,7 @@ Available static markers
The arguments are the same as for :c:func:`function__entry`
.. c:function:: line(str filename, str funcname, int lineno)
.. object:: line(str filename, str funcname, int lineno)
This marker indicates a Python line is about to be executed. It is
the equivalent of line-by-line tracing with a Python profiler. It is
@ -306,24 +304,24 @@ Available static markers
The arguments are the same as for :c:func:`function__entry`.
.. c:function:: gc__start(int generation)
.. object:: gc__start(int generation)
Fires when the Python interpreter starts a garbage collection cycle.
``arg0`` is the generation to scan, like :func:`gc.collect()`.
.. c:function:: gc__done(long collected)
.. object:: gc__done(long collected)
Fires when the Python interpreter finishes a garbage collection
cycle. ``arg0`` is the number of collected objects.
.. c:function:: import__find__load__start(str modulename)
.. object:: import__find__load__start(str modulename)
Fires before :mod:`importlib` attempts to find and load the module.
``arg0`` is the module name.
.. versionadded:: 3.7
.. c:function:: import__find__load__done(str modulename, int found)
.. object:: import__find__load__done(str modulename, int found)
Fires after :mod:`importlib`'s find_and_load function is called.
``arg0`` is the module name, ``arg1`` indicates if module was
@ -332,7 +330,7 @@ Available static markers
.. versionadded:: 3.7
.. c:function:: audit(str event, void *tuple)
.. object:: audit(str event, void *tuple)
Fires when :func:`sys.audit` or :c:func:`PySys_Audit` is called.
``arg0`` is the event name as C string, ``arg1`` is a :c:type:`PyObject`
@ -375,14 +373,14 @@ If this file is installed in SystemTap's tapset directory (e.g.
``/usr/share/systemtap/tapset``), then these additional probepoints become
available:
.. c:function:: python.function.entry(str filename, str funcname, int lineno, frameptr)
.. object:: python.function.entry(str filename, str funcname, int lineno, frameptr)
This probe point indicates that execution of a Python function has begun.
It is only triggered for pure-Python (bytecode) functions.
.. c:function:: python.function.return(str filename, str funcname, int lineno, frameptr)
.. object:: python.function.return(str filename, str funcname, int lineno, frameptr)
This probe point is the converse of :c:func:`python.function.return`, and
This probe point is the converse of ``python.function.return``, and
indicates that execution of a Python function has ended (either via
``return``, or via an exception). It is only triggered for pure-Python
(bytecode) functions.

4
Doc/howto/logging-cookbook.rst
View File

@ -1368,7 +1368,7 @@ An example dictionary-based configuration
-----------------------------------------
Below is an example of a logging configuration dictionary - it's taken from
the `documentation on the Django project <https://docs.djangoproject.com/en/1.9/topics/logging/#configuring-logging>`_.
the `documentation on the Django project <https://docs.djangoproject.com/en/stable/topics/logging/#configuring-logging>`_.
This dictionary is passed to :func:`~config.dictConfig` to put the configuration into effect::
LOGGING = {
@ -1424,7 +1424,7 @@ This dictionary is passed to :func:`~config.dictConfig` to put the configuration
}
For more information about this configuration, you can see the `relevant
section <https://docs.djangoproject.com/en/1.9/topics/logging/#configuring-logging>`_
section <https://docs.djangoproject.com/en/stable/topics/logging/#configuring-logging>`_
of the Django documentation.
.. _cookbook-rotator-namer:

30
Doc/howto/logging.rst
View File

@ -1078,20 +1078,22 @@ need more precise control over what logging information is collected. Here's a
list of things you can do to avoid processing during logging which you don't
need:
+-----------------------------------------------+----------------------------------------+
| What you don't want to collect | How to avoid collecting it |
+===============================================+========================================+
| Information about where calls were made from. | Set ``logging._srcfile`` to ``None``. |
| | This avoids calling |
| | :func:`sys._getframe`, which may help |
| | to speed up your code in environments |
| | like PyPy (which can't speed up code |
| | that uses :func:`sys._getframe`). |
+-----------------------------------------------+----------------------------------------+
| Threading information. | Set ``logging.logThreads`` to ``0``. |
+-----------------------------------------------+----------------------------------------+
| Process information. | Set ``logging.logProcesses`` to ``0``. |
+-----------------------------------------------+----------------------------------------+
+-----------------------------------------------------+---------------------------------------------------+
| What you don't want to collect | How to avoid collecting it |
+=====================================================+===================================================+
| Information about where calls were made from. | Set ``logging._srcfile`` to ``None``. |
| | This avoids calling :func:`sys._getframe`, which |
| | may help to speed up your code in environments |
| | like PyPy (which can't speed up code that uses |
| | :func:`sys._getframe`). |
+-----------------------------------------------------+---------------------------------------------------+
| Threading information. | Set ``logging.logThreads`` to ``False``. |
+-----------------------------------------------------+---------------------------------------------------+
| Current process ID (:func:`os.getpid`) | Set ``logging.logProcesses`` to ``False``. |
+-----------------------------------------------------+---------------------------------------------------+
| Current process name when using ``multiprocessing`` | Set ``logging.logMultiprocessing`` to ``False``. |
| to manage multiple processes. | |
+-----------------------------------------------------+---------------------------------------------------+
Also note that the core logging module only includes the basic handlers. If
you don't import :mod:`logging.handlers` and :mod:`logging.config`, they won't

10
Doc/howto/unicode.rst
View File

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

2
Doc/library/__future__.rst
View File

@ -90,7 +90,7 @@ language using this mechanism:
| generator_stop | 3.5.0b1 | 3.7 | :pep:`479`: |
| | | | *StopIteration handling inside generators* |
+------------------+-------------+--------------+---------------------------------------------+
| annotations | 3.7.0b1 | 4.0 | :pep:`563`: |
| annotations | 3.7.0b1 | 3.10 | :pep:`563`: |
| | | | *Postponed evaluation of annotations* |
+------------------+-------------+--------------+---------------------------------------------+

27
Doc/library/abc.rst
View File

@ -174,10 +174,11 @@ The :mod:`abc` module also provides the following decorator:
to declare abstract methods for properties and descriptors.
Dynamically adding abstract methods to a class, or attempting to modify the
abstraction status of a method or class once it is created, are not
supported. The :func:`abstractmethod` only affects subclasses derived using
regular inheritance; "virtual subclasses" registered with the ABC's
:meth:`register` method are not affected.
abstraction status of a method or class once it is created, are only
supported using the :func:`update_abstractmethods` function. The
:func:`abstractmethod` only affects subclasses derived using regular
inheritance; "virtual subclasses" registered with the ABC's :meth:`register`
method are not affected.
When :func:`abstractmethod` is applied in combination with other method
descriptors, it should be applied as the innermost decorator, as shown in
@ -235,7 +236,6 @@ The :mod:`abc` module also provides the following decorator:
super-call in a framework that uses cooperative
multiple-inheritance.
The :mod:`abc` module also supports the following legacy decorators:
.. decorator:: abstractclassmethod
@ -335,6 +335,23 @@ 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
be called from within a class decorator.
Returns *cls*, to allow usage as a class decorator.
If *cls* is not an instance of :class:`ABCMeta`, does nothing.
.. note::
This function assumes that *cls*'s superclasses are already updated.
It does not update any subclasses.
.. versionadded:: 3.10
.. rubric:: Footnotes

2
Doc/library/aifc.rst
View File

@ -208,6 +208,7 @@ number of frames must be filled in.
.. method:: aifc.tell()
:noindex:
Return the current write position in the output file. Useful in combination
with :meth:`setmark`.
@ -232,6 +233,7 @@ number of frames must be filled in.
.. method:: aifc.close()
:noindex:
Close the AIFF file. The header of the file is updated to reflect the actual
size of the audio data. After calling this method, the object can no longer be

175
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
@ -1134,6 +1149,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.
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
^^^^^^^^
@ -1148,8 +1171,8 @@ keyword argument to :meth:`~ArgumentParser.add_argument`::
>>> parser.parse_args(['--foo', 'BAR'])
Namespace(foo='BAR')
>>> parser.parse_args([])
usage: argparse.py [-h] [--foo FOO]
argparse.py: error: option --foo is required
usage: [-h] --foo FOO
: error: the following arguments are required: --foo
As the example shows, if an option is marked as ``required``,
:meth:`~ArgumentParser.parse_args` will report an error if that option is not
@ -1180,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
@ -1198,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
@ -1212,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
@ -1239,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
@ -1256,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
@ -1274,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
@ -1678,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
@ -1688,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
@ -1711,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:

5
Doc/library/array.rst
View File

@ -257,7 +257,6 @@ Examples::
Packing and unpacking of External Data Representation (XDR) data as used in some
remote procedure call systems.
`The Numerical Python Documentation <https://docs.scipy.org/doc/>`_
The Numeric Python extension (NumPy) defines another array type; see
http://www.numpy.org/ for further information about Numerical Python.
`NumPy <https://numpy.org/>`_
The NumPy package defines another array type.

87
Doc/library/ast.rst
View File

@ -80,12 +80,13 @@ Node classes
end_col_offset
Instances of :class:`ast.expr` and :class:`ast.stmt` subclasses have
:attr:`lineno`, :attr:`col_offset`, :attr:`lineno`, and :attr:`col_offset`
attributes. The :attr:`lineno` and :attr:`end_lineno` are the first and
last line numbers of source text span (1-indexed so the first line is line 1)
and the :attr:`col_offset` and :attr:`end_col_offset` are the corresponding
UTF-8 byte offsets of the first and last tokens that generated the node.
The UTF-8 offset is recorded because the parser uses UTF-8 internally.
:attr:`lineno`, :attr:`col_offset`, :attr:`end_lineno`, and
:attr:`end_col_offset` attributes. The :attr:`lineno` and :attr:`end_lineno`
are the first and last line numbers of source text span (1-indexed so the
first line is line 1) and the :attr:`col_offset` and :attr:`end_col_offset`
are the corresponding UTF-8 byte offsets of the first and last tokens that
generated the node. The UTF-8 offset is recorded because the parser uses
UTF-8 internally.
Note that the end positions are not required by the compiler and are
therefore optional. The end offset is *after* the last symbol, for example
@ -1503,6 +1504,13 @@ Async and await
fields as :class:`For` and :class:`With`, respectively. Only valid in the
body of an :class:`AsyncFunctionDef`.
.. note::
When a string is parsed by :func:`ast.parse`, operator nodes (subclasses
of :class:`ast.operator`, :class:`ast.unaryop`, :class:`ast.cmpop`,
:class:`ast.boolop` and :class:`ast.expr_context`) on the returned tree
will be singletons. Changes to one will be reflected in all other
occurrences of the same value (e.g. :class:`ast.Add`).
:mod:`ast` Helpers
------------------
@ -1553,7 +1561,12 @@ and classes for traversing abstract syntax trees:
.. warning::
The produced code string will not necessarily be equal to the original
code that generated the :class:`ast.AST` object.
code that generated the :class:`ast.AST` object (without any compiler
optimizations, such as constant tuples/frozensets).
.. warning::
Trying to unparse a highly complex expression would result with
:exc:`RecursionError`.
.. versionadded:: 3.9
@ -1563,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
@ -1575,12 +1588,19 @@ 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.
.. versionchanged:: 3.9
Now supports creating empty sets with ``'set()'``.
.. versionchanged:: 3.10
For string inputs, leading spaces and tabs are now stripped.
.. function:: get_docstring(node, clean=True)
@ -1748,6 +1768,34 @@ and classes for traversing abstract syntax trees:
Added the *indent* option.
.. _ast-compiler-flags:
Compiler Flags
--------------
The following flags may be passed to :func:`compile` in order to change
effects on the compilation of a program:
.. data:: PyCF_ALLOW_TOP_LEVEL_AWAIT
Enables support for top-level ``await``, ``async for``, ``async with``
and async comprehensions.
.. versionadded:: 3.8
.. data:: PyCF_ONLY_AST
Generates and returns an abstract syntax tree instead of returning a
compiled code object.
.. data:: PyCF_TYPE_COMMENTS
Enables support for :pep:`484` and :pep:`526` style type comments
(``# type: <type>``, ``# type: ignore <stuff>``).
.. versionadded:: 3.8
.. _ast-cli:
Command-Line Usage
@ -1795,5 +1843,24 @@ to stdout. Otherwise, the content is read from stdin.
.. seealso::
`Green Tree Snakes <https://greentreesnakes.readthedocs.io/>`_, an external documentation resource, has good
details on working with Python ASTs.
`Green Tree Snakes <https://greentreesnakes.readthedocs.io/>`_, an external
documentation resource, has good details on working with Python ASTs.
`ASTTokens <https://asttokens.readthedocs.io/en/latest/user-guide.html>`_
annotates Python ASTs with the positions of tokens and text in the source
code that generated them. This is helpful for tools that make source code
transformations.
`leoAst.py <http://leoeditor.com/appendices.html#leoast-py>`_ unifies the
token-based and parse-tree-based views of python programs by inserting
two-way links between tokens and ast nodes.
`LibCST <https://libcst.readthedocs.io/>`_ parses code as a Concrete Syntax
Tree that looks like an ast tree and keeps all formatting details. It's
useful for building automated refactoring (codemod) applications and
linters.
`Parso <https://parso.readthedocs.io>`_ is a Python parser that supports
error recovery and round-trip parsing for different Python versions (in
multiple Python versions). Parso is also able to list multiple syntax errors
in your python file.

12
Doc/library/asyncio-dev.rst
View File

@ -73,7 +73,7 @@ event loop, no other Tasks can run in the same thread. When a Task
executes an ``await`` expression, the running Task gets suspended, and
the event loop executes the next Task.
To schedule a callback from a different OS thread, the
To schedule a :term:`callback` from another OS thread, the
:meth:`loop.call_soon_threadsafe` method should be used. Example::
loop.call_soon_threadsafe(callback, *args)
@ -107,6 +107,16 @@ The :meth:`loop.run_in_executor` method can be used with a
blocking code in a different OS thread without blocking the OS thread
that the event loop runs in.
There is currently no way to schedule coroutines or callbacks directly
from a different process (such as one started with
:mod:`multiprocessing`). The :ref:`Event Loop Methods <asyncio-event-loop>`
section lists APIs that can read from pipes and watch file descriptors
without blocking the event loop. In addition, asyncio's
:ref:`Subprocess <asyncio-subprocess>` APIs provide a way to start a
process and communicate with it from the event loop. Lastly, the
aforementioned :meth:`loop.run_in_executor` method can also be used
with a :class:`concurrent.futures.ProcessPoolExecutor` to execute
code in a different process.
.. _asyncio-handle-blocking:

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

@ -191,8 +191,8 @@ Scheduling callbacks
.. method:: loop.call_soon(callback, *args, context=None)
Schedule a *callback* to be called with *args* arguments at
the next iteration of the event loop.
Schedule the *callback* :term:`callback` to be called with
*args* arguments at the next iteration of the event loop.
Callbacks are called in the order in which they are registered.
Each callback will be called exactly once.
@ -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.

6
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.
@ -219,7 +219,7 @@ implementation used by the asyncio event loop:
This implementation registers a :py:data:`SIGCHLD` signal handler on
instantiation. That can break third-party code that installs a custom handler for
`SIGCHLD`. signal).
:py:data:`SIGCHLD` signal.
The watcher avoids disrupting other code spawning processes
by polling every process explicitly on a :py:data:`SIGCHLD` signal.

2
Doc/library/asyncio-protocol.rst
View File

@ -993,7 +993,7 @@ loop.subprocess_exec() and SubprocessProtocol
An example of a subprocess protocol used to get the output of a
subprocess and to wait for the subprocess exit.
The subprocess is created by th :meth:`loop.subprocess_exec` method::
The subprocess is created by the :meth:`loop.subprocess_exec` method::
import asyncio
import sys

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.

21
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,16 +99,10 @@ 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::
The default asyncio event loop implementation on **Windows** does not
support subprocesses. Subprocesses are available for Windows if a
:class:`ProactorEventLoop` is used.
See :ref:`Subprocess Support on Windows <asyncio-windows-subprocess>`
Subprocesses are available for Windows if a :class:`ProactorEventLoop` is
used. See :ref:`Subprocess Support on Windows <asyncio-windows-subprocess>`
for details.
.. seealso::

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

87
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::
@ -387,6 +381,14 @@ Running Tasks Concurrently
# Task C: Compute factorial(4)...
# Task C: factorial(4) = 24
.. note::
If *return_exceptions* is False, cancelling gather() after it
has been marked done won't cancel any submitted awaitables.
For instance, gather can be marked done after propagating an
exception to the caller, therefore, calling ``gather.cancel()``
after catching an exception (raised by one of the awaitables) from
gather won't cancel any other awaitables.
.. versionchanged:: 3.7
If the *gather* itself is cancelled, the cancellation is
propagated regardless of *return_exceptions*.
@ -395,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>`.
@ -428,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.
@ -458,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::
@ -492,14 +488,13 @@ 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*
set concurrently and block until the condition specified
iterable concurrently and block until the condition specified
by *return_when*.
The *aws* set must not be empty.
The *aws* iterable must not be empty.
Returns two sets of Tasks/Futures: ``(done, pending)``.
@ -545,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::
@ -582,19 +573,16 @@ 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*
set concurrently. Return an iterator of coroutines.
iterable concurrently. Return an iterator of coroutines.
Each coroutine returned can be awaited to get the earliest next
result from the set of the remaining awaitables.
result from the iterable of the remaining awaitables.
Raises :exc:`asyncio.TimeoutError` if the timeout occurs before
all Futures are done.
.. deprecated-removed:: 3.8 3.10
The *loop* parameter.
Example::
for coro in as_completed(aws):
@ -605,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.
@ -735,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.
@ -901,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.
@ -922,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.
@ -962,31 +950,6 @@ Task Object
.. versionadded:: 3.8
.. classmethod:: all_tasks(loop=None)
Return a set of all tasks for an event loop.
By default all tasks for the current event loop are returned.
If *loop* is ``None``, the :func:`get_event_loop` function
is used to get the current loop.
.. deprecated-removed:: 3.7 3.9
Do not call this as a task method. Use the :func:`asyncio.all_tasks`
function instead.
.. classmethod:: current_task(loop=None)
Return the currently running task or ``None``.
If *loop* is ``None``, the :func:`get_event_loop` function
is used to get the current loop.
.. deprecated-removed:: 3.7 3.9
Do not call this as a task method. Use the
:func:`asyncio.current_task` function instead.
.. _asyncio_generator_based_coro:

26
Doc/library/audit_events.rst
View File

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

25
Doc/library/base64.rst
View File

@ -124,7 +124,7 @@ The modern interface provides:
whether a lowercase alphabet is acceptable as input. For security purposes,
the default is ``False``.
:rfc:`3548` allows for optional mapping of the digit 0 (zero) to the letter O
:rfc:`4648` allows for optional mapping of the digit 0 (zero) to the letter O
(oh), and for optional mapping of the digit 1 (one) to either the letter I (eye)
or letter L (el). The optional argument *map01* when not ``None``, specifies
which letter the digit 1 should be mapped to (when *map01* is not ``None``, the
@ -136,6 +136,27 @@ The modern interface provides:
input.
.. function:: b32hexencode(s)
Similar to :func:`b32encode` but uses the Extended Hex Alphabet, as defined in
:rfc:`4648`.
.. versionadded:: 3.10
.. function:: b32hexdecode(s, casefold=False)
Similar to :func:`b32decode` but uses the Extended Hex Alphabet, as defined in
:rfc:`4648`.
This version does not allow the digit 0 (zero) to the letter O (oh) and digit
1 (one) to either the letter I (eye) or letter L (el) mappings, all these
characters are included in the Extended Hex Alphabet and are not
interchangable.
.. versionadded:: 3.10
.. function:: b16encode(s)
Encode the :term:`bytes-like object` *s* using Base16 and return the
@ -178,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`.

118
Doc/library/bisect.rst
View File

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

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

@ -349,7 +349,7 @@ For simple text calendars this module provides the following functions.
.. function:: monthcalendar(year, month)
Returns a matrix representing a month's calendar. Each row represents a week;
days outside of the month a represented by zeros. Each week begins with Monday
days outside of the month are represented by zeros. Each week begins with Monday
unless set by :func:`setfirstweekday`.

11
Doc/library/codecs.rst
View File

@ -163,11 +163,14 @@ function:
:class:`CodecInfo` object. In case a search function cannot find
a given encoding, it should return ``None``.
.. note::
Search function registration is not currently reversible,
which may cause problems in some cases, such as unit testing or
module reloading.
.. function:: unregister(search_function)
Unregister a codec search function and clear the registry's cache.
If the search function is not registered, do nothing.
.. versionadded:: 3.10
While the builtin :func:`open` and the associated :mod:`io` module are the
recommended approach for working with encoded text files, this module

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

@ -98,12 +98,20 @@ ABC Inherits from Abstract Methods Mixin
.. class:: Container
Hashable
Sized
Callable
ABCs for classes that provide respectively the methods :meth:`__contains__`,
:meth:`__hash__`, :meth:`__len__`, and :meth:`__call__`.
ABC for classes that provide the :meth:`__contains__` method.
.. class:: Hashable
ABC for classes that provide the :meth:`__hash__` method.
.. class:: Sized
ABC for classes that provide the :meth:`__len__` method.
.. class:: Callable
ABC for classes that provide the :meth:`__call__` method.
.. class:: Iterable
@ -185,7 +193,7 @@ ABC Inherits from Abstract Methods Mixin
expressions. Custom implementations must provide the :meth:`__await__`
method.
:term:`Coroutine` objects and instances of the
:term:`Coroutine <coroutine>` objects and instances of the
:class:`~collections.abc.Coroutine` ABC are all instances of this ABC.
.. note::
@ -283,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

@ -857,6 +857,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.

11
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
@ -221,7 +221,8 @@ ProcessPoolExecutor
The :class:`ProcessPoolExecutor` class is an :class:`Executor` subclass that
uses a pool of processes to execute calls asynchronously.
:class:`ProcessPoolExecutor` uses the :mod:`multiprocessing` module, which
allows it to side-step the :term:`Global Interpreter Lock` but also means that
allows it to side-step the :term:`Global Interpreter Lock
<global interpreter lock>` but also means that
only picklable objects can be executed and returned.
The ``__main__`` module must be importable by worker subprocesses. This means
@ -235,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.
@ -249,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

173
Doc/library/configparser.rst
View File

@ -135,6 +135,30 @@ involves the ``DEFAULT`` section which provides default values for all other
sections [1]_. Note also that keys in sections are
case-insensitive and stored in lowercase [1]_.
It is possible to read several configurations into a single
:class:`ConfigParser`, where the most recently added configuration has the
highest priority. Any conflicting keys are taken from the more recent
configuration while the previously existing keys are retained.
.. doctest::
>>> another_config = configparser.ConfigParser()
>>> another_config.read('example.ini')
['example.ini']
>>> another_config['topsecret.server.com']['Port']
'50022'
>>> another_config.read_string("[topsecret.server.com]\nPort=48484")
>>> another_config['topsecret.server.com']['Port']
'48484'
>>> another_config.read_dict({"topsecret.server.com": {"Port": 21212}})
>>> another_config['topsecret.server.com']['Port']
'21212'
>>> another_config['topsecret.server.com']['ForwardX11']
'no'
This behaviour is equivalent to a :meth:`ConfigParser.read` call with several
files passed to the *filenames* parameter.
Supported Datatypes
-------------------
@ -674,97 +698,98 @@ be overridden by subclasses or by attribute assignment.
.. attribute:: ConfigParser.BOOLEAN_STATES
By default when using :meth:`~ConfigParser.getboolean`, config parsers
consider the following values ``True``: ``'1'``, ``'yes'``, ``'true'``,
``'on'`` and the following values ``False``: ``'0'``, ``'no'``, ``'false'``,
``'off'``. You can override this by specifying a custom dictionary of strings
and their Boolean outcomes. For example:
By default when using :meth:`~ConfigParser.getboolean`, config parsers
consider the following values ``True``: ``'1'``, ``'yes'``, ``'true'``,
``'on'`` and the following values ``False``: ``'0'``, ``'no'``, ``'false'``,
``'off'``. You can override this by specifying a custom dictionary of strings
and their Boolean outcomes. For example:
.. doctest::
.. doctest::
>>> custom = configparser.ConfigParser()
>>> custom['section1'] = {'funky': 'nope'}
>>> custom['section1'].getboolean('funky')
Traceback (most recent call last):
...
ValueError: Not a boolean: nope
>>> custom.BOOLEAN_STATES = {'sure': True, 'nope': False}
>>> custom['section1'].getboolean('funky')
False
>>> custom = configparser.ConfigParser()
>>> custom['section1'] = {'funky': 'nope'}
>>> custom['section1'].getboolean('funky')
Traceback (most recent call last):
...
ValueError: Not a boolean: nope
>>> custom.BOOLEAN_STATES = {'sure': True, 'nope': False}
>>> custom['section1'].getboolean('funky')
False
Other typical Boolean pairs include ``accept``/``reject`` or
``enabled``/``disabled``.
Other typical Boolean pairs include ``accept``/``reject`` or
``enabled``/``disabled``.
.. method:: ConfigParser.optionxform(option)
:noindex:
This method transforms option names on every read, get, or set
operation. The default converts the name to lowercase. This also
means that when a configuration file gets written, all keys will be
lowercase. Override this method if that's unsuitable.
For example:
This method transforms option names on every read, get, or set
operation. The default converts the name to lowercase. This also
means that when a configuration file gets written, all keys will be
lowercase. Override this method if that's unsuitable.
For example:
.. doctest::
.. doctest::
>>> config = """
... [Section1]
... Key = Value
...
... [Section2]
... AnotherKey = Value
... """
>>> typical = configparser.ConfigParser()
>>> typical.read_string(config)
>>> list(typical['Section1'].keys())
['key']
>>> list(typical['Section2'].keys())
['anotherkey']
>>> custom = configparser.RawConfigParser()
>>> custom.optionxform = lambda option: option
>>> custom.read_string(config)
>>> list(custom['Section1'].keys())
['Key']
>>> list(custom['Section2'].keys())
['AnotherKey']
>>> config = """
... [Section1]
... Key = Value
...
... [Section2]
... AnotherKey = Value
... """
>>> typical = configparser.ConfigParser()
>>> typical.read_string(config)
>>> list(typical['Section1'].keys())
['key']
>>> list(typical['Section2'].keys())
['anotherkey']
>>> custom = configparser.RawConfigParser()
>>> custom.optionxform = lambda option: option
>>> custom.read_string(config)
>>> list(custom['Section1'].keys())
['Key']
>>> list(custom['Section2'].keys())
['AnotherKey']
.. note::
The optionxform function transforms option names to a canonical form.
This should be an idempotent function: if the name is already in
canonical form, it should be returned unchanged.
.. note::
The optionxform function transforms option names to a canonical form.
This should be an idempotent function: if the name is already in
canonical form, it should be returned unchanged.
.. attribute:: ConfigParser.SECTCRE
A compiled regular expression used to parse section headers. The default
matches ``[section]`` to the name ``"section"``. Whitespace is considered
part of the section name, thus ``[ larch ]`` will be read as a section of
name ``" larch "``. Override this attribute if that's unsuitable. For
example:
A compiled regular expression used to parse section headers. The default
matches ``[section]`` to the name ``"section"``. Whitespace is considered
part of the section name, thus ``[ larch ]`` will be read as a section of
name ``" larch "``. Override this attribute if that's unsuitable. For
example:
.. doctest::
.. doctest::
>>> import re
>>> config = """
... [Section 1]
... option = value
...
... [ Section 2 ]
... another = val
... """
>>> typical = configparser.ConfigParser()
>>> typical.read_string(config)
>>> typical.sections()
['Section 1', ' Section 2 ']
>>> custom = configparser.ConfigParser()
>>> custom.SECTCRE = re.compile(r"\[ *(?P<header>[^]]+?) *\]")
>>> custom.read_string(config)
>>> custom.sections()
['Section 1', 'Section 2']
>>> import re
>>> config = """
... [Section 1]
... option = value
...
... [ Section 2 ]
... another = val
... """
>>> typical = configparser.ConfigParser()
>>> typical.read_string(config)
>>> typical.sections()
['Section 1', ' Section 2 ']
>>> custom = configparser.ConfigParser()
>>> custom.SECTCRE = re.compile(r"\[ *(?P<header>[^]]+?) *\]")
>>> custom.read_string(config)
>>> custom.sections()
['Section 1', 'Section 2']
.. note::
.. note::
While ConfigParser objects also use an ``OPTCRE`` attribute for recognizing
option lines, it's not recommended to override it because that would
interfere with constructor options *allow_no_value* and *delimiters*.
While ConfigParser objects also use an ``OPTCRE`` attribute for recognizing
option lines, it's not recommended to override it because that would
interfere with constructor options *allow_no_value* and *delimiters*.
Legacy API Examples

13
Doc/library/constants.rst
View File

@ -19,19 +19,21 @@ A small number of constants live in the built-in namespace. They are:
.. data:: None
The sole value of the type ``NoneType``. ``None`` is frequently used to
represent the absence of a value, as when default arguments are not passed to a
function. Assignments to ``None`` are illegal and raise a :exc:`SyntaxError`.
An object frequently used to represent the absence of a value, as when
default arguments are not passed to a function. Assignments to ``None``
are illegal and raise a :exc:`SyntaxError`.
``None`` is the sole instance of the :data:`NoneType` type.
.. data:: NotImplemented
Special value which should be returned by the binary special methods
A special value which should be returned by the binary special methods
(e.g. :meth:`__eq__`, :meth:`__lt__`, :meth:`__add__`, :meth:`__rsub__`,
etc.) to indicate that the operation is not implemented with respect to
the other type; may be returned by the in-place binary special methods
(e.g. :meth:`__imul__`, :meth:`__iand__`, etc.) for the same purpose.
It should not be evaluated in a boolean context.
``NotImplemented`` is the sole instance of the :data:`types.NotImplementedType` type.
.. note::
@ -59,8 +61,9 @@ A small number of constants live in the built-in namespace. They are:
.. index:: single: ...; ellipsis literal
.. data:: Ellipsis
The same as the ellipsis literal "``...``". Special value used mostly in conjunction
The same as the ellipsis literal "``...``". Special value used mostly in conjunction
with extended slicing syntax for user-defined container data types.
``Ellipsis`` is the sole instance of the :data:`types.EllipsisType` type.
.. data:: __debug__

115
Doc/library/contextlib.rst
View File

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

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

1
Doc/library/copy.rst
View File

@ -86,6 +86,7 @@ The latter is called to implement the deep copy operation; it is passed one
argument, the ``memo`` dictionary. If the :meth:`__deepcopy__` implementation needs
to make a deep copy of a component, it should call the :func:`deepcopy` function
with the component as first argument and the memo dictionary as second argument.
The memo dictionary should be treated as an opaque object.
.. seealso::

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