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

Merge branch 'master' into fix-server-classvar

Browse source
This commit is contained in:
Bar Harel 2021-12-13 13:56:34 +02:00
commit 9d328ab39e
No known key found for this signature in database
GPG key ID: D97113ABDA476F3D
1572 changed files with 102796 additions and 73455 deletions
Download patch file Download diff file Expand all files Collapse all files

16
.azure-pipelines/ci.yml
View file

@ -1,14 +1,14 @@
variables:
coverage: false
trigger: ['main', '3.9', '3.8', '3.7']
trigger: ['main', '3.10', '3.9', '3.8', '3.7']
jobs:
- job: Prebuild
displayName: Pre-build checks
pool:
vmImage: ubuntu-18.04
vmImage: ubuntu-20.04
steps:
- template: ./prebuild-checks.yml
@ -20,7 +20,7 @@ jobs:
condition: and(succeeded(), eq(dependencies.Prebuild.outputs['docs.run'], 'true'))
pool:
vmImage: ubuntu-18.04
vmImage: ubuntu-20.04
steps:
- template: ./docs-steps.yml
@ -40,7 +40,7 @@ jobs:
testRunPlatform: macos
pool:
vmImage: macos-10.14
vmImage: macos-10.15
steps:
- template: ./macos-steps.yml
@ -52,12 +52,12 @@ jobs:
condition: and(succeeded(), eq(dependencies.Prebuild.outputs['tests.run'], 'true'))
pool:
vmImage: ubuntu-18.04
vmImage: ubuntu-20.04
variables:
testRunTitle: '$(build.sourceBranchName)-linux'
testRunPlatform: linux
openssl_version: 1.1.1k
openssl_version: 1.1.1l
steps:
- template: ./posix-steps.yml
@ -78,12 +78,12 @@ jobs:
)
pool:
vmImage: ubuntu-18.04
vmImage: ubuntu-20.04
variables:
testRunTitle: '$(Build.SourceBranchName)-linux-coverage'
testRunPlatform: linux-coverage
openssl_version: 1.1.1k
openssl_version: 1.1.1l
steps:
- template: ./posix-steps.yml

26
.azure-pipelines/find-tools.yml Normal file
View file

@ -0,0 +1,26 @@
# Locate a set of the tools used for builds
steps:
- template: windows-release/find-sdk.yml
parameters:
toolname: 'signtool.exe'
- powershell: |
$vcvarsall = (& "${env:ProgramFiles(x86)}\Microsoft Visual Studio\Installer\vswhere.exe" `
-prerelease `
-latest `
-requires Microsoft.VisualStudio.Component.VC.Tools.x86.x64 `
-find VC\Auxiliary\Build\vcvarsall.bat)
Write-Host "Found vcvarsall at $vcvarsall"
Write-Host "##vso[task.setVariable variable=vcvarsall]$vcvarsall"
displayName: 'Find vcvarsall.bat'
- powershell: |
$msbuild = (& "${env:ProgramFiles(x86)}\Microsoft Visual Studio\Installer\vswhere.exe" `
-prerelease `
-latest `
-requires Microsoft.VisualStudio.Component.VC.Tools.x86.x64 `
-find MSBuild\Current\Bin\msbuild.exe)
Write-Host "Found MSBuild at $msbuild"
Write-Host "##vso[task.setVariable variable=msbuild]$msbuild"
displayName: 'Find MSBuild'

86
.azure-pipelines/libffi-build.yml Normal file
View file

@ -0,0 +1,86 @@
name: $(SourceTag)_$(Date:yyyyMMdd)$(Rev:.rr)
variables:
IntDir: '$(Build.BinariesDirectory)'
OutDir: '$(Build.ArtifactStagingDirectory)'
# MUST BE SET AT QUEUE TIME
# SigningCertificate: 'Python Software Foundation'
# SourcesRepo: 'https://github.com/python/cpython-source-deps'
# SourceTag: 'libffi-3.4.2'
jobs:
- job: Build_LibFFI
displayName: LibFFI
pool:
vmImage: windows-latest
workspace:
clean: all
steps:
- checkout: none
- template: ./find-tools.yml
- powershell: |
mkdir -Force "$(IntDir)\script"
iwr "https://github.com/python/cpython/raw/main/PCbuild/prepare_libffi.bat" `
-outfile "$(IntDir)\script\prepare_libffi.bat"
displayName: 'Download build script'
- powershell: |
git clone $(SourcesRepo) -b $(SourceTag) --depth 1 -c core.autocrlf=false -c core.eol=lf .
displayName: 'Check out LibFFI sources'
- script: 'prepare_libffi.bat --install-cygwin'
workingDirectory: '$(IntDir)\script'
displayName: 'Install Cygwin and build'
env:
VCVARSALL: '$(vcvarsall)'
LIBFFI_SOURCE: '$(Build.SourcesDirectory)'
LIBFFI_OUT: '$(OutDir)'
- powershell: |
if ((gci *\*.dll).Count -lt 4) {
Write-Error "Did not generate enough DLL files"
}
if ((gci *\Include\ffi.h).Count -lt 4) {
Write-Error "Did not generate enough include files"
}
failOnStderr: true
workingDirectory: '$(OutDir)'
displayName: 'Verify files were created'
- publish: '$(OutDir)'
artifact: 'unsigned'
displayName: 'Publish unsigned build'
- job: Sign_LibFFI
displayName: Sign LibFFI
dependsOn: Build_LibFFI
pool:
name: 'Windows Release'
workspace:
clean: all
steps:
- checkout: none
- download: current
artifact: unsigned
- template: ./find-tools.yml
- powershell: |
signtool sign /q /a `
/n "Python Software Foundation" `
/fd sha256 `
/tr http://timestamp.digicert.com/ /td sha256 `
/d "LibFFI for Python" `
(gci "$(Pipeline.Workspace)\unsigned\*.dll" -r)
displayName: 'Sign files'
- publish: '$(Pipeline.Workspace)\unsigned'
artifact: 'libffi'
displayName: 'Publish libffi'

110
.azure-pipelines/openssl-build.yml Normal file
View file

@ -0,0 +1,110 @@
name: $(SourceTag)_$(Date:yyyyMMdd)$(Rev:.rr)
variables:
IntDir: '$(Build.BinariesDirectory)'
OutDir: '$(Build.ArtifactStagingDirectory)'
# MUST BE SET AT QUEUE TIME
# SigningCertificate: 'Python Software Foundation'
# SourcesRepo: 'https://github.com/python/cpython-source-deps'
# SourceTag: 'openssl-1.1.1k'
jobs:
- job: Build_SSL
displayName: OpenSSL
pool:
name: 'Windows Release'
#vmImage: windows-latest
strategy:
matrix:
win32:
Platform: 'win32'
VCPlatform: 'amd64_x86'
OpenSSLPlatform: 'VC-WIN32 no-asm'
amd64:
Platform: 'amd64'
VCPlatform: 'amd64'
OpenSSLPlatform: 'VC-WIN64A-masm'
arm32:
Platform: 'arm32'
VCPlatform: 'amd64_arm'
OpenSSLPlatform: 'VC-WIN32-ARM'
arm64:
Platform: 'arm64'
VCPlatform: 'amd64_arm64'
OpenSSLPlatform: 'VC-WIN64-ARM'
workspace:
clean: all
steps:
- checkout: none
- template: ./find-tools.yml
- powershell: |
git clone $(SourcesRepo) -b $(SourceTag) --depth 1 .
displayName: 'Check out OpenSSL sources'
- powershell: |
$f = gi ms\uplink.c
$c1 = gc $f
$c2 = $c1 -replace '\(\(h = GetModuleHandle\(NULL\)\) == NULL\)', '((h = GetModuleHandleA("_ssl.pyd")) == NULL) if ((h = GetModuleHandleA("_ssl_d.pyd")) == NULL) if ((h = GetModuleHandle(NULL)) == NULL /*patched*/)'
if ($c2 -ne $c1) {
$c2 | Out-File $f -Encoding ASCII
} else {
Write-Host '##warning Failed to patch uplink.c'
}
displayName: 'Apply uplink.c patch'
- script: |
call "$(vcvarsall)" $(VCPlatform)
perl "$(Build.SourcesDirectory)\Configure" $(OpenSSLPlatform)
nmake
workingDirectory: '$(IntDir)'
displayName: 'Build OpenSSL'
- script: |
call "$(vcvarsall)" $(VCPlatform)
signtool sign /q /a /n "$(SigningCertificate)" /fd sha256 /tr http://timestamp.digicert.com/ /td sha256 /d "OpenSSL for Python" *.dll
workingDirectory: '$(IntDir)'
displayName: 'Sign OpenSSL Build'
condition: and(succeeded(), variables['SigningCertificate'])
- task: CopyFiles@2
displayName: 'Copy built libraries for upload'
inputs:
SourceFolder: '$(IntDir)'
Contents: |
lib*.dll
lib*.pdb
lib*.lib
include\openssl\*.h
TargetFolder: '$(OutDir)'
- task: CopyFiles@2
displayName: 'Copy header files for upload'
inputs:
SourceFolder: '$(Build.SourcesDirectory)'
Contents: |
include\openssl\*
TargetFolder: '$(OutDir)'
- task: CopyFiles@2
displayName: 'Copy applink files for upload'
inputs:
SourceFolder: '$(Build.SourcesDirectory)\ms'
Contents: applink.c
TargetFolder: '$(OutDir)\include'
- task: CopyFiles@2
displayName: 'Copy LICENSE for upload'
inputs:
SourceFolder: '$(Build.SourcesDirectory)'
Contents: LICENSE
TargetFolder: '$(OutDir)'
- publish: '$(OutDir)'
artifact: '$(Platform)'
displayName: 'Publishing $(Platform)'

16
.azure-pipelines/pr.yml
View file

@ -1,14 +1,14 @@
variables:
coverage: false
pr: ['main', '3.9', '3.8', '3.7']
pr: ['main', '3.10', '3.9', '3.8', '3.7']
jobs:
- job: Prebuild
displayName: Pre-build checks
pool:
vmImage: ubuntu-18.04
vmImage: ubuntu-20.04
steps:
- template: ./prebuild-checks.yml
@ -20,7 +20,7 @@ jobs:
condition: and(succeeded(), eq(dependencies.Prebuild.outputs['docs.run'], 'true'))
pool:
vmImage: ubuntu-18.04
vmImage: ubuntu-20.04
steps:
- template: ./docs-steps.yml
@ -38,7 +38,7 @@ jobs:
testRunPlatform: macos
pool:
vmImage: macos-10.14
vmImage: macos-10.15
steps:
- template: ./macos-steps.yml
@ -52,12 +52,12 @@ jobs:
condition: and(succeeded(), eq(dependencies.Prebuild.outputs['tests.run'], 'true'))
pool:
vmImage: ubuntu-18.04
vmImage: ubuntu-20.04
variables:
testRunTitle: '$(system.pullRequest.TargetBranch)-linux'
testRunPlatform: linux
openssl_version: 1.1.1k
openssl_version: 1.1.1l
steps:
- template: ./posix-steps.yml
@ -78,12 +78,12 @@ jobs:
)
pool:
vmImage: ubuntu-18.04
vmImage: ubuntu-20.04
variables:
testRunTitle: '$(Build.SourceBranchName)-linux-coverage'
testRunPlatform: linux-coverage
openssl_version: 1.1.1k
openssl_version: 1.1.1l
steps:
- template: ./posix-steps.yml

65
.azure-pipelines/tcltk-build.yml Normal file
View file

@ -0,0 +1,65 @@
name: tcl$(TkSourceTag)_$(Date:yyyyMMdd)$(Rev:.rr)
variables:
IntDir: '$(Build.BinariesDirectory)\obj'
ExternalsDir: '$(Build.BinariesDirectory)\externals'
OutDir: '$(Build.ArtifactStagingDirectory)'
Configuration: 'Release'
# MUST BE SET AT QUEUE TIME
# SigningCertificate: 'Python Software Foundation'
# SourcesRepo: 'https://github.com/python/cpython-source-deps'
# TclSourceTag: 'tcl-core-8.6.12.0'
# TkSourceTag: 'tk-8.6.12.0'
# TixSourceTag: 'tix-8.4.3.6'
jobs:
- job: Build_TclTk
displayName: 'Tcl/Tk'
pool:
name: 'Windows Release'
#vmImage: windows-latest
workspace:
clean: all
steps:
- template: ./find-tools.yml
- powershell: |
git clone $(SourcesRepo) -b $(TclSourceTag) --depth 1 "$(ExternalsDir)\$(TclSourceTag)"
displayName: 'Check out Tcl sources'
- powershell: |
git clone $(SourcesRepo) -b $(TkSourceTag) --depth 1 "$(ExternalsDir)\$(TkSourceTag)"
displayName: 'Check out Tk sources'
- powershell: |
git clone $(SourcesRepo) -b $(TixSourceTag) --depth 1 "$(ExternalsDir)\$(TixSourceTag)"
displayName: 'Check out Tix sources'
# This msbuild.rsp file will be used by the build to forcibly override these variables
- powershell: |
del -Force -EA 0 msbuild.rsp
"/p:IntDir=$(IntDir)\" >> msbuild.rsp
"/p:ExternalsDir=$(ExternalsDir)\" >> msbuild.rsp
"/p:tclDir=$(ExternalsDir)\$(TclSourceTag)\" >> msbuild.rsp
"/p:tkDir=$(ExternalsDir)\$(TkSourceTag)\" >> msbuild.rsp
"/p:tixDir=$(ExternalsDir)\$(TixSourceTag)\" >> msbuild.rsp
displayName: 'Generate msbuild.rsp'
- powershell: |
& "$(msbuild)" PCbuild\tcl.vcxproj "@msbuild.rsp" /p:Platform=Win32 /p:tcltkDir="$(OutDir)\win32"
& "$(msbuild)" PCbuild\tk.vcxproj "@msbuild.rsp" /p:Platform=Win32 /p:tcltkDir="$(OutDir)\win32"
& "$(msbuild)" PCbuild\tix.vcxproj "@msbuild.rsp" /p:Platform=Win32 /p:tcltkDir="$(OutDir)\win32"
displayName: 'Build for win32'
- powershell: |
& "$(msbuild)" PCbuild\tcl.vcxproj "@msbuild.rsp" /p:Platform=x64 /p:tcltkDir="$(OutDir)\amd64"
& "$(msbuild)" PCbuild\tk.vcxproj "@msbuild.rsp" /p:Platform=x64 /p:tcltkDir="$(OutDir)\amd64"
& "$(msbuild)" PCbuild\tix.vcxproj "@msbuild.rsp" /p:Platform=x64 /p:tcltkDir="$(OutDir)\amd64"
displayName: 'Build for amd64'
- publish: '$(OutDir)'
artifact: 'tcltk'
displayName: 'Publishing tcltk'

5
.gitattributes vendored
View file

@ -46,8 +46,9 @@ Modules/clinic/*.h linguist-generated=true
Objects/clinic/*.h linguist-generated=true
PC/clinic/*.h linguist-generated=true
Python/clinic/*.h linguist-generated=true
Python/importlib.h linguist-generated=true
Python/importlib_external.h linguist-generated=true
Python/deepfreeze/*.c linguist-generated=true
Python/frozen_modules/*.h linguist-generated=true
Python/frozen_modules/MANIFEST linguist-generated=true
Include/internal/pycore_ast.h linguist-generated=true
Python/Python-ast.c linguist-generated=true
Include/opcode.h linguist-generated=true

66
.github/workflows/build.yml vendored
View file

@ -4,6 +4,7 @@ name: Tests
# it prevents to mark a job as mandatory. A PR cannot be merged if a job is
# mandatory but not scheduled because of "paths-ignore".
on:
workflow_dispatch:
push:
branches:
- 'main'
@ -63,6 +64,18 @@ jobs:
- uses: actions/setup-python@v2
- name: Install Dependencies
run: sudo ./.github/workflows/posix-deps-apt.sh
- name: Add ccache to PATH
run: echo "PATH=/usr/lib/ccache:$PATH" >> $GITHUB_ENV
- name: Configure ccache action
uses: hendrikmuhs/ccache-action@v1
- name: Check Autoconf version 2.69 and aclocal 1.16.3
run: |
grep "Generated by GNU Autoconf 2.69" configure
grep "aclocal 1.16.3" aclocal.m4
grep -q "runstatedir" configure
grep -q "PKG_PROG_PKG_CONFIG" aclocal.m4
- name: Regenerate autoconf files
run: docker run --rm -v $(pwd):/src quay.io/tiran/cpython_autoconf:269
- name: Build CPython
run: |
# Build Python with the libpython dynamic library
@ -71,11 +84,13 @@ jobs:
make regen-stdlib-module-names
- name: Check for changes
run: |
git add -u
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 or build.bat --regen ;)"
if test -n "$changes"; then
echo "Generated files not up to date."
echo "Perhaps you forgot to run make regen-all or build.bat --regen. ;)"
echo "configure files must be regenerated with a specific, unpatched version of autoconf."
echo "$changes"
exit 1
fi
@ -89,6 +104,8 @@ jobs:
runs-on: windows-latest
needs: check_source
if: needs.check_source.outputs.run_tests == 'true'
env:
IncludeUwp: 'true'
steps:
- uses: actions/checkout@v2
- name: Build CPython
@ -103,6 +120,8 @@ jobs:
runs-on: windows-latest
needs: check_source
if: needs.check_source.outputs.run_tests == 'true'
env:
IncludeUwp: 'true'
steps:
- uses: actions/checkout@v2
- name: Register MSVC problem matcher
@ -123,8 +142,12 @@ jobs:
PYTHONSTRICTEXTENSIONBUILD: 1
steps:
- uses: actions/checkout@v2
- name: Prepare homebrew environment variables
run: |
echo "LDFLAGS=-L$(brew --prefix tcl-tk)/lib" >> $GITHUB_ENV
echo "PKG_CONFIG_PATH=$(brew --prefix openssl@1.1)/lib/pkgconfig:$(brew --prefix tcl-tk)/lib/pkgconfig" >> $GITHUB_ENV
- name: Configure CPython
run: ./configure --with-pydebug --with-openssl=/usr/local/opt/openssl --prefix=/opt/python-dev
run: ./configure --with-pydebug --prefix=/opt/python-dev
- name: Build CPython
run: make -j4
- name: Display build info
@ -138,7 +161,7 @@ jobs:
needs: check_source
if: needs.check_source.outputs.run_tests == 'true'
env:
OPENSSL_VER: 1.1.1k
OPENSSL_VER: 1.1.1l
PYTHONSTRICTEXTENSIONBUILD: 1
steps:
- uses: actions/checkout@v2
@ -153,7 +176,7 @@ jobs:
echo "LD_LIBRARY_PATH=${GITHUB_WORKSPACE}/multissl/openssl/${OPENSSL_VER}/lib" >> $GITHUB_ENV
- name: 'Restore OpenSSL build'
id: cache-openssl
uses: actions/cache@v2.1.6
uses: actions/cache@v2.1.7
with:
path: ./multissl/openssl/${{ env.OPENSSL_VER }}
key: ${{ runner.os }}-multissl-openssl-${{ env.OPENSSL_VER }}
@ -165,13 +188,28 @@ jobs:
echo "PATH=/usr/lib/ccache:$PATH" >> $GITHUB_ENV
- name: Configure ccache action
uses: hendrikmuhs/ccache-action@v1
- name: Configure CPython
run: ./configure --with-pydebug --with-openssl=$OPENSSL_DIR
- name: Build CPython
- name: Setup directory envs for out-of-tree builds
run: |
echo "CPYTHON_RO_SRCDIR=$(realpath -m ${GITHUB_WORKSPACE}/../cpython-ro-srcdir)" >> $GITHUB_ENV
echo "CPYTHON_BUILDDIR=$(realpath -m ${GITHUB_WORKSPACE}/../cpython-builddir)" >> $GITHUB_ENV
- name: Create directories for read-only out-of-tree builds
run: mkdir -p $CPYTHON_RO_SRCDIR $CPYTHON_BUILDDIR
- name: Bind mount sources read-only
run: sudo mount --bind -o ro $GITHUB_WORKSPACE $CPYTHON_RO_SRCDIR
- name: Configure CPython out-of-tree
working-directory: ${{ env.CPYTHON_BUILDDIR }}
run: ../cpython-ro-srcdir/configure --with-pydebug --with-openssl=$OPENSSL_DIR
- name: Build CPython out-of-tree
working-directory: ${{ env.CPYTHON_BUILDDIR }}
run: make -j4
- name: Display build info
working-directory: ${{ env.CPYTHON_BUILDDIR }}
run: make pythoninfo
- name: Remount sources writable for tests
# some tests write to srcdir, lack of pyc files slows down testing
run: sudo mount $CPYTHON_RO_SRCDIR -oremount,rw
- name: Tests
working-directory: ${{ env.CPYTHON_BUILDDIR }}
run: xvfb-run make buildbottest TESTOPTS="-j4 -uall,-cpu"
build_ubuntu_ssltests:
@ -182,7 +220,7 @@ jobs:
strategy:
fail-fast: false
matrix:
openssl_ver: [1.1.1k, 3.0.0-beta1]
openssl_ver: [1.1.1l, 3.0.0]
env:
OPENSSL_VER: ${{ matrix.openssl_ver }}
MULTISSL_DIR: ${{ github.workspace }}/multissl
@ -201,7 +239,7 @@ jobs:
echo "LD_LIBRARY_PATH=${GITHUB_WORKSPACE}/multissl/openssl/${OPENSSL_VER}/lib" >> $GITHUB_ENV
- name: 'Restore OpenSSL build'
id: cache-openssl
uses: actions/cache@v2.1.6
uses: actions/cache@v2.1.7
with:
path: ./multissl/openssl/${{ env.OPENSSL_VER }}
key: ${{ runner.os }}-multissl-openssl-${{ env.OPENSSL_VER }}
@ -229,7 +267,7 @@ jobs:
needs: check_source
if: needs.check_source.outputs.run_tests == 'true'
env:
OPENSSL_VER: 1.1.1k
OPENSSL_VER: 1.1.1l
PYTHONSTRICTEXTENSIONBUILD: 1
ASAN_OPTIONS: detect_leaks=0:allocator_may_return_null=1:handle_segv=0
steps:
@ -245,7 +283,7 @@ jobs:
echo "LD_LIBRARY_PATH=${GITHUB_WORKSPACE}/multissl/openssl/${OPENSSL_VER}/lib" >> $GITHUB_ENV
- name: 'Restore OpenSSL build'
id: cache-openssl
uses: actions/cache@v2.1.6
uses: actions/cache@v2.1.7
with:
path: ./multissl/openssl/${{ env.OPENSSL_VER }}
key: ${{ runner.os }}-multissl-openssl-${{ env.OPENSSL_VER }}
@ -264,4 +302,4 @@ jobs:
- name: Display build info
run: make pythoninfo
- name: Tests
run: xvfb-run make buildbottest TESTOPTS="-j4 -uall,-cpu -x test_ctypes test_crypt test_decimal test_faulthandler test_interpreters test___all__ test_idle test_tix test_tk test_ttk_guionly test_ttk_textonly"
run: xvfb-run make buildbottest TESTOPTS="-j4 -uall,-cpu -x test_ctypes test_crypt test_decimal test_faulthandler test_interpreters test___all__ test_idle test_tix test_tk test_ttk_guionly test_ttk_textonly test_multiprocessing_fork test_multiprocessing_forkserver test_multiprocessing_spawn"

1
.github/workflows/build_msi.yml vendored
View file

@ -1,6 +1,7 @@
name: TestsMSI
on:
workflow_dispatch:
push:
branches:
- 'main'

12
.github/workflows/doc.yml vendored
View file

@ -1,6 +1,7 @@
name: Docs
on:
workflow_dispatch:
#push:
# branches:
# - 'main'
@ -37,8 +38,15 @@ jobs:
run: make -j4
- 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 html
# Run "check doctest html" as 3 steps to get a more readable output
# in the web UI
- name: 'Check documentation'
run: make -C Doc/ PYTHON=../python SPHINXOPTS="-q -W --keep-going -j4" check
# Use "xvfb-run" since some doctest tests open GUI windows
- name: 'Run documentation doctest'
run: xvfb-run make -C Doc/ PYTHON=../python SPHINXOPTS="-q -W --keep-going -j4" doctest
- name: 'Build HTML documentation'
run: make -C Doc/ PYTHON=../python SPHINXOPTS="-q -W --keep-going -j4" html
- name: 'Upload'
uses: actions/upload-artifact@v2.2.4
with:

1
.github/workflows/posix-deps-apt.sh vendored
View file

@ -3,6 +3,7 @@ apt-get update
apt-get -yq install \
build-essential \
pkg-config \
ccache \
gdb \
lcov \

24
.gitignore vendored
View file

@ -10,6 +10,7 @@
*.so.*
*.dylib
*.dll
*.wasm
*.orig
*.pyc
*.pyd
@ -59,16 +60,27 @@ Lib/distutils/command/*.pdb
Lib/lib2to3/*.pickle
Lib/test/data/*
!Lib/test/data/README
/_bootstrap_python
/Makefile
/Makefile.pre
Mac/Makefile
Mac/PythonLauncher/Info.plist
Mac/PythonLauncher/Makefile
Mac/PythonLauncher/Python Launcher
Mac/PythonLauncher/Python Launcher.app/*
Mac/Resources/app/Info.plist
Mac/Resources/framework/Info.plist
Mac/pythonw
/*.framework/
Misc/python.pc
Misc/python-embed.pc
Misc/python-config.sh
Modules/Setup.config
Modules/Setup.local
Modules/Setup.stdlib
Modules/config.c
Modules/ld_so_aix
Programs/_freeze_importlib
Programs/_freeze_module
Programs/_testembed
PC/python_nt*.h
PC/pythonnt_rc*.h
@ -103,9 +115,12 @@ Tools/unicode/data/
/config.log
/config.status
/config.status.lineno
# hendrikmuhs/ccache-action@v1
/.ccache
/platform
/profile-clean-stamp
/profile-run-stamp
/Python/deepfreeze/*.c
/pybuilddir.txt
/pyconfig.h
/python-config
@ -120,6 +135,13 @@ Tools/unicode/data/
Tools/msi/obj
Tools/ssl/amd64
Tools/ssl/win32
Tools/freeze/test/outdir
# The frozen modules are always generated by the build so we don't
# keep them in the repo. Also see Tools/scripts/freeze_modules.py.
Python/frozen_modules/*.h
# The manifest can be generated at any time with "make regen-frozen".
Python/frozen_modules/MANIFEST
# Two-trick pony for OSX and other case insensitive file systems:
# Ignore ./python binary on Unix but still look into ./Python/ directory.

4
Doc/Makefile
View file

@ -117,6 +117,10 @@ suspicious:
"or in build/$(BUILDER)/suspicious.csv. If all issues are false" \
"positives, append that file to tools/susp-ignored.csv."; \
false; }
@echo "⚠ make suspicious is deprecated and will be removed soon."
@echo "⚠ Use:"
@echo "⚠ make check"
@echo "⚠ instead."
coverage: BUILDER = coverage
coverage: build

4
Doc/bugs.rst
View file

@ -80,6 +80,10 @@ taken on the bug.
Article which goes into some detail about how to create a useful bug report.
This describes what kind of information is useful and why it is useful.
`Bug Writing Guidelines <https://bugzilla.mozilla.org/page.cgi?id=bug-writing.html>`_
Information about writing a good bug report. Some of this is specific to the
Mozilla project, but describes general good practices.
.. _contributing-to-python:
Getting started contributing to Python yourself

9
Doc/c-api/apiabiversion.rst
View file

@ -58,5 +58,14 @@ See :ref:`stable` for a discussion of API and ABI stability across versions.
Thus ``3.4.1a2`` is hexversion ``0x030401a2`` and ``3.10.0`` is
hexversion ``0x030a00f0``.
This version is also available via the symbol :data:`Py_Version`.
.. c:var:: const unsigned long Py_Version
The Python runtime version number encoded in a single constant integer, with
the same format as the c:macro:`PY_VERSION_HEX` macro.
This contains the Python version used at run time.
.. versionadded:: 3.11
All the given macros are defined in :source:`Include/patchlevel.h`.

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

@ -185,7 +185,7 @@ Object Calling API
Various functions are available for calling a Python object.
Each converts its arguments to a convention supported by the called object –
either *tp_call* or vectorcall.
In order to do as litle conversion as possible, pick one that best fits
In order to do as little conversion as possible, pick one that best fits
the format of data you have available.
The following table summarizes the available functions;

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

@ -103,13 +103,14 @@ Refer to :ref:`using-capsules` for more information on using these objects.
Import a pointer to a C object from a capsule attribute in a module. The
*name* parameter should specify the full name to the attribute, as in
``module.attribute``. The *name* stored in the capsule must match this
string exactly. If *no_block* is true, import the module without blocking
(using :c:func:`PyImport_ImportModuleNoBlock`). If *no_block* is false,
import the module conventionally (using :c:func:`PyImport_ImportModule`).
string exactly.
Return the capsule's internal *pointer* on success. On failure, set an
exception and return ``NULL``.
.. versionchanged:: 3.3
*no_block* has no effect anymore.
.. c:function:: int PyCapsule_IsValid(PyObject *capsule, const char *name)

9
Doc/c-api/exceptions.rst
View file

@ -100,7 +100,7 @@ For convenience, some of these functions will always return a
This is the most common way to set the error indicator. The first argument
specifies the exception type; it is normally one of the standard exceptions,
e.g. :c:data:`PyExc_RuntimeError`. You need not increment its reference count.
The second argument is an error message; it is decoded from ``'utf-8``'.
The second argument is an error message; it is decoded from ``'utf-8'``.
.. c:function:: void PyErr_SetObject(PyObject *type, PyObject *value)
@ -482,7 +482,6 @@ Querying the error indicator
to an exception that was *already caught*, not to an exception that was
freshly raised. This function steals the references of the arguments.
To clear the exception state, pass ``NULL`` for all three arguments.
For general rules about the three arguments, see :c:func:`PyErr_Restore`.
.. note::
@ -493,6 +492,12 @@ Querying the error indicator
.. versionadded:: 3.3
.. versionchanged:: 3.11
The ``type`` and ``traceback`` arguments are no longer used and
can be NULL. The interpreter now derives them from the exception
instance (the ``value`` argument). The function still steals
references of all three arguments.
Signal Handling
===============

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

@ -33,6 +33,14 @@ Constructors for container types must conform to two rules:
#. Once all the fields which may contain references to other containers are
initialized, it must call :c:func:`PyObject_GC_Track`.
Similarly, the deallocator for the object must conform to a similar pair of
rules:
#. Before fields which refer to other containers are invalidated,
:c:func:`PyObject_GC_UnTrack` must be called.
#. The object's memory must be deallocated using :c:func:`PyObject_GC_Del`.
.. warning::
If a type adds the Py_TPFLAGS_HAVE_GC, then it *must* implement at least
a :c:member:`~PyTypeObject.tp_traverse` handler or explicitly use one
@ -100,14 +108,6 @@ Constructors for container types must conform to two rules:
.. versionadded:: 3.9
Similarly, the deallocator for the object must conform to a similar pair of
rules:
#. Before fields which refer to other containers are invalidated,
:c:func:`PyObject_GC_UnTrack` must be called.
#. The object's memory must be deallocated using :c:func:`PyObject_GC_Del`.
.. c:function:: void PyObject_GC_Del(void *op)

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

@ -110,7 +110,7 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
Suppress error messages when calculating the module search path in
:c:func:`Py_GetPath`.
Private flag used by ``_freeze_importlib`` and ``frozenmain`` programs.
Private flag used by ``_freeze_module`` and ``frozenmain`` programs.
.. c:var:: int Py_HashRandomizationFlag
@ -486,7 +486,7 @@ Process-wide parameters
(set by :c:func:`Py_SetProgramName` above) and some environment variables.
The returned string consists of a series of directory names separated by a
platform dependent delimiter character. The delimiter character is ``':'``
on Unix and Mac OS X, ``';'`` on Windows. The returned string points into
on Unix and macOS, ``';'`` on Windows. The returned string points into
static storage; the caller should not modify its value. The list
:data:`sys.path` is initialized with this value on interpreter startup; it
can be (and usually is) modified later to change the search path for loading
@ -518,7 +518,7 @@ Process-wide parameters
default search path but uses the one provided instead. This is useful if
Python is embedded by an application that has full knowledge of the location
of all modules. The path components should be separated by the platform
dependent delimiter character, which is ``':'`` on Unix and Mac OS X, ``';'``
dependent delimiter character, which is ``':'`` on Unix and macOS, ``';'``
on Windows.
This also causes :data:`sys.executable` to be set to the program
@ -553,6 +553,8 @@ Process-wide parameters
period. The returned string points into static storage; the caller should not
modify its value. The value is available to Python code as :data:`sys.version`.
See also the :data:`Py_Version` constant.
.. c:function:: const char* Py_GetPlatform()
@ -561,7 +563,7 @@ Process-wide parameters
Return the platform identifier for the current platform. On Unix, this is
formed from the "official" name of the operating system, converted to lower
case, followed by the major revision number; e.g., for Solaris 2.x, which is
also known as SunOS 5.x, the value is ``'sunos5'``. On Mac OS X, it is
also known as SunOS 5.x, the value is ``'sunos5'``. On macOS, it is
``'darwin'``. On Windows, it is ``'win'``. The returned string points into
static storage; the caller should not modify its value. The value is available
to Python code as ``sys.platform``.
@ -1173,6 +1175,26 @@ All of the following functions must be called after :c:func:`Py_Initialize`.
.. versionadded:: 3.9
.. c:function:: void PyThreadState_EnterTracing(PyThreadState *tstate)
Suspend tracing and profiling in the Python thread state *tstate*.
Resume them using the :c:func:`PyThreadState_LeaveTracing` function.
.. versionadded:: 3.11
.. c:function:: void PyThreadState_LeaveTracing(PyThreadState *tstate)
Resume tracing and profiling in the Python thread state *tstate* suspended
by the :c:func:`PyThreadState_EnterTracing` function.
See also :c:func:`PyEval_SetTrace` and :c:func:`PyEval_SetProfile`
functions.
.. versionadded:: 3.11
.. c:function:: PyInterpreterState* PyInterpreterState_Get(void)
Get the current interpreter.
@ -1623,6 +1645,8 @@ Python-level trace functions in previous versions.
profile function is called for all monitored events except :const:`PyTrace_LINE`
:const:`PyTrace_OPCODE` and :const:`PyTrace_EXCEPTION`.
See also the :func:`sys.setprofile` function.
The caller must hold the :term:`GIL`.
@ -1635,6 +1659,8 @@ Python-level trace functions in previous versions.
will not receive :const:`PyTrace_C_CALL`, :const:`PyTrace_C_EXCEPTION` or
:const:`PyTrace_C_RETURN` as a value for the *what* parameter.
See also the :func:`sys.settrace` function.
The caller must hold the :term:`GIL`.

54
Doc/c-api/init_config.rst
View file

@ -22,7 +22,7 @@ There are two kinds of configuration:
* The :ref:`Isolated Configuration <init-isolated-conf>` can be used to embed
Python into an application. It isolates Python from the system. For example,
environments variables are ignored, the LC_CTYPE locale is left unchanged and
no signal handler is registred.
no signal handler is registered.
The :c:func:`Py_RunMain` function can be used to write a customized Python
program.
@ -479,6 +479,9 @@ PyConfig
Fields which are already initialized are left unchanged.
Fields for :ref:`path configuration <init-path-config>` are no longer
calculated or modified when calling this function, as of Python 3.11.
The :c:func:`PyConfig_Read` function only parses
:c:member:`PyConfig.argv` arguments once: :c:member:`PyConfig.parse_argv`
is set to ``2`` after arguments are parsed. Since Python arguments are
@ -493,6 +496,12 @@ PyConfig
parsed, and arguments are only parsed if
:c:member:`PyConfig.parse_argv` equals ``1``.
.. versionchanged:: 3.11
:c:func:`PyConfig_Read` no longer calculates all paths, and so fields
listed under :ref:`Python Path Configuration <init-path-config>` may
no longer be updated until :c:func:`Py_InitializeFromConfig` is
called.
.. c:function:: void PyConfig_Clear(PyConfig *config)
Release configuration memory.
@ -596,13 +605,16 @@ PyConfig
.. versionadded:: 3.10
.. c:member:: int no_debug_ranges
.. c:member:: int code_debug_ranges
If equals to ``1``, disables the inclusion of the end line and column
If equals to ``0``, disables the inclusion of the end line and column
mappings in code objects. Also disables traceback printing carets to
specific error locations.
Default: ``0``.
Set to ``0`` by the :envvar:`PYTHONNODEBUGRANGES` environment variable
and by the :option:`-X no_debug_ranges <-X>` command line option.
Default: ``1``.
.. versionadded:: 3.11
@ -706,7 +718,7 @@ PyConfig
* Otherwise, use the :term:`locale encoding`:
``nl_langinfo(CODESET)`` result.
At Python statup, the encoding name is normalized to the Python codec
At Python startup, the encoding name is normalized to the Python codec
name. For example, ``"ANSI_X3.4-1968"`` is replaced with ``"ascii"``.
See also the :c:member:`~PyConfig.filesystem_errors` member.
@ -845,12 +857,19 @@ PyConfig
Default: value of the ``PLATLIBDIR`` macro which is set by the
:option:`configure --with-platlibdir option <--with-platlibdir>`
(default: ``"lib"``).
(default: ``"lib"``, or ``"DLLs"`` on Windows).
Part of the :ref:`Python Path Configuration <init-path-config>` input.
.. versionadded:: 3.9
.. versionchanged:: 3.11
This macro is now used on Windows to locate the standard
library extension modules, typically under ``DLLs``. However,
for compatibility, note that this value is ignored for any
non-standard layouts, including in-tree builds and virtual
environments.
.. c:member:: wchar_t* pythonpath_env
Module search paths (:data:`sys.path`) as a string separated by ``DELIM``
@ -867,9 +886,9 @@ PyConfig
Module search paths: :data:`sys.path`.
If :c:member:`~PyConfig.module_search_paths_set` is equal to 0, the
function calculating the :ref:`Python Path Configuration <init-path-config>`
overrides the :c:member:`~PyConfig.module_search_paths` and sets
If :c:member:`~PyConfig.module_search_paths_set` is equal to 0,
:c:func:`Py_InitializeFromConfig` will replace
:c:member:`~PyConfig.module_search_paths` and sets
:c:member:`~PyConfig.module_search_paths_set` to ``1``.
Default: empty list (``module_search_paths``) and ``0``
@ -941,16 +960,16 @@ PyConfig
.. c:member:: int pathconfig_warnings
On Unix, if non-zero, calculating the :ref:`Python Path Configuration
<init-path-config>` can log warnings into ``stderr``. If equals to 0,
suppress these warnings.
It has no effect on Windows.
If non-zero, calculation of path configuration is allowed to log
warnings into ``stderr``. If equals to 0, suppress these warnings.
Default: ``1`` in Python mode, ``0`` in isolated mode.
Part of the :ref:`Python Path Configuration <init-path-config>` input.
.. versionchanged:: 3.11
Now also applies on Windows.
.. c:member:: wchar_t* prefix
The site-specific directory prefix where the platform independent Python
@ -1302,10 +1321,9 @@ variables, command line arguments (:c:member:`PyConfig.argv` is not parsed)
and user site directory. The C standard streams (ex: ``stdout``) and the
LC_CTYPE locale are left unchanged. Signal handlers are not installed.
Configuration files are still used with this configuration. Set the
:ref:`Python Path Configuration <init-path-config>` ("output fields") to ignore these
configuration files and avoid the function computing the default path
configuration.
Configuration files are still used with this configuration to determine
paths that are unspecified. Ensure :c:member:`PyConfig.home` is specified
to avoid computing the default path configuration.
.. _init-python-config:

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

@ -105,6 +105,93 @@ defined closer to where they are useful (e.g. :c:macro:`Py_RETURN_NONE`).
Others of a more general utility are defined here. This is not necessarily a
complete listing.
.. c:macro:: Py_ABS(x)
Return the absolute value of ``x``.
.. versionadded:: 3.3
.. c:macro:: Py_ALWAYS_INLINE
Ask the compiler to always inline a static inline function. The compiler can
ignore it and decides to not inline the function.
It can be used to inline performance critical static inline functions when
building Python in debug mode with function inlining disabled. For example,
MSC disables function inlining when building in debug mode.
Marking blindly a static inline function with Py_ALWAYS_INLINE can result in
worse performances (due to increased code size for example). The compiler is
usually smarter than the developer for the cost/benefit analysis.
If Python is :ref:`built in debug mode <debug-build>` (if the ``Py_DEBUG``
macro is defined), the :c:macro:`Py_ALWAYS_INLINE` macro does nothing.
It must be specified before the function return type. Usage::
static inline Py_ALWAYS_INLINE int random(void) { return 4; }
.. versionadded:: 3.11
.. c:macro:: Py_CHARMASK(c)
Argument must be a character or an integer in the range [-128, 127] or [0,
255]. This macro returns ``c`` cast to an ``unsigned char``.
.. c:macro:: Py_DEPRECATED(version)
Use this for deprecated declarations. The macro must be placed before the
symbol name.
Example::
Py_DEPRECATED(3.8) PyAPI_FUNC(int) Py_OldFunction(void);
.. versionchanged:: 3.8
MSVC support was added.
.. c:macro:: Py_GETENV(s)
Like ``getenv(s)``, but returns ``NULL`` if :option:`-E` was passed on the
command line (i.e. if ``Py_IgnoreEnvironmentFlag`` is set).
.. c:macro:: Py_MAX(x, y)
Return the maximum value between ``x`` and ``y``.
.. versionadded:: 3.3
.. c:macro:: Py_MEMBER_SIZE(type, member)
Return the size of a structure (``type``) ``member`` in bytes.
.. versionadded:: 3.6
.. c:macro:: Py_MIN(x, y)
Return the minimum value between ``x`` and ``y``.
.. versionadded:: 3.3
.. c:macro:: Py_NO_INLINE
Disable inlining on a function. For example, it reduces the C stack
consumption: useful on LTO+PGO builds which heavily inline code (see
:issue:`33720`).
Usage::
Py_NO_INLINE static int random(void) { return 4; }
.. versionadded:: 3.11
.. c:macro:: Py_STRINGIFY(x)
Convert ``x`` to a C string. E.g. ``Py_STRINGIFY(123)`` returns
``"123"``.
.. versionadded:: 3.4
.. c:macro:: Py_UNREACHABLE()
Use this when you have a code path that cannot be reached by design.
@ -127,47 +214,6 @@ complete listing.
.. versionadded:: 3.7
.. c:macro:: Py_ABS(x)
Return the absolute value of ``x``.
.. versionadded:: 3.3
.. c:macro:: Py_MIN(x, y)
Return the minimum value between ``x`` and ``y``.
.. versionadded:: 3.3
.. c:macro:: Py_MAX(x, y)
Return the maximum value between ``x`` and ``y``.
.. versionadded:: 3.3
.. c:macro:: Py_STRINGIFY(x)
Convert ``x`` to a C string. E.g. ``Py_STRINGIFY(123)`` returns
``"123"``.
.. versionadded:: 3.4
.. c:macro:: Py_MEMBER_SIZE(type, member)
Return the size of a structure (``type``) ``member`` in bytes.
.. versionadded:: 3.6
.. c:macro:: Py_CHARMASK(c)
Argument must be a character or an integer in the range [-128, 127] or [0,
255]. This macro returns ``c`` cast to an ``unsigned char``.
.. c:macro:: Py_GETENV(s)
Like ``getenv(s)``, but returns ``NULL`` if :option:`-E` was passed on the
command line (i.e. if ``Py_IgnoreEnvironmentFlag`` is set).
.. c:macro:: Py_UNUSED(arg)
Use this for unused arguments in a function definition to silence compiler
@ -175,18 +221,6 @@ complete listing.
.. versionadded:: 3.4
.. c:macro:: Py_DEPRECATED(version)
Use this for deprecated declarations. The macro must be placed before the
symbol name.
Example::
Py_DEPRECATED(3.8) PyAPI_FUNC(int) Py_OldFunction(void);
.. versionchanged:: 3.8
MSVC support was added.
.. c:macro:: PyDoc_STRVAR(name, str)
Creates a variable with name ``name`` that can be used in docstrings.
@ -221,6 +255,7 @@ complete listing.
{NULL, NULL}
};
.. _api-objects:
Objects, Types and Reference Counts

15
Doc/c-api/iter.rst
View file

@ -9,10 +9,10 @@ There are two functions specifically for working with iterators.
.. c:function:: int PyIter_Check(PyObject *o)
Return non-zero if the object *o* supports the iterator protocol, and ``0``
otherwise. This function always succeeds.
Return non-zero if the object *o* can be safely passed to
:c:func:`PyIter_Next`, and ``0`` otherwise. This function always succeeds.
.. c:function:: int PyAiter_Check(PyObject *o)
.. c:function:: int PyAIter_Check(PyObject *o)
Returns non-zero if the object 'obj' provides :class:`AsyncIterator`
protocols, and ``0`` otherwise. This function always succeeds.
@ -21,10 +21,11 @@ There are two functions specifically for working with iterators.
.. c:function:: PyObject* PyIter_Next(PyObject *o)
Return the next value from the iteration *o*. The object must be an iterator
(it is up to the caller to check this). If there are no remaining values,
returns ``NULL`` with no exception set. If an error occurs while retrieving
the item, returns ``NULL`` and passes along the exception.
Return the next value from the iterator *o*. The object must be an iterator
according to :c:func:`PyIter_Check` (it is up to the caller to check this).
If there are no remaining values, returns ``NULL`` with no exception set.
If an error occurs while retrieving the item, returns ``NULL`` and passes
along the exception.
To write a loop which iterates over an iterator, the C code should look
something like this::

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

@ -358,7 +358,7 @@ Object Protocol
iterated.
.. c:function:: PyObject* PyObject_GetAiter(PyObject *o)
.. c:function:: PyObject* PyObject_GetAIter(PyObject *o)
This is the equivalent to the Python expression ``aiter(o)``. Takes an
:class:`AsyncIterable` object and returns an :class:`AsyncIterator` for it.

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

@ -99,7 +99,10 @@ the definition of all other Python objects.
Return a :term:`borrowed reference`.
The :c:func:`Py_SET_TYPE` function must be used to set an object type.
Use the :c:func:`Py_SET_TYPE` function to set an object type.
.. versionchanged:: 3.11
:c:func:`Py_TYPE()` is changed to an inline static function.
.. c:function:: int Py_IS_TYPE(PyObject *o, PyTypeObject *type)
@ -121,9 +124,10 @@ the definition of all other Python objects.
Get the reference count of the Python object *o*.
Use the :c:func:`Py_SET_REFCNT()` function to set an object reference count.
.. versionchanged:: 3.10
:c:func:`Py_REFCNT()` is changed to the inline static function.
Use :c:func:`Py_SET_REFCNT()` to set an object reference count.
.. c:function:: void Py_SET_REFCNT(PyObject *o, Py_ssize_t refcnt)
@ -137,7 +141,10 @@ the definition of all other Python objects.
Get the size of the Python object *o*.
The :c:func:`Py_SET_SIZE` function must be used to set an object size.
Use the :c:func:`Py_SET_SIZE` function to set an object size.
.. versionchanged:: 3.11
:c:func:`Py_SIZE()` is changed to an inline static function.
.. c:function:: void Py_SET_SIZE(PyVarObject *o, Py_ssize_t size)

9
Doc/c-api/type.rst
View file

@ -112,6 +112,13 @@ Type Objects
.. versionadded:: 3.11
.. c:function:: PyObject* PyType_GetQualName(PyTypeObject *type)
Return the type's qualified name. Equivalent to getting the
type's ``__qualname__`` attribute.
.. versionadded:: 3.11
.. c:function:: void* PyType_GetSlot(PyTypeObject *type, int slot)
Return the function pointer stored in the given slot. If the
@ -180,7 +187,7 @@ The following functions and structs are used to create
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`.
retrieved with :c:func:`PyType_GetModule`.
The associated module is not inherited by subclasses; it must be specified
for each class individually.

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

@ -31,7 +31,7 @@ two types exist -- :ref:`GenericAlias <types-genericalias>` and
static PyMethodDef my_obj_methods[] = {
// Other methods.
...
{"__class_getitem__", (PyCFunction)Py_GenericAlias, METH_O|METH_CLASS, "See PEP 585"}
{"__class_getitem__", Py_GenericAlias, METH_O|METH_CLASS, "See PEP 585"}
...
}

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

@ -189,138 +189,138 @@ sub-slots
.. table::
:widths: 26,17,12
+---------------------------------------------------------+-----------------------------------+--------------+
| Slot | :ref:`Type <slot-typedefs-table>` | special |
| | | methods |
+=========================================================+===================================+==============+
| :c:member:`~PyAsyncMethods.am_await` | :c:type:`unaryfunc` | __await__ |
+---------------------------------------------------------+-----------------------------------+--------------+
| :c:member:`~PyAsyncMethods.am_aiter` | :c:type:`unaryfunc` | __aiter__ |
+---------------------------------------------------------+-----------------------------------+--------------+
| :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__ |
| | | __radd__ |
+---------------------------------------------------------+-----------------------------------+--------------+
| :c:member:`~PyNumberMethods.nb_inplace_add` | :c:type:`binaryfunc` | __iadd__ |
+---------------------------------------------------------+-----------------------------------+--------------+
| :c:member:`~PyNumberMethods.nb_subtract` | :c:type:`binaryfunc` | __sub__ |
| | | __rsub__ |
+---------------------------------------------------------+-----------------------------------+--------------+
| :c:member:`~PyNumberMethods.nb_inplace_subtract` | :c:type:`binaryfunc` | __sub__ |
+---------------------------------------------------------+-----------------------------------+--------------+
| :c:member:`~PyNumberMethods.nb_multiply` | :c:type:`binaryfunc` | __mul__ |
| | | __rmul__ |
+---------------------------------------------------------+-----------------------------------+--------------+
| :c:member:`~PyNumberMethods.nb_inplace_multiply` | :c:type:`binaryfunc` | __mul__ |
+---------------------------------------------------------+-----------------------------------+--------------+
| :c:member:`~PyNumberMethods.nb_remainder` | :c:type:`binaryfunc` | __mod__ |
| | | __rmod__ |
+---------------------------------------------------------+-----------------------------------+--------------+
| :c:member:`~PyNumberMethods.nb_inplace_remainder` | :c:type:`binaryfunc` | __mod__ |
+---------------------------------------------------------+-----------------------------------+--------------+
| :c:member:`~PyNumberMethods.nb_divmod` | :c:type:`binaryfunc` | __divmod__ |
| | | __rdivmod__ |
+---------------------------------------------------------+-----------------------------------+--------------+
| :c:member:`~PyNumberMethods.nb_power` | :c:type:`ternaryfunc` | __pow__ |
| | | __rpow__ |
+---------------------------------------------------------+-----------------------------------+--------------+
| :c:member:`~PyNumberMethods.nb_inplace_power` | :c:type:`ternaryfunc` | __pow__ |
+---------------------------------------------------------+-----------------------------------+--------------+
| :c:member:`~PyNumberMethods.nb_negative` | :c:type:`unaryfunc` | __neg__ |
+---------------------------------------------------------+-----------------------------------+--------------+
| :c:member:`~PyNumberMethods.nb_positive` | :c:type:`unaryfunc` | __pos__ |
+---------------------------------------------------------+-----------------------------------+--------------+
| :c:member:`~PyNumberMethods.nb_absolute` | :c:type:`unaryfunc` | __abs__ |
+---------------------------------------------------------+-----------------------------------+--------------+
| :c:member:`~PyNumberMethods.nb_bool` | :c:type:`inquiry` | __bool__ |
+---------------------------------------------------------+-----------------------------------+--------------+
| :c:member:`~PyNumberMethods.nb_invert` | :c:type:`unaryfunc` | __invert__ |
+---------------------------------------------------------+-----------------------------------+--------------+
| :c:member:`~PyNumberMethods.nb_lshift` | :c:type:`binaryfunc` | __lshift__ |
| | | __rlshift__ |
+---------------------------------------------------------+-----------------------------------+--------------+
| :c:member:`~PyNumberMethods.nb_inplace_lshift` | :c:type:`binaryfunc` | __lshift__ |
+---------------------------------------------------------+-----------------------------------+--------------+
| :c:member:`~PyNumberMethods.nb_rshift` | :c:type:`binaryfunc` | __rshift__ |
| | | __rrshift__ |
+---------------------------------------------------------+-----------------------------------+--------------+
| :c:member:`~PyNumberMethods.nb_inplace_rshift` | :c:type:`binaryfunc` | __rshift__ |
+---------------------------------------------------------+-----------------------------------+--------------+
| :c:member:`~PyNumberMethods.nb_and` | :c:type:`binaryfunc` | __and__ |
| | | __rand__ |
+---------------------------------------------------------+-----------------------------------+--------------+
| :c:member:`~PyNumberMethods.nb_inplace_and` | :c:type:`binaryfunc` | __and__ |
+---------------------------------------------------------+-----------------------------------+--------------+
| :c:member:`~PyNumberMethods.nb_xor` | :c:type:`binaryfunc` | __xor__ |
| | | __rxor__ |
+---------------------------------------------------------+-----------------------------------+--------------+
| :c:member:`~PyNumberMethods.nb_inplace_xor` | :c:type:`binaryfunc` | __xor__ |
+---------------------------------------------------------+-----------------------------------+--------------+
| :c:member:`~PyNumberMethods.nb_or` | :c:type:`binaryfunc` | __or__ |
| | | __ror__ |
+---------------------------------------------------------+-----------------------------------+--------------+
| :c:member:`~PyNumberMethods.nb_inplace_or` | :c:type:`binaryfunc` | __or__ |
+---------------------------------------------------------+-----------------------------------+--------------+
| :c:member:`~PyNumberMethods.nb_int` | :c:type:`unaryfunc` | __int__ |
+---------------------------------------------------------+-----------------------------------+--------------+
| :c:member:`~PyNumberMethods.nb_reserved` | void * | |
+---------------------------------------------------------+-----------------------------------+--------------+
| :c:member:`~PyNumberMethods.nb_float` | :c:type:`unaryfunc` | __float__ |
+---------------------------------------------------------+-----------------------------------+--------------+
| :c:member:`~PyNumberMethods.nb_floor_divide` | :c:type:`binaryfunc` | __floordiv__ |
+---------------------------------------------------------+-----------------------------------+--------------+
| :c:member:`~PyNumberMethods.nb_inplace_floor_divide` | :c:type:`binaryfunc` | __floordiv__ |
+---------------------------------------------------------+-----------------------------------+--------------+
| :c:member:`~PyNumberMethods.nb_true_divide` | :c:type:`binaryfunc` | __truediv__ |
+---------------------------------------------------------+-----------------------------------+--------------+
| :c:member:`~PyNumberMethods.nb_inplace_true_divide` | :c:type:`binaryfunc` | __truediv__ |
+---------------------------------------------------------+-----------------------------------+--------------+
| :c:member:`~PyNumberMethods.nb_index` | :c:type:`unaryfunc` | __index__ |
+---------------------------------------------------------+-----------------------------------+--------------+
| :c:member:`~PyNumberMethods.nb_matrix_multiply` | :c:type:`binaryfunc` | __matmul__ |
| | | __rmatmul__ |
+---------------------------------------------------------+-----------------------------------+--------------+
| :c:member:`~PyNumberMethods.nb_inplace_matrix_multiply` | :c:type:`binaryfunc` | __matmul__ |
+---------------------------------------------------------+-----------------------------------+--------------+
| |
+---------------------------------------------------------+-----------------------------------+--------------+
| :c:member:`~PyMappingMethods.mp_length` | :c:type:`lenfunc` | __len__ |
+---------------------------------------------------------+-----------------------------------+--------------+
| :c:member:`~PyMappingMethods.mp_subscript` | :c:type:`binaryfunc` | __getitem__ |
+---------------------------------------------------------+-----------------------------------+--------------+
| :c:member:`~PyMappingMethods.mp_ass_subscript` | :c:type:`objobjargproc` | __setitem__, |
| | | __delitem__ |
+---------------------------------------------------------+-----------------------------------+--------------+
| |
+---------------------------------------------------------+-----------------------------------+--------------+
| :c:member:`~PySequenceMethods.sq_length` | :c:type:`lenfunc` | __len__ |
+---------------------------------------------------------+-----------------------------------+--------------+
| :c:member:`~PySequenceMethods.sq_concat` | :c:type:`binaryfunc` | __add__ |
+---------------------------------------------------------+-----------------------------------+--------------+
| :c:member:`~PySequenceMethods.sq_repeat` | :c:type:`ssizeargfunc` | __mul__ |
+---------------------------------------------------------+-----------------------------------+--------------+
| :c:member:`~PySequenceMethods.sq_item` | :c:type:`ssizeargfunc` | __getitem__ |
+---------------------------------------------------------+-----------------------------------+--------------+
| :c:member:`~PySequenceMethods.sq_ass_item` | :c:type:`ssizeobjargproc` | __setitem__ |
| | | __delitem__ |
+---------------------------------------------------------+-----------------------------------+--------------+
| :c:member:`~PySequenceMethods.sq_contains` | :c:type:`objobjproc` | __contains__ |
+---------------------------------------------------------+-----------------------------------+--------------+
| :c:member:`~PySequenceMethods.sq_inplace_concat` | :c:type:`binaryfunc` | __iadd__ |
+---------------------------------------------------------+-----------------------------------+--------------+
| :c:member:`~PySequenceMethods.sq_inplace_repeat` | :c:type:`ssizeargfunc` | __imul__ |
+---------------------------------------------------------+-----------------------------------+--------------+
| |
+---------------------------------------------------------+-----------------------------------+--------------+
| :c:member:`~PyBufferProcs.bf_getbuffer` | :c:func:`getbufferproc` | |
+---------------------------------------------------------+-----------------------------------+--------------+
| :c:member:`~PyBufferProcs.bf_releasebuffer` | :c:func:`releasebufferproc` | |
+---------------------------------------------------------+-----------------------------------+--------------+
+---------------------------------------------------------+-----------------------------------+---------------+
| Slot | :ref:`Type <slot-typedefs-table>` | special |
| | | methods |
+=========================================================+===================================+===============+
| :c:member:`~PyAsyncMethods.am_await` | :c:type:`unaryfunc` | __await__ |
+---------------------------------------------------------+-----------------------------------+---------------+
| :c:member:`~PyAsyncMethods.am_aiter` | :c:type:`unaryfunc` | __aiter__ |
+---------------------------------------------------------+-----------------------------------+---------------+
| :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__ |
| | | __radd__ |
+---------------------------------------------------------+-----------------------------------+---------------+
| :c:member:`~PyNumberMethods.nb_inplace_add` | :c:type:`binaryfunc` | __iadd__ |
+---------------------------------------------------------+-----------------------------------+---------------+
| :c:member:`~PyNumberMethods.nb_subtract` | :c:type:`binaryfunc` | __sub__ |
| | | __rsub__ |
+---------------------------------------------------------+-----------------------------------+---------------+
| :c:member:`~PyNumberMethods.nb_inplace_subtract` | :c:type:`binaryfunc` | __isub__ |
+---------------------------------------------------------+-----------------------------------+---------------+
| :c:member:`~PyNumberMethods.nb_multiply` | :c:type:`binaryfunc` | __mul__ |
| | | __rmul__ |
+---------------------------------------------------------+-----------------------------------+---------------+
| :c:member:`~PyNumberMethods.nb_inplace_multiply` | :c:type:`binaryfunc` | __imul__ |
+---------------------------------------------------------+-----------------------------------+---------------+
| :c:member:`~PyNumberMethods.nb_remainder` | :c:type:`binaryfunc` | __mod__ |
| | | __rmod__ |
+---------------------------------------------------------+-----------------------------------+---------------+
| :c:member:`~PyNumberMethods.nb_inplace_remainder` | :c:type:`binaryfunc` | __imod__ |
+---------------------------------------------------------+-----------------------------------+---------------+
| :c:member:`~PyNumberMethods.nb_divmod` | :c:type:`binaryfunc` | __divmod__ |
| | | __rdivmod__ |
+---------------------------------------------------------+-----------------------------------+---------------+
| :c:member:`~PyNumberMethods.nb_power` | :c:type:`ternaryfunc` | __pow__ |
| | | __rpow__ |
+---------------------------------------------------------+-----------------------------------+---------------+
| :c:member:`~PyNumberMethods.nb_inplace_power` | :c:type:`ternaryfunc` | __ipow__ |
+---------------------------------------------------------+-----------------------------------+---------------+
| :c:member:`~PyNumberMethods.nb_negative` | :c:type:`unaryfunc` | __neg__ |
+---------------------------------------------------------+-----------------------------------+---------------+
| :c:member:`~PyNumberMethods.nb_positive` | :c:type:`unaryfunc` | __pos__ |
+---------------------------------------------------------+-----------------------------------+---------------+
| :c:member:`~PyNumberMethods.nb_absolute` | :c:type:`unaryfunc` | __abs__ |
+---------------------------------------------------------+-----------------------------------+---------------+
| :c:member:`~PyNumberMethods.nb_bool` | :c:type:`inquiry` | __bool__ |
+---------------------------------------------------------+-----------------------------------+---------------+
| :c:member:`~PyNumberMethods.nb_invert` | :c:type:`unaryfunc` | __invert__ |
+---------------------------------------------------------+-----------------------------------+---------------+
| :c:member:`~PyNumberMethods.nb_lshift` | :c:type:`binaryfunc` | __lshift__ |
| | | __rlshift__ |
+---------------------------------------------------------+-----------------------------------+---------------+
| :c:member:`~PyNumberMethods.nb_inplace_lshift` | :c:type:`binaryfunc` | __ilshift__ |
+---------------------------------------------------------+-----------------------------------+---------------+
| :c:member:`~PyNumberMethods.nb_rshift` | :c:type:`binaryfunc` | __rshift__ |
| | | __rrshift__ |
+---------------------------------------------------------+-----------------------------------+---------------+
| :c:member:`~PyNumberMethods.nb_inplace_rshift` | :c:type:`binaryfunc` | __irshift__ |
+---------------------------------------------------------+-----------------------------------+---------------+
| :c:member:`~PyNumberMethods.nb_and` | :c:type:`binaryfunc` | __and__ |
| | | __rand__ |
+---------------------------------------------------------+-----------------------------------+---------------+
| :c:member:`~PyNumberMethods.nb_inplace_and` | :c:type:`binaryfunc` | __iand__ |
+---------------------------------------------------------+-----------------------------------+---------------+
| :c:member:`~PyNumberMethods.nb_xor` | :c:type:`binaryfunc` | __xor__ |
| | | __rxor__ |
+---------------------------------------------------------+-----------------------------------+---------------+
| :c:member:`~PyNumberMethods.nb_inplace_xor` | :c:type:`binaryfunc` | __ixor__ |
+---------------------------------------------------------+-----------------------------------+---------------+
| :c:member:`~PyNumberMethods.nb_or` | :c:type:`binaryfunc` | __or__ |
| | | __ror__ |
+---------------------------------------------------------+-----------------------------------+---------------+
| :c:member:`~PyNumberMethods.nb_inplace_or` | :c:type:`binaryfunc` | __ior__ |
+---------------------------------------------------------+-----------------------------------+---------------+
| :c:member:`~PyNumberMethods.nb_int` | :c:type:`unaryfunc` | __int__ |
+---------------------------------------------------------+-----------------------------------+---------------+
| :c:member:`~PyNumberMethods.nb_reserved` | void * | |
+---------------------------------------------------------+-----------------------------------+---------------+
| :c:member:`~PyNumberMethods.nb_float` | :c:type:`unaryfunc` | __float__ |
+---------------------------------------------------------+-----------------------------------+---------------+
| :c:member:`~PyNumberMethods.nb_floor_divide` | :c:type:`binaryfunc` | __floordiv__ |
+---------------------------------------------------------+-----------------------------------+---------------+
| :c:member:`~PyNumberMethods.nb_inplace_floor_divide` | :c:type:`binaryfunc` | __ifloordiv__ |
+---------------------------------------------------------+-----------------------------------+---------------+
| :c:member:`~PyNumberMethods.nb_true_divide` | :c:type:`binaryfunc` | __truediv__ |
+---------------------------------------------------------+-----------------------------------+---------------+
| :c:member:`~PyNumberMethods.nb_inplace_true_divide` | :c:type:`binaryfunc` | __itruediv__ |
+---------------------------------------------------------+-----------------------------------+---------------+
| :c:member:`~PyNumberMethods.nb_index` | :c:type:`unaryfunc` | __index__ |
+---------------------------------------------------------+-----------------------------------+---------------+
| :c:member:`~PyNumberMethods.nb_matrix_multiply` | :c:type:`binaryfunc` | __matmul__ |
| | | __rmatmul__ |
+---------------------------------------------------------+-----------------------------------+---------------+
| :c:member:`~PyNumberMethods.nb_inplace_matrix_multiply` | :c:type:`binaryfunc` | __imatmul__ |
+---------------------------------------------------------+-----------------------------------+---------------+
| |
+---------------------------------------------------------+-----------------------------------+---------------+
| :c:member:`~PyMappingMethods.mp_length` | :c:type:`lenfunc` | __len__ |
+---------------------------------------------------------+-----------------------------------+---------------+
| :c:member:`~PyMappingMethods.mp_subscript` | :c:type:`binaryfunc` | __getitem__ |
+---------------------------------------------------------+-----------------------------------+---------------+
| :c:member:`~PyMappingMethods.mp_ass_subscript` | :c:type:`objobjargproc` | __setitem__, |
| | | __delitem__ |
+---------------------------------------------------------+-----------------------------------+---------------+
| |
+---------------------------------------------------------+-----------------------------------+---------------+
| :c:member:`~PySequenceMethods.sq_length` | :c:type:`lenfunc` | __len__ |
+---------------------------------------------------------+-----------------------------------+---------------+
| :c:member:`~PySequenceMethods.sq_concat` | :c:type:`binaryfunc` | __add__ |
+---------------------------------------------------------+-----------------------------------+---------------+
| :c:member:`~PySequenceMethods.sq_repeat` | :c:type:`ssizeargfunc` | __mul__ |
+---------------------------------------------------------+-----------------------------------+---------------+
| :c:member:`~PySequenceMethods.sq_item` | :c:type:`ssizeargfunc` | __getitem__ |
+---------------------------------------------------------+-----------------------------------+---------------+
| :c:member:`~PySequenceMethods.sq_ass_item` | :c:type:`ssizeobjargproc` | __setitem__ |
| | | __delitem__ |
+---------------------------------------------------------+-----------------------------------+---------------+
| :c:member:`~PySequenceMethods.sq_contains` | :c:type:`objobjproc` | __contains__ |
+---------------------------------------------------------+-----------------------------------+---------------+
| :c:member:`~PySequenceMethods.sq_inplace_concat` | :c:type:`binaryfunc` | __iadd__ |
+---------------------------------------------------------+-----------------------------------+---------------+
| :c:member:`~PySequenceMethods.sq_inplace_repeat` | :c:type:`ssizeargfunc` | __imul__ |
+---------------------------------------------------------+-----------------------------------+---------------+
| |
+---------------------------------------------------------+-----------------------------------+---------------+
| :c:member:`~PyBufferProcs.bf_getbuffer` | :c:func:`getbufferproc` | |
+---------------------------------------------------------+-----------------------------------+---------------+
| :c:member:`~PyBufferProcs.bf_releasebuffer` | :c:func:`releasebufferproc` | |
+---------------------------------------------------------+-----------------------------------+---------------+
.. _slot-typedefs-table:
@ -668,6 +668,18 @@ and :c:type:`PyType_Type` effectively act as defaults.)
:c:func:`PyObject_GC_Del` if the instance was allocated using
:c:func:`PyObject_GC_New` or :c:func:`PyObject_GC_NewVar`.
If the type supports garbage collection (has the :const:`Py_TPFLAGS_HAVE_GC`
flag bit set), the destructor should call :c:func:`PyObject_GC_UnTrack`
before clearing any member fields.
.. code-block:: c
static void foo_dealloc(foo_object *self) {
PyObject_GC_UnTrack(self);
Py_CLEAR(self->ref);
Py_TYPE(self)->tp_free((PyObject *)self);
}
Finally, if the type is heap allocated (:const:`Py_TPFLAGS_HEAPTYPE`), the
deallocator should decrement the reference count for its type object after
calling the type deallocator. In order to avoid dangling pointers, the
@ -1509,9 +1521,9 @@ and :c:type:`PyType_Type` effectively act as defaults.)
.. c:member:: getiterfunc PyTypeObject.tp_iter
An optional pointer to a function that returns an iterator for the object. Its
presence normally signals that the instances of this type are iterable (although
sequences may be iterable without this function).
An optional pointer to a function that returns an :term:`iterator` for the
object. Its presence normally signals that the instances of this type are
:term:`iterable` (although sequences may be iterable without this function).
This function has the same signature as :c:func:`PyObject_GetIter`::
@ -1524,8 +1536,8 @@ and :c:type:`PyType_Type` effectively act as defaults.)
.. c:member:: iternextfunc PyTypeObject.tp_iternext
An optional pointer to a function that returns the next item in an iterator.
The signature is::
An optional pointer to a function that returns the next item in an
:term:`iterator`. The signature is::
PyObject *tp_iternext(PyObject *self);
@ -2417,8 +2429,8 @@ Async Object Structures
PyObject *am_await(PyObject *self);
The returned object must be an iterator, i.e. :c:func:`PyIter_Check` must
return ``1`` for it.
The returned object must be an :term:`iterator`, i.e. :c:func:`PyIter_Check`
must return ``1`` for it.
This slot may be set to ``NULL`` if an object is not an :term:`awaitable`.

11
Doc/data/refcounts.dat
View file

@ -1073,8 +1073,8 @@ PyInterpreterState_New:PyInterpreterState*:::
PyIter_Check:int:::
PyIter_Check:PyObject*:o:0:
PyAiter_Check:int:::
PyAiter_Check:PyObject*:o:0:
PyAIter_Check:int:::
PyAIter_Check:PyObject*:o:0:
PyIter_Next:PyObject*::+1:
PyIter_Next:PyObject*:o:0:
@ -1700,8 +1700,8 @@ PyObject_GetItem:PyObject*:key:0:
PyObject_GetIter:PyObject*::+1:
PyObject_GetIter:PyObject*:o:0:
PyObject_GetAiter:PyObject*::+1:
PyObject_GetAiter:PyObject*:o:0:
PyObject_GetAIter:PyObject*::+1:
PyObject_GetAIter:PyObject*:o:0:
PyObject_HasAttr:int:::
PyObject_HasAttr:PyObject*:o:0:
@ -2310,6 +2310,9 @@ PyType_GetFlags:PyTypeObject*:type:0:
PyType_GetName:PyObject*::+1:
PyType_GetName:PyTypeObject*:type:0:
PyType_GetQualName:PyObject*::+1:
PyType_GetQualName:PyTypeObject*:type:0:
PyType_GetSlot:void*:::
PyType_GetSlot:PyTypeObject*:type:0:
PyType_GetSlot:int:slot::

8
Doc/data/stable_abi.dat
View file

@ -1,5 +1,5 @@
role,name,added,ifdef_note
function,PyAiter_Check,3.10,
function,PyAIter_Check,3.10,
function,PyArg_Parse,3.2,
function,PyArg_ParseTuple,3.2,
function,PyArg_ParseTupleAndKeywords,3.2,
@ -189,6 +189,7 @@ var,PyExc_ArithmeticError,3.2,
var,PyExc_AssertionError,3.2,
var,PyExc_AttributeError,3.2,
var,PyExc_BaseException,3.2,
var,PyExc_BaseExceptionGroup,3.11,
var,PyExc_BlockingIOError,3.7,
var,PyExc_BrokenPipeError,3.7,
var,PyExc_BufferError,3.2,
@ -491,7 +492,7 @@ function,PyObject_GenericGetAttr,3.2,
function,PyObject_GenericGetDict,3.10,
function,PyObject_GenericSetAttr,3.2,
function,PyObject_GenericSetDict,3.7,
function,PyObject_GetAiter,3.10,
function,PyObject_GetAIter,3.10,
function,PyObject_GetAttr,3.2,
function,PyObject_GetAttrString,3.2,
function,PyObject_GetItem,3.2,
@ -569,6 +570,7 @@ function,PyStructSequence_GetItem,3.2,
function,PyStructSequence_New,3.2,
function,PyStructSequence_NewType,3.2,
function,PyStructSequence_SetItem,3.2,
var,PyStructSequence_UnnamedField,3.11,
var,PySuper_Type,3.2,
function,PySys_AddWarnOption,3.2,
function,PySys_AddWarnOptionUnicode,3.2,
@ -644,6 +646,7 @@ function,PyType_GetFlags,3.2,
function,PyType_GetModule,3.10,
function,PyType_GetModuleState,3.10,
function,PyType_GetName,3.11,
function,PyType_GetQualName,3.11,
function,PyType_GetSlot,3.4,
function,PyType_IsSubtype,3.2,
function,PyType_Modified,3.2,
@ -827,6 +830,7 @@ type,Py_UCS4,3.2,
macro,Py_UNBLOCK_THREADS,3.2,
var,Py_UTF8Mode,3.8,
function,Py_VaBuildValue,3.2,
var,Py_Version,3.11,
function,Py_XNewRef,3.10,
type,Py_intptr_t,3.2,
type,Py_ssize_t,3.2,

10
Doc/distributing/index.rst
View file

@ -31,7 +31,7 @@ installing other Python projects, refer to the
Key terms
=========
* the `Python Packaging Index <https://pypi.org>`__ is a public
* the `Python Package Index <https://pypi.org>`__ is a public
repository of open source licensed packages made available for use by
other Python users
* the `Python Packaging Authority
@ -101,7 +101,7 @@ by invoking the ``pip`` module at the command line::
.. note::
For POSIX users (including Mac OS X and Linux users), these instructions
For POSIX users (including macOS and Linux users), these instructions
assume the use of a :term:`virtual environment`.
For Windows users, these instructions assume that the option to
@ -127,14 +127,14 @@ involved in creating and publishing a project:
* `Project structure`_
* `Building and packaging the project`_
* `Uploading the project to the Python Packaging Index`_
* `Uploading the project to the Python Package Index`_
* `The .pypirc file`_
.. _Project structure: \
https://packaging.python.org/tutorials/packaging-projects/#packaging-python-projects
.. _Building and packaging the project: \
https://packaging.python.org/tutorials/packaging-projects/#creating-the-package-files
.. _Uploading the project to the Python Packaging Index: \
.. _Uploading the project to the Python Package Index: \
https://packaging.python.org/tutorials/packaging-projects/#uploading-the-distribution-archives
.. _The .pypirc file: \
https://packaging.python.org/specifications/pypirc/
@ -150,7 +150,7 @@ These are quick answers or links for some common tasks.
This isn't an easy topic, but here are a few tips:
* check the Python Packaging Index to see if the name is already in use
* check the Python Package Index to see if the name is already in use
* check popular hosting sites like GitHub, Bitbucket, etc to see if there
is already a project with that name
* check what comes up in a web search for the name you're considering

24
Doc/distutils/apiref.rst
View file

@ -373,7 +373,7 @@ This module provides the following functions.
compiler object under Unix---if you supply a value for *compiler*, *plat* is
ignored.
.. % Is the posix/nt only thing still true? Mac OS X seems to work, and
.. % Is the posix/nt only thing still true? macOS seems to work, and
.. % returns a UnixCCompiler instance. How to document this... hmm.
@ -1119,11 +1119,11 @@ other utility module.
For non-POSIX platforms, currently just returns ``sys.platform``.
For Mac OS X systems the OS version reflects the minimal version on which
For macOS systems the OS version reflects the minimal version on which
binaries will run (that is, the value of ``MACOSX_DEPLOYMENT_TARGET``
during the build of Python), not the OS version of the current system.
For universal binary builds on Mac OS X the architecture value reflects
For universal binary builds on macOS the architecture value reflects
the universal binary status instead of the architecture of the current
processor. For 32-bit universal binaries the architecture is ``fat``,
for 64-bit universal binaries the architecture is ``fat64``, and
@ -1132,7 +1132,7 @@ other utility module.
a 3-way universal build (ppc, i386, x86_64) and ``intel`` is used for
a universal build with the i386 and x86_64 architectures
Examples of returned values on Mac OS X:
Examples of returned values on macOS:
* ``macosx-10.3-ppc``
@ -1852,22 +1852,6 @@ Subclasses of :class:`Command` must define the following methods.
.. % todo
:mod:`distutils.command.bdist_msi` --- Build a Microsoft Installer binary package
=================================================================================
.. module:: distutils.command.bdist_msi
:synopsis: Build a binary distribution as a Windows MSI file
.. class:: bdist_msi
.. deprecated:: 3.9
Use bdist_wheel (wheel packages) instead.
Builds a `Windows Installer`_ (.msi) binary package.
.. _Windows Installer: https://msdn.microsoft.com/en-us/library/cc185688(VS.85).aspx
:mod:`distutils.command.bdist_rpm` --- Build a binary distribution as a Redhat RPM and SRPM
===========================================================================================

5
Doc/distutils/builtdist.rst
View file

@ -138,11 +138,6 @@ generated by each, are:
+--------------------------+-------------------------------------+
| :command:`bdist_rpm` | rpm, srpm |
+--------------------------+-------------------------------------+
| :command:`bdist_msi` | msi |
+--------------------------+-------------------------------------+
.. note::
bdist_msi is deprecated since Python 3.9.
The following sections give details on the individual :command:`bdist_\*`
commands.

12
Doc/extending/extending.rst
View file

@ -127,13 +127,11 @@ Intermezzo: Errors and Exceptions
An important convention throughout the Python interpreter is the following: when
a function fails, it should set an exception condition and return an error value
(usually a ``NULL`` pointer). Exceptions are stored in a static global variable
inside the interpreter; if this variable is ``NULL`` no exception has occurred. A
second global variable stores the "associated value" of the exception (the
second argument to :keyword:`raise`). A third variable contains the stack
traceback in case the error originated in Python code. These three variables
are the C equivalents of the result in Python of :meth:`sys.exc_info` (see the
section on module :mod:`sys` in the Python Library Reference). It is important
(usually ``-1`` or a ``NULL`` pointer). Exception information is stored in
three members of the interpreter's thread state. These are ``NULL`` if
there is no exception. Otherwise they are the C equivalents of the members
of the Python tuple returned by :meth:`sys.exc_info`. These are the
exception type, exception instance, and a traceback object. It is important
to know about them to understand how errors are passed around.
The Python API defines a number of functions to set various types of exceptions.

16
Doc/extending/newtypes.rst
View file

@ -73,7 +73,19 @@ function::
newdatatype_dealloc(newdatatypeobject *obj)
{
free(obj->obj_UnderlyingDatatypePtr);
Py_TYPE(obj)->tp_free(obj);
Py_TYPE(obj)->tp_free((PyObject *)obj);
}
If your type supports garbage collection, the destructor should call
:c:func:`PyObject_GC_UnTrack` before clearing any member fields::
static void
newdatatype_dealloc(newdatatypeobject *obj)
{
PyObject_GC_UnTrack(obj);
Py_CLEAR(obj->other_obj);
...
Py_TYPE(obj)->tp_free((PyObject *)obj);
}
.. index::
@ -381,7 +393,7 @@ analogous to the :ref:`rich comparison methods <richcmpfuncs>`, like
:c:func:`PyObject_RichCompareBool`.
This function is called with two Python objects and the operator as arguments,
where the operator is one of ``Py_EQ``, ``Py_NE``, ``Py_LE``, ``Py_GT``,
where the operator is one of ``Py_EQ``, ``Py_NE``, ``Py_LE``, ``Py_GE``,
``Py_LT`` or ``Py_GT``. It should compare the two objects with respect to the
specified operator and return ``Py_True`` or ``Py_False`` if the comparison is
successful, ``Py_NotImplemented`` to indicate that comparison is not

2
Doc/faq/design.rst
View file

@ -714,7 +714,7 @@ Why don't generators support the with statement?
For technical reasons, a generator used directly as a context manager
would not work correctly. When, as is most common, a generator is used as
an iterator run to completion, no closing is needed. When it is, wrap
it as "contextlib.closing(generator)" in the 'with' statment.
it as "contextlib.closing(generator)" in the 'with' statement.
Why are colons required for the if/while/def/class statements?

3
Doc/faq/extending.rst
View file

@ -290,9 +290,6 @@ complete example using the GNU readline library (you may want to ignore
#define PY_SSIZE_T_CLEAN
#include <Python.h>
#include <object.h>
#include <compile.h>
#include <eval.h>
int main (int argc, char* argv[])
{

98
Doc/faq/gui.rst
View file

@ -14,17 +14,8 @@ Graphic User Interface FAQ
General GUI Questions
=====================
What platform-independent GUI toolkits exist for Python?
========================================================
Depending on what platform(s) you are aiming at, there are several. Some
of them haven't been ported to Python 3 yet. At least `Tkinter`_ and `Qt`_
are known to be Python 3-compatible.
.. XXX check links
Tkinter
-------
What GUI toolkits exist for Python?
===================================
Standard builds of Python include an object-oriented interface to the Tcl/Tk
widget set, called :ref:`tkinter <Tkinter>`. This is probably the easiest to
@ -32,85 +23,14 @@ install (since it comes included with most
`binary distributions <https://www.python.org/downloads/>`_ of Python) and use.
For more info about Tk, including pointers to the source, see the
`Tcl/Tk home page <https://www.tcl.tk>`_. Tcl/Tk is fully portable to the
Mac OS X, Windows, and Unix platforms.
wxWidgets
---------
wxWidgets (https://www.wxwidgets.org) is a free, portable GUI class
library written in C++ that provides a native look and feel on a
number of platforms, with Windows, Mac OS X, GTK, X11, all listed as
current stable targets. Language bindings are available for a number
of languages including Python, Perl, Ruby, etc.
`wxPython <https://www.wxpython.org>`_ is the Python binding for
wxwidgets. While it often lags slightly behind the official wxWidgets
releases, it also offers a number of features via pure Python
extensions that are not available in other language bindings. There
is an active wxPython user and developer community.
Both wxWidgets and wxPython are free, open source, software with
permissive licences that allow their use in commercial products as
well as in freeware or shareware.
Qt
---
There are bindings available for the Qt toolkit (using either `PyQt
<https://riverbankcomputing.com/software/pyqt/intro>`_ or `PySide
<https://wiki.qt.io/PySide>`_) and for KDE (`PyKDE4 <https://techbase.kde.org/Languages/Python/Using_PyKDE_4>`__).
PyQt is currently more mature than PySide, but you must buy a PyQt license from
`Riverbank Computing <https://www.riverbankcomputing.com/commercial/license-faq>`_
if you want to write proprietary applications. PySide is free for all applications.
Qt 4.5 upwards is licensed under the LGPL license; also, commercial licenses
are available from `The Qt Company <https://www.qt.io/licensing/>`_.
Gtk+
----
The `GObject introspection bindings <https://wiki.gnome.org/Projects/PyGObject>`_
for Python allow you to write GTK+ 3 applications. There is also a
`Python GTK+ 3 Tutorial <https://python-gtk-3-tutorial.readthedocs.io>`_.
The older PyGtk bindings for the `Gtk+ 2 toolkit <https://www.gtk.org>`_ have
been implemented by James Henstridge; see <http://www.pygtk.org>.
Kivy
----
`Kivy <https://kivy.org/>`_ is a cross-platform GUI library supporting both
desktop operating systems (Windows, macOS, Linux) and mobile devices (Android,
iOS). It is written in Python and Cython, and can use a range of windowing
backends.
Kivy is free and open source software distributed under the MIT license.
FLTK
----
Python bindings for `the FLTK toolkit <http://www.fltk.org>`_, a simple yet
powerful and mature cross-platform windowing system, are available from `the
PyFLTK project <https://pyfltk.sourceforge.io/>`_.
OpenGL
------
For OpenGL bindings, see `PyOpenGL <http://pyopengl.sourceforge.net>`_.
What platform-specific GUI toolkits exist for Python?
========================================================
By installing the `PyObjc Objective-C bridge
<https://pypi.org/project/pyobjc/>`_, Python programs can use Mac OS X's
Cocoa libraries.
:ref:`Pythonwin <windows-faq>` by Mark Hammond includes an interface to the
Microsoft Foundation Classes and a Python programming environment
that's written mostly in Python using the MFC classes.
macOS, Windows, and Unix platforms.
Depending on what platform(s) you are aiming at, there are also several
alternatives. A `list of cross-platform
<https://wiki.python.org/moin/GuiProgramming#Cross-Platform_Frameworks>`_ and
`platform-specific
<https://wiki.python.org/moin/GuiProgramming#Platform-specific_Frameworks>`_ GUI
frameworks can be found on the python wiki.
Tkinter questions
=================

2
Doc/faq/installed.rst
View file

@ -29,7 +29,7 @@ there are several possible ways it could have gotten there.
* Some Windows machines also have Python installed. At this writing we're aware
of computers from Hewlett-Packard and Compaq that include Python. Apparently
some of HP/Compaq's administrative tools are written in Python.
* Many Unix-compatible operating systems, such as Mac OS X and some Linux
* Many Unix-compatible operating systems, such as macOS and some Linux
distributions, have Python installed by default; it's included in the base
installation.

7
Doc/faq/library.rst
View file

@ -240,9 +240,6 @@ Be sure to use the :mod:`threading` module and not the :mod:`_thread` module.
The :mod:`threading` module builds convenient abstractions on top of the
low-level primitives provided by the :mod:`_thread` module.
Aahz has a set of slides from his threading tutorial that are helpful; see
http://www.pythoncraft.com/OSCON2001/.
None of my threads seem to run: why?
------------------------------------
@ -614,9 +611,9 @@ use ``p.read(n)``.
How do I access the serial (RS232) port?
----------------------------------------
For Win32, POSIX (Linux, BSD, etc.), Jython:
For Win32, OSX, Linux, BSD, Jython, IronPython:
http://pyserial.sourceforge.net
https://pypi.org/project/pyserial/
For Unix, see a Usenet post by Mitch Chapman:

72
Doc/faq/programming.rst
View file

@ -836,6 +836,27 @@ ago? ``-190 % 12 == 2`` is useful; ``-190 % 12 == -10`` is a bug waiting to
bite.
How do I get int literal attribute instead of SyntaxError?
----------------------------------------------------------
Trying to lookup an ``int`` literal attribute in the normal manner gives
a syntax error because the period is seen as a decimal point::
>>> 1.__class__
File "<stdin>", line 1
1.__class__
^
SyntaxError: invalid decimal literal
The solution is to separate the literal from the period
with either a space or parentheses.
>>> 1 .__class__
<class 'int'>
>>> (1).__class__
<class 'int'>
How do I convert a string to a number?
--------------------------------------
@ -1826,6 +1847,55 @@ For example, here is the implementation of
return True
return False
How can a subclass control what data is stored in an immutable instance?
------------------------------------------------------------------------
When subclassing an immutable type, override the :meth:`__new__` method
instead of the :meth:`__init__` method. The latter only runs *after* an
instance is created, which is too late to alter data in an immutable
instance.
All of these immutable classes have a different signature than their
parent class:
.. testcode::
from datetime import date
class FirstOfMonthDate(date):
"Always choose the first day of the month"
def __new__(cls, year, month, day):
return super().__new__(cls, year, month, 1)
class NamedInt(int):
"Allow text names for some numbers"
xlat = {'zero': 0, 'one': 1, 'ten': 10}
def __new__(cls, value):
value = cls.xlat.get(value, value)
return super().__new__(cls, value)
class TitleStr(str):
"Convert str to name suitable for a URL path"
def __new__(cls, s):
s = s.lower().replace(' ', '-')
s = ''.join([c for c in s if c.isalnum() or c == '-'])
return super().__new__(cls, s)
The classes can be used like this:
.. doctest::
>>> FirstOfMonthDate(2012, 2, 14)
FirstOfMonthDate(2012, 2, 1)
>>> NamedInt('ten')
10
>>> NamedInt(20)
20
>>> TitleStr('Blog: Why Python Rocks')
'blog-why-python-rocks'
How do I cache method calls?
----------------------------
@ -2022,7 +2092,7 @@ Jim Roskind suggests performing steps in the following order in each module:
* ``import`` statements
* active code (including globals that are initialized from imported values).
van Rossum doesn't like this approach much because the imports appear in a
Van Rossum doesn't like this approach much because the imports appear in a
strange place, but it does work.
Matthias Urlichs recommends restructuring your code so that the recursive import

2
Doc/faq/windows.rst
View file

@ -212,7 +212,7 @@ Embedding the Python interpreter in a Windows app can be summarized as follows:
.. code-block:: c
#include "python.h"
#include <Python.h>
...
Py_Initialize(); // Initialize Python.
initmyAppc(); // Initialize (import) the helper class.

14
Doc/glossary.rst
View file

@ -510,12 +510,13 @@ Glossary
: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
A :term:`type` that can be parameterized; typically a
:ref:`container class<sequence-types>` such as :class:`list` or
:class:`dict`. 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.
For more details, see :ref:`generic alias types<types-genericalias>`,
:pep:`483`, :pep:`484`, :pep:`585`, and the :mod:`typing` module.
GIL
See :term:`global interpreter lock`.
@ -658,6 +659,11 @@ Glossary
More information can be found in :ref:`typeiter`.
.. impl-detail::
CPython does not consistently apply the requirement that an iterator
define :meth:`__iter__`.
key function
A key function or collation function is a callable that returns a value
used for sorting or ordering. For example, :func:`locale.strxfrm` is

2
Doc/howto/annotations.rst
View file

@ -156,7 +156,7 @@ Manually Un-Stringizing Stringized Annotations
require annotating with string values that specifically
*can't* be evaluated. For example:
* :pep:`604` union types using `|`, before support for this
* :pep:`604` union types using ``|``, before support for this
was added to Python 3.10.
* Definitions that aren't needed at runtime, only imported
when :const:`typing.TYPE_CHECKING` is true.

3
Doc/howto/clinic.rst
View file

@ -567,9 +567,6 @@ expression. Currently the following are explicitly supported:
* Simple symbolic constants like ``sys.maxsize``, which must
start with the name of the module
In case you're curious, this is implemented in ``from_builtin()``
in ``Lib/inspect.py``.
(In the future, this may need to get even more elaborate,
to allow full expressions like ``CONSTANT - 1``.)

9
Doc/howto/descriptor.rst
View file

@ -1264,6 +1264,9 @@ Using the non-data descriptor protocol, a pure Python version of
def __get__(self, obj, objtype=None):
return self.f
def __call__(self, *args, **kwds):
return self.f(*args, **kwds)
.. testcode::
:hide:
@ -1272,6 +1275,8 @@ Using the non-data descriptor protocol, a pure Python version of
def f(x):
return x * 10
wrapped_ord = StaticMethod(ord)
.. doctest::
:hide:
@ -1279,6 +1284,8 @@ Using the non-data descriptor protocol, a pure Python version of
30
>>> E_sim().f(3)
30
>>> wrapped_ord('A')
65
Class methods
@ -1344,7 +1351,7 @@ Using the non-data descriptor protocol, a pure Python version of
if cls is None:
cls = type(obj)
if hasattr(type(self.f), '__get__'):
return self.f.__get__(cls)
return self.f.__get__(cls, cls)
return MethodType(self.f, cls)
.. testcode::

23
Doc/howto/enum.rst
View file

@ -636,7 +636,7 @@ an incorrect member::
Before :class:`StrEnum`, ``Directions.NORTH`` would have been the :class:`tuple`
``('north',)``.
.. versionadded:: 3.10
.. versionadded:: 3.11
IntFlag
@ -659,7 +659,7 @@ used.
details.
.. versionadded:: 3.6
.. versionchanged:: 3.10
.. versionchanged:: 3.11
Sample :class:`IntFlag` class::
@ -696,7 +696,7 @@ It is also possible to name the combinations::
Named combinations are considered aliases. Aliases do not show up during
iteration, but can be returned from by-value lookups.
.. versionchanged:: 3.10
.. versionchanged:: 3.11
Another important difference between :class:`IntFlag` and :class:`Enum` is that
if no flags are set (the value is 0), its boolean evaluation is :data:`False`::
@ -728,7 +728,7 @@ be combined with them (but may lose :class:`IntFlag` membership::
>>> list(RW)
[Perm.R, Perm.W]
.. versionadded:: 3.10
.. versionadded:: 3.11
Flag
@ -789,7 +789,7 @@ value::
>>> list(purple)
[Color.RED, Color.BLUE]
.. versionadded:: 3.10
.. versionadded:: 3.11
.. note::
@ -936,9 +936,10 @@ and raise an error if the two do not match::
_Private__names
"""""""""""""""
Private names are not converted to enum members, but remain normal attributes.
:ref:`Private names <private-name-mangling>` are not converted to enum members,
but remain normal attributes.
.. versionchanged:: 3.10
.. versionchanged:: 3.11
``Enum`` member type
@ -961,7 +962,6 @@ it will raise a :exc:`DeprecationWarning`::
<FieldTypes.size: 2>
.. versionchanged:: 3.5
.. versionchanged:: 3.10
Creating members that are mixed with other data types
@ -997,11 +997,12 @@ Plain :class:`Enum` classes always evaluate as :data:`True`.
"""""""""""""""""""""""""""""
If you give your enum subclass extra methods, like the `Planet`_
class below, those methods will show up in a :func:`dir` of the member,
but not of the class::
class below, those methods will show up in a :func:`dir` of the member and the
class. Attributes defined in an :func:`__init__` method will only show up in a
:func:`dir` of the member::
>>> dir(Planet)
['EARTH', 'JUPITER', 'MARS', 'MERCURY', 'NEPTUNE', 'SATURN', 'URANUS', 'VENUS', '__class__', '__doc__', '__members__', '__module__']
['EARTH', 'JUPITER', 'MARS', 'MERCURY', 'NEPTUNE', 'SATURN', 'URANUS', 'VENUS', '__class__', '__doc__', '__init__', '__members__', '__module__', 'surface_gravity']
>>> dir(Planet.EARTH)
['__class__', '__doc__', '__module__', 'mass', 'name', 'radius', 'surface_gravity', 'value']

9
Doc/howto/functional.rst
View file

@ -65,11 +65,10 @@ output must only depend on its input.
Some languages are very strict about purity and don't even have assignment
statements such as ``a=3`` or ``c = a + b``, but it's difficult to avoid all
side effects. Printing to the screen or writing to a disk file are side
effects, for example. For example, in Python a call to the :func:`print` or
:func:`time.sleep` function both return no useful value; they're only called for
their side effects of sending some text to the screen or pausing execution for a
second.
side effects, such as printing to the screen or writing to a disk file. Another
example is a call to the :func:`print` or :func:`time.sleep` function, neither
of which returns a useful value. Both are called only for their side effects
of sending some text to the screen or pausing execution for a second.
Python programs written in functional style usually won't go to the extreme of
avoiding all I/O or all assignments; instead, they'll provide a

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

@ -541,6 +541,17 @@ alternative there, as well as adapting the above script to use your alternative
serialization.
Running a logging socket listener in production
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
To run a logging listener in production, you may need to use a process-management tool
such as `Supervisor <http://supervisord.org/>`_. `Here
<https://gist.github.com/vsajip/4b227eeec43817465ca835ca66f75e2b>`_ is a Gist which
provides the bare-bones files to run the above functionality using Supervisor: you
will need to change the `/path/to/` parts in the Gist to reflect the actual paths you
want to use.
.. _context-info:
Adding contextual information to your logging output
@ -982,6 +993,17 @@ to this (remembering to first import :mod:`concurrent.futures`)::
for i in range(10):
executor.submit(worker_process, queue, worker_configurer)
Deploying Web applications using Gunicorn and uWSGI
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
When deploying Web applications using `Gunicorn <https://gunicorn.org/>`_ or `uWSGI
<https://uwsgi-docs.readthedocs.io/en/latest/>`_ (or similar), multiple worker
processes are created to handle client requests. In such environments, avoid creating
file-based handlers directly in your web application. Instead, use a
:class:`SocketHandler` to log from the web application to a listener in a separate
process. This can be set up using a process management tool such as Supervisor - see
`Running a logging socket listener in production`_ for more details.
Using file rotation
-------------------

5
Doc/includes/sqlite3/complete_statement.py
View file

@ -24,7 +24,10 @@ while True:
if buffer.lstrip().upper().startswith("SELECT"):
print(cur.fetchall())
except sqlite3.Error as e:
print("An error occurred:", e.args[0])
err_msg = str(e)
err_code = e.sqlite_errorcode
err_name = e.sqlite_errorname
print(f"{err_name} ({err_code}): {err_msg}")
buffer = ""
con.close()

4
Doc/includes/sqlite3/text_factory.py
View file

@ -3,9 +3,9 @@ import sqlite3
con = sqlite3.connect(":memory:")
cur = con.cursor()
AUSTRIA = "\xd6sterreich"
AUSTRIA = "Österreich"
# by default, rows are returned as Unicode
# by default, rows are returned as str
cur.execute("select ?", (AUSTRIA,))
row = cur.fetchone()
assert row[0] == AUSTRIA

8
Doc/install/index.rst
View file

@ -206,7 +206,7 @@ directory.
If you don't choose an installation directory---i.e., if you just run ``setup.py
install``\ ---then the :command:`install` command installs to the standard
location for third-party Python modules. This location varies by platform and
by how you built/installed Python itself. On Unix (and Mac OS X, which is also
by how you built/installed Python itself. On Unix (and macOS, which is also
Unix-based), it also depends on whether the module distribution being installed
is pure Python or contains extensions ("non-pure"):
@ -236,7 +236,7 @@ Notes:
:file:`{prefix}` and :file:`{exec-prefix}` stand for the directories that Python
is installed to, and where it finds its libraries at run-time. They are always
the same under Windows, and very often the same under Unix and Mac OS X. You
the same under Windows, and very often the same under Unix and macOS. You
can find out what your Python installation uses for :file:`{prefix}` and
:file:`{exec-prefix}` by running Python in interactive mode and typing a few
simple commands. Under Unix, just type ``python`` at the shell prompt. Under
@ -312,7 +312,7 @@ install into it. It is enabled with a simple option::
Files will be installed into subdirectories of :data:`site.USER_BASE` (written
as :file:`{userbase}` hereafter). This scheme installs pure Python modules and
extension modules in the same location (also known as :data:`site.USER_SITE`).
Here are the values for UNIX, including Mac OS X:
Here are the values for UNIX, including macOS:
=============== ===========================================================
Type of file Installation directory
@ -735,7 +735,7 @@ Location and names of config files
----------------------------------
The names and locations of the configuration files vary slightly across
platforms. On Unix and Mac OS X, the three configuration files (in the order
platforms. On Unix and macOS, the three configuration files (in the order
they are processed) are:
+--------------+----------------------------------------------------------+-------+

12
Doc/installing/index.rst
View file

@ -44,7 +44,7 @@ Key terms
``venv``. It allows virtual environments to be used on versions of
Python prior to 3.4, which either don't provide ``venv`` at all, or
aren't able to automatically install ``pip`` into created environments.
* The `Python Packaging Index <https://pypi.org>`__ is a public
* The `Python Package Index <https://pypi.org>`__ is a public
repository of open source licensed packages made available for use by
other Python users.
* the `Python Packaging Authority
@ -78,13 +78,13 @@ The standard packaging tools are all designed to be used from the command
line.
The following command will install the latest version of a module and its
dependencies from the Python Packaging Index::
dependencies from the Python Package Index::
python -m pip install SomePackage
.. note::
For POSIX users (including Mac OS X and Linux users), the examples in
For POSIX users (including macOS and Linux users), the examples in
this guide assume the use of a :term:`virtual environment`.
For Windows users, the examples in this guide assume that the option to
@ -163,7 +163,7 @@ rather than attempting to install them with ``pip``.
... work with multiple versions of Python installed in parallel?
----------------------------------------------------------------
On Linux, Mac OS X, and other POSIX systems, use the versioned Python commands
On Linux, macOS, and other POSIX systems, use the versioned Python commands
in combination with the ``-m`` switch to run the appropriate copy of
``pip``::
@ -225,8 +225,8 @@ users being expected to compile extension modules from source as part of
the installation process.
With the introduction of support for the binary ``wheel`` format, and the
ability to publish wheels for at least Windows and Mac OS X through the
Python Packaging Index, this problem is expected to diminish over time,
ability to publish wheels for at least Windows and macOS through the
Python Package Index, this problem is expected to diminish over time,
as users are more regularly able to install pre-built extensions rather
than needing to build them themselves.

23
Doc/library/2to3.rst
View file

@ -11,6 +11,11 @@ contains a rich set of fixers that will handle almost all code. 2to3 supporting
library :mod:`lib2to3` is, however, a flexible and generic library, so it is
possible to write your own fixers for 2to3.
.. deprecated-removed:: 3.11 3.13
The ``lib2to3`` module was marked pending for deprecation in Python 3.9
(raising :exc:`PendingDeprecationWarning` on import) and fully deprecated
in Python 3.11 (raising :exc:`DeprecationWarning`). The ``2to3`` tool is
part of that. It will be removed in Python 3.13.
.. _2to3-using:
@ -333,7 +338,8 @@ and off individually. They are described here in more detail.
.. 2to3fixer:: nonzero
Renames :meth:`__nonzero__` to :meth:`~object.__bool__`.
Renames definitions of methods called :meth:`__nonzero__`
to :meth:`~object.__bool__`.
.. 2to3fixer:: numliterals
@ -464,12 +470,15 @@ and off individually. They are described here in more detail.
--------------
.. deprecated:: 3.10
Python 3.9 will switch to a PEG parser (see :pep:`617`), and Python 3.10 may
include new language syntax that is not parsable by lib2to3's LL(1) parser.
The ``lib2to3`` module may be removed from the standard library in a future
Python version. Consider third-party alternatives such as `LibCST`_ or
`parso`_.
.. deprecated-removed:: 3.11 3.13
Python 3.9 switched to a PEG parser (see :pep:`617`) while lib2to3 is
using a less flexible LL(1) parser. Python 3.10 includes new language
syntax that is not parsable by lib2to3's LL(1) parser (see :pep:`634`).
The ``lib2to3`` module was marked pending for deprecation in Python 3.9
(raising :exc:`PendingDeprecationWarning` on import) and fully deprecated
in Python 3.11 (raising :exc:`DeprecationWarning`).
It will be removed from the standard library in Python 3.13.
Consider third-party alternatives such as `LibCST`_ or `parso`_.
.. note::

377
Doc/library/__main__.rst
View file

@ -1,25 +1,368 @@
:mod:`__main__` --- Top-level script environment
================================================
:mod:`__main__` --- Top-level code environment
==============================================
.. module:: __main__
:synopsis: The environment where the top-level script is run.
:synopsis: The environment where top-level code is run. Covers command-line
interfaces, import-time behavior, and ``__name__ == '__main__'``.
--------------
``'__main__'`` is the name of the scope in which top-level code executes.
A module's __name__ is set equal to ``'__main__'`` when read from
standard input, a script, or from an interactive prompt.
In Python, the special name ``__main__`` is used for two important constructs:
A module can discover whether or not it is running in the main scope by
checking its own ``__name__``, which allows a common idiom for conditionally
executing code in a module when it is run as a script or with ``python
-m`` but not when it is imported::
1. the name of the top-level environment of the program, which can be
checked using the ``__name__ == '__main__'`` expression; and
2. the ``__main__.py`` file in Python packages.
if __name__ == "__main__":
# execute only if run as a script
main()
Both of these mechanisms are related to Python modules; how users interact with
them and how they interact with each other. They are explained in detail
below. If you're new to Python modules, see the tutorial section
:ref:`tut-modules` for an introduction.
For a package, the same effect can be achieved by including a
``__main__.py`` module, the contents of which will be executed when the
module is run with ``-m``.
.. _name_equals_main:
``__name__ == '__main__'``
---------------------------
When a Python module or package is imported, ``__name__`` is set to the
module's name. Usually, this is the name of the Python file itself without the
``.py`` extension::
>>> import configparser
>>> configparser.__name__
'configparser'
If the file is part of a package, ``__name__`` will also include the parent
package's path::
>>> from concurrent.futures import process
>>> process.__name__
'concurrent.futures.process'
However, if the module is executed in the top-level code environment,
its ``__name__`` is set to the string ``'__main__'``.
What is the "top-level code environment"?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
``__main__`` is the name of the environment where top-level code is run.
"Top-level code" is the first user-specified Python module that starts running.
It's "top-level" because it imports all other modules that the program needs.
Sometimes "top-level code" is called an *entry point* to the application.
The top-level code environment can be:
* the scope of an interactive prompt::
>>> __name__
'__main__'
* the Python module passed to the Python interpreter as a file argument:
.. code-block:: shell-session
$ python3 helloworld.py
Hello, world!
* the Python module or package passed to the Python interpreter with the
:option:`-m` argument:
.. code-block:: shell-session
$ python3 -m tarfile
usage: tarfile.py [-h] [-v] (...)
* Python code read by the Python interpreter from standard input:
.. code-block:: shell-session
$ echo "import this" | python3
The Zen of Python, by Tim Peters
Beautiful is better than ugly.
Explicit is better than implicit.
...
* Python code passed to the Python interpreter with the :option:`-c` argument:
.. code-block:: shell-session
$ python3 -c "import this"
The Zen of Python, by Tim Peters
Beautiful is better than ugly.
Explicit is better than implicit.
...
In each of these situations, the top-level module's ``__name__`` is set to
``'__main__'``.
As a result, a module can discover whether or not it is running in the
top-level environment by checking its own ``__name__``, which allows a common
idiom for conditionally executing code when the module is not initialized from
an import statement::
if __name__ == '__main__':
# Execute when the module is not initialized from an import statement.
...
.. seealso::
For a more detailed look at how ``__name__`` is set in all situations, see
the tutorial section :ref:`tut-modules`.
Idiomatic Usage
^^^^^^^^^^^^^^^
Some modules contain code that is intended for script use only, like parsing
command-line arguments or fetching data from standard input. If a module
like this was imported from a different module, for example to unit test
it, the script code would unintentionally execute as well.
This is where using the ``if __name__ == '__main__'`` code block comes in
handy. Code within this block won't run unless the module is executed in the
top-level environment.
Putting as few statements as possible in the block below ``if __name___ ==
'__main__'`` can improve code clarity and correctness. Most often, a function
named ``main`` encapsulates the program's primary behavior::
# echo.py
import shlex
import sys
def echo(phrase: str) -> None:
"""A dummy wrapper around print."""
# for demonstration purposes, you can imagine that there is some
# valuable and reusable logic inside this function
print(phrase)
def main() -> int:
"""Echo the input arguments to standard output"""
phrase = shlex.join(sys.argv)
echo(phrase)
return 0
if __name__ == '__main__':
sys.exit(main()) # next section explains the use of sys.exit
Note that if the module didn't encapsulate code inside the ``main`` function
but instead put it directly within the ``if __name__ == '__main__'`` block,
the ``phrase`` variable would be global to the entire module. This is
error-prone as other functions within the module could be unintentionally using
the global variable instead of a local name. A ``main`` function solves this
problem.
Using a ``main`` function has the added benefit of the ``echo`` function itself
being isolated and importable elsewhere. When ``echo.py`` is imported, the
``echo`` and ``main`` functions will be defined, but neither of them will be
called, because ``__name__ != '__main__'``.
Packaging Considerations
^^^^^^^^^^^^^^^^^^^^^^^^
``main`` functions are often used to create command-line tools by specifying
them as entry points for console scripts. When this is done,
`pip <https://pip.pypa.io/>`_ inserts the function call into a template script,
where the return value of ``main`` is passed into :func:`sys.exit`.
For example::
sys.exit(main())
Since the call to ``main`` is wrapped in :func:`sys.exit`, the expectation is
that your function will return some value acceptable as an input to
:func:`sys.exit`; typically, an integer or ``None`` (which is implicitly
returned if your function does not have a return statement).
By proactively following this convention ourselves, our module will have the
same behavior when run directly (i.e. ``python3 echo.py``) as it will have if
we later package it as a console script entry-point in a pip-installable
package.
In particular, be careful about returning strings from your ``main`` function.
:func:`sys.exit` will interpret a string argument as a failure message, so
your program will have an exit code of ``1``, indicating failure, and the
string will be written to :data:`sys.stderr`. The ``echo.py`` example from
earlier exemplifies using the ``sys.exit(main())`` convention.
.. seealso::
`Python Packaging User Guide <https://packaging.python.org/>`_
contains a collection of tutorials and references on how to distribute and
install Python packages with modern tools.
``__main__.py`` in Python Packages
----------------------------------
If you are not familiar with Python packages, see section :ref:`tut-packages`
of the tutorial. Most commonly, the ``__main__.py`` file is used to provide
a command-line interface for a package. Consider the following hypothetical
package, "bandclass":
.. code-block:: text
bandclass
├── __init__.py
├── __main__.py
└── student.py
``__main__.py`` will be executed when the package itself is invoked
directly from the command line using the :option:`-m` flag. For example:
.. code-block:: shell-session
$ python3 -m bandclass
This command will cause ``__main__.py`` to run. How you utilize this mechanism
will depend on the nature of the package you are writing, but in this
hypothetical case, it might make sense to allow the teacher to search for
students::
# bandclass/__main__.py
import sys
from .student import search_students
student_name = sys.argv[2] if len(sys.argv) >= 2 else ''
print(f'Found student: {search_students(student_name)}')
Note that ``from .student import search_students`` is an example of a relative
import. This import style can be used when referencing modules within a
package. For more details, see :ref:`intra-package-references` in the
:ref:`tut-modules` section of the tutorial.
Idiomatic Usage
^^^^^^^^^^^^^^^
The contents of ``__main__.py`` typically isn't fenced with
``if __name__ == '__main__'`` blocks. Instead, those files are kept short,
functions to execute from other modules. Those other modules can then be
easily unit-tested and are properly reusable.
If used, an ``if __name__ == '__main__'`` block will still work as expected
for a ``__main__.py`` file within a package, because its ``__name__``
attribute will include the package's path if imported::
>>> import asyncio.__main__
>>> asyncio.__main__.__name__
'asyncio.__main__'
This won't work for ``__main__.py`` files in the root directory of a .zip file
though. Hence, for consistency, minimal ``__main__.py`` like the :mod:`venv`
one mentioned above are preferred.
.. seealso::
See :mod:`venv` for an example of a package with a minimal ``__main__.py``
in the standard library. It doesn't contain a ``if __name__ == '__main__'``
block. You can invoke it with ``python3 -m venv [directory]``.
See :mod:`runpy` for more details on the :option:`-m` flag to the
interpreter executable.
See :mod:`zipapp` for how to run applications packaged as *.zip* files. In
this case Python looks for a ``__main__.py`` file in the root directory of
the archive.
``import __main__``
-------------------
Regardless of which module a Python program was started with, other modules
running within that same program can import the top-level environment's scope
(:term:`namespace`) by importing the ``__main__`` module. This doesn't import
a ``__main__.py`` file but rather whichever module that received the special
name ``'__main__'``.
Here is an example module that consumes the ``__main__`` namespace::
# namely.py
import __main__
def did_user_define_their_name():
return 'my_name' in dir(__main__)
def print_user_name():
if not did_user_define_their_name():
raise ValueError('Define the variable `my_name`!')
if '__file__' in dir(__main__):
print(__main__.my_name, "found in file", __main__.__file__)
else:
print(__main__.my_name)
Example usage of this module could be as follows::
# start.py
import sys
from namely import print_user_name
# my_name = "Dinsdale"
def main():
try:
print_user_name()
except ValueError as ve:
return str(ve)
if __name__ == "__main__":
sys.exit(main())
Now, if we started our program, the result would look like this:
.. code-block:: shell-session
$ python3 start.py
Define the variable `my_name`!
The exit code of the program would be 1, indicating an error. Uncommenting the
line with ``my_name = "Dinsdale"`` fixes the program and now it exits with
status code 0, indicating success:
.. code-block:: shell-session
$ python3 start.py
Dinsdale found in file /path/to/start.py
Note that importing ``__main__`` doesn't cause any issues with unintentionally
running top-level code meant for script use which is put in the
``if __name__ == "__main__"`` block of the ``start`` module. Why does this work?
Python inserts an empty ``__main__`` module in :attr:`sys.modules` at
interpreter startup, and populates it by running top-level code. In our example
this is the ``start`` module which runs line by line and imports ``namely``.
In turn, ``namely`` imports ``__main__`` (which is really ``start``). That's an
import cycle! Fortunately, since the partially populated ``__main__``
module is present in :attr:`sys.modules`, Python passes that to ``namely``.
See :ref:`Special considerations for __main__ <import-dunder-main>` in the
import system's reference for details on how this works.
The Python REPL is another example of a "top-level environment", so anything
defined in the REPL becomes part of the ``__main__`` scope::
>>> import namely
>>> namely.did_user_define_their_name()
False
>>> namely.print_user_name()
Traceback (most recent call last):
...
ValueError: Define the variable `my_name`!
>>> my_name = 'Jabberwocky'
>>> namely.did_user_define_their_name()
True
>>> namely.print_user_name()
Jabberwocky
Note that in this case the ``__main__`` scope doesn't contain a ``__file__``
attribute as it's interactive.
The ``__main__`` scope is used in the implementation of :mod:`pdb` and
:mod:`rlcompleter`.

2
Doc/library/argparse.rst
View file

@ -1109,7 +1109,7 @@ Anything with more interesting error-handling or resource management should be
done downstream after the arguments are parsed.
For example, JSON or YAML conversions have complex error cases that require
better reporting than can be given by the ``type`` keyword. An
better reporting than can be given by the ``type`` keyword. A
:exc:`~json.JSONDecodeError` would not be well formatted and a
:exc:`FileNotFound` exception would not be handled at all.

15
Doc/library/ast.rst
View file

@ -1266,7 +1266,7 @@ Pattern matching
the pattern matches the subject.
``body`` contains a list of nodes to execute if the pattern matches and
the result of evaluating the guard expression is truthy.
the result of evaluating the guard expression is true.
.. doctest::
@ -1917,6 +1917,19 @@ and classes for traversing abstract syntax trees:
``await`` as variable names. The lowest supported version is
``(3, 4)``; the highest is ``sys.version_info[0:2]``.
If source contains a null character ('\0'), :exc:`ValueError` is raised.
.. warning::
Note that successfully parsing source code into an AST object doesn't
guarantee that the source code provided is valid Python code that can
be executed as the compilation step can raise further :exc:`SyntaxError`
exceptions. For instance, the source ``return 42`` generates a valid
AST node for a return statement, but it cannot be compiled alone (it needs
to be inside a function node).
In particular, :func:`ast.parse` won't do any scoping checks, which the
compilation step does.
.. warning::
It is possible to crash the Python interpreter with a
sufficiently large/complex string due to stack depth limitations

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

@ -57,7 +57,7 @@ When the debug mode is enabled:
* The execution time of the I/O selector is logged if it takes too long to
perform an I/O operation.
* Callbacks taking longer than 100ms are logged. The
* Callbacks taking longer than 100 milliseconds are logged. The
:attr:`loop.slow_callback_duration` attribute can be used to set the
minimum execution duration in seconds that is considered "slow".

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

@ -216,6 +216,10 @@ Scheduling callbacks
A thread-safe variant of :meth:`call_soon`. Must be used to
schedule callbacks *from another thread*.
Raises :exc:`RuntimeError` if called on a loop that's been closed.
This can happen on a secondary thread when the main application is
shutting down.
See the :ref:`concurrency and multithreading <asyncio-multithreading>`
section of the documentation.
@ -489,24 +493,9 @@ Opening network connections
.. coroutinemethod:: loop.create_datagram_endpoint(protocol_factory, \
local_addr=None, remote_addr=None, *, \
family=0, proto=0, flags=0, \
reuse_address=None, reuse_port=None, \
reuse_port=None, \
allow_broadcast=None, sock=None)
.. note::
The parameter *reuse_address* is no longer supported, as using
:py:data:`~sockets.SO_REUSEADDR` poses a significant security concern for
UDP. Explicitly passing ``reuse_address=True`` will raise an exception.
When multiple processes with differing UIDs assign sockets to an
identical UDP socket address with ``SO_REUSEADDR``, incoming packets can
become randomly distributed among the sockets.
For supported platforms, *reuse_port* can be used as a replacement for
similar functionality. With *reuse_port*,
:py:data:`~sockets.SO_REUSEPORT` is used instead, which specifically
prevents processes with differing UIDs from assigning sockets to the same
socket address.
Create a datagram connection.
The socket family can be either :py:data:`~socket.AF_INET`,
@ -553,16 +542,31 @@ Opening network connections
:ref:`UDP echo server protocol <asyncio-udp-echo-server-protocol>` examples.
.. versionchanged:: 3.4.4
The *family*, *proto*, *flags*, *reuse_address*, *reuse_port,
The *family*, *proto*, *flags*, *reuse_address*, *reuse_port*,
*allow_broadcast*, and *sock* parameters were added.
.. versionchanged:: 3.8.1
The *reuse_address* parameter is no longer supported due to security
concerns.
The *reuse_address* parameter is no longer supported, as using
:py:data:`~sockets.SO_REUSEADDR` poses a significant security concern for
UDP. Explicitly passing ``reuse_address=True`` will raise an exception.
When multiple processes with differing UIDs assign sockets to an
identical UDP socket address with ``SO_REUSEADDR``, incoming packets can
become randomly distributed among the sockets.
For supported platforms, *reuse_port* can be used as a replacement for
similar functionality. With *reuse_port*,
:py:data:`~sockets.SO_REUSEPORT` is used instead, which specifically
prevents processes with differing UIDs from assigning sockets to the same
socket address.
.. versionchanged:: 3.8
Added support for Windows.
.. versionchanged:: 3.11
The *reuse_address* parameter, disabled since Python 3.9.0, 3.8.1,
3.7.6 and 3.6.10, has been entirely removed.
.. coroutinemethod:: loop.create_unix_connection(protocol_factory, \
path=None, *, ssl=None, sock=None, \
server_hostname=None, ssl_handshake_timeout=None)
@ -627,6 +631,11 @@ Creating network servers
assumed and a list of multiple sockets will be returned (most likely
one for IPv4 and another one for IPv6).
* The *port* parameter can be set to specify which port the server should
listen on. If ``0`` or ``None`` (the default), a random unused port will
be selected (note that if *host* resolves to multiple network interfaces,
a different random port will be selected for each interface).
* *family* can be set to either :data:`socket.AF_INET` or
:data:`~socket.AF_INET6` to force the socket to use IPv4 or IPv6.
If not set, the *family* will be determined from host name
@ -1234,9 +1243,10 @@ async/await code consider using the high-level
.. note::
The default asyncio event loop on **Windows** does not support
subprocesses. See :ref:`Subprocess Support on Windows
<asyncio-windows-subprocess>` for details.
On Windows, the default event loop :class:`ProactorEventLoop` supports
subprocesses, whereas :class:`SelectorEventLoop` does not. See
:ref:`Subprocess Support on Windows <asyncio-windows-subprocess>` for
details.
.. coroutinemethod:: loop.subprocess_exec(protocol_factory, *args, \
stdin=subprocess.PIPE, stdout=subprocess.PIPE, \

3
Doc/library/asyncio-future.rst
View file

@ -54,6 +54,9 @@ Future Functions
See also the :func:`create_task` function which is the
preferred way for creating new Tasks.
Save a reference to the result of this function, to avoid
a task disappearing mid execution.
.. versionchanged:: 3.5.1
The function accepts any :term:`awaitable` object.

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

@ -63,7 +63,7 @@ All event loops on Windows do not support the following methods:
methods are not supported.
The resolution of the monotonic clock on Windows is usually around 15.6
msec. The best resolution is 0.5 msec. The resolution depends on the
milliseconds. The best resolution is 0.5 milliseconds. The resolution depends on the
hardware (availability of `HPET
<https://en.wikipedia.org/wiki/High_Precision_Event_Timer>`_) and on the
Windows configuration.

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

@ -352,6 +352,7 @@ TCP echo client using the :func:`asyncio.open_connection` function::
print(f'Send: {message!r}')
writer.write(message.encode())
await writer.drain()
data = await reader.read(100)
print(f'Received: {data.decode()!r}')
@ -395,8 +396,8 @@ TCP echo server using the :func:`asyncio.start_server` function::
server = await asyncio.start_server(
handle_echo, '127.0.0.1', 8888)
addr = server.sockets[0].getsockname()
print(f'Serving on {addr}')
addrs = ', '.join(str(sock.getsockname()) for sock in server.sockets)
print(f'Serving on {addrs}')
async with server:
await server.serve_forever()

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

@ -271,6 +271,11 @@ Creating Tasks
task = asyncio.ensure_future(coro())
...
.. important::
Save a reference to the result of this function, to avoid
a task disappearing mid execution.
.. versionadded:: 3.7
.. versionchanged:: 3.8
@ -294,12 +299,6 @@ Sleeping
tasks to run. This can be used by long-running functions to avoid
blocking the event loop for the full duration of the function call.
.. deprecated-removed:: 3.8 3.10
The ``loop`` parameter. This function has been implicitly getting the
current running loop since 3.7. See
:ref:`What's New in 3.10's Removed section <whatsnew310-removed>`
for more information.
.. _asyncio_example_sleep:
Example of coroutine displaying the current date every second

4
Doc/library/base64.rst
View file

@ -78,6 +78,8 @@ The modern interface provides:
these non-alphabet characters in the input result in a
:exc:`binascii.Error`.
For more information about the strict base64 check, see :func:`binascii.a2b_base64`
.. function:: standard_b64encode(s)
@ -152,7 +154,7 @@ The modern interface provides:
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.
interchangeable.
.. versionadded:: 3.10

47
Doc/library/binascii.rst
View file

@ -8,14 +8,13 @@
.. index::
module: uu
module: base64
module: binhex
--------------
The :mod:`binascii` module contains a number of methods to convert between
binary and various ASCII-encoded binary representations. Normally, you will not
use these functions directly but use wrapper modules like :mod:`uu`,
:mod:`base64`, or :mod:`binhex` instead. The :mod:`binascii` module contains
use these functions directly but use wrapper modules like :mod:`uu` or
:mod:`base64` instead. The :mod:`binascii` module contains
low-level functions written in C for greater speed that are used by the
higher-level modules.
@ -98,45 +97,6 @@ The :mod:`binascii` module defines the following functions:
stream.
.. function:: a2b_hqx(string)
Convert binhex4 formatted ASCII data to binary, without doing RLE-decompression.
The string should contain a complete number of binary bytes, or (in case of the
last portion of the binhex4 data) have the remaining bits zero.
.. deprecated:: 3.9
.. function:: rledecode_hqx(data)
Perform RLE-decompression on the data, as per the binhex4 standard. The
algorithm uses ``0x90`` after a byte as a repeat indicator, followed by a count.
A count of ``0`` specifies a byte value of ``0x90``. The routine returns the
decompressed data, unless data input data ends in an orphaned repeat indicator,
in which case the :exc:`Incomplete` exception is raised.
.. versionchanged:: 3.2
Accept only bytestring or bytearray objects as input.
.. deprecated:: 3.9
.. function:: rlecode_hqx(data)
Perform binhex4 style RLE-compression on *data* and return the result.
.. deprecated:: 3.9
.. function:: b2a_hqx(data)
Perform hexbin4 binary-to-ASCII translation and return the resulting string. The
argument should already be RLE-coded, and have a length divisible by 3 (except
possibly the last fragment).
.. deprecated:: 3.9
.. function:: crc_hqx(data, value)
Compute a 16-bit CRC value of *data*, starting with *value* as the
@ -222,9 +182,6 @@ The :mod:`binascii` module defines the following functions:
Support for RFC compliant base64-style encoding in base 16, 32, 64,
and 85.
Module :mod:`binhex`
Support for the binhex format used on the Macintosh.
Module :mod:`uu`
Support for UU encoding used on Unix.

59
Doc/library/binhex.rst
View file

@ -1,59 +0,0 @@
:mod:`binhex` --- Encode and decode binhex4 files
=================================================
.. module:: binhex
:synopsis: Encode and decode files in binhex4 format.
**Source code:** :source:`Lib/binhex.py`
.. deprecated:: 3.9
--------------
This module encodes and decodes files in binhex4 format, a format allowing
representation of Macintosh files in ASCII. Only the data fork is handled.
The :mod:`binhex` module defines the following functions:
.. function:: binhex(input, output)
Convert a binary file with filename *input* to binhex file *output*. The
*output* parameter can either be a filename or a file-like object (any object
supporting a :meth:`write` and :meth:`close` method).
.. function:: hexbin(input, output)
Decode a binhex file *input*. *input* may be a filename or a file-like object
supporting :meth:`read` and :meth:`close` methods. The resulting file is written
to a file named *output*, unless the argument is ``None`` in which case the
output filename is read from the binhex file.
The following exception is also defined:
.. exception:: Error
Exception raised when something can't be encoded using the binhex format (for
example, a filename is too long to fit in the filename field), or when input is
not properly encoded binhex data.
.. seealso::
Module :mod:`binascii`
Support module containing ASCII-to-binary and binary-to-ASCII conversions.
.. _binhex-notes:
Notes
-----
There is an alternative, more powerful interface to the coder and decoder, see
the source for details.
If you code or decode textfiles on non-Macintosh platforms they will still use
the old Macintosh newline convention (carriage-return as end of line).

5
Doc/library/calendar.rst
View file

@ -279,16 +279,13 @@ interpreted as prescribed by the ISO 8601 standard. Year 0 is 1 BC, year -1 is
This subclass of :class:`TextCalendar` can be passed a locale name in the
constructor and will return month and weekday names in the specified locale.
If this locale includes an encoding all strings containing month and weekday
names will be returned as unicode.
.. class:: LocaleHTMLCalendar(firstweekday=0, locale=None)
This subclass of :class:`HTMLCalendar` can be passed a locale name in the
constructor and will return month and weekday names in the specified
locale. If this locale includes an encoding all strings containing month and
weekday names will be returned as unicode.
locale.
.. note::

2
Doc/library/cgi.rst
View file

@ -89,7 +89,7 @@ To get at submitted form data, use the :class:`FieldStorage` class. If the form
contains non-ASCII characters, use the *encoding* keyword parameter set to the
value of the encoding defined for the document. It is usually contained in the
META tag in the HEAD section of the HTML document or by the
:mailheader:`Content-Type` header). This reads the form contents from the
:mailheader:`Content-Type` header. This reads the form contents from the
standard input or the environment (depending on the value of various
environment variables set according to the CGI standard). Since it may consume
standard input, it should be instantiated only once.

5
Doc/library/codecs.rst
View file

@ -204,6 +204,9 @@ wider range of codecs when working with binary files:
*buffering* has the same meaning as for the built-in :func:`open` function.
It defaults to -1 which means that the default buffer size will be used.
.. versionchanged:: 3.11
The ``'U'`` mode has been removed.
.. function:: EncodedFile(file, data_encoding, file_encoding=None, errors='strict')
@ -923,7 +926,7 @@ it's a device to determine the storage layout of the encoded bytes, and vanishes
once the byte sequence has been decoded into a string; as a ``ZERO WIDTH
NO-BREAK SPACE`` it's a normal character that will be decoded like any other.
There's another encoding that is able to encoding the full range of Unicode
There's another encoding that is able to encode the full range of Unicode
characters: UTF-8. UTF-8 is an 8-bit encoding, which means there are no issues
with byte order in UTF-8. Each byte in a UTF-8 byte sequence consists of two
parts: marker bits (the most significant bits) and payload bits. The marker bits

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

@ -14,7 +14,7 @@
.. testsetup:: *
from collections import *
from collections.abc import *
import itertools
__name__ = '<doctest>'
@ -24,6 +24,89 @@ This module provides :term:`abstract base classes <abstract base class>` that
can be used to test whether a class provides a particular interface; for
example, whether it is hashable or whether it is a mapping.
An :func:`issubclass` or :func:`isinstance` test for an interface works in one
of three ways.
1) A newly written class can inherit directly from one of the
abstract base classes. The class must supply the required abstract
methods. The remaining mixin methods come from inheritance and can be
overridden if desired. Other methods may be added as needed:
.. testcode::
class C(Sequence): # Direct inheritance
def __init__(self): ... # Extra method not required by the ABC
def __getitem__(self, index): ... # Required abstract method
def __len__(self): ... # Required abstract method
def count(self, value): ... # Optionally override a mixin method
.. doctest::
>>> issubclass(C, Sequence)
True
>>> isinstance(C(), Sequence)
True
2) Existing classes and built-in classes can be registered as "virtual
subclasses" of the ABCs. Those classes should define the full API
including all of the abstract methods and all of the mixin methods.
This lets users rely on :func:`issubclass` or :func:`isinstance` tests
to determine whether the full interface is supported. The exception to
this rule is for methods that are automatically inferred from the rest
of the API:
.. testcode::
class D: # No inheritance
def __init__(self): ... # Extra method not required by the ABC
def __getitem__(self, index): ... # Abstract method
def __len__(self): ... # Abstract method
def count(self, value): ... # Mixin method
def index(self, value): ... # Mixin method
Sequence.register(D) # Register instead of inherit
.. doctest::
>>> issubclass(D, Sequence)
True
>>> isinstance(D(), Sequence)
True
In this example, class :class:`D` does not need to define
``__contains__``, ``__iter__``, and ``__reversed__`` because the
:ref:`in-operator <comparisons>`, the :term:`iteration <iterable>`
logic, and the :func:`reversed` function automatically fall back to
using ``__getitem__`` and ``__len__``.
3) Some simple interfaces are directly recognizable by the presence of
the required methods (unless those methods have been set to
:const:`None`):
.. testcode::
class E:
def __iter__(self): ...
def __next__(next): ...
.. doctest::
>>> issubclass(E, Iterable)
True
>>> isinstance(E(), Iterable)
True
Complex interfaces do not support this last technique because an
interface is more than just the presence of method names. Interfaces
specify semantics and relationships between methods that cannot be
inferred solely from the presence of specific method names. For
example, knowing that a class supplies ``__getitem__``, ``__len__``, and
``__iter__`` is insufficient for distinguishing a :class:`Sequence` from
a :class:`Mapping`.
.. versionadded:: 3.9
These abstract classes now support ``[]``. See :ref:`types-genericalias`
and :pep:`585`.
.. _collections-abstract-base-classes:
@ -34,67 +117,86 @@ The collections module offers the following :term:`ABCs <abstract base class>`:
.. tabularcolumns:: |l|L|L|L|
========================== ====================== ======================= ====================================================
ABC Inherits from Abstract Methods Mixin Methods
========================== ====================== ======================= ====================================================
:class:`Container` ``__contains__``
:class:`Hashable` ``__hash__``
:class:`Iterable` ``__iter__``
:class:`Iterator` :class:`Iterable` ``__next__`` ``__iter__``
:class:`Reversible` :class:`Iterable` ``__reversed__``
:class:`Generator` :class:`Iterator` ``send``, ``throw`` ``close``, ``__iter__``, ``__next__``
:class:`Sized` ``__len__``
:class:`Callable` ``__call__``
:class:`Collection` :class:`Sized`, ``__contains__``,
:class:`Iterable`, ``__iter__``,
:class:`Container` ``__len__``
============================== ====================== ======================= ====================================================
ABC Inherits from Abstract Methods Mixin Methods
============================== ====================== ======================= ====================================================
:class:`Container` [1]_ ``__contains__``
:class:`Hashable` [1]_ ``__hash__``
:class:`Iterable` [1]_ [2]_ ``__iter__``
:class:`Iterator` [1]_ :class:`Iterable` ``__next__`` ``__iter__``
:class:`Reversible` [1]_ :class:`Iterable` ``__reversed__``
:class:`Generator` [1]_ :class:`Iterator` ``send``, ``throw`` ``close``, ``__iter__``, ``__next__``
:class:`Sized` [1]_ ``__len__``
:class:`Callable` [1]_ ``__call__``
:class:`Collection` [1]_ :class:`Sized`, ``__contains__``,
:class:`Iterable`, ``__iter__``,
:class:`Container` ``__len__``
:class:`Sequence` :class:`Reversible`, ``__getitem__``, ``__contains__``, ``__iter__``, ``__reversed__``,
:class:`Collection` ``__len__`` ``index``, and ``count``
:class:`Sequence` :class:`Reversible`, ``__getitem__``, ``__contains__``, ``__iter__``, ``__reversed__``,
:class:`Collection` ``__len__`` ``index``, and ``count``
:class:`MutableSequence` :class:`Sequence` ``__getitem__``, Inherited :class:`Sequence` methods and
``__setitem__``, ``append``, ``reverse``, ``extend``, ``pop``,
``__delitem__``, ``remove``, and ``__iadd__``
``__len__``,
``insert``
:class:`MutableSequence` :class:`Sequence` ``__getitem__``, Inherited :class:`Sequence` methods and
``__setitem__``, ``append``, ``reverse``, ``extend``, ``pop``,
``__delitem__``, ``remove``, and ``__iadd__``
``__len__``,
``insert``
:class:`ByteString` :class:`Sequence` ``__getitem__``, Inherited :class:`Sequence` methods
``__len__``
:class:`ByteString` :class:`Sequence` ``__getitem__``, Inherited :class:`Sequence` methods
``__len__``
:class:`Set` :class:`Collection` ``__contains__``, ``__le__``, ``__lt__``, ``__eq__``, ``__ne__``,
``__iter__``, ``__gt__``, ``__ge__``, ``__and__``, ``__or__``,
``__len__`` ``__sub__``, ``__xor__``, and ``isdisjoint``
:class:`Set` :class:`Collection` ``__contains__``, ``__le__``, ``__lt__``, ``__eq__``, ``__ne__``,
``__iter__``, ``__gt__``, ``__ge__``, ``__and__``, ``__or__``,
``__len__`` ``__sub__``, ``__xor__``, and ``isdisjoint``
:class:`MutableSet` :class:`Set` ``__contains__``, Inherited :class:`Set` methods and
``__iter__``, ``clear``, ``pop``, ``remove``, ``__ior__``,
``__len__``, ``__iand__``, ``__ixor__``, and ``__isub__``
``add``,
``discard``
:class:`MutableSet` :class:`Set` ``__contains__``, Inherited :class:`Set` methods and
``__iter__``, ``clear``, ``pop``, ``remove``, ``__ior__``,
``__len__``, ``__iand__``, ``__ixor__``, and ``__isub__``
``add``,
``discard``
:class:`Mapping` :class:`Collection` ``__getitem__``, ``__contains__``, ``keys``, ``items``, ``values``,
``__iter__``, ``get``, ``__eq__``, and ``__ne__``
``__len__``
:class:`Mapping` :class:`Collection` ``__getitem__``, ``__contains__``, ``keys``, ``items``, ``values``,
``__iter__``, ``get``, ``__eq__``, and ``__ne__``
``__len__``
:class:`MutableMapping` :class:`Mapping` ``__getitem__``, Inherited :class:`Mapping` methods and
``__setitem__``, ``pop``, ``popitem``, ``clear``, ``update``,
``__delitem__``, and ``setdefault``
``__iter__``,
``__len__``
:class:`MutableMapping` :class:`Mapping` ``__getitem__``, Inherited :class:`Mapping` methods and
``__setitem__``, ``pop``, ``popitem``, ``clear``, ``update``,
``__delitem__``, and ``setdefault``
``__iter__``,
``__len__``
:class:`MappingView` :class:`Sized` ``__len__``
:class:`ItemsView` :class:`MappingView`, ``__contains__``,
:class:`Set` ``__iter__``
:class:`KeysView` :class:`MappingView`, ``__contains__``,
:class:`Set` ``__iter__``
:class:`ValuesView` :class:`MappingView`, ``__contains__``, ``__iter__``
:class:`Collection`
:class:`Awaitable` ``__await__``
:class:`Coroutine` :class:`Awaitable` ``send``, ``throw`` ``close``
:class:`AsyncIterable` ``__aiter__``
:class:`AsyncIterator` :class:`AsyncIterable` ``__anext__`` ``__aiter__``
:class:`AsyncGenerator` :class:`AsyncIterator` ``asend``, ``athrow`` ``aclose``, ``__aiter__``, ``__anext__``
========================== ====================== ======================= ====================================================
:class:`MappingView` :class:`Sized` ``__len__``
:class:`ItemsView` :class:`MappingView`, ``__contains__``,
:class:`Set` ``__iter__``
:class:`KeysView` :class:`MappingView`, ``__contains__``,
:class:`Set` ``__iter__``
:class:`ValuesView` :class:`MappingView`, ``__contains__``, ``__iter__``
:class:`Collection`
:class:`Awaitable` [1]_ ``__await__``
:class:`Coroutine` [1]_ :class:`Awaitable` ``send``, ``throw`` ``close``
:class:`AsyncIterable` [1]_ ``__aiter__``
:class:`AsyncIterator` [1]_ :class:`AsyncIterable` ``__anext__`` ``__aiter__``
:class:`AsyncGenerator` [1]_ :class:`AsyncIterator` ``asend``, ``athrow`` ``aclose``, ``__aiter__``, ``__anext__``
============================== ====================== ======================= ====================================================
.. rubric:: Footnotes
.. [1] These ABCs override :meth:`object.__subclasshook__` to support
testing an interface by verifying the required methods are present
and have not been set to :const:`None`. This only works for simple
interfaces. More complex interfaces require registration or direct
subclassing.
.. [2] Checking ``isinstance(obj, Iterable)`` detects classes that are
registered as :class:`Iterable` or that have an :meth:`__iter__`
method, but it does not detect classes that iterate with the
:meth:`__getitem__` method. The only reliable way to determine
whether an object is :term:`iterable` is to call ``iter(obj)``.
Collections Abstract Base Classes -- Detailed Descriptions
----------------------------------------------------------
.. class:: Container
@ -244,8 +346,10 @@ ABC Inherits from Abstract Methods Mixin
.. versionadded:: 3.6
Examples and Recipes
--------------------
These ABCs allow us to ask classes or instances if they provide
ABCs allow us to ask classes or instances if they provide
particular functionality, for example::
size = None

97
Doc/library/collections.rst
View file

@ -343,7 +343,7 @@ All of those tests treat missing elements as having zero counts so that
``Counter(a=1) == Counter(a=1, b=0)`` returns true.
.. versionadded:: 3.10
Rich comparison operations we were added
Rich comparison operations were added.
.. versionchanged:: 3.10
In equality tests, missing elements are treated as having zero counts.
@ -1175,41 +1175,98 @@ variants of :func:`functools.lru_cache`:
.. testcode::
class LRU:
from time import time
def __init__(self, func, maxsize=128):
class TimeBoundedLRU:
"LRU Cache that invalidates and refreshes old entries."
def __init__(self, func, maxsize=128, maxage=30):
self.cache = OrderedDict() # { args : (timestamp, result)}
self.func = func
self.maxsize = maxsize
self.cache = OrderedDict()
self.maxage = maxage
def __call__(self, *args):
if args in self.cache:
value = self.cache[args]
self.cache.move_to_end(args)
return value
value = self.func(*args)
if len(self.cache) >= self.maxsize:
self.cache.popitem(False)
self.cache[args] = value
return value
timestamp, result = self.cache[args]
if time() - timestamp <= self.maxage:
return result
result = self.func(*args)
self.cache[args] = time(), result
if len(self.cache) > self.maxsize:
self.cache.popitem(0)
return result
.. testcode::
class MultiHitLRUCache:
""" LRU cache that defers caching a result until
it has been requested multiple times.
To avoid flushing the LRU cache with one-time requests,
we don't cache until a request has been made more than once.
"""
def __init__(self, func, maxsize=128, maxrequests=4096, cache_after=1):
self.requests = OrderedDict() # { uncached_key : request_count }
self.cache = OrderedDict() # { cached_key : function_result }
self.func = func
self.maxrequests = maxrequests # max number of uncached requests
self.maxsize = maxsize # max number of stored return values
self.cache_after = cache_after
def __call__(self, *args):
if args in self.cache:
self.cache.move_to_end(args)
return self.cache[args]
result = self.func(*args)
self.requests[args] = self.requests.get(args, 0) + 1
if self.requests[args] <= self.cache_after:
self.requests.move_to_end(args)
if len(self.requests) > self.maxrequests:
self.requests.popitem(0)
else:
self.requests.pop(args, None)
self.cache[args] = result
if len(self.cache) > self.maxsize:
self.cache.popitem(0)
return result
.. doctest::
:hide:
>>> def square(x):
... return x ** 2
... return x * x
...
>>> s = LRU(square, maxsize=5)
>>> actual = [(s(x), s(x)) for x in range(20)]
>>> expected = [(x**2, x**2) for x in range(20)]
>>> actual == expected
>>> f = MultiHitLRUCache(square, maxsize=4, maxrequests=6)
>>> list(map(f, range(10))) # First requests, don't cache
[0, 1, 4, 9, 16, 25, 36, 49, 64, 81]
>>> f(4) # Cache the second request
16
>>> f(6) # Cache the second request
36
>>> f(2) # The first request aged out, so don't cache
4
>>> f(6) # Cache hit
36
>>> f(4) # Cache hit and move to front
16
>>> list(f.cache.values())
[36, 16]
>>> set(f.requests).isdisjoint(f.cache)
True
>>> actual = list(s.cache.items())
>>> expected = [((x,), x**2) for x in range(15, 20)]
>>> actual == expected
>>> list(map(f, [9, 8, 7])) # Cache these second requests
[81, 64, 49]
>>> list(map(f, [7, 9])) # Cache hits
[49, 81]
>>> list(f.cache.values())
[16, 64, 49, 81]
>>> set(f.requests).isdisjoint(f.cache)
True
:class:`UserDict` objects
-------------------------

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

@ -231,7 +231,7 @@ that :class:`ProcessPoolExecutor` will not work in the interactive interpreter.
Calling :class:`Executor` or :class:`Future` methods from a callable submitted
to a :class:`ProcessPoolExecutor` will result in deadlock.
.. class:: ProcessPoolExecutor(max_workers=None, mp_context=None, initializer=None, initargs=())
.. class:: ProcessPoolExecutor(max_workers=None, mp_context=None, initializer=None, initargs=(), max_tasks_per_child=None)
An :class:`Executor` subclass that executes calls asynchronously using a pool
of at most *max_workers* processes. If *max_workers* is ``None`` or not
@ -252,6 +252,11 @@ to a :class:`ProcessPoolExecutor` will result in deadlock.
pending jobs will raise a :exc:`~concurrent.futures.process.BrokenProcessPool`,
as well as any attempt to submit more jobs to the pool.
*max_tasks_per_child* is an optional argument that specifies the maximum
number of tasks a single process can execute before it will exit and be
replaced with a fresh worker process. The default *max_tasks_per_child* is
``None`` which means worker processes will live as long as the pool.
.. versionchanged:: 3.3
When one of the worker processes terminates abruptly, a
:exc:`BrokenProcessPool` error is now raised. Previously, behaviour
@ -264,6 +269,10 @@ to a :class:`ProcessPoolExecutor` will result in deadlock.
Added the *initializer* and *initargs* arguments.
.. versionchanged:: 3.11
The *max_tasks_per_child* argument was added to allow users to
control the lifetime of workers in the pool.
.. _processpoolexecutor-example:

28
Doc/library/configparser.rst
View file

@ -261,7 +261,8 @@ A configuration file consists of sections, each led by a ``[section]`` header,
followed by key/value entries separated by a specific string (``=`` or ``:`` by
default [1]_). By default, section names are case sensitive but keys are not
[1]_. Leading and trailing whitespace is removed from keys and values.
Values can be omitted, in which case the key/value delimiter may also be left
Values can be omitted if the parser is configured to allow it [1]_,
in which case the key/value delimiter may also be left
out. Values can also span multiple lines, as long as they are indented deeper
than the first line of the value. Depending on the parser's mode, blank lines
may be treated as parts of multiline values or ignored.
@ -1200,28 +1201,6 @@ ConfigParser Objects
names is stripped before :meth:`optionxform` is called.
.. method:: readfp(fp, filename=None)
.. deprecated:: 3.2
Use :meth:`read_file` instead.
.. versionchanged:: 3.2
:meth:`readfp` now iterates on *fp* instead of calling ``fp.readline()``.
For existing code calling :meth:`readfp` with arguments which don't
support iteration, the following generator may be used as a wrapper
around the file-like object::
def readline_generator(fp):
line = fp.readline()
while line:
yield line
line = fp.readline()
Instead of ``parser.readfp(fp)`` use
``parser.read_file(readline_generator(fp))``.
.. data:: MAX_INTERPOLATION_DEPTH
The maximum depth for recursive interpolation for :meth:`get` when the *raw*
@ -1359,6 +1338,9 @@ Exceptions
The ``filename`` attribute and :meth:`__init__` argument were renamed to
``source`` for consistency.
.. versionchanged:: 3.11
The deprecated ``filename`` attribute was removed.
.. rubric:: Footnotes

23
Doc/library/contextlib.rst
View file

@ -130,7 +130,9 @@ Functions and classes provided:
either as decorators or with :keyword:`async with` statements::
import time
from contextlib import asynccontextmanager
@asynccontextmanager
async def timeit():
now = time.monotonic()
try:
@ -353,6 +355,23 @@ Functions and classes provided:
.. versionadded:: 3.5
.. function:: chdir(path)
Non parallel-safe context manager to change the current working directory.
As this changes a global state, the working directory, it is not suitable
for use in most threaded or async contexts. It is also not suitable for most
non-linear code execution, like generators, where the program execution is
temporarily relinquished -- unless explicitely desired, you should not yield
when this context manager is active.
This is a simple wrapper around :func:`~os.chdir`, it changes the current
working directory upon entering and restores the old one on exit.
This context manager is :ref:`reentrant <reentrant-cms>`.
.. versionadded:: 3.11
.. class:: ContextDecorator()
A base class that enables a context manager to also be used as a decorator.
@ -900,8 +919,8 @@ but may also be used *inside* a :keyword:`!with` statement that is already
using the same context manager.
:class:`threading.RLock` is an example of a reentrant context manager, as are
:func:`suppress` and :func:`redirect_stdout`. Here's a very simple example of
reentrant use::
:func:`suppress`, :func:`redirect_stdout`, and :func:`chdir`. Here's a very
simple example of reentrant use::
>>> from contextlib import redirect_stdout
>>> from io import StringIO

2
Doc/library/contextvars.rst
View file

@ -94,7 +94,7 @@ Context Variables
# var.get() would raise a LookupError.
.. class:: contextvars.Token
.. class:: Token
*Token* objects are returned by the :meth:`ContextVar.set` method.
They can be passed to the :meth:`ContextVar.reset` method to revert

2
Doc/library/copy.rst
View file

@ -60,7 +60,7 @@ The :func:`deepcopy` function avoids these problems by:
components copied.
This module does not copy types like module, method, stack trace, stack frame,
file, socket, window, array, or any similar types. It does "copy" functions and
file, socket, window, or any similar types. It does "copy" functions and
classes (shallow and deeply), by returning the original object unchanged; this
is compatible with the way these are treated by the :mod:`pickle` module.

4
Doc/library/csv.rst
View file

@ -383,6 +383,8 @@ Dialects support the following attributes:
:const:`False`. On reading, the *escapechar* removes any special meaning from
the following character. It defaults to :const:`None`, which disables escaping.
.. versionchanged:: 3.11
An empty *escapechar* is not allowed.
.. attribute:: Dialect.lineterminator
@ -402,6 +404,8 @@ Dialects support the following attributes:
as the *delimiter* or *quotechar*, or which contain new-line characters. It
defaults to ``'"'``.
.. versionchanged:: 3.11
An empty *quotechar* is not allowed.
.. attribute:: Dialect.quoting

29
Doc/library/ctypes.rst
View file

@ -20,7 +20,7 @@ ctypes tutorial
Note: The code samples in this tutorial use :mod:`doctest` to make sure that
they actually work. Since some code samples behave differently under Linux,
Windows, or Mac OS X, they contain doctest directives in comments.
Windows, or macOS, they contain doctest directives in comments.
Note: Some code samples reference the ctypes :class:`c_int` type. On platforms
where ``sizeof(long) == sizeof(int)`` it is an alias to :class:`c_long`.
@ -80,7 +80,7 @@ the library by creating an instance of CDLL by calling the constructor::
<CDLL 'libc.so.6', handle ... at ...>
>>>
.. XXX Add section for Mac OS X.
.. XXX Add section for macOS.
.. _ctypes-accessing-functions-from-loaded-dlls:
@ -330,10 +330,9 @@ property::
10 b'Hi\x00lo\x00\x00\x00\x00\x00'
>>>
The :func:`create_string_buffer` function replaces the :func:`c_buffer` function
(which is still available as an alias), as well as the :func:`c_string` function
from earlier ctypes releases. To create a mutable memory block containing
unicode characters of the C type :c:type:`wchar_t` use the
The :func:`create_string_buffer` function replaces the old :func:`c_buffer`
function (which is still available as an alias). To create a mutable memory
block containing unicode characters of the C type :c:type:`wchar_t`, use the
:func:`create_unicode_buffer` function.
@ -1088,7 +1087,9 @@ size, we show only how this table can be read with :mod:`ctypes`::
>>> class struct_frozen(Structure):
... _fields_ = [("name", c_char_p),
... ("code", POINTER(c_ubyte)),
... ("size", c_int)]
... ("size", c_int),
... ("get_code", POINTER(c_ubyte)), # Function pointer
... ]
...
>>>
@ -1096,7 +1097,7 @@ We have defined the :c:type:`struct _frozen` data type, so we can get the pointe
to the table::
>>> FrozenTable = POINTER(struct_frozen)
>>> table = FrozenTable.in_dll(pythonapi, "PyImport_FrozenModules")
>>> table = FrozenTable.in_dll(pythonapi, "_PyImport_FrozenBootstrap")
>>>
Since ``table`` is a ``pointer`` to the array of ``struct_frozen`` records, we
@ -1112,9 +1113,7 @@ hit the ``NULL`` entry::
...
_frozen_importlib 31764
_frozen_importlib_external 41499
__hello__ 161
__phello__ -161
__phello__.spam 161
zipimport 12345
>>>
The fact that standard Python has a frozen module and a frozen package
@ -1288,7 +1287,7 @@ Here are some examples::
'libbz2.so.1.0'
>>>
On OS X, :func:`find_library` tries several predefined naming schemes and paths
On macOS, :func:`find_library` tries several predefined naming schemes and paths
to locate the library, and returns a full pathname if successful::
>>> from ctypes.util import find_library
@ -1320,7 +1319,7 @@ There are several ways to load shared libraries into the Python process. One
way is to instantiate one of the following classes:
.. class:: CDLL(name, mode=DEFAULT_MODE, handle=None, use_errno=False, use_last_error=False, winmode=0)
.. class:: CDLL(name, mode=DEFAULT_MODE, handle=None, use_errno=False, use_last_error=False, winmode=None)
Instances of this class represent loaded shared libraries. Functions in these
libraries use the standard C calling convention, and are assumed to return
@ -1342,7 +1341,7 @@ way is to instantiate one of the following classes:
-- A tool to find DLL dependents.
.. class:: OleDLL(name, mode=DEFAULT_MODE, handle=None, use_errno=False, use_last_error=False, winmode=0)
.. class:: OleDLL(name, mode=DEFAULT_MODE, handle=None, use_errno=False, use_last_error=False, winmode=None)
Windows only: Instances of this class represent loaded shared libraries,
functions in these libraries use the ``stdcall`` calling convention, and are
@ -1355,7 +1354,7 @@ way is to instantiate one of the following classes:
:exc:`WindowsError` used to be raised.
.. class:: WinDLL(name, mode=DEFAULT_MODE, handle=None, use_errno=False, use_last_error=False, winmode=0)
.. class:: WinDLL(name, mode=DEFAULT_MODE, handle=None, use_errno=False, use_last_error=False, winmode=None)
Windows only: Instances of this class represent loaded shared libraries,
functions in these libraries use the ``stdcall`` calling convention, and are

2
Doc/library/curses.rst
View file

@ -368,7 +368,7 @@ The module :mod:`curses` defines the following functions:
Set the maximum time in milliseconds that can elapse between press and release
events in order for them to be recognized as a click, and return the previous
interval value. The default value is 200 msec, or one fifth of a second.
interval value. The default value is 200 milliseconds, or one fifth of a second.
.. function:: mousemask(mousemask)

143
Doc/library/dataclasses.rst
View file

@ -205,7 +205,7 @@ Module contents
follows a field with a default value. This is true whether this
occurs in a single class, or as a result of class inheritance.
.. function:: field(*, default=MISSING, default_factory=MISSING, init=True, repr=True, hash=None, compare=True, metadata=None, kw_only=MISSING):
.. function:: field(*, default=MISSING, default_factory=MISSING, init=True, repr=True, hash=None, compare=True, metadata=None, kw_only=MISSING)
For common and simple use cases, no other functionality is
required. There are, however, some dataclass features that
@ -221,10 +221,9 @@ Module contents
c.mylist += [1, 2, 3]
As shown above, the :const:`MISSING` value is a sentinel object used to
detect if the ``default`` and ``default_factory`` parameters are
provided. This sentinel is used because ``None`` is a valid value
for ``default``. No code should directly use the :const:`MISSING`
value.
detect if some parameters are provided by the user. This sentinel is
used because ``None`` is a valid value for some parameters with
a distinct meaning. No code should directly use the :const:`MISSING` value.
The parameters to :func:`field` are:
@ -325,7 +324,10 @@ Module contents
Converts the dataclass ``instance`` to a dict (by using the
factory function ``dict_factory``). Each dataclass is converted
to a dict of its fields, as ``name: value`` pairs. dataclasses, dicts,
lists, and tuples are recursed into. For example::
lists, and tuples are recursed into. Other objects are copied with
:func:`copy.deepcopy`.
Example of using :func:`asdict` on nested dataclasses::
@dataclass
class Point:
@ -342,21 +344,32 @@ Module contents
c = C([Point(0, 0), Point(10, 4)])
assert asdict(c) == {'mylist': [{'x': 0, 'y': 0}, {'x': 10, 'y': 4}]}
Raises :exc:`TypeError` if ``instance`` is not a dataclass instance.
To create a shallow copy, the following workaround may be used::
dict((field.name, getattr(instance, field.name)) for field in fields(instance))
:func:`asdict` raises :exc:`TypeError` if ``instance`` is not a dataclass
instance.
.. function:: astuple(instance, *, tuple_factory=tuple)
Converts the dataclass ``instance`` to a tuple (by using the
factory function ``tuple_factory``). Each dataclass is converted
to a tuple of its field values. dataclasses, dicts, lists, and
tuples are recursed into.
tuples are recursed into. Other objects are copied with
:func:`copy.deepcopy`.
Continuing from the previous example::
assert astuple(p) == (10, 20)
assert astuple(c) == ([(0, 0), (10, 4)],)
Raises :exc:`TypeError` if ``instance`` is not a dataclass instance.
To create a shallow copy, the following workaround may be used::
tuple(getattr(instance, field.name) for field in dataclasses.fields(instance))
:func:`astuple` raises :exc:`TypeError` if ``instance`` is not a dataclass
instance.
.. function:: make_dataclass(cls_name, fields, *, bases=(), namespace=None, init=True, repr=True, eq=True, order=False, unsafe_hash=False, frozen=False, match_args=True, kw_only=False, slots=False)
@ -640,74 +653,80 @@ re-ordered :meth:`__init__` parameter list.
Default factory functions
-------------------------
If a :func:`field` specifies a ``default_factory``, it is called with
zero arguments when a default value for the field is needed. For
example, to create a new instance of a list, use::
If a :func:`field` specifies a ``default_factory``, it is called with
zero arguments when a default value for the field is needed. For
example, to create a new instance of a list, use::
mylist: list = field(default_factory=list)
mylist: list = field(default_factory=list)
If a field is excluded from :meth:`__init__` (using ``init=False``)
and the field also specifies ``default_factory``, then the default
factory function will always be called from the generated
:meth:`__init__` function. This happens because there is no other
way to give the field an initial value.
If a field is excluded from :meth:`__init__` (using ``init=False``)
and the field also specifies ``default_factory``, then the default
factory function will always be called from the generated
:meth:`__init__` function. This happens because there is no other
way to give the field an initial value.
Mutable default values
----------------------
Python stores default member variable values in class attributes.
Consider this example, not using dataclasses::
Python stores default member variable values in class attributes.
Consider this example, not using dataclasses::
class C:
x = []
def add(self, element):
self.x.append(element)
class C:
x = []
def add(self, element):
self.x.append(element)
o1 = C()
o2 = C()
o1.add(1)
o2.add(2)
assert o1.x == [1, 2]
assert o1.x is o2.x
o1 = C()
o2 = C()
o1.add(1)
o2.add(2)
assert o1.x == [1, 2]
assert o1.x is o2.x
Note that the two instances of class ``C`` share the same class
variable ``x``, as expected.
Note that the two instances of class ``C`` share the same class
variable ``x``, as expected.
Using dataclasses, *if* this code was valid::
Using dataclasses, *if* this code was valid::
@dataclass
class D:
x: List = []
def add(self, element):
self.x += element
@dataclass
class D:
x: List = []
def add(self, element):
self.x += element
it would generate code similar to::
it would generate code similar to::
class D:
x = []
def __init__(self, x=x):
self.x = x
def add(self, element):
self.x += element
class D:
x = []
def __init__(self, x=x):
self.x = x
def add(self, element):
self.x += element
assert D().x is D().x
assert D().x is D().x
This has the same issue as the original example using class ``C``.
That is, two instances of class ``D`` that do not specify a value
for ``x`` when creating a class instance will share the same copy
of ``x``. Because dataclasses just use normal Python class
creation they also share this behavior. There is no general way
for Data Classes to detect this condition. Instead, the
:func:`dataclass` decorator will raise a :exc:`TypeError` if it
detects a default parameter of type ``list``, ``dict``, or ``set``.
This is a partial solution, but it does protect against many common
errors.
This has the same issue as the original example using class ``C``.
That is, two instances of class ``D`` that do not specify a value
for ``x`` when creating a class instance will share the same copy
of ``x``. Because dataclasses just use normal Python class
creation they also share this behavior. There is no general way
for Data Classes to detect this condition. Instead, the
:func:`dataclass` decorator will raise a :exc:`TypeError` if it
detects an unhashable default parameter. The assumption is that if
a value is unhashable, it is mutable. This is a partial solution,
but it does protect against many common errors.
Using default factory functions is a way to create new instances of
mutable types as default values for fields::
Using default factory functions is a way to create new instances of
mutable types as default values for fields::
@dataclass
class D:
x: list = field(default_factory=list)
@dataclass
class D:
x: list = field(default_factory=list)
assert D().x is not D().x
assert D().x is not D().x
.. versionchanged:: 3.11
Instead of looking for and disallowing objects of type ``list``,
``dict``, or ``set``, unhashable objects are now not allowed as
default values. Unhashability is used to approximate
mutability.

17
Doc/library/datetime.rst
View file

@ -27,6 +27,9 @@ on efficient attribute extraction for output formatting and manipulation.
Module :mod:`time`
Time access and conversions.
Module :mod:`zoneinfo`
Concrete time zones representing the IANA time zone database.
Package `dateutil <https://dateutil.readthedocs.io/en/stable/>`_
Third-party library with expanded time zone and parsing support.
@ -2174,14 +2177,13 @@ only EST (fixed offset -5 hours), or only EDT (fixed offset -4 hours)).
.. seealso::
`dateutil.tz <https://dateutil.readthedocs.io/en/stable/tz.html>`_
:mod:`zoneinfo`
The :mod:`datetime` module has a basic :class:`timezone` class (for
handling arbitrary fixed offsets from UTC) and its :attr:`timezone.utc`
attribute (a UTC timezone instance).
*dateutil.tz* library brings the *IANA timezone database*
(also known as the Olson database) to Python, and its usage is
recommended.
``zoneinfo`` brings the *IANA timezone database* (also known as the Olson
database) to Python, and its usage is recommended.
`IANA timezone database <https://www.iana.org/time-zones>`_
The Time Zone Database (often called tz, tzdata or zoneinfo) contains code
@ -2357,8 +2359,8 @@ requires, and these work on all platforms with a standard C implementation.
| | decimal number. | | \(9) |
+-----------+--------------------------------+------------------------+-------+
| ``%f`` | Microsecond as a decimal | 000000, 000001, ..., | \(5) |
| | number, zero-padded on the | 999999 | |
| | left. | | |
| | number, zero-padded to 6 | 999999 | |
| | digits. | | |
+-----------+--------------------------------+------------------------+-------+
| ``%z`` | UTC offset in the form | (empty), +0000, | \(6) |
| | ``±HHMM[SS[.ffffff]]`` (empty | -0400, +1030, | |
@ -2431,7 +2433,8 @@ incomplete or ambiguous ISO 8601 directives will raise a :exc:`ValueError`.
The full set of format codes supported varies across platforms, because Python
calls the platform C library's :func:`strftime` function, and platform
variations are common. To see the full set of format codes supported on your
platform, consult the :manpage:`strftime(3)` documentation.
platform, consult the :manpage:`strftime(3)` documentation. There are also
differences between platforms in handling of unsupported format specifiers.
.. versionadded:: 3.6
``%G``, ``%u`` and ``%V`` were added.

16
Doc/library/dbm.rst
View file

@ -33,6 +33,8 @@ the Oracle Berkeley DB.
file's format can't be guessed; or a string containing the required module
name, such as ``'dbm.ndbm'`` or ``'dbm.gnu'``.
.. versionchanged:: 3.11
Accepts :term:`path-like object` for filename.
.. function:: open(file, flag='r', mode=0o666)
@ -77,6 +79,9 @@ available, as well as :meth:`get` and :meth:`setdefault`.
Deleting a key from a read-only database raises database module specific error
instead of :exc:`KeyError`.
.. versionchanged:: 3.11
Accepts :term:`path-like object` for file.
Key and values are always stored as bytes. This means that when
strings are used they are implicitly converted to the default encoding before
being stored.
@ -202,6 +207,9 @@ supported.
In addition to the dictionary-like methods, ``gdbm`` objects have the
following methods:
.. versionchanged:: 3.11
Accepts :term:`path-like object` for filename.
.. method:: gdbm.firstkey()
It's possible to loop over every key in the database using this method and the
@ -216,7 +224,7 @@ supported.
contains them all::
k = db.firstkey()
while k != None:
while k is not None:
print(k)
k = db.nextkey(k)
@ -298,6 +306,9 @@ to locate the appropriate header file to simplify building this module.
In addition to the dictionary-like methods, ``ndbm`` objects
provide the following method:
.. versionchanged:: 3.11
Accepts :term:`path-like object` for filename.
.. method:: ndbm.close()
Close the ``ndbm`` database.
@ -379,6 +390,9 @@ The module defines the following:
flags ``'r'`` and ``'w'`` no longer creates a database if it does not
exist.
.. versionchanged:: 3.11
Accepts :term:`path-like object` for filename.
In addition to the methods provided by the
:class:`collections.abc.MutableMapping` class, :class:`dumbdbm` objects
provide the following methods:

209
Doc/library/dis.rst
View file

@ -293,12 +293,13 @@ details of bytecode instructions as :class:`Instruction` instances:
.. data:: argval
resolved arg value (if known), otherwise same as arg
resolved arg value (if any), otherwise ``None``
.. data:: argrepr
human readable description of operation argument
human readable description of operation argument (if any),
otherwise an empty string.
.. data:: offset
@ -405,156 +406,29 @@ result back on the stack.
.. versionadded:: 3.5
**Binary operations**
**Binary and in-place operations**
Binary operations remove the top of the stack (TOS) and the second top-most
stack item (TOS1) from the stack. They perform the operation, and put the
result back on the stack.
.. opcode:: BINARY_POWER
Implements ``TOS = TOS1 ** TOS``.
.. opcode:: BINARY_MULTIPLY
Implements ``TOS = TOS1 * TOS``.
.. opcode:: BINARY_MATRIX_MULTIPLY
Implements ``TOS = TOS1 @ TOS``.
.. versionadded:: 3.5
.. opcode:: BINARY_FLOOR_DIVIDE
Implements ``TOS = TOS1 // TOS``.
.. opcode:: BINARY_TRUE_DIVIDE
Implements ``TOS = TOS1 / TOS``.
.. opcode:: BINARY_MODULO
Implements ``TOS = TOS1 % TOS``.
.. opcode:: BINARY_ADD
Implements ``TOS = TOS1 + TOS``.
.. opcode:: BINARY_SUBTRACT
Implements ``TOS = TOS1 - TOS``.
.. opcode:: BINARY_SUBSCR
Implements ``TOS = TOS1[TOS]``.
.. opcode:: BINARY_LSHIFT
Implements ``TOS = TOS1 << TOS``.
.. opcode:: BINARY_RSHIFT
Implements ``TOS = TOS1 >> TOS``.
.. opcode:: BINARY_AND
Implements ``TOS = TOS1 & TOS``.
.. opcode:: BINARY_XOR
Implements ``TOS = TOS1 ^ TOS``.
.. opcode:: BINARY_OR
Implements ``TOS = TOS1 | TOS``.
**In-place operations**
In-place operations are like binary operations, in that they remove TOS and
TOS1, and push the result back on the stack, but the operation is done in-place
when TOS1 supports it, and the resulting TOS may be (but does not have to be)
the original TOS1.
.. opcode:: INPLACE_POWER
Implements in-place ``TOS = TOS1 ** TOS``.
.. opcode:: BINARY_OP (op)
Implements the binary and in-place operators (depending on the value of
*op*).
.. versionadded:: 3.11
.. opcode:: INPLACE_MULTIPLY
.. opcode:: BINARY_SUBSCR
Implements in-place ``TOS = TOS1 * TOS``.
.. opcode:: INPLACE_MATRIX_MULTIPLY
Implements in-place ``TOS = TOS1 @ TOS``.
.. versionadded:: 3.5
.. opcode:: INPLACE_FLOOR_DIVIDE
Implements in-place ``TOS = TOS1 // TOS``.
.. opcode:: INPLACE_TRUE_DIVIDE
Implements in-place ``TOS = TOS1 / TOS``.
.. opcode:: INPLACE_MODULO
Implements in-place ``TOS = TOS1 % TOS``.
.. opcode:: INPLACE_ADD
Implements in-place ``TOS = TOS1 + TOS``.
.. opcode:: INPLACE_SUBTRACT
Implements in-place ``TOS = TOS1 - TOS``.
.. opcode:: INPLACE_LSHIFT
Implements in-place ``TOS = TOS1 << TOS``.
.. opcode:: INPLACE_RSHIFT
Implements in-place ``TOS = TOS1 >> TOS``.
.. opcode:: INPLACE_AND
Implements in-place ``TOS = TOS1 & TOS``.
.. opcode:: INPLACE_XOR
Implements in-place ``TOS = TOS1 ^ TOS``.
.. opcode:: INPLACE_OR
Implements in-place ``TOS = TOS1 | TOS``.
Implements ``TOS = TOS1[TOS]``.
.. opcode:: STORE_SUBSCR
@ -710,12 +584,14 @@ iterations of the loop.
.. opcode:: WITH_EXCEPT_START
Calls the function in position 7 on the stack with the top three
Calls the function in position 8 on the stack with the top three
items on the stack as arguments.
Used to implement the call ``context_manager.__exit__(*exc_info())`` when an exception
has occurred in a :keyword:`with` statement.
.. versionadded:: 3.9
.. versionchanged:: 3.11
The ``__exit__`` function is in position 8 of the stack rather than 7.
.. opcode:: POP_EXCEPT_AND_RERAISE
@ -724,7 +600,7 @@ iterations of the loop.
of the stack and sets the ``f_lasti`` attribute of the frame with that value.
Then pops the next exception from the stack uses it to restore the current exception.
Finally it re-raises the originally popped exception.
Used in excpetion handler cleanup.
Used in exception handler cleanup.
.. versionadded:: 3.11
@ -754,15 +630,6 @@ iterations of the loop.
.. versionadded:: 3.11
.. opcode:: COPY_DICT_WITHOUT_KEYS
TOS is a tuple of mapping keys, and TOS1 is the match subject. Replace TOS
with a :class:`dict` formed from the items of TOS1, but without any of the
keys in TOS.
.. versionadded:: 3.10
.. opcode:: GET_LEN
Push ``len(TOS)`` onto the stack.
@ -794,11 +661,14 @@ iterations of the loop.
TOS is a tuple of mapping keys, and TOS1 is the match subject. If TOS1
contains all of the keys in TOS, push a :class:`tuple` containing the
corresponding values, followed by ``True``. Otherwise, push ``None``,
followed by ``False``.
corresponding values. Otherwise, push ``None``.
.. versionadded:: 3.10
.. versionchanged:: 3.11
Previously, this instruction also pushed a boolean value indicating
success (``True``) or failure (``False``).
All of the following opcodes use their arguments.
@ -1005,10 +875,13 @@ All of the following opcodes use their arguments.
.. opcode:: JUMP_IF_NOT_EXC_MATCH (target)
Tests whether the second value on the stack is an exception matching TOS,
and jumps if it is not. Pops two values from the stack.
and jumps if it is not. Pops one value from the stack.
.. versionadded:: 3.9
.. versionchanged:: 3.11
This opcode no longer pops the active exception.
.. opcode:: JUMP_IF_TRUE_OR_POP (target)
@ -1120,6 +993,15 @@ All of the following opcodes use their arguments.
``i`` is no longer offset by the length of ``co_varnames``.
.. opcode:: COPY_FREE_VARS (n)
Copies the ``n`` free variables from the closure into the frame.
Removes the need for special code on the caller's side when calling
closures.
.. versionadded:: 3.11
.. opcode:: RAISE_VARARGS (argc)
Raises an exception using one of the 3 forms of the ``raise`` statement,
@ -1276,17 +1158,20 @@ All of the following opcodes use their arguments.
against, and TOS2 is the match subject. *count* is the number of positional
sub-patterns.
Pop TOS. If TOS2 is an instance of TOS1 and has the positional and keyword
attributes required by *count* and TOS, set TOS to ``True`` and TOS1 to a
tuple of extracted attributes. Otherwise, set TOS to ``False``.
Pop TOS, TOS1, and TOS2. If TOS2 is an instance of TOS1 and has the
positional and keyword attributes required by *count* and TOS, push a tuple
of extracted attributes. Otherwise, push ``None``.
.. versionadded:: 3.10
.. versionchanged:: 3.11
Previously, this instruction also pushed a boolean value indicating
success (``True``) or failure (``False``).
.. opcode:: GEN_START (kind)
Pops TOS. If TOS was not ``None``, raises an exception. The ``kind``
operand corresponds to the type of generator or coroutine and determines
the error message. The legal kinds are 0 for generator, 1 for coroutine,
Pops TOS. The ``kind`` operand corresponds to the type of generator or
coroutine. The legal kinds are 0 for generator, 1 for coroutine,
and 2 for async generator.
.. versionadded:: 3.10
@ -1300,6 +1185,14 @@ All of the following opcodes use their arguments.
.. versionadded:: 3.10
.. opcode:: COPY (i)
Push the *i*-th item to the top of the stack. The item is not removed from its
original location.
.. versionadded:: 3.11
.. opcode:: HAVE_ARGUMENT
This is not really an opcode. It identifies the dividing line between

21
Doc/library/doctest.rst
View file

@ -485,25 +485,24 @@ Some details you should read once, but won't need to remember:
.. index:: single: ^ (caret); marker
* For some :exc:`SyntaxError`\ s, Python displays the character position of the
syntax error, using a ``^`` marker::
* For some exceptions, Python displays the position of the error using ``^``
markers and tildes::
>>> 1 1
>>> 1 + None
File "<stdin>", line 1
1 1
^
SyntaxError: invalid syntax
1 + None
~~^~~~~~
TypeError: unsupported operand type(s) for +: 'int' and 'NoneType'
Since the lines showing the position of the error come before the exception type
and detail, they are not checked by doctest. For example, the following test
would pass, even though it puts the ``^`` marker in the wrong location::
>>> 1 1
Traceback (most recent call last):
>>> 1 + None
File "<stdin>", line 1
1 1
^
SyntaxError: invalid syntax
1 + None
^~~~~~~~
TypeError: unsupported operand type(s) for +: 'int' and 'NoneType'
.. _option-flags-and-directives:

10
Doc/library/enum.rst
View file

@ -162,7 +162,8 @@ Data Types
.. method:: EnumType.__dir__(cls)
Returns ``['__class__', '__doc__', '__members__', '__module__']`` and the
names of the members in *cls*::
names of the members in ``cls``. User-defined methods and methods from
mixin classes will also be included::
>>> dir(Color)
['BLUE', 'GREEN', 'RED', '__class__', '__doc__', '__members__', '__module__']
@ -260,7 +261,7 @@ Data Types
.. method:: Enum.__dir__(self)
Returns ``['__class__', '__doc__', '__module__', 'name', 'value']`` and
any public methods defined on *self.__class__*::
any public methods defined on ``self.__class__`` or a mixin class::
>>> from datetime import date
>>> class Weekday(Enum):
@ -397,6 +398,7 @@ Data Types
Using :class:`auto` with :class:`StrEnum` results in values of the member name,
lower-cased.
.. versionadded:: 3.11
.. class:: Flag
@ -651,8 +653,8 @@ Data Types
---------------
Utilites and Decorators
-----------------------
Utilities and Decorators
------------------------
.. class:: auto

35
Doc/library/exceptions.rst
View file

@ -34,6 +34,10 @@ class or one of its subclasses, and not from :exc:`BaseException`. More
information on defining exceptions is available in the Python Tutorial under
:ref:`tut-userexceptions`.
Exception context
-----------------
When raising (or re-raising) an exception in an :keyword:`except` or
:keyword:`finally` clause
:attr:`__context__` is automatically set to the last exception caught; if the
@ -67,6 +71,25 @@ exceptions so that the final line of the traceback always shows the last
exception that was raised.
Inheriting from built-in exceptions
-----------------------------------
User code can create subclasses that inherit from an exception type.
It's recommended to only subclass one exception type at a time to avoid
any possible conflicts between how the bases handle the ``args``
attribute, as well as due to possible memory layout incompatibilities.
.. impl-detail::
Most built-in exceptions are implemented in C for efficiency, see:
:source:`Objects/exceptions.c`. Some have custom memory layouts
which makes it impossible to create a subclass that inherits from
multiple exception types. The memory layout of a type is an implementation
detail and might change between Python versions, leading to new
conflicts in the future. Therefore, it's recommended to avoid
subclassing multiple exception types altogether.
Base classes
------------
@ -104,6 +127,14 @@ The following exceptions are used mostly as base classes for other exceptions.
tb = sys.exc_info()[2]
raise OtherException(...).with_traceback(tb)
.. attribute:: __note__
A mutable field which is :const:`None` by default and can be set to a string.
If it is not :const:`None`, it is included in the traceback. This field can
be used to enrich exceptions after they have been caught.
.. versionadded:: 3.11
.. exception:: Exception
@ -748,6 +779,8 @@ The following exceptions are used as warning categories; see the
(:pep:`565`). Enabling the :ref:`Python Development Mode <devmode>` shows
this warning.
The deprecation policy is described in :pep:`387`.
.. exception:: PendingDeprecationWarning
@ -762,6 +795,8 @@ The following exceptions are used as warning categories; see the
Ignored by the default warning filters. Enabling the :ref:`Python
Development Mode <devmode>` shows this warning.
The deprecation policy is described in :pep:`387`.
.. exception:: SyntaxWarning

5
Doc/library/fcntl.rst
View file

@ -44,6 +44,11 @@ descriptor.
``F_SETPIPE_SZ`` constants, which allow to check and modify a pipe's size
respectively.
.. versionchanged:: 3.11
On FreeBSD, the fcntl module exposes the ``F_DUP2FD`` and ``F_DUP2FD_CLOEXEC``
constants, which allow to duplicate a file descriptor, the latter setting
``FD_CLOEXEC`` flag in addition.
The module defines the following functions:

25
Doc/library/fileinput.rst
View file

@ -50,8 +50,8 @@ You can control how files are opened by providing an opening hook via the
*openhook* parameter to :func:`fileinput.input` or :class:`FileInput()`. The
hook must be a function that takes two arguments, *filename* and *mode*, and
returns an accordingly opened file-like object. If *encoding* and/or *errors*
are specified, they will be passed to the hook as aditional keyword arguments.
This module provides a :func:`hook_encoded` to support compressed files.
are specified, they will be passed to the hook as additional keyword arguments.
This module provides a :func:`hook_compressed` to support compressed files.
The following function is the primary interface of this module:
@ -146,14 +146,13 @@ available for subclassing as well:
Class :class:`FileInput` is the implementation; its methods :meth:`filename`,
:meth:`fileno`, :meth:`lineno`, :meth:`filelineno`, :meth:`isfirstline`,
:meth:`isstdin`, :meth:`nextfile` and :meth:`close` correspond to the
functions of the same name in the module. In addition it has a
:meth:`~io.TextIOBase.readline` method which returns the next input line,
and a :meth:`__getitem__` method which implements the sequence behavior.
The sequence must be accessed in strictly sequential order; random access
and :meth:`~io.TextIOBase.readline` cannot be mixed.
functions of the same name in the module. In addition it is :term:`iterable`
and has a :meth:`~io.TextIOBase.readline` method which returns the next
input line. The sequence must be accessed in strictly sequential order;
random access and :meth:`~io.TextIOBase.readline` cannot be mixed.
With *mode* you can specify which file mode will be passed to :func:`open`. It
must be one of ``'r'``, ``'rU'``, ``'U'`` and ``'rb'``.
must be one of ``'r'`` and ``'rb'``.
The *openhook*, when given, must be a function that takes two arguments,
*filename* and *mode*, and returns an accordingly opened file-like object. You
@ -171,18 +170,16 @@ available for subclassing as well:
.. versionchanged:: 3.2
Can be used as a context manager.
.. deprecated:: 3.4
The ``'rU'`` and ``'U'`` modes.
.. deprecated:: 3.8
Support for :meth:`__getitem__` method is deprecated.
.. versionchanged:: 3.8
The keyword parameter *mode* and *openhook* are now keyword-only.
.. versionchanged:: 3.10
The keyword-only parameter *encoding* and *errors* are added.
.. versionchanged:: 3.11
The ``'rU'`` and ``'U'`` modes and the :meth:`__getitem__` method have
been removed.
**Optional in-place filtering:** if the keyword argument ``inplace=True`` is
passed to :func:`fileinput.input` or to the :class:`FileInput` constructor, the

4
Doc/library/fractions.rst
View file

@ -94,6 +94,10 @@ another rational number, or from a string.
Underscores are now permitted when creating a :class:`Fraction` instance
from a string, following :PEP:`515` rules.
.. versionchanged:: 3.11
:class:`Fraction` implements ``__int__`` now to satisfy
``typing.SupportsInt`` instance checks.
.. attribute:: numerator
Numerator of the Fraction in lowest term.

64
Doc/library/functions.rst
View file

@ -66,9 +66,6 @@ are always available. They are listed here in alphabetical order.
Return an :term:`asynchronous iterator` for an :term:`asynchronous iterable`.
Equivalent to calling ``x.__aiter__()``.
``aiter(x)`` itself has an ``__aiter__()`` method that returns ``x``,
so ``aiter(aiter(x))`` is the same as ``aiter(x)``.
Note: Unlike :func:`iter`, :func:`aiter` has no 2-argument variant.
.. versionadded:: 3.10
@ -557,7 +554,7 @@ are always available. They are listed here in alphabetical order.
a suite of Python statements which is then executed (unless a syntax error
occurs). [#]_ If it is a code object, it is simply executed. In all cases,
the code that's executed is expected to be valid as file input (see the
section "File input" in the Reference Manual). Be aware that the
section :ref:`file-input` in the Reference Manual). Be aware that the
:keyword:`nonlocal`, :keyword:`yield`, and :keyword:`return`
statements may not be used outside of
function definitions even within the context of code passed to the
@ -736,9 +733,9 @@ are always available. They are listed here in alphabetical order.
.. function:: globals()
Return a dictionary representing the current global symbol table. This is always
the dictionary of the current module (inside a function or method, this is the
module where it is defined, not the module from which it is called).
Return the dictionary implementing the current module namespace. For code within
functions, this is set when the function is defined and remains the same
regardless of where the function is called.
.. function:: hasattr(object, name)
@ -916,9 +913,9 @@ are always available. They are listed here in alphabetical order.
Return ``True`` if *class* is a subclass (direct, indirect, or :term:`virtual
<abstract base class>`) of *classinfo*. A
class is considered a subclass of itself. *classinfo* may be a tuple of class
objects or a :ref:`types-union`, in which case every entry in *classinfo*
will be checked. In any other
case, a :exc:`TypeError` exception is raised.
objects or a :ref:`types-union`, in which case return ``True`` if *class* is a
subclass of any entry in *classinfo*. In any other case, a :exc:`TypeError`
exception is raised.
.. versionchanged:: 3.10
*classinfo* can be a :ref:`types-union`.
@ -929,8 +926,8 @@ are always available. They are listed here in alphabetical order.
Return an :term:`iterator` object. The first argument is interpreted very
differently depending on the presence of the second argument. Without a
second argument, *object* must be a collection object which supports the
iteration protocol (the :meth:`__iter__` method), or it must support the
sequence protocol (the :meth:`__getitem__` method with integer arguments
:term:`iterable` protocol (the :meth:`__iter__` method), or it must support
the sequence protocol (the :meth:`__getitem__` method with integer arguments
starting at ``0``). If it does not support either of those protocols,
:exc:`TypeError` is raised. If the second argument, *sentinel*, is given,
then *object* must be a callable object. The iterator created in this case
@ -1060,7 +1057,7 @@ are always available. They are listed here in alphabetical order.
.. function:: next(iterator[, default])
Retrieve the next item from the *iterator* by calling its
Retrieve the next item from the :term:`iterator` by calling its
:meth:`~iterator.__next__` method. If *default* is given, it is returned
if the iterator is exhausted, otherwise :exc:`StopIteration` is raised.
@ -1156,12 +1153,6 @@ are always available. They are listed here in alphabetical order.
first decoded using a platform-dependent encoding or using the specified
*encoding* if given.
There is an additional mode character permitted, ``'U'``, which no longer
has any effect, and is considered deprecated. It previously enabled
:term:`universal newlines` in text mode, which became the default behavior
in Python 3.0. Refer to the documentation of the
:ref:`newline <open-newline-parameter>` parameter for further details.
.. note::
Python doesn't depend on the underlying operating system's notion of text
@ -1304,8 +1295,7 @@ are always available. They are listed here in alphabetical order.
The ``mode`` and ``flags`` arguments may have been modified or inferred from
the original call.
.. versionchanged::
3.3
.. versionchanged:: 3.3
* The *opener* parameter was added.
* The ``'x'`` mode was added.
@ -1313,30 +1303,26 @@ are always available. They are listed here in alphabetical order.
* :exc:`FileExistsError` is now raised if the file opened in exclusive
creation mode (``'x'``) already exists.
.. versionchanged::
3.4
.. versionchanged:: 3.4
* The file is now non-inheritable.
.. deprecated-removed:: 3.4 3.10
The ``'U'`` mode.
.. versionchanged::
3.5
.. versionchanged:: 3.5
* If the system call is interrupted and the signal handler does not raise an
exception, the function now retries the system call instead of raising an
:exc:`InterruptedError` exception (see :pep:`475` for the rationale).
* The ``'namereplace'`` error handler was added.
.. versionchanged::
3.6
.. versionchanged:: 3.6
* Support added to accept objects implementing :class:`os.PathLike`.
* On Windows, opening a console buffer may return a subclass of
:class:`io.RawIOBase` other than :class:`io.FileIO`.
.. versionchanged:: 3.11
The ``'U'`` mode has been removed.
.. function:: ord(c)
Given a string representing one Unicode character, return an integer
@ -1356,8 +1342,11 @@ are always available. They are listed here in alphabetical order.
coercion rules for binary arithmetic operators apply. For :class:`int`
operands, the result has the same type as the operands (after coercion)
unless the second argument is negative; in that case, all arguments are
converted to float and a float result is delivered. For example, ``10**2``
returns ``100``, but ``10**-2`` returns ``0.01``.
converted to float and a float result is delivered. For example, ``pow(10, 2)``
returns ``100``, but ``pow(10, -2)`` returns ``0.01``. For a negative base of
type :class:`int` or :class:`float` and a non-integral exponent, a complex
result is delivered. For example, ``pow(-9, 0.5)`` returns a value close
to ``3j``.
For :class:`int` operands *base* and *exp*, if *mod* is present, *mod* must
also be of integer type and *mod* must be nonzero. If *mod* is present and
@ -1603,6 +1592,15 @@ are always available. They are listed here in alphabetical order.
compare equal --- this is helpful for sorting in multiple passes (for
example, sort by department, then by salary grade).
The sort algorithm uses only ``<`` comparisons between items. While
defining an :meth:`~object.__lt__` method will suffice for sorting,
:PEP:`8` recommends that all six :ref:`rich comparisons
<comparisons>` be implemented. This will help avoid bugs when using
the same data with other ordering tools such as :func:`max` that rely
on a different underlying method. Implementing all six comparisons
also helps avoid confusion for mixed type comparisons which can call
reflected the :meth:`~object.__gt__` method.
For sorting examples and a brief sorting tutorial, see :ref:`sortinghowto`.
.. decorator:: staticmethod

62
Doc/library/functools.rst
View file

@ -160,10 +160,16 @@ The :mod:`functools` module defines the following functions:
grow without bound.
If *typed* is set to true, function arguments of different types will be
cached separately. For example, ``f(3)`` and ``f(3.0)`` will always be
treated as distinct calls with distinct results. If *typed* is false,
the implementation will usually but not always regard them as equivalent
calls and only cache a single result.
cached separately. If *typed* is false, the implementation will usually
regard them as equivalent calls and only cache a single result. (Some
types such as *str* and *int* may be cached separately even when *typed*
is false.)
Note, type specificity applies only to the function's immediate arguments
rather than their contents. The scalar arguments, ``Decimal(42)`` and
``Fraction(42)`` are be treated as distinct calls with distinct results.
In contrast, the tuple arguments ``('answer', Decimal(42))`` and
``('answer', Fraction(42))`` are treated as equivalent.
The wrapped function is instrumented with a :func:`cache_parameters`
function that returns a new :class:`dict` showing the values for *maxsize*
@ -402,8 +408,8 @@ The :mod:`functools` module defines the following functions:
dispatch>` :term:`generic function`.
To define a generic function, decorate it with the ``@singledispatch``
decorator. Note that the dispatch happens on the type of the first argument,
create your function accordingly::
decorator. When defining a function using ``@singledispatch``, note that the
dispatch happens on the type of the first argument::
>>> from functools import singledispatch
>>> @singledispatch
@ -413,9 +419,9 @@ The :mod:`functools` module defines the following functions:
... print(arg)
To add overloaded implementations to the function, use the :func:`register`
attribute of the generic function. It is a decorator. For functions
annotated with types, the decorator will infer the type of the first
argument automatically::
attribute of the generic function, which can be used as a decorator. For
functions annotated with types, the decorator will infer the type of the
first argument automatically::
>>> @fun.register
... def _(arg: int, verbose=False):
@ -441,17 +447,17 @@ The :mod:`functools` module defines the following functions:
...
To enable registering lambdas and pre-existing functions, the
:func:`register` attribute can be used in a functional form::
To enable registering :term:`lambdas<lambda>` and pre-existing functions,
the :func:`register` attribute can also be used in a functional form::
>>> def nothing(arg, verbose=False):
... print("Nothing.")
...
>>> fun.register(type(None), nothing)
The :func:`register` attribute returns the undecorated function which
enables decorator stacking, pickling, as well as creating unit tests for
each variant independently::
The :func:`register` attribute returns the undecorated function. This
enables decorator stacking, :mod:`pickling<pickle>`, and the creation
of unit tests for each variant independently::
>>> @fun.register(float)
... @fun.register(Decimal)
@ -486,11 +492,12 @@ The :mod:`functools` module defines the following functions:
Where there is no registered implementation for a specific type, its
method resolution order is used to find a more generic implementation.
The original function decorated with ``@singledispatch`` is registered
for the base ``object`` type, which means it is used if no better
for the base :class:`object` type, which means it is used if no better
implementation is found.
If an implementation registered to :term:`abstract base class`, virtual
subclasses will be dispatched to that implementation::
If an implementation is registered to an :term:`abstract base class`,
virtual subclasses of the base class will be dispatched to that
implementation::
>>> from collections.abc import Mapping
>>> @fun.register
@ -503,7 +510,7 @@ The :mod:`functools` module defines the following functions:
>>> fun({"a": "b"})
a => b
To check which implementation will the generic function choose for
To check which implementation the generic function will choose for
a given type, use the ``dispatch()`` attribute::
>>> fun.dispatch(float)
@ -526,7 +533,7 @@ The :mod:`functools` module defines the following functions:
.. versionadded:: 3.4
.. versionchanged:: 3.7
The :func:`register` attribute supports using type annotations.
The :func:`register` attribute now supports using type annotations.
.. class:: singledispatchmethod(func)
@ -535,8 +542,9 @@ The :mod:`functools` module defines the following functions:
dispatch>` :term:`generic function`.
To define a generic method, decorate it with the ``@singledispatchmethod``
decorator. Note that the dispatch happens on the type of the first non-self
or non-cls argument, create your function accordingly::
decorator. When defining a function using ``@singledispatchmethod``, note
that the dispatch happens on the type of the first non-*self* or non-*cls*
argument::
class Negator:
@singledispatchmethod
@ -552,9 +560,10 @@ The :mod:`functools` module defines the following functions:
return not arg
``@singledispatchmethod`` supports nesting with other decorators such as
``@classmethod``. Note that to allow for ``dispatcher.register``,
``singledispatchmethod`` must be the *outer most* decorator. Here is the
``Negator`` class with the ``neg`` methods being class bound::
:func:`@classmethod<classmethod>`. Note that to allow for
``dispatcher.register``, ``singledispatchmethod`` must be the *outer most*
decorator. Here is the ``Negator`` class with the ``neg`` methods bound to
the class, rather than an instance of the class::
class Negator:
@singledispatchmethod
@ -572,8 +581,9 @@ The :mod:`functools` module defines the following functions:
def _(cls, arg: bool):
return not arg
The same pattern can be used for other similar decorators: ``staticmethod``,
``abstractmethod``, and others.
The same pattern can be used for other similar decorators:
:func:`@staticmethod<staticmethod>`,
:func:`@abstractmethod<abc.abstractmethod>`, and others.
.. versionadded:: 3.8

17
Doc/library/gzip.rst
View file

@ -174,19 +174,30 @@ The module defines the following items:
Compress the *data*, returning a :class:`bytes` object containing
the compressed data. *compresslevel* and *mtime* have the same meaning as in
the :class:`GzipFile` constructor above.
the :class:`GzipFile` constructor above. When *mtime* is set to ``0``, this
function is equivalent to :func:`zlib.compress` with *wbits* set to ``31``.
The zlib function is faster.
.. versionadded:: 3.2
.. versionchanged:: 3.8
Added the *mtime* parameter for reproducible output.
.. versionchanged:: 3.11
Speed is improved by compressing all data at once instead of in a
streamed fashion. Calls with *mtime* set to ``0`` are delegated to
:func:`zlib.compress` for better speed.
.. function:: decompress(data)
Decompress the *data*, returning a :class:`bytes` object containing the
uncompressed data.
uncompressed data. This function is capable of decompressing multi-member
gzip data (multiple gzip blocks concatenated together). When the data is
certain to contain only one member the :func:`zlib.decompress` function with
*wbits* set to 31 is faster.
.. versionadded:: 3.2
.. versionchanged:: 3.11
Speed is improved by decompressing members at once in memory instead of in
a streamed fashion.
.. _gzip-usage-examples:

6
Doc/library/hashlib.rst
View file

@ -376,10 +376,10 @@ Constructor functions also accept the following tree hashing parameters:
* *depth*: maximal depth of tree (1 to 255, 255 if unlimited, 1 in
sequential mode).
* *leaf_size*: maximal byte length of leaf (0 to 2**32-1, 0 if unlimited or in
* *leaf_size*: maximal byte length of leaf (0 to ``2**32-1``, 0 if unlimited or in
sequential mode).
* *node_offset*: node offset (0 to 2**64-1 for BLAKE2b, 0 to 2**48-1 for
* *node_offset*: node offset (0 to ``2**64-1`` for BLAKE2b, 0 to ``2**48-1`` for
BLAKE2s, 0 for the first, leftmost, leaf, or in sequential mode).
* *node_depth*: node depth (0 to 255, 0 for leaves, or in sequential mode).
@ -500,7 +500,7 @@ Keyed hashing
Keyed hashing can be used for authentication as a faster and simpler
replacement for `Hash-based message authentication code
<https://en.wikipedia.org/wiki/Hash-based_message_authentication_code>`_ (HMAC).
<https://en.wikipedia.org/wiki/HMAC>`_ (HMAC).
BLAKE2 can be securely used in prefix-MAC mode thanks to the
indifferentiability property inherited from BLAKE.

2
Doc/library/html.entities.rst
View file

@ -44,4 +44,4 @@ This module defines four dictionaries, :data:`html5`,
.. rubric:: Footnotes
.. [#] See https://www.w3.org/TR/html5/syntax.html#named-character-references
.. [#] See https://html.spec.whatwg.org/multipage/syntax.html#named-character-references

8
Doc/library/http.cookiejar.rst
View file

@ -122,7 +122,7 @@ The following classes are provided:
:mod:`http.cookiejar` and :mod:`http.cookies` modules do not depend on each
other.
https://curl.haxx.se/rfc/cookie_spec.html
https://curl.se/rfc/cookie_spec.html
The specification of the original Netscape cookie protocol. Though this is
still the dominant protocol, the 'Netscape cookie protocol' implemented by all
the major browsers (and :mod:`http.cookiejar`) only bears a passing resemblance to
@ -494,7 +494,8 @@ and ``".168.1.2"``, 192.168.1.2 is blocked, but 193.168.1.2 is not.
.. method:: DefaultCookiePolicy.is_blocked(domain)
Return whether *domain* is on the blocklist for setting or receiving cookies.
Return ``True`` if *domain* is on the blocklist for setting or receiving
cookies.
.. method:: DefaultCookiePolicy.allowed_domains()
@ -509,7 +510,7 @@ and ``".168.1.2"``, 192.168.1.2 is blocked, but 193.168.1.2 is not.
.. method:: DefaultCookiePolicy.is_not_allowed(domain)
Return whether *domain* is not on the allowlist for setting or receiving
Return ``True`` if *domain* is not on the allowlist for setting or receiving
cookies.
:class:`DefaultCookiePolicy` instances have the following attributes, which are
@ -766,4 +767,3 @@ returned::
cj = CookieJar(policy)
opener = urllib.request.build_opener(urllib.request.HTTPCookieProcessor(cj))
r = opener.open("http://example.com/")

2
Doc/library/idle.rst
View file

@ -518,7 +518,7 @@ and not restarting the Shell thereafter. This is especially useful
after adding imports at the top of a file. This also increases
possible attribute completions.
Completion boxes intially exclude names beginning with '_' or, for
Completion boxes initially exclude names beginning with '_' or, for
modules, not included in '__all__'. The hidden names can be accessed
by typing '_' after '.', either before or after the box is opened.

4
Doc/library/importlib.metadata.rst
View file

@ -11,7 +11,7 @@
.. versionchanged:: 3.10
``importlib.metadata`` is no longer provisional.
**Source code:** :source:`Lib/importlib/metadata.py`
**Source code:** :source:`Lib/importlib/metadata/__init__.py`
``importlib.metadata`` is a library that provides for access to installed
package metadata. Built in part on Python's import system, this library
@ -255,7 +255,7 @@ function::
Package distributions
---------------------
A convience method to resolve the distribution or
A convenience method to resolve the distribution or
distributions (in the case of a namespace package) for top-level
Python packages or modules::

234
Doc/library/importlib.rst
View file

@ -145,6 +145,10 @@ Functions
.. versionadded:: 3.3
.. versionchanged:: 3.10
Namespace packages created/installed in a different :data:`sys.path`
location after the same namespace was already imported are noticed.
.. function:: reload(module)
Reload a previously imported *module*. The argument must be a module object,
@ -383,11 +387,11 @@ ABC hierarchy::
See :pep:`302` for the exact definition for a loader.
Loaders that wish to support resource reading should implement a
``get_resource_reader(fullname)`` method as specified by
:meth:`get_resource_reader` method as specified by
:class:`importlib.abc.ResourceReader`.
.. versionchanged:: 3.7
Introduced the optional ``get_resource_reader()`` method.
Introduced the optional :meth:`get_resource_reader` method.
.. method:: create_module(spec)
@ -405,17 +409,17 @@ ABC hierarchy::
An abstract method that executes the module in its own namespace
when a module is imported or reloaded. The module should already
be initialized when ``exec_module()`` is called. When this method exists,
:meth:`~importlib.abc.Loader.create_module` must be defined.
be initialized when :meth:`exec_module` is called. When this method exists,
:meth:`create_module` must be defined.
.. versionadded:: 3.4
.. versionchanged:: 3.6
:meth:`~importlib.abc.Loader.create_module` must also be defined.
:meth:`create_module` must also be defined.
.. method:: load_module(fullname)
A legacy method for loading a module. If the module cannot be
A legacy method for loading a module. If the module cannot be
loaded, :exc:`ImportError` is raised, otherwise the loaded module is
returned.
@ -423,62 +427,64 @@ ABC hierarchy::
module should be used and reloaded.
Otherwise the loader should create a new module and insert it into
:data:`sys.modules` before any loading begins, to prevent recursion
from the import. If the loader inserted a module and the load fails, it
from the import. If the loader inserted a module and the load fails, it
must be removed by the loader from :data:`sys.modules`; modules already
in :data:`sys.modules` before the loader began execution should be left
alone (see :func:`importlib.util.module_for_loader`).
The loader should set several attributes on the module.
(Note that some of these attributes can change when a module is
The loader should set several attributes on the module
(note that some of these attributes can change when a module is
reloaded):
- :attr:`__name__`
The name of the module.
The module's fully-qualified name.
It is ``'__main__'`` for an executed module.
- :attr:`__file__`
The path to where the module data is stored (not set for built-in
modules).
The location the :term:`loader` used to load the module.
For example, for modules loaded from a .py file this is the filename.
It is not set on all modules (e.g. built-in modules).
- :attr:`__cached__`
The path to where a compiled version of the module is/should be
stored (not set when the attribute would be inappropriate).
The filename of a compiled version of the module's code.
It is not set on all modules (e.g. built-in modules).
- :attr:`__path__`
A list of strings specifying the search path within a
package. This attribute is not set on modules.
The list of locations where the package's submodules will be found.
Most of the time this is a single directory.
The import system passes this attribute to ``__import__()`` and to finders
in the same way as :attr:`sys.path` but just for the package.
It is not set on non-package modules so it can be used
as an indicator that the module is a package.
- :attr:`__package__`
The fully-qualified name of the package under which the module was
loaded as a submodule (or the empty string for top-level modules).
For packages, it is the same as :attr:`__name__`. The
:func:`importlib.util.module_for_loader` decorator can handle the
details for :attr:`__package__`.
The fully-qualified name of the package the module is in (or the
empty string for a top-level module).
If the module is a package then this is the same as :attr:`__name__`.
- :attr:`__loader__`
The loader used to load the module. The
:func:`importlib.util.module_for_loader` decorator can handle the
details for :attr:`__package__`.
The :term:`loader` used to load the module.
When :meth:`exec_module` is available then backwards-compatible
functionality is provided.
.. versionchanged:: 3.4
Raise :exc:`ImportError` when called instead of
:exc:`NotImplementedError`. Functionality provided when
:exc:`NotImplementedError`. Functionality provided when
:meth:`exec_module` is available.
.. deprecated:: 3.4
The recommended API for loading a module is :meth:`exec_module`
(and :meth:`create_module`). Loaders should implement
it instead of load_module(). The import machinery takes care of
all the other responsibilities of load_module() when exec_module()
is implemented.
(and :meth:`create_module`). Loaders should implement it instead of
:meth:`load_module`. The import machinery takes care of all the
other responsibilities of :meth:`load_module` when
:meth:`exec_module` is implemented.
.. method:: module_repr(module)
A legacy method which when implemented calculates and returns the
given module's repr, as a string. The module type's default repr() will
use the result of this method as appropriate.
A legacy method which when implemented calculates and returns the given
module's representation, as a string. The module type's default
:meth:`__repr__` will use the result of this method as appropriate.
.. versionadded:: 3.3
@ -815,20 +821,66 @@ ABC hierarchy::
.. versionadded:: 3.9
.. attribute:: name
Abstract. The base name of this object without any parent references.
.. abstractmethod:: iterdir()
Yield Traversable objects in self.
.. abstractmethod:: is_dir()
Return True if self is a directory.
.. abstractmethod:: is_file()
Return True if self is a file.
.. abstractmethod:: joinpath(child)
Return Traversable child in self.
.. abstractmethod:: __truediv__(child)
Return Traversable child in self.
.. abstractmethod:: open(mode='r', *args, **kwargs)
*mode* may be 'r' or 'rb' to open as text or binary. Return a handle
suitable for reading (same as :attr:`pathlib.Path.open`).
When opening as text, accepts encoding parameters such as those
accepted by :attr:`io.TextIOWrapper`.
.. method:: read_bytes()
Read contents of self as bytes.
.. method:: read_text(encoding=None)
Read contents of self as text.
.. class:: TraversableResources
An abstract base class for resource readers capable of serving
the ``files`` interface. Subclasses ResourceReader and provides
concrete implementations of the ResourceReader's abstract
methods. Therefore, any loader supplying TraversableReader
also supplies ResourceReader.
the :meth:`importlib.resources.files` interface. Subclasses
:class:`importlib.abc.ResourceReader` and provides
concrete implementations of the :class:`importlib.abc.ResourceReader`'s
abstract methods. Therefore, any loader supplying
:class:`importlib.abc.TraversableReader` also supplies ResourceReader.
Loaders that wish to support resource reading are expected to
implement this interface.
.. versionadded:: 3.9
.. abstractmethod:: files()
Returns a :class:`importlib.abc.Traversable` object for the loaded
package.
:mod:`importlib.resources` -- Resources
---------------------------------------
@ -865,7 +917,9 @@ not** have to exist as physical files and directories on the file system.
on `using importlib.resources
<http://importlib-resources.readthedocs.io/en/latest/using.html>`_ and
`migrating from pkg_resources to importlib.resources
<http://importlib-resources.readthedocs.io/en/latest/migration.html>`_.
<http://importlib-resources.readthedocs.io/en/latest/migration.html>`_
and
`migrating legacy usage <https://importlib-resources.readthedocs.io/en/latest/using.html#migrating-from-legacy>`_.
Loaders that wish to support resource reading should implement a
``get_resource_reader(fullname)`` method as specified by
@ -927,6 +981,8 @@ The following functions are available.
sub-resources (i.e. it cannot be a directory). This function returns a
``typing.BinaryIO`` instance, a binary I/O stream open for reading.
.. deprecated:: 3.11
.. function:: open_text(package, resource, encoding='utf-8', errors='strict')
@ -942,6 +998,8 @@ The following functions are available.
This function returns a ``typing.TextIO`` instance, a text I/O stream open
for reading.
.. deprecated:: 3.11
.. function:: read_binary(package, resource)
@ -954,6 +1012,8 @@ The following functions are available.
sub-resources (i.e. it cannot be a directory). This function returns the
contents of the resource as :class:`bytes`.
.. deprecated:: 3.11
.. function:: read_text(package, resource, encoding='utf-8', errors='strict')
@ -967,6 +1027,8 @@ The following functions are available.
have the same meaning as with built-in :func:`open`. This function
returns the contents of the resource as :class:`str`.
.. deprecated:: 3.11
.. function:: path(package, resource)
@ -982,6 +1044,8 @@ The following functions are available.
within *package*; it may not contain path separators and it may not have
sub-resources (i.e. it cannot be a directory).
.. deprecated:: 3.11
.. function:: is_resource(package, name)
@ -990,6 +1054,8 @@ The following functions are available.
*package* is either a name or a module object which conforms to the
``Package`` requirements.
.. deprecated:: 3.11
.. function:: contents(package)
@ -1000,6 +1066,8 @@ The following functions are available.
*package* is either a name or a module object which conforms to the
``Package`` requirements.
.. deprecated:: 3.11
:mod:`importlib.machinery` -- Importers and path hooks
------------------------------------------------------
@ -1353,72 +1421,101 @@ find and load modules.
.. versionadded:: 3.4
.. class:: NamespaceLoader(name, path, path_finder):
A concrete implementation of :class:`importlib.abc.InspectLoader` for
namespace packages. This is an alias for a private class and is only made
public for introspecting the ``__loader__`` attribute on namespace
packages::
>>> from importlib.machinery import NamespaceLoader
>>> import my_namespace
>>> isinstance(my_namespace.__loader__, NamespaceLoader)
True
>>> import importlib.abc
>>> isinstance(my_namespace.__loader__, importlib.abc.Loader)
True
.. versionadded:: 3.11
.. class:: ModuleSpec(name, loader, *, origin=None, loader_state=None, is_package=None)
A specification for a module's import-system-related state. This is
typically exposed as the module's ``__spec__`` attribute. In the
typically exposed as the module's :attr:`__spec__` attribute. In the
descriptions below, the names in parentheses give the corresponding
attribute available directly on the module object.
E.g. ``module.__spec__.origin == module.__file__``. Note however that
attribute available directly on the module object,
e.g. ``module.__spec__.origin == module.__file__``. Note, however, that
while the *values* are usually equivalent, they can differ since there is
no synchronization between the two objects. Thus it is possible to update
the module's ``__path__`` at runtime, and this will not be automatically
reflected in ``__spec__.submodule_search_locations``.
no synchronization between the two objects. For example, it is possible to update
the module's :attr:`__file__` at runtime and this will not be automatically
reflected in the module's :attr:`__spec__.origin`, and vice versa.
.. versionadded:: 3.4
.. attribute:: name
(``__name__``)
(:attr:`__name__`)
A string for the fully-qualified name of the module.
The module's fully-qualified name.
The :term:`finder` should always set this attribute to a non-empty string.
.. attribute:: loader
(``__loader__``)
(:attr:`__loader__`)
The :term:`Loader <loader>` that should be used when loading
the module. :term:`Finders <finder>` should always set this.
The :term:`loader` used to load the module.
The :term:`finder` should always set this attribute.
.. attribute:: origin
(``__file__``)
(:attr:`__file__`)
Name of the place from which the module is loaded, e.g. "builtin" for
built-in modules and the filename for modules loaded from source.
Normally "origin" should be set, but it may be ``None`` (the default)
which indicates it is unspecified (e.g. for namespace packages).
The location the :term:`loader` should use to load the module.
For example, for modules loaded from a .py file this is the filename.
The :term:`finder` should always set this attribute to a meaningful value
for the :term:`loader` to use. In the uncommon case that there is not one
(like for namespace packages), it should be set to ``None``.
.. attribute:: submodule_search_locations
(``__path__``)
(:attr:`__path__`)
List of strings for where to find submodules, if a package (``None``
otherwise).
The list of locations where the package's submodules will be found.
Most of the time this is a single directory.
The :term:`finder` should set this attribute to a list, even an empty one, to indicate
to the import system that the module is a package. It should be set to ``None`` for
non-package modules. It is set automatically later to a special object for
namespace packages.
.. attribute:: loader_state
Container of extra module-specific data for use during loading (or
``None``).
The :term:`finder` may set this attribute to an object containing additional,
module-specific data to use when loading the module. Otherwise it should be
set to ``None``.
.. attribute:: cached
(``__cached__``)
(:attr:`__cached__`)
String for where the compiled module should be stored (or ``None``).
The filename of a compiled version of the module's code.
The :term:`finder` should always set this attribute but it may be ``None``
for modules that do not need compiled code stored.
.. attribute:: parent
(``__package__``)
(:attr:`__package__`)
(Read-only) The fully-qualified name of the package under which the module
should be loaded as a submodule (or the empty string for top-level modules).
For packages, it is the same as :attr:`__name__`.
(Read-only) The fully-qualified name of the package the module is in (or the
empty string for a top-level module).
If the module is a package then this is the same as :attr:`name`.
.. attribute:: has_location
Boolean indicating whether or not the module's "origin"
attribute refers to a loadable location.
``True`` if the spec's :attr:`origin` refers to a loadable location,
``False`` otherwise. This value impacts how :attr:`origin` is interpreted
and how the module's :attr:`__file__` is populated.
:mod:`importlib.util` -- Utility code for importers
---------------------------------------------------
@ -1510,8 +1607,9 @@ an :term:`importer`.
:exc:`ImportError` is raised if **name** is a relative module name but
**package** is a false value (e.g. ``None`` or the empty string).
:exc:`ImportError` is also raised a relative name would escape its containing
package (e.g. requesting ``..bacon`` from within the ``spam`` package).
:exc:`ImportError` is also raised if a relative name would escape its
containing package (e.g. requesting ``..bacon`` from within the ``spam``
package).
.. versionadded:: 3.3

65
Doc/library/inspect.rst
View file

@ -275,6 +275,24 @@ attributes:
listed in the metaclass' custom :meth:`__dir__`.
.. function:: getmembers_static(object[, predicate])
Return all the members of an object in a list of ``(name, value)``
pairs sorted by name without triggering dynamic lookup via the descriptor
protocol, __getattr__ or __getattribute__. Optionally, only return members
that satisfy a given predicate.
.. note::
:func:`getmembers_static` may not be able to retrieve all members
that getmembers can fetch (like dynamically created attributes)
and may find members that getmembers can't (like descriptors
that raise AttributeError). It can also return descriptor objects
instead of instance members in some cases.
.. versionadded:: 3.11
.. function:: getmodulename(path)
Return the name of the module named by the file *path*, without including the
@ -935,26 +953,6 @@ Classes and functions
times.
.. function:: getargspec(func)
Get the names and default values of a Python function's parameters. A
:term:`named tuple` ``ArgSpec(args, varargs, keywords, defaults)`` is
returned. *args* is a list of the parameter names. *varargs* and *keywords*
are the names of the ``*`` and ``**`` parameters or ``None``. *defaults* is a
tuple of default argument values or ``None`` if there are no default
arguments; if this tuple has *n* elements, they correspond to the last
*n* elements listed in *args*.
.. deprecated:: 3.0
Use :func:`getfullargspec` for an updated API that is usually a drop-in
replacement, but also correctly handles function annotations and
keyword-only parameters.
Alternatively, use :func:`signature` and
:ref:`Signature Object <inspect-signature-object>`, which provide a
more structured introspection API for callables.
.. function:: getfullargspec(func)
Get the names and default values of a Python function's parameters. A
@ -1015,33 +1013,6 @@ Classes and functions
This function was inadvertently marked as deprecated in Python 3.5.
.. function:: formatargspec(args[, varargs, varkw, defaults, kwonlyargs, kwonlydefaults, annotations[, formatarg, formatvarargs, formatvarkw, formatvalue, formatreturns, formatannotations]])
Format a pretty argument spec from the values returned by
:func:`getfullargspec`.
The first seven arguments are (``args``, ``varargs``, ``varkw``,
``defaults``, ``kwonlyargs``, ``kwonlydefaults``, ``annotations``).
The other six arguments are functions that are called to turn argument names,
``*`` argument name, ``**`` argument name, default values, return annotation
and individual annotations into strings, respectively.
For example:
>>> from inspect import formatargspec, getfullargspec
>>> def f(a: int, b: float):
... pass
...
>>> formatargspec(*getfullargspec(f))
'(a: int, b: float)'
.. deprecated:: 3.5
Use :func:`signature` and
:ref:`Signature Object <inspect-signature-object>`, which provide a
better introspecting API for callables.
.. function:: formatargvalues(args[, varargs, varkw, locals, formatarg, formatvarargs, formatvarkw, formatvalue])
Format a pretty argument spec from the four values returned by

2
Doc/library/intro.rst
View file

@ -58,5 +58,5 @@ Notes on availability
operating system.
* If not separately noted, all functions that claim "Availability: Unix" are
supported on Mac OS X, which builds on a Unix core.
supported on macOS, which builds on a Unix core.

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