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

Merge branch 'master' into topic/34716

This commit is contained in:
Jackson Riley 2020-10-23 17:23:53 +01:00
parent 07ac103195 7c4065d305
commit cb5eeb1270
1974 changed files with 261362 additions and 109438 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

55
.azure-pipelines/ci.yml
View File

@ -1,18 +1,14 @@
variables:
manylinux: false
coverage: false
resources:
containers:
- container: manylinux1
image: pyca/cryptography-manylinux1:x86_64
trigger: ['master', '3.9', '3.8', '3.7']
jobs:
- job: Prebuild
displayName: Pre-build checks
pool:
vmImage: ubuntu-16.04
vmImage: ubuntu-18.04
steps:
- template: ./prebuild-checks.yml
@ -24,7 +20,7 @@ jobs:
condition: and(succeeded(), eq(dependencies.Prebuild.outputs['docs.run'], 'true'))
pool:
vmImage: ubuntu-16.04
vmImage: ubuntu-18.04
steps:
- template: ./docs-steps.yml
@ -35,7 +31,9 @@ jobs:
- job: macOS_CI_Tests
displayName: macOS CI Tests
dependsOn: Prebuild
condition: and(succeeded(), eq(dependencies.Prebuild.outputs['tests.run'], 'true'))
#condition: and(succeeded(), eq(dependencies.Prebuild.outputs['tests.run'], 'true'))
# bpo-39837: macOS tests on Azure Pipelines are disabled
condition: false
variables:
testRunTitle: '$(build.sourceBranchName)-macos'
@ -54,12 +52,12 @@ jobs:
condition: and(succeeded(), eq(dependencies.Prebuild.outputs['tests.run'], 'true'))
pool:
vmImage: ubuntu-16.04
vmImage: ubuntu-18.04
variables:
testRunTitle: '$(build.sourceBranchName)-linux'
testRunPlatform: linux
openssl_version: 1.1.1d
openssl_version: 1.1.1g
steps:
- template: ./posix-steps.yml
@ -67,37 +65,6 @@ jobs:
dependencies: apt
- job: ManyLinux1_CI_Tests
displayName: ManyLinux1 CI Tests
dependsOn: Prebuild
condition: |
and(
and(
succeeded(),
eq(variables['manylinux'], 'true')
),
eq(dependencies.Prebuild.outputs['tests.run'], 'true')
)
pool:
vmImage: ubuntu-16.04
container: manylinux1
variables:
testRunTitle: '$(build.sourceBranchName)-manylinux1'
testRunPlatform: manylinux1
openssl_version: ''
steps:
- template: ./posix-steps.yml
parameters:
dependencies: yum
sudo_dependencies: ''
xvfb: false
patchcheck: false
- job: Ubuntu_Coverage_CI_Tests
displayName: Ubuntu CI Tests (coverage)
dependsOn: Prebuild
@ -111,12 +78,12 @@ jobs:
)
pool:
vmImage: ubuntu-16.04
vmImage: ubuntu-18.04
variables:
testRunTitle: '$(Build.SourceBranchName)-linux-coverage'
testRunPlatform: linux-coverage
openssl_version: 1.1.1d
openssl_version: 1.1.1g
steps:
- template: ./posix-steps.yml
@ -145,7 +112,7 @@ jobs:
buildOpt: '-p x64'
testRunTitle: '$(Build.SourceBranchName)-win64'
testRunPlatform: win64
maxParallel: 2
maxParallel: 4
steps:
- template: ./windows-steps.yml

2
.azure-pipelines/macos-steps.yml
View File

@ -6,7 +6,7 @@ steps:
- script: ./configure --with-pydebug --with-openssl=/usr/local/opt/openssl --prefix=/opt/python-azdev
displayName: 'Configure CPython (debug)'
- script: make -s -j4
- script: make -j4
displayName: 'Build CPython'
- script: make pythoninfo

4
.azure-pipelines/posix-steps.yml
View File

@ -20,7 +20,7 @@ steps:
- script: ./configure --with-pydebug
displayName: 'Configure CPython (debug)'
- script: make -s -j4
- script: make -j4
displayName: 'Build CPython'
- ${{ if eq(parameters.coverage, 'true') }}:
@ -49,7 +49,7 @@ steps:
- script: ./venv/bin/python -m coverage xml
displayName: 'Generate coverage.xml'
- script: source ./venv/bin/activate && bash <(curl -s https://codecov.io/bash)
- script: source ./venv/bin/activate && bash <(curl -s https://codecov.io/bash) -y .github/codecov.yml
displayName: 'Publish code coverage results'

58
.azure-pipelines/pr.yml
View File

@ -1,18 +1,14 @@
variables:
manylinux: false
coverage: false
resources:
containers:
- container: manylinux1
image: pyca/cryptography-manylinux1:x86_64
pr: ['master', '3.9', '3.8', '3.7']
jobs:
- job: Prebuild
displayName: Pre-build checks
pool:
vmImage: ubuntu-16.04
vmImage: ubuntu-18.04
steps:
- template: ./prebuild-checks.yml
@ -24,7 +20,7 @@ jobs:
condition: and(succeeded(), eq(dependencies.Prebuild.outputs['docs.run'], 'true'))
pool:
vmImage: ubuntu-16.04
vmImage: ubuntu-18.04
steps:
- template: ./docs-steps.yml
@ -33,7 +29,9 @@ jobs:
- job: macOS_PR_Tests
displayName: macOS PR Tests
dependsOn: Prebuild
condition: and(succeeded(), eq(dependencies.Prebuild.outputs['tests.run'], 'true'))
#condition: and(succeeded(), eq(dependencies.Prebuild.outputs['tests.run'], 'true'))
# bpo-39837: macOS tests on Azure Pipelines are disabled
condition: false
variables:
testRunTitle: '$(system.pullRequest.TargetBranch)-macos'
@ -54,12 +52,12 @@ jobs:
condition: and(succeeded(), eq(dependencies.Prebuild.outputs['tests.run'], 'true'))
pool:
vmImage: ubuntu-16.04
vmImage: ubuntu-18.04
variables:
testRunTitle: '$(system.pullRequest.TargetBranch)-linux'
testRunPlatform: linux
openssl_version: 1.1.1d
openssl_version: 1.1.1g
steps:
- template: ./posix-steps.yml
@ -67,37 +65,6 @@ jobs:
dependencies: apt
- job: ManyLinux1_PR_Tests
displayName: ManyLinux1 PR Tests
dependsOn: Prebuild
condition: |
and(
and(
succeeded(),
eq(variables['manylinux'], 'true')
),
eq(dependencies.Prebuild.outputs['tests.run'], 'true')
)
pool:
vmImage: ubuntu-16.04
container: manylinux1
variables:
testRunTitle: '$(system.pullRequest.TargetBranch)-manylinux1'
testRunPlatform: manylinux1
openssl_version: ''
steps:
- template: ./posix-steps.yml
parameters:
dependencies: yum
sudo_dependencies: ''
xvfb: false
patchcheck: false
- job: Ubuntu_Coverage_PR_Tests
displayName: Ubuntu PR Tests (coverage)
dependsOn: Prebuild
@ -111,12 +78,12 @@ jobs:
)
pool:
vmImage: ubuntu-16.04
vmImage: ubuntu-18.04
variables:
testRunTitle: '$(Build.SourceBranchName)-linux-coverage'
testRunPlatform: linux-coverage
openssl_version: 1.1.1d
openssl_version: 1.1.1g
steps:
- template: ./posix-steps.yml
@ -145,7 +112,10 @@ jobs:
buildOpt: '-p x64'
testRunTitle: '$(System.PullRequest.TargetBranch)-win64'
testRunPlatform: win64
maxParallel: 2
winarm64:
arch: arm64
buildOpt: '-p arm64'
maxParallel: 4
steps:
- template: ./windows-steps.yml

3
.azure-pipelines/windows-release/build-steps.yml
View File

@ -43,7 +43,7 @@ steps:
- powershell: |
$env:SigningCertificate = $null
.\python.bat PC\layout -vv -t "$(Build.BinariesDirectory)\catalog" --catalog "${env:CAT}.cdf" --preset-default
$(_HostPython) PC\layout -vv -b "$(Build.BinariesDirectory)\bin" -t "$(Build.BinariesDirectory)\catalog" --catalog "${env:CAT}.cdf" --preset-default --arch $(Arch)
makecat "${env:CAT}.cdf"
del "${env:CAT}.cdf"
if (-not (Test-Path "${env:CAT}.cat")) {
@ -52,6 +52,7 @@ steps:
displayName: 'Generate catalog'
env:
CAT: $(Build.BinariesDirectory)\bin\$(Arch)\python
PYTHON_HEXVERSION: $(VersionHex)
- task: PublishPipelineArtifact@0
displayName: 'Publish binaries'

10
.azure-pipelines/windows-release/layout-command.yml
View File

@ -1,12 +1,20 @@
steps:
- task: DownloadPipelineArtifact@1
displayName: 'Download artifact: bin_$(HostArch)'
condition: and(succeeded(), variables['HostArch'])
inputs:
artifactName: bin_$(HostArch)
targetPath: $(Build.BinariesDirectory)\bin_$(HostArch)
- powershell: >
Write-Host (
'##vso[task.setvariable variable=LayoutCmd]&
"{0}\bin\python.exe"
"$(Python)"
"{1}\PC\layout"
-vv
--source "{1}"
--build "{0}\bin"
--arch "$(Name)"
--temp "{0}\layout-temp"
--include-cat "{0}\bin\python.cat"
--doc-build "{0}\doc"'

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

@ -1,6 +1,12 @@
steps:
- template: ./checkout.yml
- powershell: |
$d = (.\PCbuild\build.bat -V) | %{ if($_ -match '\s+(\w+):\s*(.+)\s*$') { @{$Matches[1] = $Matches[2];} }};
Write-Host "##vso[task.setvariable variable=SigningDescription]Python $($d.PythonVersion)"
displayName: 'Update signing description'
condition: and(succeeded(), not(variables['SigningDescription']))
- task: DownloadPipelineArtifact@1
displayName: 'Download artifact: doc'
inputs:
@ -54,6 +60,7 @@ steps:
- powershell: |
copy $(Build.BinariesDirectory)\amd64\Activate.ps1 Lib\venv\scripts\common\Activate.ps1 -Force
displayName: 'Copy signed files into sources'
condition: and(succeeded(), variables['SigningCertificate'])
- script: |
call Tools\msi\get_externals.bat

33
.azure-pipelines/windows-release/stage-build.yml
View File

@ -3,7 +3,7 @@ jobs:
displayName: Docs build
pool:
name: 'Windows Release'
#vmName: win2016-vs2017
#vmImage: windows-2019
workspace:
clean: all
@ -16,14 +16,16 @@ jobs:
env:
BUILDDIR: $(Build.BinariesDirectory)\Doc
#- powershell: iwr "https://www.python.org/ftp/python/3.7.3/python373.chm" -OutFile "$(Build.BinariesDirectory)\python390a0.chm"
# displayName: 'Cheat at building CHM docs'
- script: Doc\make.bat htmlhelp
displayName: 'Build CHM docs'
env:
BUILDDIR: $(Build.BinariesDirectory)\Doc
#- powershell: |
# mkdir -Force "$(Build.BinariesDirectory)\Doc\htmlhelp"
# iwr "https://www.python.org/ftp/python/3.8.0/python380.chm" -OutFile "$(Build.BinariesDirectory)\Doc\htmlhelp\python390a0.chm"
# displayName: 'Cheat at building CHM docs'
- task: CopyFiles@2
displayName: 'Assemble artifact: Doc'
inputs:
@ -43,7 +45,7 @@ jobs:
displayName: Python build
pool:
vmName: win2016-vs2017
vmImage: windows-2019
workspace:
clean: all
@ -55,16 +57,31 @@ jobs:
Arch: win32
Platform: x86
Configuration: Release
_HostPython: .\python
win32_d:
Name: win32_d
Arch: win32
Platform: x86
Configuration: Debug
_HostPython: .\python
amd64_d:
Name: amd64_d
Arch: amd64
Platform: x64
Configuration: Debug
_HostPython: .\python
arm64:
Name: arm64
Arch: arm64
Platform: ARM64
Configuration: Release
_HostPython: python
arm64_d:
Name: arm64_d
Arch: arm64
Platform: ARM64
Configuration: Debug
_HostPython: python
steps:
- template: ./build-steps.yml
@ -74,7 +91,7 @@ jobs:
condition: and(succeeded(), ne(variables['DoPGO'], 'true'))
pool:
vmName: win2016-vs2017
vmImage: windows-2019
workspace:
clean: all
@ -86,6 +103,7 @@ jobs:
Arch: amd64
Platform: x64
Configuration: Release
_HostPython: .\python
steps:
- template: ./build-steps.yml
@ -111,6 +129,7 @@ jobs:
Arch: amd64
Platform: x64
Configuration: Release
_HostPython: .\python
steps:
- template: ./build-steps.yml
@ -122,7 +141,7 @@ jobs:
displayName: Publish Tcl/Tk Library
pool:
vmName: windows-latest
vmImage: windows-2019
workspace:
clean: all

7
.azure-pipelines/windows-release/stage-layout-embed.yml
View File

@ -4,7 +4,7 @@ jobs:
condition: and(succeeded(), eq(variables['DoEmbed'], 'true'))
pool:
vmName: win2016-vs2017
vmImage: windows-2019
workspace:
clean: all
@ -19,6 +19,11 @@ jobs:
Name: amd64
Python: $(Build.BinariesDirectory)\bin\python.exe
PYTHONHOME: $(Build.SourcesDirectory)
arm64:
Name: arm64
HostArch: amd64
Python: $(Build.BinariesDirectory)\bin_amd64\python.exe
PYTHONHOME: $(Build.SourcesDirectory)
steps:
- template: ./checkout.yml

19
.azure-pipelines/windows-release/stage-layout-full.yml
View File

@ -4,7 +4,7 @@ jobs:
condition: and(succeeded(), eq(variables['DoLayout'], 'true'))
pool:
vmName: win2016-vs2017
vmImage: windows-2019
workspace:
clean: all
@ -13,11 +13,18 @@ jobs:
matrix:
win32:
Name: win32
Python: $(Build.BinariesDirectory)\bin_$(Name)\python.exe
Python: $(Build.BinariesDirectory)\bin\python.exe
PYTHONHOME: $(Build.SourcesDirectory)
TclLibrary: $(Build.BinariesDirectory)\tcltk_lib\tcl8
amd64:
Name: amd64
Python: $(Build.BinariesDirectory)\bin_$(Name)\python.exe
Python: $(Build.BinariesDirectory)\bin\python.exe
PYTHONHOME: $(Build.SourcesDirectory)
TclLibrary: $(Build.BinariesDirectory)\tcltk_lib\tcl8
arm64:
Name: arm64
HostArch: amd64
Python: $(Build.BinariesDirectory)\bin_amd64\python.exe
PYTHONHOME: $(Build.SourcesDirectory)
steps:
@ -43,13 +50,15 @@ jobs:
- task: DownloadPipelineArtifact@1
displayName: 'Download artifact: tcltk_lib_$(Name)'
condition: and(succeeded(), variables['TclLibrary'])
inputs:
artifactName: tcltk_lib_$(Name)
targetPath: $(Build.BinariesDirectory)\tcltk_lib
- powershell: |
copy $(Build.BinariesDirectory)\bin\Activate.ps1 Lib\venv\scripts\common\Activate.ps1 -Force
copy "$(Build.BinariesDirectory)\bin\Activate.ps1" Lib\venv\scripts\common\Activate.ps1 -Force
displayName: 'Copy signed files into sources'
condition: and(succeeded(), variables['SigningCertificate'])
- template: ./layout-command.yml
@ -57,7 +66,7 @@ jobs:
$(LayoutCmd) --copy "$(Build.ArtifactStagingDirectory)\layout" --preset-default
displayName: 'Generate full layout'
env:
TCL_LIBRARY: $(Build.BinariesDirectory)\tcltk_lib\tcl8
TCL_LIBRARY: $(TclLibrary)
- task: PublishPipelineArtifact@0
displayName: 'Publish Artifact: layout_full_$(Name)'

21
.azure-pipelines/windows-release/stage-layout-msix.yml
View File

@ -3,7 +3,7 @@ jobs:
displayName: Make MSIX layout
pool:
vmName: win2016-vs2017
vmImage: windows-2019
workspace:
clean: all
@ -12,11 +12,18 @@ jobs:
matrix:
#win32:
# Name: win32
# Python: $(Build.BinariesDirectory)\bin_$(Name)\python.exe
# Python: $(Build.BinariesDirectory)\bin\python.exe
# PYTHONHOME: $(Build.SourcesDirectory)
# TclLibrary: $(Build.BinariesDirectory)\tcltk_lib\tcl8
amd64:
Name: amd64
Python: $(Build.BinariesDirectory)\bin_$(Name)\python.exe
Python: $(Build.BinariesDirectory)\bin\python.exe
PYTHONHOME: $(Build.SourcesDirectory)
TclLibrary: $(Build.BinariesDirectory)\tcltk_lib\tcl8
arm64:
Name: arm64
HostArch: amd64
Python: $(Build.BinariesDirectory)\bin_amd64\python.exe
PYTHONHOME: $(Build.SourcesDirectory)
steps:
@ -36,13 +43,15 @@ jobs:
- task: DownloadPipelineArtifact@1
displayName: 'Download artifact: tcltk_lib_$(Name)'
condition: and(succeeded(), variables['TclLibrary'])
inputs:
artifactName: tcltk_lib_$(Name)
targetPath: $(Build.BinariesDirectory)\tcltk_lib
- powershell: |
copy $(Build.BinariesDirectory)\bin\Activate.ps1 Lib\venv\scripts\common\Activate.ps1 -Force
copy "$(Build.BinariesDirectory)\bin\Activate.ps1" Lib\venv\scripts\common\Activate.ps1 -Force
displayName: 'Copy signed files into sources'
condition: and(succeeded(), variables['SigningCertificate'])
- template: ./layout-command.yml
@ -51,7 +60,7 @@ jobs:
$(LayoutCmd) --copy "$(Build.ArtifactStagingDirectory)\appx-store" --preset-appx --precompile
displayName: 'Generate store APPX layout'
env:
TCL_LIBRARY: $(Build.BinariesDirectory)\tcltk_lib\tcl8
TCL_LIBRARY: $(TclLibrary)
- task: PublishPipelineArtifact@0
displayName: 'Publish Artifact: layout_appxstore_$(Name)'
@ -79,7 +88,7 @@ jobs:
$(LayoutCmd) --copy "$(Build.ArtifactStagingDirectory)\appx" --preset-appx --precompile --include-symbols --include-tests
displayName: 'Generate sideloading APPX layout'
env:
TCL_LIBRARY: $(Build.BinariesDirectory)\tcltk_lib\tcl8
TCL_LIBRARY: $(TclLibrary)
- task: PublishPipelineArtifact@0
displayName: 'Publish Artifact: layout_appx_$(Name)'

14
.azure-pipelines/windows-release/stage-layout-nuget.yml
View File

@ -4,7 +4,7 @@ jobs:
condition: and(succeeded(), eq(variables['DoNuget'], 'true'))
pool:
vmName: win2016-vs2017
vmImage: windows-2019
workspace:
clean: all
@ -13,11 +13,16 @@ jobs:
matrix:
win32:
Name: win32
Python: $(Build.BinariesDirectory)\bin_$(Name)\python.exe
Python: $(Build.BinariesDirectory)\bin\python.exe
PYTHONHOME: $(Build.SourcesDirectory)
amd64:
Name: amd64
Python: $(Build.BinariesDirectory)\bin_$(Name)\python.exe
Python: $(Build.BinariesDirectory)\bin\python.exe
PYTHONHOME: $(Build.SourcesDirectory)
arm64:
Name: arm64
HostArch: amd64
Python: $(Build.BinariesDirectory)\bin_amd64\python.exe
PYTHONHOME: $(Build.SourcesDirectory)
steps:
@ -32,14 +37,13 @@ jobs:
- powershell: |
copy $(Build.BinariesDirectory)\bin\Activate.ps1 Lib\venv\scripts\common\Activate.ps1 -Force
displayName: 'Copy signed files into sources'
condition: and(succeeded(), variables['SigningCertificate'])
- template: ./layout-command.yml
- powershell: |
$(LayoutCmd) --copy "$(Build.ArtifactStagingDirectory)\nuget" --preset-nuget
displayName: 'Generate nuget layout'
env:
TCL_LIBRARY: $(Build.BinariesDirectory)\bin_$(Name)\tcl\tcl8
- task: PublishPipelineArtifact@0
displayName: 'Publish Artifact: layout_nuget_$(Name)'

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

@ -4,7 +4,7 @@ jobs:
condition: and(succeeded(), not(variables['SigningCertificate']))
pool:
vmName: win2016-vs2017
vmImage: windows-2019
variables:
ReleaseUri: http://www.python.org/{arch}

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

@ -3,7 +3,7 @@ jobs:
displayName: Pack MSIX bundles
pool:
vmName: win2016-vs2017
vmImage: windows-2019
workspace:
clean: all
@ -20,6 +20,16 @@ jobs:
Artifact: appxstore
Suffix: -store
Upload: true
arm64:
Name: arm64
Artifact: appx
Suffix:
ShouldSign: true
arm64_store:
Name: arm64
Artifact: appxstore
Suffix: -store
Upload: true
steps:
- template: ./checkout.yml
@ -95,9 +105,15 @@ jobs:
clean: all
steps:
- checkout: none
- template: ./checkout.yml
- template: ./find-sdk.yml
- powershell: |
$d = (.\PCbuild\build.bat -V) | %{ if($_ -match '\s+(\w+):\s*(.+)\s*$') { @{$Matches[1] = $Matches[2];} }};
Write-Host "##vso[task.setvariable variable=SigningDescription]Python $($d.PythonVersion)"
displayName: 'Update signing description'
condition: and(succeeded(), not(variables['SigningDescription']))
- task: DownloadBuildArtifacts@0
displayName: 'Download Artifact: unsigned_msix'
inputs:

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

@ -4,7 +4,7 @@ jobs:
condition: and(succeeded(), eq(variables['DoNuget'], 'true'))
pool:
vmName: win2016-vs2017
vmImage: windows-2019
workspace:
clean: all
@ -15,6 +15,8 @@ jobs:
Name: amd64
win32:
Name: win32
arm64:
Name: arm64
steps:
- checkout: none

7
.azure-pipelines/windows-release/stage-publish-nugetorg.yml
View File

@ -4,7 +4,7 @@ jobs:
condition: and(succeeded(), eq(variables['DoNuget'], 'true'))
pool:
vmName: win2016-vs2017
vmImage: windows-2019
workspace:
clean: all
@ -31,6 +31,11 @@ jobs:
buildVersionToDownload: specific
buildId: $(BuildToPublish)
- powershell: 'gci pythonarm*.nupkg | %{ Write-Host "Not publishing: $($_.Name)"; gi $_ } | del'
displayName: 'Prevent publishing ARM/ARM64 packages'
workingDirectory: '$(Build.BinariesDirectory)\nuget'
condition: and(succeeded(), not(variables['PublishArmPackages']))
- task: NuGetCommand@2
displayName: Push packages
condition: and(succeeded(), eq(variables['SigningCertificate'], variables['__RealSigningCertificate']))

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

@ -4,7 +4,7 @@ jobs:
condition: and(succeeded(), and(eq(variables['DoMSI'], 'true'), eq(variables['DoEmbed'], 'true')))
pool:
#vmName: win2016-vs2017
#vmImage: windows-2019
name: 'Windows Release'
workspace:
@ -39,7 +39,6 @@ jobs:
artifactName: embed
downloadPath: $(Build.BinariesDirectory)
- task: DownloadPipelineArtifact@1
displayName: 'Download artifact from $(BuildToPublish): Doc'
condition: and(succeeded(), variables['BuildToPublish'])
@ -76,6 +75,11 @@ jobs:
buildVersionToDownload: specific
buildId: $(BuildToPublish)
- powershell: 'gci *embed-arm*.zip | %{ Write-Host "Not publishing: $($_.Name)"; gi $_ } | del'
displayName: 'Prevent publishing ARM/ARM64 packages'
workingDirectory: '$(Build.BinariesDirectory)\embed'
condition: and(succeeded(), not(variables['PublishArmPackages']))
- template: ./gpg-sign.yml
parameters:

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

@ -4,7 +4,7 @@ jobs:
condition: and(succeeded(), eq(variables['DoMSIX'], 'true'))
pool:
vmName: win2016-vs2017
vmImage: windows-2019
workspace:
clean: all

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

@ -19,11 +19,19 @@ jobs:
Name: win32
amd64:
Name: amd64
arm64:
Name: arm64
steps:
- template: ./checkout.yml
- template: ./find-sdk.yml
- powershell: |
$d = (.\PCbuild\build.bat -V) | %{ if($_ -match '\s+(\w+):\s*(.+)\s*$') { @{$Matches[1] = $Matches[2];} }};
Write-Host "##vso[task.setvariable variable=SigningDescription]Python $($d.PythonVersion)"
displayName: 'Update signing description'
condition: and(succeeded(), not(variables['SigningDescription']))
- powershell: |
Write-Host "##vso[build.addbuildtag]signed"
displayName: 'Add build tags'
@ -112,7 +120,7 @@ jobs:
condition: and(succeeded(), not(variables['SigningCertificate']))
pool:
vmName: win2016-vs2017
vmImage: windows-2019
steps:
- checkout: none

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

@ -4,7 +4,7 @@ jobs:
condition: and(succeeded(), eq(variables['DoEmbed'], 'true'))
pool:
vmName: win2016-vs2017
vmImage: windows-2019
workspace:
clean: all

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

@ -3,7 +3,7 @@ jobs:
displayName: Test MSI
pool:
vmName: win2016-vs2017
vmImage: windows-2019
workspace:
clean: all

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

@ -4,7 +4,7 @@ jobs:
condition: and(succeeded(), eq(variables['DoNuget'], 'true'))
pool:
vmName: win2016-vs2017
vmImage: windows-2019
workspace:
clean: all

4
.azure-pipelines/windows-steps.yml
View File

@ -19,9 +19,11 @@ steps:
- script: python.bat -m test.pythoninfo
displayName: 'Display build info'
condition: and(succeeded(), variables['testRunPlatform'])
- script: PCbuild\rt.bat -q -uall -u-cpu -rwW --slowest --timeout=1200 -j0 --junit-xml="$(Build.BinariesDirectory)\test-results.xml" --tempdir="$(Build.BinariesDirectory)\test"
displayName: 'Tests'
condition: and(succeeded(), variables['testRunPlatform'])
env:
PREFIX: $(Py_OutDir)\$(arch)
@ -32,4 +34,4 @@ steps:
mergeTestResults: true
testRunTitle: $(testRunTitle)
platform: $(testRunPlatform)
condition: succeededOrFailed()
condition: and(succeededOrFailed(), variables['testRunPlatform'])

12
.gitattributes vendored
View File

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

28
.github/CODEOWNERS vendored
View File

@ -9,9 +9,16 @@
# Core
**/*context* @1st1
**/*genobject* @1st1
**/*genobject* @1st1 @markshannon
**/*hamt* @1st1
Objects/dict* @methane
Objects/set* @rhettinger
Objects/dict* @methane @markshannon
Objects/type* @markshannon
Objects/codeobject.c @markshannon
Objects/frameobject.c @markshannon
Objects/call.c @markshannon
Python/ceval.c @markshannon
Python/compile.c @markshannon
# Hashing
**/*hashlib* @python/crypto-team @tiran
@ -71,8 +78,11 @@ Include/pytime.h @pganssle @abalkin
/Modules/gcmodule.c @pablogsal
/Doc/library/gc.rst @pablogsal
# Parser/Pgen
/Parser/pgen/ @pablogsal
# Parser
/Parser/ @pablogsal @lysnikolaou
/Tools/peg_generator/ @pablogsal @lysnikolaou
/Lib/test/test_peg_generator/ @pablogsal @lysnikolaou
/Grammar/python.gram @pablogsal @lysnikolaou
# SQLite 3
**/*sqlite* @berkerpeksag
@ -93,6 +103,7 @@ Include/pytime.h @pganssle @abalkin
/Tools/msi/ @python/windows-team
/Tools/nuget/ @python/windows-team
# Misc
**/*itertools* @rhettinger
**/*collections* @rhettinger
**/*random* @rhettinger
@ -108,6 +119,15 @@ Include/pytime.h @pganssle @abalkin
**/*typing* @gvanrossum @ilevkivskyi
**/*asyncore @giampaolo
**/*asynchat @giampaolo
**/*ftplib @giampaolo
**/*shutil @giampaolo
**/*enum* @ethanfurman
**/*cgi* @ethanfurman
**/*tarfile* @ethanfurman
# macOS
/Mac/ @python/macos-team
**/*osx_support* @python/macos-team

16
.github/CONTRIBUTING.rst vendored
View File

@ -8,18 +8,18 @@ Build Status
+ `Stable buildbots <http://buildbot.python.org/3.x.stable/>`_
- 3.9
+ `Stable buildbots <http://buildbot.python.org/3.9.stable/>`_
- 3.8
+ `Stable buildbots <http://buildbot.python.org/3.8.stable/>`_
- 3.7
+ `Stable buildbots <http://buildbot.python.org/3.7.stable/>`_
- 3.6
+ `Stable buildbots <http://buildbot.python.org/3.6.stable/>`_
- 2.7
+ `Stable buildbots <http://buildbot.python.org/2.7.stable/>`_
Thank You
---------

1
.github/FUNDING.yml vendored
View File

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

2
.github/codecov.yml vendored
View File

@ -5,7 +5,7 @@ codecov:
comment: off
ignore:
- "Doc/**/*"
- "Misc/*"
- "Misc/**/*"
- "Mac/**/*"
- "PC/**/*"
- "PCbuild/**/*"

18
.github/problem-matchers/gcc.json vendored Normal file
View File

@ -0,0 +1,18 @@
{
"__comment": "Taken from vscode-cpptools's Extension/package.json gcc rule",
"problemMatcher": [
{
"owner": "gcc-problem-matcher",
"pattern": [
{
"regexp": "^(.*):(\\d+):(\\d+):\\s+(?:fatal\\s+)?(warning|error):\\s+(.*)$",
"file": 1,
"line": 2,
"column": 3,
"severity": 4,
"message": 5
}
]
}
]
}

40
.github/problem-matchers/sphinx.json vendored Normal file
View File

@ -0,0 +1,40 @@
{
"problemMatcher": [
{
"owner": "sphinx-problem-matcher",
"pattern": [
{
"regexp": "^(.*):(\\d+):\\s+(\\w*):\\s+(.*)$",
"file": 1,
"line": 2,
"severity": 3,
"message": 4
}
]
},
{
"owner": "sphinx-problem-matcher-loose",
"pattern": [
{
"_comment": "A bit of a looser pattern, doesn't look for line numbers, just looks for file names relying on them to start with / and end with .rst",
"regexp": "(\/.*\\.rst):\\s+(\\w*):\\s+(.*)$",
"file": 1,
"severity": 2,
"message": 3
}
]
},
{
"owner": "sphinx-problem-matcher-loose-no-severity",
"pattern": [
{
"_comment": "Looks for file names ending with .rst and line numbers but without severity",
"regexp": "^(.*\\.rst):(\\d+):(.*)$",
"file": 1,
"line": 2,
"message": 3
}
]
}
]
}

123
.github/workflows/build.yml vendored Normal file
View File

@ -0,0 +1,123 @@
name: Tests
# bpo-40548: "paths-ignore" is not used to skip documentation-only PRs, because
# 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:
push:
branches:
- master
- 3.9
- 3.8
- 3.7
pull_request:
branches:
- master
- 3.9
- 3.8
- 3.7
jobs:
check_source:
name: 'Check for source changes'
runs-on: ubuntu-latest
outputs:
run_tests: ${{ steps.check.outputs.run_tests }}
steps:
- uses: actions/checkout@v2
- name: Check for source changes
id: check
run: |
if [ -z "GITHUB_BASE_REF" ]; then
echo '::set-output name=run_tests::true'
else
git fetch origin $GITHUB_BASE_REF --depth=1
# git diff "origin/$GITHUB_BASE_REF..." (3 dots) may be more
# reliable than git diff "origin/$GITHUB_BASE_REF.." (2 dots),
# but it requires to download more commits (this job uses
# "git fetch --depth=1").
#
# git diff "origin/$GITHUB_BASE_REF..." (3 dots) works with Git
# 2.26, but Git 2.28 is stricter and fails with "no merge base".
#
# git diff "origin/$GITHUB_BASE_REF.." (2 dots) should be enough on
# GitHub, since GitHub starts by merging origin/$GITHUB_BASE_REF
# into the PR branch anyway.
#
# https://github.com/python/core-workflow/issues/373
git diff --name-only origin/$GITHUB_BASE_REF.. | grep -qvE '(\.rst$|^Doc|^Misc)' && echo '::set-output name=run_tests::true' || true
fi
build_win32:
name: 'Windows (x86)'
runs-on: windows-latest
needs: check_source
if: needs.check_source.outputs.run_tests == 'true'
steps:
- uses: actions/checkout@v2
- name: Build CPython
run: .\PCbuild\build.bat -e -p Win32
- name: Display build info
run: .\python.bat -m test.pythoninfo
- name: Tests
run: .\PCbuild\rt.bat -q -uall -u-cpu -rwW --slowest --timeout=1200 -j0
build_win_amd64:
name: 'Windows (x64)'
runs-on: windows-latest
needs: check_source
if: needs.check_source.outputs.run_tests == 'true'
steps:
- uses: actions/checkout@v2
- name: Build CPython
run: .\PCbuild\build.bat -e -p x64
- name: Display build info
run: .\python.bat -m test.pythoninfo
- name: Tests
run: .\PCbuild\rt.bat -x64 -q -uall -u-cpu -rwW --slowest --timeout=1200 -j0
build_macos:
name: 'macOS'
runs-on: macos-latest
needs: check_source
if: needs.check_source.outputs.run_tests == 'true'
steps:
- uses: actions/checkout@v2
- name: Configure CPython
run: ./configure --with-pydebug --with-openssl=/usr/local/opt/openssl --prefix=/opt/python-dev
- name: Build CPython
run: make -j4
- name: Display build info
run: make pythoninfo
- name: Tests
run: make buildbottest TESTOPTS="-j4 -uall,-cpu"
build_ubuntu:
name: 'Ubuntu'
runs-on: ubuntu-latest
needs: check_source
if: needs.check_source.outputs.run_tests == 'true'
env:
OPENSSL_VER: 1.1.1f
steps:
- uses: actions/checkout@v2
- name: Register gcc problem matcher
run: echo "::add-matcher::.github/problem-matchers/gcc.json"
- name: Install Dependencies
run: sudo ./.github/workflows/posix-deps-apt.sh
- name: 'Restore OpenSSL build'
id: cache-openssl
uses: actions/cache@v1
with:
path: ./multissl/openssl/${{ env.OPENSSL_VER }}
key: ${{ runner.os }}-multissl-openssl-${{ env.OPENSSL_VER }}
- name: Install OpenSSL
if: steps.cache-openssl.outputs.cache-hit != 'true'
run: python3 Tools/ssl/multissltests.py --steps=library --base-directory $PWD/multissl --openssl $OPENSSL_VER --system Linux
- name: Configure CPython
run: ./configure --with-pydebug --with-openssl=$PWD/multissl/openssl/$OPENSSL_VER
- name: Build CPython
run: make -j4
- name: Display build info
run: make pythoninfo
- name: Tests
run: xvfb-run make buildbottest TESTOPTS="-j4 -uall,-cpu"

36
.github/workflows/build_msi.yml vendored Normal file
View File

@ -0,0 +1,36 @@
name: TestsMSI
on:
push:
branches:
- master
- 3.9
- 3.8
- 3.7
paths:
- 'Tools/msi/**'
pull_request:
branches:
- master
- 3.9
- 3.8
- 3.7
paths:
- 'Tools/msi/**'
jobs:
build_win32:
name: 'Windows (x86) Installer'
runs-on: windows-latest
steps:
- uses: actions/checkout@v2
- name: Build CPython installer
run: .\Tools\msi\build.bat -x86
build_win_amd64:
name: 'Windows (x64) Installer'
runs-on: windows-latest
steps:
- uses: actions/checkout@v2
- name: Build CPython installer
run: .\Tools\msi\build.bat -x64

94
.github/workflows/coverage.yml vendored Normal file
View File

@ -0,0 +1,94 @@
name: Coverage
on:
push:
branches:
- master
- 3.9
- 3.8
- 3.7
paths-ignore:
- 'Doc/**'
- 'Misc/**'
#pull_request:
# branches:
# - master
# - 3.9
# - 3.8
# - 3.7
# paths-ignore:
# - 'Doc/**'
# - 'Misc/**'
jobs:
coverage_ubuntu:
name: 'Ubuntu (Coverage)'
runs-on: ubuntu-latest
env:
OPENSSL_VER: 1.1.1f
steps:
- uses: actions/checkout@v2
- name: Install Dependencies
run: sudo ./.github/workflows/posix-deps-apt.sh
- name: 'Restore OpenSSL build'
id: cache-openssl
uses: actions/cache@v1
with:
path: ./multissl/openssl/${{ env.OPENSSL_VER }}
key: ${{ runner.os }}-multissl-openssl-${{ env.OPENSSL_VER }}
- name: Install OpenSSL
if: steps.cache-openssl.outputs.cache-hit != 'true'
run: python3 Tools/ssl/multissltests.py --steps=library --base-directory $PWD/multissl --openssl $OPENSSL_VER --system Linux
- name: Configure CPython
run: ./configure --with-openssl=$PWD/multissl/openssl/$OPENSSL_VER
- name: Build CPython
run: make -j4
- name: Display build info
run: make pythoninfo
- name: 'Coverage Preparation'
run: |
./python -m venv .venv
source ./.venv/bin/activate
python -m pip install -U coverage
python -m pip install -r Misc/requirements-test.txt
python -m test.pythoninfo
export PYTHONPATH=`find .venv -name fullcoverage`
- name: 'Tests with coverage'
run: >
source ./.venv/bin/activate &&
xvfb-run python -m coverage
run --branch --pylib
-m test
--fail-env-changed
-uall,-cpu
-x test_multiprocessing_fork
-x test_multiprocessing_forkserver
-x test_multiprocessing_spawn
-x test_concurrent_futures
|| true
- name: 'Publish code coverage results'
run: |
export PYTHONPATH=
source ./.venv/bin/activate
bash <(curl -s https://codecov.io/bash) -y .github/codecov.yml
env:
CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
c_coverage_ubuntu:
name: 'Ubuntu (C Coverage)'
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Install Dependencies
run: sudo ./.github/workflows/posix-deps-apt.sh
- name: Configure CPython
run: ./configure
- name: 'Build CPython and measure coverage'
run: xvfb-run make -j4 coverage-report
- name: 'Publish code coverage results'
if: always()
run: |
make pythoninfo
bash <(curl -s https://codecov.io/bash) -y .github/codecov.yml
env:
CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}

44
.github/workflows/doc.yml vendored Normal file
View File

@ -0,0 +1,44 @@
name: Docs
on:
#push:
# branches:
# - master
# - 3.9
# - 3.8
# - 3.7
# paths:
# - 'Doc/**'
pull_request:
branches:
- master
- 3.9
- 3.8
- 3.7
paths:
- 'Doc/**'
- 'Misc/**'
jobs:
build_doc:
name: 'Docs'
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Register Sphinx problem matcher
run: echo "::add-matcher::.github/problem-matchers/sphinx.json"
- name: 'Install Dependencies'
run: sudo ./.github/workflows/posix-deps-apt.sh && sudo apt-get install wamerican
- name: 'Configure CPython'
run: ./configure --with-pydebug
- name: 'Build CPython'
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 suspicious html
- name: 'Upload'
uses: actions/upload-artifact@v1
with:
name: doc-html
path: Doc/build/html

21
.github/workflows/posix-deps-apt.sh vendored Executable file
View File

@ -0,0 +1,21 @@
#!/bin/sh
apt-get update
apt-get -yq install \
build-essential \
zlib1g-dev \
libbz2-dev \
liblzma-dev \
libncurses5-dev \
libreadline6-dev \
libsqlite3-dev \
libssl-dev \
libgdbm-dev \
tk-dev \
lzma \
lzma-dev \
liblzma-dev \
libffi-dev \
uuid-dev \
xvfb \
lcov

4
.gitignore vendored
View File

@ -6,7 +6,8 @@
*.iml
*.o
*.a
*.so*
*.so
*.so.*
*.dylib
*.dll
*.orig
@ -70,6 +71,7 @@ Programs/_freeze_importlib
Programs/_testembed
PC/python_nt*.h
PC/pythonnt_rc*.h
Modules/python.exp
PC/*/*.exp
PC/*/*.lib
PC/*/*.bsc

33
.travis.yml
View File

@ -1,6 +1,5 @@
language: c
dist: xenial
group: beta
dist: bionic
# To cache doc-building dependencies and C compiler output.
cache:
@ -11,7 +10,7 @@ cache:
env:
global:
- OPENSSL=1.1.1d
- OPENSSL=1.1.1f
- OPENSSL_DIR="$HOME/multissl/openssl/${OPENSSL}"
- PATH="${OPENSSL_DIR}/bin:$PATH"
- CFLAGS="-I${OPENSSL_DIR}/include"
@ -52,10 +51,7 @@ matrix:
env: TESTING=docs
before_script:
- cd Doc
# Sphinx is pinned so that new versions that introduce new warnings won't suddenly cause build failures.
# (Updating the version is fine as long as no warnings are raised by doing so.)
# The theme used by the docs is stored separately, so we need to install that as well.
- python -m pip install sphinx==2.2.0 blurb python-docs-theme
- make venv PYTHON=python
script:
- make check suspicious html SPHINXOPTS="-q -W -j4"
- name: "Documentation tests"
@ -83,19 +79,28 @@ matrix:
packages:
- xvfb
before_script:
- |
if [[ "$TRAVIS_PULL_REQUEST" != "false" ]]
then
echo "Don't run Python coverage on pull requests."
exit
fi
- ./configure
- make -j4
# Need a venv that can parse covered code.
- ./python -m venv venv
- ./venv/bin/python -m pip install -U coverage
- ./venv/bin/python -m pip install -r Misc/requirements-test.txt
- ./venv/bin/python -m test.pythoninfo
- export PYTHONPATH=`find venv -name fullcoverage`
script:
# Skip tests that re-run the entire test suite.
- xvfb-run ./venv/bin/python -m coverage run --branch --pylib -m test --fail-env-changed -uall,-cpu -x test_multiprocessing_fork -x test_multiprocessing_forkserver -x test_multiprocessing_spawn -x test_concurrent_futures || true
after_script: # Probably should be after_success once test suite updated to run under coverage.py.
# Make the `coverage` command available to Codecov w/ a version of Python that can parse all source files.
- export PYTHONPATH=
- source ./venv/bin/activate
- bash <(curl -s https://codecov.io/bash)
- bash <(curl -s https://codecov.io/bash) -y .github/codecov.yml
- name: "Test code coverage (C)"
os: linux
language: c
@ -107,12 +112,18 @@ matrix:
- lcov
- xvfb
before_script:
- |
if [[ "$TRAVIS_PULL_REQUEST" != "false" ]]
then
echo "Don't run C coverage on pull requests."
exit
fi
- ./configure
script:
- xvfb-run make -j4 coverage-report
after_script: # Probably should be after_success once test suite updated to run under coverage.py.
- make pythoninfo
- bash <(curl -s https://codecov.io/bash)
- bash <(curl -s https://codecov.io/bash) -y .github/codecov.yml
before_install:
@ -158,7 +169,9 @@ install:
before_script:
# -Og is much faster than -O0
- CFLAGS="${CFLAGS} -Og" ./configure --with-pydebug
- make -j4 regen-all
- eval "$(pyenv init -)"
- pyenv global 3.8
- PYTHON_FOR_REGEN=python3.8 make -j4 regen-all
- changes=`git status --porcelain`
- |
# Check for changes in regenerated files

2
Doc/Makefile
View File

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

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

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

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

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

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

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

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

@ -35,17 +35,11 @@ To call an object, use :c:func:`PyObject_Call` or other
The Vectorcall Protocol
-----------------------
.. versionadded:: 3.8
.. versionadded:: 3.9
The vectorcall protocol was introduced in :pep:`590` as an additional protocol
for making calls more efficient.
.. warning::
The vectorcall API is provisional and expected to become public in
Python 3.9, with a different names and, possibly, changed semantics.
If you use the it, plan for updating your code for Python 3.9.
As rule of thumb, CPython will prefer the vectorcall for internal calls
if the callable supports it. However, this is not a hard rule.
Additionally, some third-party extensions use *tp_call* directly
@ -69,7 +63,7 @@ the arguments to an args tuple and kwargs dict anyway, then there is no point
in implementing vectorcall.
Classes can implement the vectorcall protocol by enabling the
:const:`_Py_TPFLAGS_HAVE_VECTORCALL` flag and setting
:const:`Py_TPFLAGS_HAVE_VECTORCALL` flag and setting
:c:member:`~PyTypeObject.tp_vectorcall_offset` to the offset inside the
object structure where a *vectorcallfunc* appears.
This is a pointer to a function with the following signature:
@ -90,14 +84,14 @@ This is a pointer to a function with the following signature:
and they must be unique.
If there are no keyword arguments, then *kwnames* can instead be *NULL*.
.. c:var:: PY_VECTORCALL_ARGUMENTS_OFFSET
.. c:macro:: PY_VECTORCALL_ARGUMENTS_OFFSET
If this flag is set in a vectorcall *nargsf* argument, the callee is allowed
to temporarily change ``args[-1]``. In other words, *args* points to
argument 1 (not 0) in the allocated vector.
The callee must restore the value of ``args[-1]`` before returning.
For :c:func:`_PyObject_VectorcallMethod`, this flag means instead that
For :c:func:`PyObject_VectorcallMethod`, this flag means instead that
``args[0]`` may be changed.
Whenever they can do so cheaply (without additional allocation), callers
@ -107,7 +101,20 @@ This is a pointer to a function with the following signature:
To call an object that implements vectorcall, use a :ref:`call API <capi-call>`
function as with any other callable.
:c:func:`_PyObject_Vectorcall` will usually be most efficient.
:c:func:`PyObject_Vectorcall` will usually be most efficient.
.. note::
In CPython 3.8, the vectorcall API and related functions were available
provisionally under names with a leading underscore:
``_PyObject_Vectorcall``, ``_Py_TPFLAGS_HAVE_VECTORCALL``,
``_PyObject_VectorcallMethod``, ``_PyVectorcall_Function``,
``_PyObject_CallOneArg``, ``_PyObject_CallMethodNoArgs``,
``_PyObject_CallMethodOneArg``.
Additionally, ``PyObject_VectorcallDict`` was available as
``_PyObject_FastCallDict``.
The old names are still defined as aliases of the new, non-underscored names.
Recursion Control
@ -137,9 +144,11 @@ Vectorcall Support API
However, the function ``PyVectorcall_NARGS`` should be used to allow
for future extensions.
This function is not part of the :ref:`limited API <stable>`.
.. versionadded:: 3.8
.. c:function:: vectorcallfunc _PyVectorcall_Function(PyObject *op)
.. c:function:: vectorcallfunc PyVectorcall_Function(PyObject *op)
If *op* does not support the vectorcall protocol (either because the type
does not or because the specific instance does not), return *NULL*.
@ -147,7 +156,9 @@ Vectorcall Support API
This function never raises an exception.
This is mostly useful to check whether or not *op* supports vectorcall,
which can be done by checking ``_PyVectorcall_Function(op) != NULL``.
which can be done by checking ``PyVectorcall_Function(op) != NULL``.
This function is not part of the :ref:`limited API <stable>`.
.. versionadded:: 3.8
@ -158,9 +169,11 @@ Vectorcall Support API
This is a specialized function, intended to be put in the
:c:member:`~PyTypeObject.tp_call` slot or be used in an implementation of ``tp_call``.
It does not check the :const:`_Py_TPFLAGS_HAVE_VECTORCALL` flag
It does not check the :const:`Py_TPFLAGS_HAVE_VECTORCALL` flag
and it does not fall back to ``tp_call``.
This function is not part of the :ref:`limited API <stable>`.
.. versionadded:: 3.8
@ -185,7 +198,7 @@ please see individual documentation for details.
+------------------------------------------+------------------+--------------------+---------------+
| :c:func:`PyObject_CallNoArgs` | ``PyObject *`` | --- | --- |
+------------------------------------------+------------------+--------------------+---------------+
| :c:func:`_PyObject_CallOneArg` | ``PyObject *`` | 1 object | --- |
| :c:func:`PyObject_CallOneArg` | ``PyObject *`` | 1 object | --- |
+------------------------------------------+------------------+--------------------+---------------+
| :c:func:`PyObject_CallObject` | ``PyObject *`` | tuple/``NULL`` | --- |
+------------------------------------------+------------------+--------------------+---------------+
@ -197,15 +210,15 @@ please see individual documentation for details.
+------------------------------------------+------------------+--------------------+---------------+
| :c:func:`PyObject_CallMethodObjArgs` | obj + name | variadic | --- |
+------------------------------------------+------------------+--------------------+---------------+
| :c:func:`_PyObject_CallMethodNoArgs` | obj + name | --- | --- |
| :c:func:`PyObject_CallMethodNoArgs` | obj + name | --- | --- |
+------------------------------------------+------------------+--------------------+---------------+
| :c:func:`_PyObject_CallMethodOneArg` | obj + name | 1 object | --- |
| :c:func:`PyObject_CallMethodOneArg` | obj + name | 1 object | --- |
+------------------------------------------+------------------+--------------------+---------------+
| :c:func:`_PyObject_Vectorcall` | ``PyObject *`` | vectorcall | vectorcall |
| :c:func:`PyObject_Vectorcall` | ``PyObject *`` | vectorcall | vectorcall |
+------------------------------------------+------------------+--------------------+---------------+
| :c:func:`_PyObject_FastCallDict` | ``PyObject *`` | vectorcall | dict/``NULL`` |
| :c:func:`PyObject_VectorcallDict` | ``PyObject *`` | vectorcall | dict/``NULL`` |
+------------------------------------------+------------------+--------------------+---------------+
| :c:func:`_PyObject_VectorcallMethod` | arg + name | vectorcall | vectorcall |
| :c:func:`PyObject_VectorcallMethod` | arg + name | vectorcall | vectorcall |
+------------------------------------------+------------------+--------------------+---------------+
@ -235,7 +248,7 @@ please see individual documentation for details.
.. versionadded:: 3.9
.. c:function:: PyObject* _PyObject_CallOneArg(PyObject *callable, PyObject *arg)
.. c:function:: PyObject* PyObject_CallOneArg(PyObject *callable, PyObject *arg)
Call a callable Python object *callable* with exactly 1 positional argument
*arg* and no keyword arguments.
@ -243,6 +256,8 @@ please see individual documentation for details.
Return the result of the call on success, or raise an exception and return
*NULL* on failure.
This function is not part of the :ref:`limited API <stable>`.
.. versionadded:: 3.9
@ -268,7 +283,7 @@ please see individual documentation for details.
This is the equivalent of the Python expression: ``callable(*args)``.
Note that if you only pass :c:type:`PyObject \*` args,
Note that if you only pass :c:type:`PyObject *` args,
:c:func:`PyObject_CallFunctionObjArgs` is a faster alternative.
.. versionchanged:: 3.4
@ -289,17 +304,17 @@ please see individual documentation for details.
This is the equivalent of the Python expression:
``obj.name(arg1, arg2, ...)``.
Note that if you only pass :c:type:`PyObject \*` args,
Note that if you only pass :c:type:`PyObject *` args,
:c:func:`PyObject_CallMethodObjArgs` is a faster alternative.
.. versionchanged:: 3.4
The types of *name* and *format* were changed from ``char *``.
.. c:function:: PyObject* PyObject_CallFunctionObjArgs(PyObject *callable, ..., NULL)
.. c:function:: PyObject* PyObject_CallFunctionObjArgs(PyObject *callable, ...)
Call a callable Python object *callable*, with a variable number of
:c:type:`PyObject \*` arguments. The arguments are provided as a variable number
:c:type:`PyObject *` arguments. The arguments are provided as a variable number
of parameters followed by *NULL*.
Return the result of the call on success, or raise an exception and return
@ -309,18 +324,18 @@ please see individual documentation for details.
``callable(arg1, arg2, ...)``.
.. c:function:: PyObject* PyObject_CallMethodObjArgs(PyObject *obj, PyObject *name, ..., NULL)
.. c:function:: PyObject* PyObject_CallMethodObjArgs(PyObject *obj, PyObject *name, ...)
Call a method of the Python object *obj*, where the name of the method is given as a
Python string object in *name*. It is called with a variable number of
:c:type:`PyObject \*` arguments. The arguments are provided as a variable number
:c:type:`PyObject *` arguments. The arguments are provided as a variable number
of parameters followed by *NULL*.
Return the result of the call on success, or raise an exception and return
*NULL* on failure.
.. c:function:: PyObject* _PyObject_CallMethodNoArgs(PyObject *obj, PyObject *name)
.. c:function:: PyObject* PyObject_CallMethodNoArgs(PyObject *obj, PyObject *name)
Call a method of the Python object *obj* without arguments,
where the name of the method is given as a Python string object in *name*.
@ -328,10 +343,12 @@ please see individual documentation for details.
Return the result of the call on success, or raise an exception and return
*NULL* on failure.
This function is not part of the :ref:`limited API <stable>`.
.. versionadded:: 3.9
.. c:function:: PyObject* _PyObject_CallMethodOneArg(PyObject *obj, PyObject *name, PyObject *arg)
.. c:function:: PyObject* PyObject_CallMethodOneArg(PyObject *obj, PyObject *name, PyObject *arg)
Call a method of the Python object *obj* with a single positional argument
*arg*, where the name of the method is given as a Python string object in
@ -340,10 +357,12 @@ please see individual documentation for details.
Return the result of the call on success, or raise an exception and return
*NULL* on failure.
This function is not part of the :ref:`limited API <stable>`.
.. versionadded:: 3.9
.. c:function:: PyObject* _PyObject_Vectorcall(PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwnames)
.. c:function:: PyObject* PyObject_Vectorcall(PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwnames)
Call a callable Python object *callable*.
The arguments are the same as for :c:type:`vectorcallfunc`.
@ -353,15 +372,11 @@ please see individual documentation for details.
Return the result of the call on success, or raise an exception and return
*NULL* on failure.
.. note::
This function is not part of the :ref:`limited API <stable>`.
This function is provisional and expected to become public in Python 3.9,
with a different name and, possibly, changed semantics.
If you use the function, plan for updating your code for Python 3.9.
.. versionadded:: 3.9
.. versionadded:: 3.8
.. c:function:: PyObject* _PyObject_FastCallDict(PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwdict)
.. c:function:: PyObject* PyObject_VectorcallDict(PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwdict)
Call *callable* with positional arguments passed exactly as in the vectorcall_ protocol,
but with keyword arguments passed as a dictionary *kwdict*.
@ -373,15 +388,11 @@ please see individual documentation for details.
already has a dictionary ready to use for the keyword arguments,
but not a tuple for the positional arguments.
.. note::
This function is not part of the :ref:`limited API <stable>`.
This function is provisional and expected to become public in Python 3.9,
with a different name and, possibly, changed semantics.
If you use the function, plan for updating your code for Python 3.9.
.. versionadded:: 3.9
.. versionadded:: 3.8
.. c:function:: PyObject* _PyObject_VectorcallMethod(PyObject *name, PyObject *const *args, size_t nargsf, PyObject *kwnames)
.. c:function:: PyObject* PyObject_VectorcallMethod(PyObject *name, PyObject *const *args, size_t nargsf, PyObject *kwnames)
Call a method using the vectorcall calling convention. The name of the method
is given as a Python string *name*. The object whose method is called is
@ -390,7 +401,7 @@ please see individual documentation for details.
*nargsf* is the number of positional arguments including *args[0]*,
plus :const:`PY_VECTORCALL_ARGUMENTS_OFFSET` if the value of ``args[0]`` may
temporarily be changed. Keyword arguments can be passed just like in
:c:func:`_PyObject_Vectorcall`.
:c:func:`PyObject_Vectorcall`.
If the object has the :const:`Py_TPFLAGS_METHOD_DESCRIPTOR` feature,
this will call the unbound method object with the full
@ -399,6 +410,8 @@ please see individual documentation for details.
Return the result of the call on success, or raise an exception and return
*NULL* on failure.
This function is not part of the :ref:`limited API <stable>`.
.. versionadded:: 3.9

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

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

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

@ -42,7 +42,7 @@ bound into a function.
.. c:function:: PyCodeObject* PyCode_NewWithPosOnlyArgs(int argcount, int posonlyargcount, int kwonlyargcount, int nlocals, int stacksize, int flags, PyObject *code, PyObject *consts, PyObject *names, PyObject *varnames, PyObject *freevars, PyObject *cellvars, PyObject *filename, PyObject *name, int firstlineno, PyObject *lnotab)
Similar to :c:func:`PyCode_New`, but with an extra "posonlyargcount" for positonal-only arguments.
Similar to :c:func:`PyCode_New`, but with an extra "posonlyargcount" for positional-only arguments.
.. versionadded:: 3.8

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

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

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

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

5
Doc/c-api/contextvars.rst
View File

@ -101,11 +101,6 @@ Context object management functions:
current context for the current thread. Returns ``0`` on success,
and ``-1`` on error.
.. c:function:: int PyContext_ClearFreeList()
Clear the context variable free list. Return the total number of
freed items. This function always succeeds.
Context variable functions:

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

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

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

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

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

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

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

@ -62,32 +62,35 @@ Dictionary Objects
.. c:function:: int PyDict_SetItem(PyObject *p, PyObject *key, PyObject *val)
Insert *value* into the dictionary *p* with a key of *key*. *key* must be
Insert *val* into the dictionary *p* with a key of *key*. *key* must be
:term:`hashable`; if it isn't, :exc:`TypeError` will be raised. Return
``0`` on success or ``-1`` on failure.
``0`` on success or ``-1`` on failure. This function *does not* steal a
reference to *val*.
.. c:function:: int PyDict_SetItemString(PyObject *p, const char *key, PyObject *val)
.. index:: single: PyUnicode_FromString()
Insert *value* into the dictionary *p* using *key* as a key. *key* should
be a :c:type:`const char\*`. The key object is created using
Insert *val* into the dictionary *p* using *key* as a key. *key* should
be a :c:type:`const char*`. The key object is created using
``PyUnicode_FromString(key)``. Return ``0`` on success or ``-1`` on
failure.
failure. This function *does not* steal a reference to *val*.
.. c:function:: int PyDict_DelItem(PyObject *p, PyObject *key)
Remove the entry in dictionary *p* with key *key*. *key* must be hashable;
if it isn't, :exc:`TypeError` is raised. Return ``0`` on success or ``-1``
on failure.
if it isn't, :exc:`TypeError` is raised.
If *key* is not in the dictionary, :exc:`KeyError` is raised.
Return ``0`` on success or ``-1`` on failure.
.. c:function:: int PyDict_DelItemString(PyObject *p, const char *key)
Remove the entry in dictionary *p* which has a key specified by the string
*key*. Return ``0`` on success or ``-1`` on failure.
Remove the entry in dictionary *p* which has a key specified by the string *key*.
If *key* is not in the dictionary, :exc:`KeyError` is raised.
Return ``0`` on success or ``-1`` on failure.
.. c:function:: PyObject* PyDict_GetItem(PyObject *p, PyObject *key)
@ -99,6 +102,10 @@ Dictionary Objects
:meth:`__eq__` methods will get suppressed.
To get error reporting use :c:func:`PyDict_GetItemWithError()` instead.
.. versionchanged:: 3.10
Calling this API without :term:`GIL` held had been allowed for historical
reason. It is no longer allowed.
.. c:function:: PyObject* PyDict_GetItemWithError(PyObject *p, PyObject *key)
@ -111,7 +118,7 @@ Dictionary Objects
.. c:function:: PyObject* PyDict_GetItemString(PyObject *p, const char *key)
This is the same as :c:func:`PyDict_GetItem`, but *key* is specified as a
:c:type:`const char\*`, rather than a :c:type:`PyObject\*`.
:c:type:`const char*`, rather than a :c:type:`PyObject*`.
Note that exceptions which occur while calling :meth:`__hash__` and
:meth:`__eq__` methods and creating a temporary string object
@ -160,7 +167,7 @@ Dictionary Objects
prior to the first call to this function to start the iteration; the
function returns true for each pair in the dictionary, and false once all
pairs have been reported. The parameters *pkey* and *pvalue* should either
point to :c:type:`PyObject\*` variables that will be filled in with each key
point to :c:type:`PyObject*` variables that will be filled in with each key
and value, respectively, or may be ``NULL``. Any references returned through
them are borrowed. *ppos* should not be altered during iteration. Its
value represents offsets within the internal dictionary structure, and
@ -231,10 +238,3 @@ Dictionary Objects
for key, value in seq2:
if override or key not in a:
a[key] = value
.. c:function:: int PyDict_ClearFreeList()
Clear the free list. Return the total number of freed items.
.. versionadded:: 3.3

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

@ -358,7 +358,7 @@ an error value).
.. c:function:: int PyErr_ResourceWarning(PyObject *source, Py_ssize_t stack_level, const char *format, ...)
Function similar to :c:func:`PyErr_WarnFormat`, but *category* is
:exc:`ResourceWarning` and pass *source* to :func:`warnings.WarningMessage`.
:exc:`ResourceWarning` and it passes *source* to :func:`warnings.WarningMessage`.
.. versionadded:: 3.6
@ -637,11 +637,21 @@ The following functions are used to create and modify Unicode exceptions from C.
*object*, *length*, *start*, *end* and *reason*. *encoding* and *reason* are
UTF-8 encoded strings.
.. deprecated:: 3.3 3.11
``Py_UNICODE`` is deprecated since Python 3.3. Please migrate to
``PyObject_CallFunction(PyExc_UnicodeEncodeError, "sOnns", ...)``.
.. c:function:: PyObject* PyUnicodeTranslateError_Create(const Py_UNICODE *object, Py_ssize_t length, Py_ssize_t start, Py_ssize_t end, const char *reason)
Create a :class:`UnicodeTranslateError` object with the attributes *object*,
*length*, *start*, *end* and *reason*. *reason* is a UTF-8 encoded string.
.. deprecated:: 3.3 3.11
``Py_UNICODE`` is deprecated since Python 3.3. Please migrate to
``PyObject_CallFunction(PyExc_UnicodeTranslateError, "Onns", ...)``.
.. c:function:: PyObject* PyUnicodeDecodeError_GetEncoding(PyObject *exc)
PyObject* PyUnicodeEncodeError_GetEncoding(PyObject *exc)
@ -773,7 +783,7 @@ Standard Exceptions
All standard Python exceptions are available as global variables whose names are
``PyExc_`` followed by the Python exception name. These have the type
:c:type:`PyObject\*`; they are all class objects. For completeness, here are all
:c:type:`PyObject*`; they are all class objects. For completeness, here are all
the variables:
.. index::
@ -983,9 +993,6 @@ Notes:
This is a base class for other standard exceptions.
(2)
This is the same as :exc:`weakref.ReferenceError`.
(3)
Only defined on Windows; protect code that uses this by testing that the
preprocessor macro ``MS_WINDOWS`` is defined.
@ -996,7 +1003,7 @@ Standard Warning Categories
All standard Python warning categories are available as global variables whose
names are ``PyExc_`` followed by the Python exception name. These have the type
:c:type:`PyObject\*`; they are all class objects. For completeness, here are all
:c:type:`PyObject*`; they are all class objects. For completeness, here are all
the variables:
.. index::

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

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

5
Doc/c-api/float.rst
View File

@ -76,8 +76,3 @@ Floating Point Objects
.. c:function:: double PyFloat_GetMin()
Return the minimum normalized positive float *DBL_MIN* as C :c:type:`double`.
.. c:function:: int PyFloat_ClearFreeList()
Clear the float free list. Return the number of items that could not
be freed.

27
Doc/c-api/gcsupport.rst
View File

@ -61,6 +61,33 @@ Constructors for container types must conform to two rules:
end of the constructor.
.. c:function:: int PyObject_IS_GC(PyObject *obj)
Returns non-zero if the object implements the garbage collector protocol,
otherwise returns 0.
The object cannot be tracked by the garbage collector if this function returns 0.
.. c:function:: int PyObject_GC_IsTracked(PyObject *op)
Returns 1 if the object type of *op* implements the GC protocol and *op* is being
currently tracked by the garbage collector and 0 otherwise.
This is analogous to the Python function :func:`gc.is_tracked`.
.. versionadded:: 3.9
.. c:function:: int PyObject_GC_IsFinalized(PyObject *op)
Returns 1 if the object type of *op* implements the GC protocol and *op* has been
already finalized by the garbage collector and 0 otherwise.
This is analogous to the Python function :func:`gc.is_finalized`.
.. versionadded:: 3.9
Similarly, the deallocator for the object must conform to a similar pair of
rules:

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

@ -81,7 +81,7 @@ When a flag is set by an option, the value of the flag is the number of times
that the option was set. For example, ``-b`` sets :c:data:`Py_BytesWarningFlag`
to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
.. c:var:: Py_BytesWarningFlag
.. c:var:: int Py_BytesWarningFlag
Issue a warning when comparing :class:`bytes` or :class:`bytearray` with
:class:`str` or :class:`bytes` with :class:`int`. Issue an error if greater
@ -89,7 +89,7 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
Set by the :option:`-b` option.
.. c:var:: Py_DebugFlag
.. c:var:: int Py_DebugFlag
Turn on parser debugging output (for expert only, depending on compilation
options).
@ -97,7 +97,7 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
Set by the :option:`-d` option and the :envvar:`PYTHONDEBUG` environment
variable.
.. c:var:: Py_DontWriteBytecodeFlag
.. c:var:: int Py_DontWriteBytecodeFlag
If set to non-zero, Python won't try to write ``.pyc`` files on the
import of source modules.
@ -105,14 +105,14 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
Set by the :option:`-B` option and the :envvar:`PYTHONDONTWRITEBYTECODE`
environment variable.
.. c:var:: Py_FrozenFlag
.. c:var:: int Py_FrozenFlag
Suppress error messages when calculating the module search path in
:c:func:`Py_GetPath`.
Private flag used by ``_freeze_importlib`` and ``frozenmain`` programs.
.. c:var:: Py_HashRandomizationFlag
.. c:var:: int Py_HashRandomizationFlag
Set to ``1`` if the :envvar:`PYTHONHASHSEED` environment variable is set to
a non-empty string.
@ -120,14 +120,14 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
If the flag is non-zero, read the :envvar:`PYTHONHASHSEED` environment
variable to initialize the secret hash seed.
.. c:var:: Py_IgnoreEnvironmentFlag
.. c:var:: int Py_IgnoreEnvironmentFlag
Ignore all :envvar:`PYTHON*` environment variables, e.g.
:envvar:`PYTHONPATH` and :envvar:`PYTHONHOME`, that might be set.
Set by the :option:`-E` and :option:`-I` options.
.. c:var:: Py_InspectFlag
.. c:var:: int Py_InspectFlag
When a script is passed as first argument or the :option:`-c` option is used,
enter interactive mode after executing the script or the command, even when
@ -136,11 +136,11 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
Set by the :option:`-i` option and the :envvar:`PYTHONINSPECT` environment
variable.
.. c:var:: Py_InteractiveFlag
.. c:var:: int Py_InteractiveFlag
Set by the :option:`-i` option.
.. c:var:: Py_IsolatedFlag
.. c:var:: int Py_IsolatedFlag
Run Python in isolated mode. In isolated mode :data:`sys.path` contains
neither the script's directory nor the user's site-packages directory.
@ -149,7 +149,7 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
.. versionadded:: 3.4
.. c:var:: Py_LegacyWindowsFSEncodingFlag
.. c:var:: int Py_LegacyWindowsFSEncodingFlag
If the flag is non-zero, use the ``mbcs`` encoding instead of the UTF-8
encoding for the filesystem encoding.
@ -161,7 +161,7 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
.. availability:: Windows.
.. c:var:: Py_LegacyWindowsStdioFlag
.. c:var:: int Py_LegacyWindowsStdioFlag
If the flag is non-zero, use :class:`io.FileIO` instead of
:class:`WindowsConsoleIO` for :mod:`sys` standard streams.
@ -173,7 +173,7 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
.. availability:: Windows.
.. c:var:: Py_NoSiteFlag
.. c:var:: int Py_NoSiteFlag
Disable the import of the module :mod:`site` and the site-dependent
manipulations of :data:`sys.path` that it entails. Also disable these
@ -182,7 +182,7 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
Set by the :option:`-S` option.
.. c:var:: Py_NoUserSiteDirectory
.. c:var:: int Py_NoUserSiteDirectory
Don't add the :data:`user site-packages directory <site.USER_SITE>` to
:data:`sys.path`.
@ -190,12 +190,12 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
Set by the :option:`-s` and :option:`-I` options, and the
:envvar:`PYTHONNOUSERSITE` environment variable.
.. c:var:: Py_OptimizeFlag
.. c:var:: int Py_OptimizeFlag
Set by the :option:`-O` option and the :envvar:`PYTHONOPTIMIZE` environment
variable.
.. c:var:: Py_QuietFlag
.. c:var:: int Py_QuietFlag
Don't display the copyright and version messages even in interactive mode.
@ -203,14 +203,14 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
.. versionadded:: 3.2
.. c:var:: Py_UnbufferedStdioFlag
.. c:var:: int Py_UnbufferedStdioFlag
Force the stdout and stderr streams to be unbuffered.
Set by the :option:`-u` option and the :envvar:`PYTHONUNBUFFERED`
environment variable.
.. c:var:: Py_VerboseFlag
.. c:var:: int Py_VerboseFlag
Print a message each time a module is initialized, showing the place
(filename or built-in module) from which it is loaded. If greater or equal
@ -830,7 +830,7 @@ code, or when embedding the Python interpreter:
.. c:type:: PyThreadState
This data structure represents the state of a single thread. The only public
data member is :c:type:`PyInterpreterState \*`:attr:`interp`, which points to
data member is :attr:`interp` (:c:type:`PyInterpreterState *`), which points to
this thread's interpreter state.
@ -842,12 +842,12 @@ code, or when embedding the Python interpreter:
single: PyEval_SaveThread()
single: PyEval_RestoreThread()
Initialize and acquire the global interpreter lock. It should be called in the
main thread before creating a second thread or engaging in any other thread
operations such as ``PyEval_ReleaseThread(tstate)``. It is not needed before
calling :c:func:`PyEval_SaveThread` or :c:func:`PyEval_RestoreThread`.
Deprecated function which does nothing.
This is a no-op when called for a second time.
In Python 3.6 and older, this function created the GIL if it didn't exist.
.. versionchanged:: 3.9
The function now does nothing.
.. versionchanged:: 3.7
This function is now called by :c:func:`Py_Initialize()`, so you don't
@ -856,6 +856,8 @@ code, or when embedding the Python interpreter:
.. versionchanged:: 3.2
This function cannot be called before :c:func:`Py_Initialize()` anymore.
.. deprecated-removed:: 3.9 3.11
.. index:: module: _thread
@ -868,6 +870,8 @@ code, or when embedding the Python interpreter:
.. versionchanged:: 3.7
The :term:`GIL` is now initialized by :c:func:`Py_Initialize()`.
.. deprecated-removed:: 3.9 3.11
.. c:function:: PyThreadState* PyEval_SaveThread()
@ -1048,6 +1052,10 @@ All of the following functions must be called after :c:func:`Py_Initialize`.
Reset all information in a thread state object. The global interpreter lock
must be held.
.. versionchanged:: 3.9
This function now calls the :c:member:`PyThreadState.on_delete` callback.
Previously, that happened in :c:func:`PyThreadState_Delete`.
.. c:function:: void PyThreadState_Delete(PyThreadState *tstate)
@ -1056,19 +1064,65 @@ All of the following functions must be called after :c:func:`Py_Initialize`.
:c:func:`PyThreadState_Clear`.
.. c:function:: void PyThreadState_DeleteCurrent()
.. c:function:: void PyThreadState_DeleteCurrent(void)
Destroy the current thread state and release the global interpreter lock.
Like :c:func:`PyThreadState_Delete`, the global interpreter lock need not
be held. The thread state must have been reset with a previous call
to :c:func:`PyThreadState_Clear`.
Destroy the current thread state and release the global interpreter lock.
Like :c:func:`PyThreadState_Delete`, the global interpreter lock need not
be held. The thread state must have been reset with a previous call
to :c:func:`PyThreadState_Clear`.
.. c:function:: PY_INT64_T PyInterpreterState_GetID(PyInterpreterState *interp)
.. c:function:: PyFrameObject* PyThreadState_GetFrame(PyThreadState *tstate)
Get the current frame of the Python thread state *tstate*.
Return a strong reference. Return ``NULL`` if no frame is currently
executing.
See also :c:func:`PyEval_GetFrame`.
*tstate* must not be ``NULL``.
.. versionadded:: 3.9
.. c:function:: uint64_t PyThreadState_GetID(PyThreadState *tstate)
Get the unique thread state identifier of the Python thread state *tstate*.
*tstate* must not be ``NULL``.
.. versionadded:: 3.9
.. c:function:: PyInterpreterState* PyThreadState_GetInterpreter(PyThreadState *tstate)
Get the interpreter of the Python thread state *tstate*.
*tstate* must not be ``NULL``.
.. versionadded:: 3.9
.. c:function:: PyInterpreterState* PyInterpreterState_Get(void)
Get the current interpreter.
Issue a fatal error if there no current Python thread state or no current
interpreter. It cannot return NULL.
The caller must hold the GIL.
.. versionadded:: 3.9
.. c:function:: int64_t PyInterpreterState_GetID(PyInterpreterState *interp)
Return the interpreter's unique ID. If there was any error in doing
so then ``-1`` is returned and an error is set.
The caller must hold the GIL.
.. versionadded:: 3.7
@ -1083,6 +1137,32 @@ All of the following functions must be called after :c:func:`Py_Initialize`.
.. versionadded:: 3.8
.. c:type:: PyObject* (*_PyFrameEvalFunction)(PyThreadState *tstate, PyFrameObject *frame, int throwflag)
Type of a frame evaluation function.
The *throwflag* parameter is used by the ``throw()`` method of generators:
if non-zero, handle the current exception.
.. versionchanged:: 3.9
The function now takes a *tstate* parameter.
.. c:function:: _PyFrameEvalFunction _PyInterpreterState_GetEvalFrameFunc(PyInterpreterState *interp)
Get the frame evaluation function.
See the :pep:`523` "Adding a frame evaluation API to CPython".
.. versionadded:: 3.9
.. c:function:: void _PyInterpreterState_SetEvalFrameFunc(PyInterpreterState *interp, _PyFrameEvalFunction eval_frame);
Set the frame evaluation function.
See the :pep:`523` "Adding a frame evaluation API to CPython".
.. versionadded:: 3.9
.. c:function:: PyObject* PyThreadState_GetDict()
@ -1110,7 +1190,7 @@ All of the following functions must be called after :c:func:`Py_Initialize`.
.. c:function:: void PyEval_AcquireThread(PyThreadState *tstate)
Acquire the global interpreter lock and set the current thread state to
*tstate*, which should not be ``NULL``. The lock must have been created earlier.
*tstate*, which must not be ``NULL``. The lock must have been created earlier.
If this thread already has the lock, deadlock ensues.
.. note::
@ -1189,7 +1269,7 @@ It is usually the only Python interpreter in a process. Unlike sub-interpreters
the main interpreter has unique process-global responsibilities like signal
handling. It is also responsible for execution during runtime initialization and
is usually the active interpreter during runtime finalization. The
:c:func:`PyInterpreterState_Main` funtion returns a pointer to its state.
:c:func:`PyInterpreterState_Main` function returns a pointer to its state.
You can switch between sub-interpreters using the :c:func:`PyThreadState_Swap`
function. You can create and destroy them using the following functions:
@ -1230,15 +1310,31 @@ function. You can create and destroy them using the following functions:
single: Py_FinalizeEx()
single: Py_Initialize()
Extension modules are shared between (sub-)interpreters as follows: the first
time a particular extension is imported, it is initialized normally, and a
(shallow) copy of its module's dictionary is squirreled away. When the same
extension is imported by another (sub-)interpreter, a new module is initialized
and filled with the contents of this copy; the extension's ``init`` function is
not called. Note that this is different from what happens when an extension is
imported after the interpreter has been completely re-initialized by calling
:c:func:`Py_FinalizeEx` and :c:func:`Py_Initialize`; in that case, the extension's
``initmodule`` function *is* called again.
Extension modules are shared between (sub-)interpreters as follows:
* For modules using multi-phase initialization,
e.g. :c:func:`PyModule_FromDefAndSpec`, a separate module object is
created and initialized for each interpreter.
Only C-level static and global variables are shared between these
module objects.
* For modules using single-phase initialization,
e.g. :c:func:`PyModule_Create`, the first time a particular extension
is imported, it is initialized normally, and a (shallow) copy of its
module's dictionary is squirreled away.
When the same extension is imported by another (sub-)interpreter, a new
module is initialized and filled with the contents of this copy; the
extension's ``init`` function is not called.
Objects in the module's dictionary thus end up shared across
(sub-)interpreters, which might cause unwanted behavior (see
`Bugs and caveats`_ below).
Note that this is different from what happens when an extension is
imported after the interpreter has been completely re-initialized by
calling :c:func:`Py_FinalizeEx` and :c:func:`Py_Initialize`; in that
case, the extension's ``initmodule`` function *is* called again.
As with multi-phase initialization, this means that only C-level static
and global variables are shared between these modules.
.. index:: single: close() (in module os)
@ -1264,14 +1360,16 @@ process, the insulation between them isn't perfect --- for example, using
low-level file operations like :func:`os.close` they can
(accidentally or maliciously) affect each other's open files. Because of the
way extensions are shared between (sub-)interpreters, some extensions may not
work properly; this is especially likely when the extension makes use of
(static) global variables, or when the extension manipulates its module's
dictionary after its initialization. It is possible to insert objects created
in one sub-interpreter into a namespace of another sub-interpreter; this should
be done with great care to avoid sharing user-defined functions, methods,
instances or classes between sub-interpreters, since import operations executed
by such objects may affect the wrong (sub-)interpreter's dictionary of loaded
modules.
work properly; this is especially likely when using single-phase initialization
or (static) global variables.
It is possible to insert objects created in one sub-interpreter into
a namespace of another (sub-)interpreter; this should be avoided if possible.
Special care should be taken to avoid sharing user-defined functions,
methods, instances or classes between sub-interpreters, since import
operations executed by such objects may affect the wrong (sub-)interpreter's
dictionary of loaded modules. It is equally important to avoid sharing
objects from which the above are reachable.
Also note that combining this functionality with :c:func:`PyGILState_\*` APIs
is delicate, because these APIs assume a bijection between Python thread states
@ -1316,6 +1414,10 @@ pointer and a void pointer argument.
This function doesn't need a current thread state to run, and it doesn't
need the global interpreter lock.
To call this function in a subinterpreter, the caller must hold the GIL.
Otherwise, the function *func* can be scheduled to be called from the wrong
interpreter.
.. warning::
This is a low-level function, only useful for very special cases.
There is no guarantee that *func* will be called as quick as
@ -1324,6 +1426,12 @@ pointer and a void pointer argument.
function is generally **not** suitable for calling Python code from
arbitrary C threads. Instead, use the :ref:`PyGILState API<gilstate>`.
.. versionchanged:: 3.9
If this function is called in a subinterpreter, the function *func* is
now scheduled to be called from the subinterpreter, rather than being
called from the main interpreter. Each subinterpreter now has its own
list of scheduled calls.
.. versionadded:: 3.1
.. _profiling:
@ -1446,6 +1554,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`.
The caller must hold the :term:`GIL`.
.. c:function:: void PyEval_SetTrace(Py_tracefunc func, PyObject *obj)
@ -1456,6 +1566,9 @@ 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.
The caller must hold the :term:`GIL`.
.. _advanced-debugging:
Advanced Debugger Support
@ -1506,7 +1619,7 @@ The Python interpreter provides low-level support for thread-local storage
(TLS) which wraps the underlying native TLS implementation to support the
Python-level thread local storage API (:class:`threading.local`). The
CPython C level APIs are similar to those offered by pthreads and Windows:
use a thread key and functions to associate a :c:type:`void\*` value per
use a thread key and functions to associate a :c:type:`void*` value per
thread.
The GIL does *not* need to be held when calling these functions; they supply
@ -1517,8 +1630,8 @@ you need to include :file:`pythread.h` to use thread-local storage.
.. note::
None of these API functions handle memory management on behalf of the
:c:type:`void\*` values. You need to allocate and deallocate them yourself.
If the :c:type:`void\*` values happen to be :c:type:`PyObject\*`, these
:c:type:`void*` values. You need to allocate and deallocate them yourself.
If the :c:type:`void*` values happen to be :c:type:`PyObject*`, these
functions don't do refcount operations on them either.
.. _thread-specific-storage-api:
@ -1614,14 +1727,14 @@ undefined if the given :c:type:`Py_tss_t` has not been initialized by
.. c:function:: int PyThread_tss_set(Py_tss_t *key, void *value)
Return a zero value to indicate successfully associating a :c:type:`void\*`
Return a zero value to indicate successfully associating a :c:type:`void*`
value with a TSS key in the current thread. Each thread has a distinct
mapping of the key to a :c:type:`void\*` value.
mapping of the key to a :c:type:`void*` value.
.. c:function:: void* PyThread_tss_get(Py_tss_t *key)
Return the :c:type:`void\*` value associated with a TSS key in the current
Return the :c:type:`void*` value associated with a TSS key in the current
thread. This returns ``NULL`` if no value is associated with the key in the
current thread.

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

@ -43,6 +43,7 @@ Functions:
* :c:func:`Py_PreInitializeFromArgs`
* :c:func:`Py_PreInitializeFromBytesArgs`
* :c:func:`Py_RunMain`
* :c:func:`Py_GetArgcArgv`
The preconfiguration (``PyPreConfig`` type) is stored in
``_PyRuntime.preconfig`` and the configuration (``PyConfig`` type) is stored in
@ -196,12 +197,12 @@ PyPreConfig
Function to initialize a preconfiguration:
.. c:function:: void PyPreConfig_InitIsolatedConfig(PyPreConfig *preconfig)
.. c:function:: void PyPreConfig_InitPythonConfig(PyPreConfig *preconfig)
Initialize the preconfiguration with :ref:`Python Configuration
<init-python-config>`.
.. c:function:: void PyPreConfig_InitPythonConfig(PyPreConfig *preconfig)
.. c:function:: void PyPreConfig_InitIsolatedConfig(PyPreConfig *preconfig)
Initialize the preconfiguration with :ref:`Isolated Configuration
<init-isolated-conf>`.
@ -423,6 +424,8 @@ PyConfig
:c:member:`~PyConfig.argv` is empty, an empty string is added to ensure
that :data:`sys.argv` always exists and is never empty.
See also the :c:member:`~PyConfig.orig_argv` member.
.. c:member:: wchar_t* base_exec_prefix
:data:`sys.base_exec_prefix`.
@ -436,6 +439,14 @@ PyConfig
:data:`sys.base_prefix`.
.. c:member:: wchar_t* platlibdir
:data:`sys.platlibdir`: platform library directory name, set at configure time
by ``--with-platlibdir``, overrideable by the ``PYTHONPLATLIBDIR``
environment variable.
.. versionadded:: 3.9
.. c:member:: int buffered_stdio
If equals to 0, enable unbuffered mode, making the stdout and stderr
@ -466,13 +477,13 @@ PyConfig
.. c:member:: int dev_mode
Development mode: see :option:`-X dev <-X>`.
If non-zero, enable the :ref:`Python Development Mode <devmode>`.
.. c:member:: int dump_refs
If non-zero, dump all objects which are still alive at exit.
Require a debug build of Python (``Py_REF_DEBUG`` macro must be defined).
``Py_TRACE_REFS`` macro must be defined in build.
.. c:member:: wchar_t* exec_prefix
@ -577,6 +588,23 @@ PyConfig
* 1: Remove assertions, set ``__debug__`` to ``False``
* 2: Strip docstrings
.. c:member:: PyWideStringList orig_argv
The list of the original command line arguments passed to the Python
executable.
If :c:member:`~PyConfig.orig_argv` list is empty and
:c:member:`~PyConfig.argv` is not a list only containing an empty
string, :c:func:`PyConfig_Read()` copies :c:member:`~PyConfig.argv` into
:c:member:`~PyConfig.orig_argv` before modifying
:c:member:`~PyConfig.argv` (if :c:member:`~PyConfig.parse_argv` is
non-zero).
See also the :c:member:`~PyConfig.argv` member and the
:c:func:`Py_GetArgcArgv` function.
.. versionadded:: 3.10
.. c:member:: int parse_argv
If non-zero, parse :c:member:`~PyConfig.argv` the same way the regular
@ -627,14 +655,6 @@ PyConfig
``python3 -m MODULE`` argument. Used by :c:func:`Py_RunMain`.
.. c:member:: int show_alloc_count
Show allocation counts at exit?
Set to 1 by :option:`-X showalloccount <-X>` command line option.
Need a special Python build with ``COUNT_ALLOCS`` macro defined.
.. c:member:: int show_ref_count
Show total reference count at exit?
@ -702,6 +722,10 @@ arguments are stripped from ``argv``: see :ref:`Command Line Arguments
The ``xoptions`` options are parsed to set other options: see :option:`-X`
option.
.. versionchanged:: 3.9
The ``show_alloc_count`` field has been removed.
Initialization with PyConfig
----------------------------
@ -757,7 +781,7 @@ configuration, and then override some parameters::
PyConfig config;
PyConfig_InitPythonConfig(&config);
/* Set the program name before reading the configuraton
/* Set the program name before reading the configuration
(decode byte string from the locale encoding).
Implicitly preinitialize Python. */
@ -878,6 +902,7 @@ Path Configuration
* Path configuration inputs:
* :c:member:`PyConfig.home`
* :c:member:`PyConfig.platlibdir`
* :c:member:`PyConfig.pathconfig_warnings`
* :c:member:`PyConfig.program_name`
* :c:member:`PyConfig.pythonpath_env`
@ -969,6 +994,16 @@ customized Python always running in isolated mode using
:c:func:`Py_RunMain`.
Py_GetArgcArgv()
----------------
.. c:function:: void Py_GetArgcArgv(int *argc, wchar_t ***argv)
Get the original command line arguments, before Python modified them.
See also :c:member:`PyConfig.orig_argv` member.
Multi-Phase Initialization Private Provisional API
--------------------------------------------------
@ -998,6 +1033,8 @@ Private provisional API:
* :c:member:`PyConfig._init_main`: if set to 0,
:c:func:`Py_InitializeFromConfig` stops at the "Core" initialization phase.
* :c:member:`PyConfig._isolated_interpreter`: if non-zero,
disallow threads, subprocesses and fork.
.. c:function:: PyStatus _Py_InitializeMain(void)

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

@ -107,11 +107,24 @@ complete listing.
.. c:macro:: Py_UNREACHABLE()
Use this when you have a code path that you do not expect to be reached.
Use this when you have a code path that cannot be reached by design.
For example, in the ``default:`` clause in a ``switch`` statement for which
all possible values are covered in ``case`` statements. Use this in places
where you might be tempted to put an ``assert(0)`` or ``abort()`` call.
In release mode, the macro helps the compiler to optimize the code, and
avoids a warning about unreachable code. For example, the macro is
implemented with ``__builtin_unreachable()`` on GCC in release mode.
A use for ``Py_UNREACHABLE()`` is following a call a function that
never returns but that is not declared :c:macro:`_Py_NO_RETURN`.
If a code path is very unlikely code but can be reached under exceptional
case, this macro must not be used. For example, under low memory condition
or if a system call returns a value out of the expected range. In this
case, it's better to report the error to the caller. If the error cannot
be reported to caller, :c:func:`Py_FatalError` can be used.
.. versionadded:: 3.7
.. c:macro:: Py_ABS(x)
@ -174,6 +187,39 @@ complete listing.
.. 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.
If Python is built without docstrings, the value will be empty.
Use :c:macro:`PyDoc_STRVAR` for docstrings to support building
Python without docstrings, as specified in :pep:`7`.
Example::
PyDoc_STRVAR(pop_doc, "Remove and return the rightmost element.");
static PyMethodDef deque_methods[] = {
// ...
{"pop", (PyCFunction)deque_pop, METH_NOARGS, pop_doc},
// ...
}
.. c:macro:: PyDoc_STR(str)
Creates a docstring for the given input string or an empty string
if docstrings are disabled.
Use :c:macro:`PyDoc_STR` in specifying docstrings to support
building Python without docstrings, as specified in :pep:`7`.
Example::
static PyMethodDef pysqlite_row_methods[] = {
{"keys", (PyCFunction)pysqlite_row_keys, METH_NOARGS,
PyDoc_STR("Returns the keys of the row.")},
{NULL, NULL}
};
.. _api-objects:
@ -183,13 +229,13 @@ Objects, Types and Reference Counts
.. index:: object: type
Most Python/C API functions have one or more arguments as well as a return value
of type :c:type:`PyObject\*`. This type is a pointer to an opaque data type
of type :c:type:`PyObject*`. This type is a pointer to an opaque data type
representing an arbitrary Python object. Since all Python object types are
treated the same way by the Python language in most situations (e.g.,
assignments, scope rules, and argument passing), it is only fitting that they
should be represented by a single C type. Almost all Python objects live on the
heap: you never declare an automatic or static variable of type
:c:type:`PyObject`, only pointer variables of type :c:type:`PyObject\*` can be
:c:type:`PyObject`, only pointer variables of type :c:type:`PyObject*` can be
declared. The sole exception are the type objects; since these must never be
deallocated, they are typically static :c:type:`PyTypeObject` objects.
@ -450,7 +496,7 @@ Types
There are few other data types that play a significant role in the Python/C
API; most are simple C types such as :c:type:`int`, :c:type:`long`,
:c:type:`double` and :c:type:`char\*`. A few structure types are used to
:c:type:`double` and :c:type:`char*`. A few structure types are used to
describe static tables used to list the functions exported by a module or the
data attributes of a new object type, and another is used to describe the value
of a complex number. These will be discussed together with the functions that

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

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

7
Doc/c-api/list.rst
View File

@ -142,10 +142,3 @@ List Objects
Return a new tuple object containing the contents of *list*; equivalent to
``tuple(list)``.
.. c:function:: int PyList_ClearFreeList()
Clear the free list. Return the total number of freed items.
.. versionadded:: 3.3

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

@ -94,23 +94,10 @@ distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate.
are no digits, :exc:`ValueError` will be raised.
.. c:function:: PyObject* PyLong_FromUnicode(Py_UNICODE *u, Py_ssize_t length, int base)
Convert a sequence of Unicode digits to a Python integer value. The Unicode
string is first encoded to a byte string using :c:func:`PyUnicode_EncodeDecimal`
and then converted using :c:func:`PyLong_FromString`.
.. deprecated-removed:: 3.3 4.0
Part of the old-style :c:type:`Py_UNICODE` API; please migrate to using
:c:func:`PyLong_FromUnicodeObject`.
.. c:function:: PyObject* PyLong_FromUnicodeObject(PyObject *u, int base)
Convert a sequence of Unicode digits in the string *u* to a Python integer
value. The Unicode string is first encoded to a byte string using
:c:func:`PyUnicode_EncodeDecimal` and then converted using
:c:func:`PyLong_FromString`.
value.
.. versionadded:: 3.3
@ -129,9 +116,8 @@ distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate.
single: OverflowError (built-in exception)
Return a C :c:type:`long` representation of *obj*. If *obj* is not an
instance of :c:type:`PyLongObject`, first call its :meth:`__index__` or
:meth:`__int__` method (if present) to convert it to a
:c:type:`PyLongObject`.
instance of :c:type:`PyLongObject`, first call its :meth:`__index__` method
(if present) to convert it to a :c:type:`PyLongObject`.
Raise :exc:`OverflowError` if the value of *obj* is out of range for a
:c:type:`long`.
@ -141,16 +127,15 @@ distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate.
.. versionchanged:: 3.8
Use :meth:`__index__` if available.
.. deprecated:: 3.8
Using :meth:`__int__` is deprecated.
.. versionchanged:: 3.10
This function will no longer use :meth:`__int__`.
.. c:function:: long PyLong_AsLongAndOverflow(PyObject *obj, int *overflow)
Return a C :c:type:`long` representation of *obj*. If *obj* is not an
instance of :c:type:`PyLongObject`, first call its :meth:`__index__` or
:meth:`__int__` method (if present) to convert it to a
:c:type:`PyLongObject`.
instance of :c:type:`PyLongObject`, first call its :meth:`__index__`
method (if present) to convert it to a :c:type:`PyLongObject`.
If the value of *obj* is greater than :const:`LONG_MAX` or less than
:const:`LONG_MIN`, set *\*overflow* to ``1`` or ``-1``, respectively, and
@ -162,8 +147,8 @@ distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate.
.. versionchanged:: 3.8
Use :meth:`__index__` if available.
.. deprecated:: 3.8
Using :meth:`__int__` is deprecated.
.. versionchanged:: 3.10
This function will no longer use :meth:`__int__`.
.. c:function:: long long PyLong_AsLongLong(PyObject *obj)
@ -172,31 +157,29 @@ distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate.
single: OverflowError (built-in exception)
Return a C :c:type:`long long` representation of *obj*. If *obj* is not an
instance of :c:type:`PyLongObject`, first call its :meth:`__index__` or
:meth:`__int__` method (if present) to convert it to a
:c:type:`PyLongObject`.
instance of :c:type:`PyLongObject`, first call its :meth:`__index__` method
(if present) to convert it to a :c:type:`PyLongObject`.
Raise :exc:`OverflowError` if the value of *obj* is out of range for a
:c:type:`long`.
:c:type:`long long`.
Returns ``-1`` on error. Use :c:func:`PyErr_Occurred` to disambiguate.
.. versionchanged:: 3.8
Use :meth:`__index__` if available.
.. deprecated:: 3.8
Using :meth:`__int__` is deprecated.
.. versionchanged:: 3.10
This function will no longer use :meth:`__int__`.
.. c:function:: long long PyLong_AsLongLongAndOverflow(PyObject *obj, int *overflow)
Return a C :c:type:`long long` representation of *obj*. If *obj* is not an
instance of :c:type:`PyLongObject`, first call its :meth:`__index__` or
:meth:`__int__` method (if present) to convert it to a
:c:type:`PyLongObject`.
instance of :c:type:`PyLongObject`, first call its :meth:`__index__` method
(if present) to convert it to a :c:type:`PyLongObject`.
If the value of *obj* is greater than :const:`PY_LLONG_MAX` or less than
:const:`PY_LLONG_MIN`, set *\*overflow* to ``1`` or ``-1``, respectively,
If the value of *obj* is greater than :const:`LLONG_MAX` or less than
:const:`LLONG_MIN`, set *\*overflow* to ``1`` or ``-1``, respectively,
and return ``-1``; otherwise, set *\*overflow* to ``0``. If any other
exception occurs set *\*overflow* to ``0`` and return ``-1`` as usual.
@ -207,8 +190,8 @@ distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate.
.. versionchanged:: 3.8
Use :meth:`__index__` if available.
.. deprecated:: 3.8
Using :meth:`__int__` is deprecated.
.. versionchanged:: 3.10
This function will no longer use :meth:`__int__`.
.. c:function:: Py_ssize_t PyLong_AsSsize_t(PyObject *pylong)
@ -278,10 +261,9 @@ distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate.
.. c:function:: unsigned long PyLong_AsUnsignedLongMask(PyObject *obj)
Return a C :c:type:`unsigned long` representation of *obj*. If *obj*
is not an instance of :c:type:`PyLongObject`, first call its
:meth:`__index__` or :meth:`__int__` method (if present) to convert
it to a :c:type:`PyLongObject`.
Return a C :c:type:`unsigned long` representation of *obj*. If *obj* is not
an instance of :c:type:`PyLongObject`, first call its :meth:`__index__`
method (if present) to convert it to a :c:type:`PyLongObject`.
If the value of *obj* is out of range for an :c:type:`unsigned long`,
return the reduction of that value modulo ``ULONG_MAX + 1``.
@ -292,19 +274,19 @@ distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate.
.. versionchanged:: 3.8
Use :meth:`__index__` if available.
.. deprecated:: 3.8
Using :meth:`__int__` is deprecated.
.. versionchanged:: 3.10
This function will no longer use :meth:`__int__`.
.. c:function:: unsigned long long PyLong_AsUnsignedLongLongMask(PyObject *obj)
Return a C :c:type:`unsigned long long` representation of *obj*. If *obj*
is not an instance of :c:type:`PyLongObject`, first call its
:meth:`__index__` or :meth:`__int__` method (if present) to convert
it to a :c:type:`PyLongObject`.
:meth:`__index__` method (if present) to convert it to a
:c:type:`PyLongObject`.
If the value of *obj* is out of range for an :c:type:`unsigned long long`,
return the reduction of that value modulo ``PY_ULLONG_MAX + 1``.
return the reduction of that value modulo ``ULLONG_MAX + 1``.
Returns ``(unsigned long long)-1`` on error. Use :c:func:`PyErr_Occurred`
to disambiguate.
@ -312,8 +294,8 @@ distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate.
.. versionchanged:: 3.8
Use :meth:`__index__` if available.
.. deprecated:: 3.8
Using :meth:`__int__` is deprecated.
.. versionchanged:: 3.10
This function will no longer use :meth:`__int__`.
.. c:function:: double PyLong_AsDouble(PyObject *pylong)

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

@ -14,8 +14,7 @@ See also :c:func:`PyObject_GetItem`, :c:func:`PyObject_SetItem` and
Return ``1`` if the object provides mapping protocol or supports slicing,
and ``0`` otherwise. Note that it returns ``1`` for Python classes with
a :meth:`__getitem__` method since in general case it is impossible to
determine what the type of keys it supports. This function always
succeeds.
determine what type of keys it supports. This function always succeeds.
.. c:function:: Py_ssize_t PyMapping_Size(PyObject *o)
@ -38,7 +37,8 @@ See also :c:func:`PyObject_GetItem`, :c:func:`PyObject_SetItem` and
Map the string *key* to the value *v* in object *o*. Returns ``-1`` on
failure. This is the equivalent of the Python statement ``o[key] = v``.
See also :c:func:`PyObject_SetItem`.
See also :c:func:`PyObject_SetItem`. This function *does not* steal a
reference to *v*.
.. c:function:: int PyMapping_DelItem(PyObject *o, PyObject *key)

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

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

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

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

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

@ -92,9 +92,3 @@ no longer available.
.. c:function:: PyObject* PyMethod_GET_SELF(PyObject *meth)
Macro version of :c:func:`PyMethod_Self` which avoids error checking.
.. c:function:: int PyMethod_ClearFreeList()
Clear the free list. Return the total number of freed items.

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

@ -153,7 +153,7 @@ or request "multi-phase initialization" by returning the definition struct itsel
.. c:member:: const char *m_doc
Docstring for the module; usually a docstring variable created with
:c:func:`PyDoc_STRVAR` is used.
:c:macro:`PyDoc_STRVAR` is used.
.. c:member:: Py_ssize_t m_size
@ -196,23 +196,47 @@ or request "multi-phase initialization" by returning the definition struct itsel
.. c:member:: traverseproc m_traverse
A traversal function to call during GC traversal of the module object, or
``NULL`` if not needed. This function may be called before module state
is allocated (:c:func:`PyModule_GetState()` may return `NULL`),
and before the :c:member:`Py_mod_exec` function is executed.
``NULL`` if not needed.
This function is not called if the module state was requested but is not
allocated yet. This is the case immediately after the module is created
and before the module is executed (:c:data:`Py_mod_exec` function). More
precisely, this function is not called if :c:member:`m_size` is greater
than 0 and the module state (as returned by :c:func:`PyModule_GetState`)
is ``NULL``.
.. versionchanged:: 3.9
No longer called before the module state is allocated.
.. c:member:: inquiry m_clear
A clear function to call during GC clearing of the module object, or
``NULL`` if not needed. This function may be called before module state
is allocated (:c:func:`PyModule_GetState()` may return `NULL`),
and before the :c:member:`Py_mod_exec` function is executed.
``NULL`` if not needed.
This function is not called if the module state was requested but is not
allocated yet. This is the case immediately after the module is created
and before the module is executed (:c:data:`Py_mod_exec` function). More
precisely, this function is not called if :c:member:`m_size` is greater
than 0 and the module state (as returned by :c:func:`PyModule_GetState`)
is ``NULL``.
.. versionchanged:: 3.9
No longer called before the module state is allocated.
.. c:member:: freefunc m_free
A function to call during deallocation of the module object, or ``NULL`` if
not needed. This function may be called before module state
is allocated (:c:func:`PyModule_GetState()` may return `NULL`),
and before the :c:member:`Py_mod_exec` function is executed.
A function to call during deallocation of the module object, or ``NULL``
if not needed.
This function is not called if the module state was requested but is not
allocated yet. This is the case immediately after the module is created
and before the module is executed (:c:data:`Py_mod_exec` function). More
precisely, this function is not called if :c:member:`m_size` is greater
than 0 and the module state (as returned by :c:func:`PyModule_GetState`)
is ``NULL``.
.. versionchanged:: 3.9
No longer called before the module state is allocated.
Single-phase initialization
...........................
@ -301,7 +325,7 @@ The *m_slots* array must be terminated by a slot with id 0.
The available slot types are:
.. c:var:: Py_mod_create
.. c:macro:: Py_mod_create
Specifies a function that is called to create the module object itself.
The *value* pointer of this slot must point to a function of the signature:
@ -333,7 +357,7 @@ The available slot types are:
``PyModuleDef`` has non-``NULL`` ``m_traverse``, ``m_clear``,
``m_free``; non-zero ``m_size``; or slots other than ``Py_mod_create``.
.. c:var:: Py_mod_exec
.. c:macro:: Py_mod_exec
Specifies a function that is called to *execute* the module.
This is equivalent to executing the code of a Python module: typically,
@ -417,7 +441,7 @@ state:
Add an object to *module* as *name*. This is a convenience function which can
be used from the module's initialization function. This steals a reference to
*value* on success. Return ``-1`` on error, ``0`` on success.
*value* on success. Return ``-1`` on error, ``0`` on success.
.. note::
@ -460,6 +484,16 @@ state:
Add a string constant to *module*.
.. c:function:: int PyModule_AddType(PyObject *module, PyTypeObject *type)
Add a type object to *module*.
The type object is finalized by calling internally :c:func:`PyType_Ready`.
The name of the type object is taken from the last component of
:c:member:`~PyTypeObject.tp_name` after dot.
Return ``-1`` on error, ``0`` on success.
.. versionadded:: 3.9
Module lookup
^^^^^^^^^^^^^
@ -493,6 +527,8 @@ since multiple such modules can be created from a single definition.
mechanisms (either by calling it directly, or by referring to its
implementation for details of the required state updates).
The caller must hold the GIL.
Return 0 on success or -1 on failure.
.. versionadded:: 3.3
@ -502,4 +538,6 @@ since multiple such modules can be created from a single definition.
Removes the module object created from *def* from the interpreter state.
Return 0 on success or -1 on failure.
The caller must hold the GIL.
.. versionadded:: 3.3

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

@ -256,6 +256,10 @@ Number Protocol
Returns the *o* converted to a Python int on success or ``NULL`` with a
:exc:`TypeError` exception raised on failure.
.. versionchanged:: 3.10
The result always has exact type :class:`int`. Previously, the result
could have been an instance of a subclass of ``int``.
.. c:function:: PyObject* PyNumber_ToBase(PyObject *n, int base)

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

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

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

@ -128,7 +128,7 @@ Object Protocol
.. versionadded:: 3.3
.. c:function:: int PyObject_GenericSetDict(PyObject *o, void *context)
.. c:function:: int PyObject_GenericSetDict(PyObject *o, PyObject *value, void *context)
A generic implementation for the setter of a ``__dict__`` descriptor. This
implementation does not allow the dictionary to be deleted.
@ -291,7 +291,7 @@ Object Protocol
is equivalent to the Python expression ``type(o)``. This function increments the
reference count of the return value. There's really no reason to use this
function instead of the common expression ``o->ob_type``, which returns a
pointer of type :c:type:`PyTypeObject\*`, except when the incremented reference
pointer of type :c:type:`PyTypeObject*`, except when the incremented reference
count is needed.
@ -331,7 +331,8 @@ Object Protocol
Map the object *key* to the value *v*. Raise an exception and
return ``-1`` on failure; return ``0`` on success. This is the
equivalent of the Python statement ``o[key] = v``.
equivalent of the Python statement ``o[key] = v``. This function *does
not* steal a reference to *v*.
.. c:function:: int PyObject_DelItem(PyObject *o, PyObject *key)

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

@ -5,34 +5,60 @@
Reflection
==========
.. c:function:: PyObject* PyEval_GetBuiltins()
.. c:function:: PyObject* PyEval_GetBuiltins(void)
Return a dictionary of the builtins in the current execution frame,
or the interpreter of the thread state if no frame is currently executing.
.. c:function:: PyObject* PyEval_GetLocals()
.. c:function:: PyObject* PyEval_GetLocals(void)
Return a dictionary of the local variables in the current execution frame,
or ``NULL`` if no frame is currently executing.
.. c:function:: PyObject* PyEval_GetGlobals()
.. c:function:: PyObject* PyEval_GetGlobals(void)
Return a dictionary of the global variables in the current execution frame,
or ``NULL`` if no frame is currently executing.
.. c:function:: PyFrameObject* PyEval_GetFrame()
.. c:function:: PyFrameObject* PyEval_GetFrame(void)
Return the current thread state's frame, which is ``NULL`` if no frame is
currently executing.
See also :c:func:`PyThreadState_GetFrame`.
.. c:function:: int PyFrame_GetBack(PyFrameObject *frame)
Get the *frame* next outer frame.
Return a strong reference, or ``NULL`` if *frame* has no outer frame.
*frame* must not be ``NULL``.
.. versionadded:: 3.9
.. c:function:: int PyFrame_GetCode(PyFrameObject *frame)
Get the *frame* code.
Return a strong reference.
*frame* must not be ``NULL``. The result (frame code) cannot be ``NULL``.
.. versionadded:: 3.9
.. c:function:: int PyFrame_GetLineNumber(PyFrameObject *frame)
Return the line number that *frame* is currently executing.
*frame* must not be ``NULL``.
.. c:function:: const char* PyEval_GetFuncName(PyObject *func)

7
Doc/c-api/set.rst
View File

@ -157,10 +157,3 @@ subtypes but not for instances of :class:`frozenset` or its subtypes.
.. c:function:: int PySet_Clear(PyObject *set)
Empty an existing set of all elements.
.. c:function:: int PySet_ClearFreeList()
Clear the free list. Return the total number of freed items.
.. versionadded:: 3.3

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

@ -62,29 +62,62 @@ the definition of all other Python objects.
See documentation of :c:type:`PyVarObject` above.
.. c:macro:: Py_TYPE(o)
.. c:function:: PyTypeObject* Py_TYPE(const PyObject *o)
This macro is used to access the :attr:`ob_type` member of a Python object.
It expands to::
Get the type of the Python object *o*.
(((PyObject*)(o))->ob_type)
Return a borrowed reference.
.. versionchanged:: 3.10
:c:func:`Py_TYPE()` is changed to the inline static function.
Use :c:func:`Py_SET_TYPE()` to set an object type.
.. c:macro:: Py_REFCNT(o)
.. c:function:: int Py_IS_TYPE(PyObject *o, PyTypeObject *type)
This macro is used to access the :attr:`ob_refcnt` member of a Python
object.
It expands to::
Return non-zero if the object *o* type is *type*. Return zero otherwise.
Equivalent to: ``Py_TYPE(o) == type``.
(((PyObject*)(o))->ob_refcnt)
.. versionadded:: 3.9
.. c:macro:: Py_SIZE(o)
.. c:function:: void Py_SET_TYPE(PyObject *o, PyTypeObject *type)
This macro is used to access the :attr:`ob_size` member of a Python object.
It expands to::
Set the object *o* type to *type*.
(((PyVarObject*)(o))->ob_size)
.. versionadded:: 3.9
.. c:function:: Py_ssize_t Py_REFCNT(const PyObject *o)
Get the reference count of the Python object *o*.
.. 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)
Set the object *o* reference counter to *refcnt*.
.. versionadded:: 3.9
.. c:function:: Py_ssize_t Py_SIZE(const PyVarObject *o)
Get the size of the Python object *o*.
.. versionchanged:: 3.10
:c:func:`Py_SIZE()` is changed to the inline static function.
Use :c:func:`Py_SET_SIZE()` to set an object size.
.. c:function:: void Py_SET_SIZE(PyVarObject *o, Py_ssize_t size)
Set the object *o* size to *size*.
.. versionadded:: 3.9
.. c:macro:: PyObject_HEAD_INIT(type)
@ -112,29 +145,62 @@ Implementing functions and methods
.. c:type:: PyCFunction
Type of the functions used to implement most Python callables in C.
Functions of this type take two :c:type:`PyObject\*` parameters and return
Functions of this type take two :c:type:`PyObject*` parameters and return
one such value. If the return value is ``NULL``, an exception shall have
been set. If not ``NULL``, the return value is interpreted as the return
value of the function as exposed in Python. The function must return a new
reference.
The function signature is::
PyObject *PyCFunction(PyObject *self,
PyObject *args);
.. c:type:: PyCFunctionWithKeywords
Type of the functions used to implement Python callables in C
with signature :const:`METH_VARARGS | METH_KEYWORDS`.
The function signature is::
PyObject *PyCFunctionWithKeywords(PyObject *self,
PyObject *args,
PyObject *kwargs);
.. c:type:: _PyCFunctionFast
Type of the functions used to implement Python callables in C
with signature :const:`METH_FASTCALL`.
The function signature is::
PyObject *_PyCFunctionFast(PyObject *self,
PyObject *const *args,
Py_ssize_t nargs);
.. c:type:: _PyCFunctionFastWithKeywords
Type of the functions used to implement Python callables in C
with signature :const:`METH_FASTCALL | METH_KEYWORDS`.
The function signature is::
PyObject *_PyCFunctionFastWithKeywords(PyObject *self,
PyObject *const *args,
Py_ssize_t nargs,
PyObject *kwnames);
.. c:type:: PyCMethod
Type of the functions used to implement Python callables in C
with signature :const:`METH_METHOD | METH_FASTCALL | METH_KEYWORDS`.
The function signature is::
PyObject *PyCMethod(PyObject *self,
PyTypeObject *defining_class,
PyObject *const *args,
Py_ssize_t nargs,
PyObject *kwnames)
.. versionadded:: 3.9
.. c:type:: PyMethodDef
@ -158,24 +224,22 @@ Implementing functions and methods
+------------------+---------------+-------------------------------+
The :attr:`ml_meth` is a C function pointer. The functions may be of different
types, but they always return :c:type:`PyObject\*`. If the function is not of
types, but they always return :c:type:`PyObject*`. If the function is not of
the :c:type:`PyCFunction`, the compiler will require a cast in the method table.
Even though :c:type:`PyCFunction` defines the first parameter as
:c:type:`PyObject\*`, it is common that the method implementation uses the
:c:type:`PyObject*`, it is common that the method implementation uses the
specific C type of the *self* object.
The :attr:`ml_flags` field is a bitfield which can include the following flags.
The individual flags indicate either a calling convention or a binding
convention.
There are four basic calling conventions for positional arguments
and two of them can be combined with :const:`METH_KEYWORDS` to support
also keyword arguments. So there are a total of 6 calling conventions:
There are these calling conventions:
.. data:: METH_VARARGS
This is the typical calling convention, where the methods have the type
:c:type:`PyCFunction`. The function expects two :c:type:`PyObject\*` values.
:c:type:`PyCFunction`. The function expects two :c:type:`PyObject*` values.
The first one is the *self* object for methods; for module functions, it is
the module object. The second parameter (often called *args*) is a tuple
object representing all arguments. This parameter is typically processed
@ -196,7 +260,7 @@ also keyword arguments. So there are a total of 6 calling conventions:
Fast calling convention supporting only positional arguments.
The methods have the type :c:type:`_PyCFunctionFast`.
The first parameter is *self*, the second parameter is a C array
of :c:type:`PyObject\*` values indicating the arguments and the third
of :c:type:`PyObject*` values indicating the arguments and the third
parameter is the number of arguments (the length of the array).
This is not part of the :ref:`limited API <stable>`.
@ -210,7 +274,7 @@ also keyword arguments. So there are a total of 6 calling conventions:
with methods of type :c:type:`_PyCFunctionFastWithKeywords`.
Keyword arguments are passed the same way as in the
:ref:`vectorcall protocol <vectorcall>`:
there is an additional fourth :c:type:`PyObject\*` parameter
there is an additional fourth :c:type:`PyObject*` parameter
which is a tuple representing the names of the keyword arguments
(which are guaranteed to be strings)
or possibly ``NULL`` if there are no keywords. The values of the keyword
@ -221,6 +285,19 @@ also keyword arguments. So there are a total of 6 calling conventions:
.. versionadded:: 3.7
.. data:: METH_METHOD | METH_FASTCALL | METH_KEYWORDS
Extension of :const:`METH_FASTCALL | METH_KEYWORDS` supporting the *defining
class*, that is, the class that contains the method in question.
The defining class might be a superclass of ``Py_TYPE(self)``.
The method needs to be of type :c:type:`PyCMethod`, the same as for
``METH_FASTCALL | METH_KEYWORDS`` with ``defining_class`` argument added after
``self``.
.. versionadded:: 3.9
.. data:: METH_NOARGS
Methods without parameters don't need to check whether arguments are given if
@ -235,7 +312,7 @@ also keyword arguments. So there are a total of 6 calling conventions:
Methods with a single object argument can be listed with the :const:`METH_O`
flag, instead of invoking :c:func:`PyArg_ParseTuple` with a ``"O"`` argument.
They have the type :c:type:`PyCFunction`, with the *self* parameter, and a
:c:type:`PyObject\*` parameter representing the single argument.
:c:type:`PyObject*` parameter representing the single argument.
These two constants are not used to indicate the calling convention but the
@ -350,10 +427,12 @@ Accessing attributes of extension types
.. _pymemberdef-offsets:
Heap allocated types (created using :c:func:`PyType_FromSpec` or similar),
``PyMemberDef`` may contain defintitions for the special members
``__dictoffset__`` and ``__weaklistoffset__``, corresponding to
:c:member:`~PyTypeObject.tp_dictoffset` and
:c:member:`~PyTypeObject.tp_weaklistoffset` in type objects.
``PyMemberDef`` may contain definitions for the special members
``__dictoffset__``, ``__weaklistoffset__`` and ``__vectorcalloffset__``,
corresponding to
:c:member:`~PyTypeObject.tp_dictoffset`,
:c:member:`~PyTypeObject.tp_weaklistoffset` and
:c:member:`~PyTypeObject.tp_vectorcall_offset` in type objects.
These must be defined with ``T_PYSSIZET`` and ``READONLY``, for example::
static PyMemberDef spam_type_members[] = {
@ -384,7 +463,7 @@ Accessing attributes of extension types
| | | getter and setter |
+-------------+------------------+-----------------------------------+
The ``get`` function takes one :c:type:`PyObject\*` parameter (the
The ``get`` function takes one :c:type:`PyObject*` parameter (the
instance) and a function pointer (the associated ``closure``)::
typedef PyObject *(*getter)(PyObject *, void *);
@ -392,7 +471,7 @@ Accessing attributes of extension types
It should return a new reference on success or ``NULL`` with a set exception
on failure.
``set`` functions take two :c:type:`PyObject\*` parameters (the instance and
``set`` functions take two :c:type:`PyObject*` parameters (the instance and
the value to be set) and a function pointer (the associated ``closure``)::
typedef int (*setter)(PyObject *, PyObject *, void *);

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

@ -309,7 +309,7 @@ accessible to C code. They all work with the current interpreter thread's
.. c:function:: int PySys_Audit(const char *event, const char *format, ...)
Raises an auditing event with any active hooks. Returns zero for success
Raise an auditing event with any active hooks. Return zero for success
and non-zero with an exception set on failure.
If any hooks have been added, *format* and other arguments will be used
@ -320,18 +320,31 @@ accessible to C code. They all work with the current interpreter thread's
arguments to this function will be consumed, using it may cause reference
leaks.)
Note that ``#`` format characters should always be treated as
``Py_ssize_t``, regardless of whether ``PY_SSIZE_T_CLEAN`` was defined.
:func:`sys.audit` performs the same function from Python code.
.. versionadded:: 3.8
.. versionchanged:: 3.8.2
Require ``Py_ssize_t`` for ``#`` format characters. Previously, an
unavoidable deprecation warning was raised.
.. c:function:: int PySys_AddAuditHook(Py_AuditHookFunction hook, void *userData)
Adds to the collection of active auditing hooks. Returns zero for success
and non-zero on failure. If the runtime has been initialized, also sets an
Append the callable *hook* to the list of active auditing hooks.
Return zero for success
and non-zero on failure. If the runtime has been initialized, also set an
error on failure. Hooks added through this API are called for all
interpreters created by the runtime.
The *userData* pointer is passed into the hook function. Since hook
functions may be called from different runtimes, this pointer should not
refer directly to Python state.
This function is safe to call before :c:func:`Py_Initialize`. When called
after runtime initialization, existing audit hooks are notified and may
silently abort the operation by raising an error subclassed from
@ -342,14 +355,10 @@ accessible to C code. They all work with the current interpreter thread's
:c:type:`PyTupleObject`. The hook function is always called with the GIL
held by the Python interpreter that raised the event.
The *userData* pointer is passed into the hook function. Since hook
functions may be called from different runtimes, this pointer should not
refer directly to Python state.
See :pep:`578` for a detailed description of auditing. Functions in the
runtime and standard library that raise events include the details in each
function's documentation and listed in the :ref:`audit events table
<audit-events>`.
See :pep:`578` for a detailed description of auditing. Functions in the
runtime and standard library that raise events are listed in the
:ref:`audit events table <audit-events>`.
Details are in each function's documentation.
.. audit-event:: sys.addaudithook "" c.PySys_AddAuditHook
@ -379,6 +388,13 @@ Process Control
function :c:func:`abort` is called which will attempt to produce a :file:`core`
file.
The ``Py_FatalError()`` function is replaced with a macro which logs
automatically the name of the current function, unless the
``Py_LIMITED_API`` macro is defined.
.. versionchanged:: 3.9
Log the function name automatically.
.. c:function:: void Py_Exit(int status)

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

@ -111,11 +111,6 @@ Tuple Objects
raises :exc:`MemoryError` or :exc:`SystemError`.
.. c:function:: int PyTuple_ClearFreeList()
Clear the free list. Return the total number of freed items.
Struct Sequence Objects
-----------------------
@ -166,7 +161,7 @@ type.
.. c:type:: PyStructSequence_Field
Describes a field of a struct sequence. As a struct sequence is modeled as a
tuple, all fields are typed as :c:type:`PyObject\*`. The index in the
tuple, all fields are typed as :c:type:`PyObject*`. The index in the
:attr:`fields` array of the :c:type:`PyStructSequence_Desc` determines which
field of the struct sequence is described.

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

@ -21,14 +21,14 @@ Type Objects
.. c:function:: int PyType_Check(PyObject *o)
Return true if the object *o* is a type object, including instances of types
derived from the standard type object. Return false in all other cases.
Return non-zero if the object *o* is a type object, including instances of
types derived from the standard type object. Return 0 in all other cases.
.. c:function:: int PyType_CheckExact(PyObject *o)
Return true if the object *o* is a type object, but not a subtype of the
standard type object. Return false in all other cases.
Return non-zero if the object *o* is a type object, but not a subtype of the
standard type object. Return 0 in all other cases.
.. c:function:: unsigned int PyType_ClearCache()
@ -57,8 +57,8 @@ Type Objects
.. c:function:: int PyType_HasFeature(PyTypeObject *o, int feature)
Return true if the type object *o* sets the feature *feature*. Type features
are denoted by single bit flags.
Return non-zero if the type object *o* sets the feature *feature*.
Type features are denoted by single bit flags.
.. c:function:: int PyType_IS_GC(PyTypeObject *o)
@ -109,6 +109,37 @@ Type Objects
.. versionadded:: 3.4
.. c:function:: PyObject* PyType_GetModule(PyTypeObject *type)
Return the module object associated with the given type when the type was
created using :c:func:`PyType_FromModuleAndSpec`.
If no module is associated with the given type, sets :py:class:`TypeError`
and returns ``NULL``.
This function is usually used to get the module in which a method is defined.
Note that in such a method, ``PyType_GetModule(Py_TYPE(self))``
may not return the intended result.
``Py_TYPE(self)`` may be a *subclass* of the intended class, and subclasses
are not necessarily defined in the same module as their superclass.
See :c:type:`PyCMethod` to get the class that defines the method.
.. versionadded:: 3.9
.. c:function:: void* PyType_GetModuleState(PyTypeObject *type)
Return the state of the module object associated with the given type.
This is a shortcut for calling :c:func:`PyModule_GetState()` on the result
of :c:func:`PyType_GetModule`.
If no module is associated with the given type, sets :py:class:`TypeError`
and returns ``NULL``.
If the *type* has an associated module but its state is ``NULL``,
returns ``NULL`` without setting an exception.
.. versionadded:: 3.9
Creating Heap-Allocated Types
.............................
@ -116,7 +147,7 @@ Creating Heap-Allocated Types
The following functions and structs are used to create
:ref:`heap types <heap-types>`.
.. c:function:: PyObject* PyType_FromSpecWithBases(PyType_Spec *spec, PyObject *bases)
.. c:function:: PyObject* PyType_FromModuleAndSpec(PyObject *module, PyType_Spec *spec, PyObject *bases)
Creates and returns a heap type object from the *spec*
(:const:`Py_TPFLAGS_HEAPTYPE`).
@ -127,8 +158,21 @@ The following functions and structs are used to create
If *bases* is ``NULL``, the *Py_tp_base* slot is used instead.
If that also is ``NULL``, the new type derives from :class:`object`.
The *module* argument can be used to record the module in which the new
class is defined. It must be a module object or ``NULL``.
If not ``NULL``, the module is associated with the new type and can later be
retreived with :c:func:`PyType_GetModule`.
The associated module is not inherited by subclasses; it must be specified
for each class individually.
This function calls :c:func:`PyType_Ready` on the new type.
.. versionadded:: 3.9
.. c:function:: PyObject* PyType_FromSpecWithBases(PyType_Spec *spec, PyObject *bases)
Equivalent to ``PyType_FromModuleAndSpec(NULL, spec, bases)``.
.. versionadded:: 3.3
.. c:function:: PyObject* PyType_FromSpec(PyType_Spec *spec)
@ -181,7 +225,8 @@ The following functions and structs are used to create
* ``Py_nb_add`` to set :c:member:`PyNumberMethods.nb_add`
* ``Py_sq_length`` to set :c:member:`PySequenceMethods.sq_length`
The following fields cannot be set using :c:type:`PyType_Spec` and :c:type:`PyType_Slot`:
The following fields cannot be set at all using :c:type:`PyType_Spec` and
:c:type:`PyType_Slot`:
* :c:member:`~PyTypeObject.tp_dict`
* :c:member:`~PyTypeObject.tp_mro`
@ -194,6 +239,11 @@ The following functions and structs are used to create
* :c:member:`~PyTypeObject.tp_dictoffset`
(see :ref:`PyMemberDef <pymemberdef-offsets>`)
* :c:member:`~PyTypeObject.tp_vectorcall_offset`
(see :ref:`PyMemberDef <pymemberdef-offsets>`)
The following fields cannot be set using :c:type:`PyType_Spec` and
:c:type:`PyType_Slot` under the limited API:
* :c:member:`~PyBufferProcs.bf_getbuffer`
* :c:member:`~PyBufferProcs.bf_releasebuffer`
@ -201,6 +251,10 @@ The following functions and structs are used to create
To avoid issues, use the *bases* argument of
:py:func:`PyType_FromSpecWithBases` instead.
.. versionchanged:: 3.9
Slots in :c:type:`PyBufferProcs` in may be set in the unlimited API.
.. c:member:: void *PyType_Slot.pfunc
The desired value of the slot. In most cases, this is a pointer

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

@ -148,15 +148,6 @@ Quick Reference
| :c:member:`~PyTypeObject.tp_vectorcall` | :c:type:`vectorcallfunc` | | | | | |
+------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+
If :const:`COUNT_ALLOCS` is defined then the following (internal-only)
fields exist as well:
* :c:member:`~PyTypeObject.tp_allocs`
* :c:member:`~PyTypeObject.tp_frees`
* :c:member:`~PyTypeObject.tp_maxalloc`
* :c:member:`~PyTypeObject.tp_prev`
* :c:member:`~PyTypeObject.tp_next`
.. [#slots]
A slot name in parentheses indicates it is (effectively) deprecated.
Names in angle brackets should be treated as read-only.
@ -693,15 +684,15 @@ and :c:type:`PyType_Type` effectively act as defaults.)
a more efficient alternative
of the simpler :c:member:`~PyTypeObject.tp_call`.
This field is only used if the flag :const:`_Py_TPFLAGS_HAVE_VECTORCALL`
This field is only used if the flag :const:`Py_TPFLAGS_HAVE_VECTORCALL`
is set. If so, this must be a positive integer containing the offset in the
instance of a :c:type:`vectorcallfunc` pointer.
The *vectorcallfunc* pointer may be ``NULL``, in which case the instance behaves
as if :const:`_Py_TPFLAGS_HAVE_VECTORCALL` was not set: calling the instance
as if :const:`Py_TPFLAGS_HAVE_VECTORCALL` was not set: calling the instance
falls back to :c:member:`~PyTypeObject.tp_call`.
Any class that sets ``_Py_TPFLAGS_HAVE_VECTORCALL`` must also set
Any class that sets ``Py_TPFLAGS_HAVE_VECTORCALL`` must also set
:c:member:`~PyTypeObject.tp_call` and make sure its behaviour is consistent
with the *vectorcallfunc* function.
This can be done by setting *tp_call* to :c:func:`PyVectorcall_Call`.
@ -728,7 +719,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
**Inheritance:**
This field is always inherited.
However, the :const:`_Py_TPFLAGS_HAVE_VECTORCALL` flag is not
However, the :const:`Py_TPFLAGS_HAVE_VECTORCALL` flag is not
always inherited. If it's not, then the subclass won't use
:ref:`vectorcall <vectorcall>`, except when
:c:func:`PyVectorcall_Call` is explicitly called.
@ -955,7 +946,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
The signature is the same as for :c:func:`PyObject_SetAttr`::
PyObject *tp_setattro(PyObject *self, PyObject *attr, PyObject *value);
int tp_setattro(PyObject *self, PyObject *attr, PyObject *value);
In addition, setting *value* to ``NULL`` to delete an attribute must be
supported. It is usually convenient to set this field to
@ -1162,7 +1153,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
type structure.
.. data:: _Py_TPFLAGS_HAVE_VECTORCALL
.. data:: Py_TPFLAGS_HAVE_VECTORCALL
This bit is set when the class implements
the :ref:`vectorcall protocol <vectorcall>`.
@ -1172,15 +1163,9 @@ and :c:type:`PyType_Type` effectively act as defaults.)
This bit is inherited for *static* subtypes if
:c:member:`~PyTypeObject.tp_call` is also inherited.
`Heap types`_ do not inherit ``_Py_TPFLAGS_HAVE_VECTORCALL``.
`Heap types`_ do not inherit ``Py_TPFLAGS_HAVE_VECTORCALL``.
.. note::
This flag is provisional and expected to become public in Python 3.9,
with a different name and, possibly, changed semantics.
If you use vectorcall, plan for updating your code for Python 3.9.
.. versionadded:: 3.8
.. versionadded:: 3.9
.. c:member:: const char* PyTypeObject.tp_doc
@ -1207,7 +1192,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
The :c:member:`~PyTypeObject.tp_traverse` pointer is used by the garbage collector to detect
reference cycles. A typical implementation of a :c:member:`~PyTypeObject.tp_traverse` function
simply calls :c:func:`Py_VISIT` on each of the instance's members that are Python
objects. For example, this is function :c:func:`local_traverse` from the
objects that the instance owns. For example, this is function :c:func:`local_traverse` from the
:mod:`_thread` extension module::
static int
@ -1227,10 +1212,36 @@ and :c:type:`PyType_Type` effectively act as defaults.)
debugging aid you may want to visit it anyway just so the :mod:`gc` module's
:func:`~gc.get_referents` function will include it.
.. warning::
When implementing :c:member:`~PyTypeObject.tp_traverse`, only the members
that the instance *owns* (by having strong references to them) must be
visited. For instance, if an object supports weak references via the
:c:member:`~PyTypeObject.tp_weaklist` slot, the pointer supporting
the linked list (what *tp_weaklist* points to) must **not** be
visited as the instance does not directly own the weak references to itself
(the weakreference list is there to support the weak reference machinery,
but the instance has no strong reference to the elements inside it, as they
are allowed to be removed even if the instance is still alive).
Note that :c:func:`Py_VISIT` requires the *visit* and *arg* parameters to
:c:func:`local_traverse` to have these specific names; don't name them just
anything.
Heap-allocated types (:const:`Py_TPFLAGS_HEAPTYPE`, such as those created
with :c:func:`PyType_FromSpec` and similar APIs) hold a reference to their
type. Their traversal function must therefore either visit
:c:func:`Py_TYPE(self) <Py_TYPE>`, or delegate this responsibility by
calling ``tp_traverse`` of another heap-allocated type (such as a
heap-allocated superclass).
If they do not, the type object may not be garbage-collected.
.. versionchanged:: 3.9
Heap-allocated types are expected to visit ``Py_TYPE(self)`` in
``tp_traverse``. In earlier versions of Python, due to
`bug 40217 <https://bugs.python.org/issue40217>`_, doing this
may lead to crashes in subclasses.
**Inheritance:**
Group: :const:`Py_TPFLAGS_HAVE_GC`, :attr:`tp_traverse`, :attr:`tp_clear`
@ -1337,7 +1348,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
The following macro is defined to ease writing rich comparison functions:
.. c:function:: PyObject \*Py_RETURN_RICHCOMPARE(VAL_A, VAL_B, int op)
.. c:macro:: Py_RETURN_RICHCOMPARE(VAL_A, VAL_B, op)
Return ``Py_True`` or ``Py_False`` from the function, depending on the
result of a comparison.
@ -1375,7 +1386,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
than zero and contains the offset in the instance structure of the weak
reference list head (ignoring the GC header, if present); this offset is used by
:c:func:`PyObject_ClearWeakRefs` and the :c:func:`PyWeakref_\*` functions. The
instance structure needs to include a field of type :c:type:`PyObject\*` which is
instance structure needs to include a field of type :c:type:`PyObject*` which is
initialized to ``NULL``.
Do not confuse this field with :c:member:`~PyTypeObject.tp_weaklist`; that is the list head for
@ -1904,31 +1915,6 @@ and :c:type:`PyType_Type` effectively act as defaults.)
.. versionadded:: 3.9 (the field exists since 3.8 but it's only used since 3.9)
The remaining fields are only defined if the feature test macro
:const:`COUNT_ALLOCS` is defined, and are for internal use only. They are
documented here for completeness. None of these fields are inherited by
subtypes.
.. c:member:: Py_ssize_t PyTypeObject.tp_allocs
Number of allocations.
.. c:member:: Py_ssize_t PyTypeObject.tp_frees
Number of frees.
.. c:member:: Py_ssize_t PyTypeObject.tp_maxalloc
Maximum simultaneously allocated objects.
.. c:member:: PyTypeObject* PyTypeObject.tp_prev
Pointer to the previous type object with a non-zero :c:member:`~PyTypeObject.tp_allocs` field.
.. c:member:: PyTypeObject* PyTypeObject.tp_next
Pointer to the next type object with a non-zero :c:member:`~PyTypeObject.tp_allocs` field.
Also, note that, in a garbage collected Python, :c:member:`~PyTypeObject.tp_dealloc` may be called from
any Python thread, not just the thread which created the object (if the object
becomes part of a refcount cycle, that cycle might be collected by a garbage

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

@ -34,6 +34,11 @@ can internally be in two states depending on how they were created:
:c:type:`Py_UNICODE*` representation; you will have to call
:c:func:`PyUnicode_READY` on them before calling any other API.
.. note::
The "legacy" Unicode object will be removed in Python 3.12 with deprecated
APIs. All Unicode objects will be "canonical" since then. See :pep:`623`
for more information.
Unicode Type
""""""""""""
@ -107,6 +112,9 @@ access internal read-only data of Unicode objects:
.. versionadded:: 3.3
.. deprecated-removed:: 3.10 3.12
This API will be removed with :c:func:`PyUnicode_FromUnicode`.
.. c:function:: Py_ssize_t PyUnicode_GET_LENGTH(PyObject *o)
@ -138,6 +146,9 @@ access internal read-only data of Unicode objects:
.. versionadded:: 3.3
.. deprecated-removed:: 3.10 3.12
``PyUnicode_WCHAR_KIND`` is deprecated.
.. c:function:: int PyUnicode_KIND(PyObject *o)
@ -188,7 +199,7 @@ access internal read-only data of Unicode objects:
.. versionadded:: 3.3
.. c:function:: PyUnicode_MAX_CHAR_VALUE(PyObject *o)
.. c:macro:: PyUnicode_MAX_CHAR_VALUE(o)
Return the maximum code point that is suitable for creating another string
based on *o*, which must be in the "canonical" representation. This is
@ -197,18 +208,13 @@ access internal read-only data of Unicode objects:
.. versionadded:: 3.3
.. c:function:: int PyUnicode_ClearFreeList()
Clear the free list. Return the total number of freed items.
.. c:function:: Py_ssize_t PyUnicode_GET_SIZE(PyObject *o)
Return the size of the deprecated :c:type:`Py_UNICODE` representation, in
code units (this includes surrogate pairs as 2 units). *o* has to be a
Unicode object (not checked).
.. deprecated-removed:: 3.3 4.0
.. deprecated-removed:: 3.3 3.12
Part of the old-style Unicode API, please migrate to using
:c:func:`PyUnicode_GET_LENGTH`.
@ -218,7 +224,7 @@ access internal read-only data of Unicode objects:
Return the size of the deprecated :c:type:`Py_UNICODE` representation in
bytes. *o* has to be a Unicode object (not checked).
.. deprecated-removed:: 3.3 4.0
.. deprecated-removed:: 3.3 3.12
Part of the old-style Unicode API, please migrate to using
:c:func:`PyUnicode_GET_LENGTH`.
@ -240,11 +246,21 @@ access internal read-only data of Unicode objects:
code to use the new :c:func:`PyUnicode_nBYTE_DATA` macros or use
:c:func:`PyUnicode_WRITE` or :c:func:`PyUnicode_READ`.
.. deprecated-removed:: 3.3 4.0
.. deprecated-removed:: 3.3 3.12
Part of the old-style Unicode API, please migrate to using the
:c:func:`PyUnicode_nBYTE_DATA` family of macros.
.. c:function:: int PyUnicode_IsIdentifier(PyObject *o)
Return ``1`` if the string is a valid identifier according to the language
definition, section :ref:`identifiers`. Return ``0`` otherwise.
.. versionchanged:: 3.9
The function does not call :c:func:`Py_FatalError` anymore if the string
is not ready.
Unicode Character Properties
""""""""""""""""""""""""""""
@ -682,8 +698,10 @@ Extension modules can continue using them, as they will not be removed in Python
string content has been filled before using any of the access macros such as
:c:func:`PyUnicode_KIND`.
Please migrate to using :c:func:`PyUnicode_FromKindAndData`,
:c:func:`PyUnicode_FromWideChar` or :c:func:`PyUnicode_New`.
.. deprecated-removed:: 3.3 3.12
Part of the old-style Unicode API, please migrate to using
:c:func:`PyUnicode_FromKindAndData`, :c:func:`PyUnicode_FromWideChar`, or
:c:func:`PyUnicode_New`.
.. c:function:: Py_UNICODE* PyUnicode_AsUnicode(PyObject *unicode)
@ -696,9 +714,10 @@ Extension modules can continue using them, as they will not be removed in Python
embedded null code points, which would cause the string to be truncated when
used in most C functions.
Please migrate to using :c:func:`PyUnicode_AsUCS4`,
:c:func:`PyUnicode_AsWideChar`, :c:func:`PyUnicode_ReadChar` or similar new
APIs.
.. deprecated-removed:: 3.3 3.12
Part of the old-style Unicode API, please migrate to using
:c:func:`PyUnicode_AsUCS4`, :c:func:`PyUnicode_AsWideChar`,
:c:func:`PyUnicode_ReadChar` or similar new APIs.
.. c:function:: PyObject* PyUnicode_TransformDecimalToASCII(Py_UNICODE *s, Py_ssize_t size)
@ -718,19 +737,10 @@ Extension modules can continue using them, as they will not be removed in Python
.. versionadded:: 3.3
.. c:function:: Py_UNICODE* PyUnicode_AsUnicodeCopy(PyObject *unicode)
Create a copy of a Unicode string ending with a null code point. Return ``NULL``
and raise a :exc:`MemoryError` exception on memory allocation failure,
otherwise return a new allocated buffer (use :c:func:`PyMem_Free` to free
the buffer). Note that the resulting :c:type:`Py_UNICODE*` string may
contain embedded null code points, which would cause the string to be
truncated when used in most C functions.
.. versionadded:: 3.2
Please migrate to using :c:func:`PyUnicode_AsUCS4Copy` or similar new APIs.
.. deprecated-removed:: 3.3 3.12
Part of the old-style Unicode API, please migrate to using
:c:func:`PyUnicode_AsUCS4`, :c:func:`PyUnicode_AsWideChar`,
:c:func:`PyUnicode_ReadChar` or similar new APIs.
.. c:function:: Py_ssize_t PyUnicode_GetSize(PyObject *unicode)
@ -738,7 +748,9 @@ Extension modules can continue using them, as they will not be removed in Python
Return the size of the deprecated :c:type:`Py_UNICODE` representation, in
code units (this includes surrogate pairs as 2 units).
Please migrate to using :c:func:`PyUnicode_GetLength`.
.. deprecated-removed:: 3.3 3.12
Part of the old-style Unicode API, please migrate to using
:c:func:`PyUnicode_GET_LENGTH`.
.. c:function:: PyObject* PyUnicode_FromObject(PyObject *obj)
@ -983,7 +995,7 @@ have the same semantics as the ones of the built-in :func:`str` string object
constructor.
Setting encoding to ``NULL`` causes the default encoding to be used
which is ASCII. The file system calls should use
which is UTF-8. The file system calls should use
:c:func:`PyUnicode_FSConverter` for encoding file names. This uses the
variable :c:data:`Py_FileSystemDefaultEncoding` internally. This
variable should be treated as read-only: on some systems, it will be a
@ -1086,6 +1098,9 @@ These are the UTF-8 codec APIs:
.. versionchanged:: 3.7
The return type is now ``const char *`` rather of ``char *``.
.. versionchanged:: 3.10
This function is a part of the :ref:`limited API <stable>`.
.. c:function:: const char* PyUnicode_AsUTF8(PyObject *unicode)
@ -1475,17 +1490,21 @@ These are the mapping codec APIs:
The following codec API is special in that maps Unicode to Unicode.
.. c:function:: PyObject* PyUnicode_Translate(PyObject *unicode, \
PyObject *mapping, const char *errors)
.. c:function:: PyObject* PyUnicode_Translate(PyObject *str, PyObject *table, const char *errors)
Translate a Unicode object using the given *mapping* object and return the
resulting Unicode object. Return ``NULL`` if an exception was raised by the
Translate a string by applying a character mapping table to it and return the
resulting Unicode object. Return ``NULL`` if an exception was raised by the
codec.
The *mapping* object must map Unicode ordinal integers to Unicode strings,
integers (which are then interpreted as Unicode ordinals) or ``None``
(causing deletion of the character). Unmapped character ordinals (ones
which cause a :exc:`LookupError`) are left untouched and are copied as-is.
The mapping table must map Unicode ordinal integers to Unicode ordinal integers
or ``None`` (causing deletion of the character).
Mapping tables need only provide the :meth:`__getitem__` interface; dictionaries
and sequences work well. Unmapped character ordinals (ones which cause a
:exc:`LookupError`) are left untouched and are copied as-is.
*errors* has the usual meaning for codecs. It may be ``NULL`` which indicates to
use the default error handling.
.. c:function:: PyObject* PyUnicode_TranslateCharmap(const Py_UNICODE *s, Py_ssize_t size, \
@ -1588,23 +1607,6 @@ They all return ``NULL`` or ``-1`` if an exception occurs.
characters are not included in the resulting strings.
.. c:function:: PyObject* PyUnicode_Translate(PyObject *str, PyObject *table, \
const char *errors)
Translate a string by applying a character mapping table to it and return the
resulting Unicode object.
The mapping table must map Unicode ordinal integers to Unicode ordinal integers
or ``None`` (causing deletion of the character).
Mapping tables need only provide the :meth:`__getitem__` interface; dictionaries
and sequences work well. Unmapped character ordinals (ones which cause a
:exc:`LookupError`) are left untouched and are copied as-is.
*errors* has the usual meaning for codecs. It may be ``NULL`` which indicates to
use the default error handling.
.. c:function:: PyObject* PyUnicode_Join(PyObject *separator, PyObject *seq)
Join a sequence of strings using the given *separator* and return the resulting

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

@ -16,11 +16,11 @@ parameter. The available start symbols are :const:`Py_eval_input`,
:const:`Py_file_input`, and :const:`Py_single_input`. These are described
following the functions which accept them as parameters.
Note also that several of these functions take :c:type:`FILE\*` parameters. One
Note also that several of these functions take :c:type:`FILE*` parameters. One
particular issue which needs to be handled carefully is that the :c:type:`FILE`
structure for different C libraries can be different and incompatible. Under
Windows (at least), it is possible for dynamically linked extensions to actually
use different libraries, so care should be taken that :c:type:`FILE\*` parameters
use different libraries, so care should be taken that :c:type:`FILE*` parameters
are only passed to these functions if it is certain that they were created by
the same library that the Python runtime is using.

14
Doc/conf.py
View File

@ -14,7 +14,8 @@ sys.path.append(os.path.abspath('includes'))
# ---------------------
extensions = ['sphinx.ext.coverage', 'sphinx.ext.doctest',
'pyspecific', 'c_annotations', 'escape4chm']
'pyspecific', 'c_annotations', 'escape4chm',
'asdl_highlight', 'peg_highlight']
doctest_global_setup = '''
@ -127,6 +128,7 @@ latex_elements['preamble'] = r'''
}
\let\Verbatim=\OriginalVerbatim
\let\endVerbatim=\endOriginalVerbatim
\setcounter{tocdepth}{2}
'''
# The paper size ('letter' or 'a4').
@ -226,3 +228,13 @@ linkcheck_ignore = [r'https://bugs.python.org/(issue)?\d+',
# Relative filename of the reference count data file.
refcount_file = 'data/refcounts.dat'
# Sphinx 2 and Sphinx 3 compatibility
# -----------------------------------
# bpo-40204: Allow Sphinx 2 syntax in the C domain
c_allow_pre_v3 = True
# bpo-40204: Disable warnings on Sphinx 2 syntax of the C domain since the
# documentation is built with -W (warnings treated as errors).
c_warn_on_allowed_pre_v3 = False

2
Doc/copyright.rst
View File

@ -4,7 +4,7 @@ Copyright
Python and this documentation is:
Copyright © 2001-2019 Python Software Foundation. All rights reserved.
Copyright © 2001-2020 Python Software Foundation. All rights reserved.
Copyright © 2000 BeOpen.com. All rights reserved.

41
Doc/data/refcounts.dat
View File

@ -1076,6 +1076,11 @@ PyIter_Check:PyObject*:o:0:
PyIter_Next:PyObject*::+1:
PyIter_Next:PyObject*:o:0:
PyIter_Send:int:::
PyIter_Send:PyObject*:iter:0:
PyIter_Send:PyObject*:arg:0:
PyIter_Send:PyObject**:presult:+1:
PyList_Append:int:::
PyList_Append:PyObject*:list:0:
PyList_Append:PyObject*:item:+1:
@ -1205,11 +1210,6 @@ PyLong_FromString:const char*:str::
PyLong_FromString:char**:pend::
PyLong_FromString:int:base::
PyLong_FromUnicode:PyObject*::+1:
PyLong_FromUnicode:Py_UNICODE*:u::
PyLong_FromUnicode:Py_ssize_t:length::
PyLong_FromUnicode:int:base::
PyLong_FromUnicodeObject:PyObject*::+1:
PyLong_FromUnicodeObject:PyObject*:u:0:
PyLong_FromUnicodeObject:int:base::
@ -1568,21 +1568,6 @@ PyOS_FSPath:PyObject*:path:0:
PyObject_ASCII:PyObject*::+1:
PyObject_ASCII:PyObject*:o:0:
PyObject_AsCharBuffer:int:::
PyObject_AsCharBuffer:PyObject*:obj:0:
PyObject_AsCharBuffer:const char**:buffer::
PyObject_AsCharBuffer:Py_ssize_t*:buffer_len::
PyObject_AsReadBuffer:int:::
PyObject_AsReadBuffer:PyObject*:obj:0:
PyObject_AsReadBuffer:const void**:buffer::
PyObject_AsReadBuffer:Py_ssize_t*:buffer_len::
PyObject_AsWriteBuffer:int:::
PyObject_AsWriteBuffer:PyObject*:obj:0:
PyObject_AsWriteBuffer:void**:buffer::
PyObject_AsWriteBuffer:Py_ssize_t*:buffer_len::
PyObject_Bytes:PyObject*::+1:
PyObject_Bytes:PyObject*:o:0:
@ -1618,9 +1603,6 @@ PyObject_CallObject:PyObject*:args:0:
PyObject_CheckBuffer:int:::
PyObject_CheckBuffer:PyObject*:obj:0:
PyObject_CheckReadBuffer:int:::
PyObject_CheckReadBuffer:PyObject*:o:0:
PyObject_DelAttr:int:::
PyObject_DelAttr:PyObject*:o:0:
PyObject_DelAttr:PyObject*:attr_name:0:
@ -1673,7 +1655,8 @@ PyObject_GenericSetAttr:PyObject*:name:0:
PyObject_GenericSetAttr:PyObject*:value:+1:
PyObject_GenericSetDict:int:::
PyObject_GenericSetDict:PyObject*:o:+1:
PyObject_GenericSetDict:PyObject*:o:0:
PyObject_GenericSetDict:PyObject*:value:+1:
PyObject_GenericSetDict:void*:context::
PyObject_GetAttr:PyObject*::+1:
@ -2305,6 +2288,11 @@ PyType_CheckExact:PyObject*:o:0:
PyType_FromSpec:PyObject*::+1:
PyType_FromSpec:PyType_Spec*:spec::
PyType_FromModuleAndSpec:PyObject*::+1:
PyType_FromModuleAndSpec:PyObject*:module:+1:
PyType_FromModuleAndSpec:PyType_Spec*:spec::
PyType_FromModuleAndSpec:PyObject*:bases:0:
PyType_FromSpecWithBases:PyObject*::+1:
PyType_FromSpecWithBases:PyType_Spec*:spec::
PyType_FromSpecWithBases:PyObject*:bases:0:
@ -2441,9 +2429,6 @@ PyUnicode_AsUnicodeAndSize:Py_UNICODE*:::
PyUnicode_AsUnicodeAndSize:PyObject*:unicode:0:
PyUnicode_AsUnicodeAndSize:Py_ssize_t*:size::
PyUnicode_AsUnicodeCopy:Py_UNICODE*:::
PyUnicode_AsUnicodeCopy:PyObject*:unicode:0:
PyUnicode_GetSize:Py_ssize_t:::
PyUnicode_GetSize:PyObject*:unicode:0:
@ -3045,8 +3030,6 @@ Py_XINCREF:PyObject*:o:+1:if o is not NULL
_PyImport_Fini:void:::
_PyImport_Init:void:::
_PyObject_New:PyObject*::+1:
_PyObject_New:PyTypeObject*:type:0:

3
Doc/distributing/index.rst
View File

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

31
Doc/distutils/apiref.rst
View File

@ -1142,6 +1142,24 @@ other utility module.
* ``macosx-10.6-intel``
For AIX, Python 3.9 and later return a string starting with "aix", followed
by additional fields (separated by ``'-'``) that represent the combined
values of AIX Version, Release and Technology Level (first field), Build Date
(second field), and bit-size (third field). Python 3.8 and earlier returned
only a single additional field with the AIX Version and Release.
Examples of returned values on AIX:
* ``aix-5307-0747-32`` # 32-bit build on AIX ``oslevel -s``: 5300-07-00-0000
* ``aix-7105-1731-64`` # 64-bit build on AIX ``oslevel -s``: 7100-05-01-1731
* ``aix-7.2`` # Legacy form reported in Python 3.8 and earlier
.. versionchanged:: 3.9
The AIX platform string format now also includes the technology level,
build date, and ABI bit-size.
.. function:: convert_path(pathname)
@ -1545,7 +1563,7 @@ Python's own build procedures.
=================================================
.. module:: distutils.text_file
:synopsis: provides the TextFile class, a simple interface to text files
:synopsis: Provides the TextFile class, a simple interface to text files
This module provides the :class:`TextFile` class, which gives an interface to
@ -1684,7 +1702,7 @@ lines, and joining lines with backslashes.
===================================================
.. module:: distutils.version
:synopsis: implements classes that represent module version numbers.
:synopsis: Implements classes that represent module version numbers.
.. % todo
@ -1699,7 +1717,7 @@ lines, and joining lines with backslashes.
===================================================================
.. module:: distutils.cmd
:synopsis: This module provides the abstract base class Command. This class
:synopsis: Provides the abstract base class :class:`~distutils.cmd.Command`. This class
is subclassed by the modules in the distutils.command subpackage.
@ -1792,7 +1810,7 @@ Subclasses of :class:`Command` must define the following methods.
==========================================================
.. module:: distutils.command
:synopsis: This subpackage contains one module for each standard Distutils command.
:synopsis: Contains one module for each standard Distutils command.
.. % \subsubsection{Individual Distutils commands}
@ -1837,6 +1855,9 @@ Subclasses of :class:`Command` must define the following methods.
.. 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
@ -2039,7 +2060,7 @@ This is described in more detail in :pep:`301`.
===================================================================
.. module:: distutils.command.check
:synopsis: Check the metadata of a package
:synopsis: Check the meta-data of a package
The ``check`` command performs some tests on the meta-data of a package.

9
Doc/distutils/builtdist.rst
View File

@ -149,6 +149,9 @@ generated by each, are:
.. note::
bdist_wininst is deprecated since Python 3.8.
.. note::
bdist_msi is deprecated since Python 3.9.
The following sections give details on the individual :command:`bdist_\*`
commands.
@ -304,6 +307,9 @@ Creating Windows Installers
.. warning::
bdist_wininst is deprecated since Python 3.8.
.. warning::
bdist_msi is deprecated since Python 3.9.
Executable installers are the natural format for binary distributions on
Windows. They display a nice graphical user interface, display some information
about the module distribution to be installed taken from the metadata in the
@ -468,3 +474,6 @@ installed for all users) and 'force' (meaning always prompt for elevation).
.. note::
bdist_wininst is deprecated since Python 3.8.
.. note::
bdist_msi is deprecated since Python 3.9.

2
Doc/distutils/examples.rst
View File

@ -255,7 +255,7 @@ Running the ``check`` command will display some warnings:
running check
warning: check: missing required meta-data: version, url
warning: check: missing meta-data: either (author and author_email) or
(maintainer and maintainer_email) must be supplied
(maintainer and maintainer_email) should be supplied
If you use the reStructuredText syntax in the ``long_description`` field and

14
Doc/extending/extending.rst
View File

@ -395,18 +395,26 @@ optionally followed by an import of the module::
}
/* Add a built-in module, before Py_Initialize */
PyImport_AppendInittab("spam", PyInit_spam);
if (PyImport_AppendInittab("spam", PyInit_spam) == -1) {
fprintf(stderr, "Error: could not extend in-built modules table\n");
exit(1);
}
/* Pass argv[0] to the Python interpreter */
Py_SetProgramName(program);
/* Initialize the Python interpreter. Required. */
/* Initialize the Python interpreter. Required.
If this step fails, it will be a fatal error. */
Py_Initialize();
/* Optionally import the module; alternatively,
import can be deferred until the embedded script
imports it. */
PyImport_ImportModule("spam");
pmodule = PyImport_ImportModule("spam");
if (!pmodule) {
PyErr_Print();
fprintf(stderr, "Error: could not import module 'spam'\n");
}
...

2
Doc/extending/newtypes_tutorial.rst
View File

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

7
Doc/faq/design.rst
View File

@ -148,6 +148,8 @@ variables and instance variables live in two different namespaces, and you need
to tell Python which namespace to use.
.. _why-can-t-i-use-an-assignment-in-an-expression:
Why can't I use an assignment in an expression?
-----------------------------------------------
@ -571,8 +573,7 @@ whether an instance or a class implements a particular ABC. The
:class:`~collections.abc.MutableMapping`.
For Python, many of the advantages of interface specifications can be obtained
by an appropriate test discipline for components. There is also a tool,
PyChecker, which can be used to find problems due to subclassing.
by an appropriate test discipline for components.
A good test suite for a module can both provide a regression test and serve as a
module interface specification and a set of examples. Many Python modules can
@ -649,7 +650,7 @@ Why doesn't Python have a "with" statement for attribute assignments?
---------------------------------------------------------------------
Python has a 'with' statement that wraps the execution of a block, calling code
on the entrance and exit from the block. Some language have a construct that
on the entrance and exit from the block. Some languages have a construct that
looks like this::
with obj:

29
Doc/faq/general.rst
View File

@ -17,12 +17,13 @@ What is Python?
Python is an interpreted, interactive, object-oriented programming language. It
incorporates modules, exceptions, dynamic typing, very high level dynamic data
types, and classes. Python combines remarkable power with very clear syntax.
It has interfaces to many system calls and libraries, as well as to various
window systems, and is extensible in C or C++. It is also usable as an
extension language for applications that need a programmable interface.
Finally, Python is portable: it runs on many Unix variants, on the Mac, and on
Windows 2000 and later.
types, and classes. It supports multiple programming paradigms beyond
object-oriented programming, such as procedural and functional programming.
Python combines remarkable power with very clear syntax. It has interfaces to
many system calls and libraries, as well as to various window systems, and is
extensible in C or C++. It is also usable as an extension language for
applications that need a programmable interface. Finally, Python is portable:
it runs on many Unix variants including Linux and macOS, and on Windows.
To find out more, start with :ref:`tutorial-index`. The `Beginner's Guide to
Python <https://wiki.python.org/moin/BeginnersGuide>`_ links to other
@ -141,9 +142,9 @@ to fix critical bugs.
Alpha, beta and release candidate versions have an additional suffix. The
suffix for an alpha version is "aN" for some small number N, the suffix for a
beta version is "bN" for some small number N, and the suffix for a release
candidate version is "cN" for some small number N. In other words, all versions
candidate version is "rcN" for some small number N. In other words, all versions
labeled 2.0aN precede the versions labeled 2.0bN, which precede versions labeled
2.0cN, and *those* precede 2.0.
2.0rcN, and *those* precede 2.0.
You may also find version numbers with a "+" suffix, e.g. "2.2+". These are
unreleased versions, built directly from the CPython development repository. In
@ -295,8 +296,8 @@ How stable is Python?
---------------------
Very stable. New, stable releases have been coming out roughly every 6 to 18
months since 1991, and this seems likely to continue. Currently there are
usually around 18 months between major releases.
months since 1991, and this seems likely to continue. As of version 3.9,
Python will have a major new release every 12 months (:pep:`602`).
The developers issue "bugfix" releases of older versions, so the stability of
existing releases gradually improves. Bugfix releases, indicated by a third
@ -308,14 +309,14 @@ releases.
The latest stable releases can always be found on the `Python download page
<https://www.python.org/downloads/>`_. There are two production-ready versions
of Python: 2.x and 3.x. The recommended version is 3.x, which is supported by
most widely used libraries. Although 2.x is still widely used, `it will not
be maintained after January 1, 2020 <https://www.python.org/dev/peps/pep-0373/>`_.
most widely used libraries. Although 2.x is still widely used, `it is not
maintained anymore <https://www.python.org/dev/peps/pep-0373/>`_.
How many people are using Python?
---------------------------------
There are probably tens of thousands of users, though it's difficult to obtain
an exact count.
There are probably millions of users, though it's difficult to obtain an exact
count.
Python is available for free download, so there are no sales figures, and it's
available from many different sites and packaged with many Linux distributions,

181
Doc/faq/programming.rst
View File

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

4
Doc/faq/windows.rst
View File

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

36
Doc/glossary.rst
View File

@ -189,6 +189,10 @@ Glossary
A list of bytecode instructions can be found in the documentation for
:ref:`the dis module <bytecodes>`.
callback
A subroutine function which is passed as an argument to be executed at
some point in the future.
class
A template for creating user-defined objects. Class definitions
normally contain method definitions which operate on instances of the
@ -304,6 +308,12 @@ Glossary
keys can be any object with :meth:`__hash__` and :meth:`__eq__` methods.
Called a hash in Perl.
dictionary comprehension
A compact way to process all or part of the elements in an iterable and
return a dictionary with the results. ``results = {n: n ** 2 for n in
range(10)}`` generates a dictionary containing key ``n`` mapped to
value ``n ** 2``. See :ref:`comprehensions`.
dictionary view
The objects returned from :meth:`dict.keys`, :meth:`dict.values`, and
:meth:`dict.items` are called dictionary views. They provide a dynamic
@ -583,7 +593,7 @@ Glossary
and :class:`tuple`) and some non-sequence types like :class:`dict`,
:term:`file objects <file object>`, and objects of any classes you define
with an :meth:`__iter__` method or with a :meth:`__getitem__` method
that implements :term:`Sequence` semantics.
that implements :term:`Sequence <sequence>` semantics.
Iterables can be
used in a :keyword:`for` loop and in many other places where a sequence is
@ -824,9 +834,11 @@ Glossary
.. _positional-only_parameter:
* :dfn:`positional-only`: specifies an argument that can be supplied only
by position. Python has no syntax for defining positional-only
parameters. However, some built-in functions have positional-only
parameters (e.g. :func:`abs`).
by position. Positional-only parameters can be defined by including a
``/`` character in the parameter list of the function definition after
them, for example *posonly1* and *posonly2* in the following::
def func(posonly1, posonly2, /, positional_or_keyword): ...
.. _keyword-only_parameter:
@ -1020,6 +1032,12 @@ Glossary
interface can be registered explicitly using
:func:`~abc.register`.
set comprehension
A compact way to process all or part of the elements in an iterable and
return a set with the results. ``results = {c for c in 'abracadabra' if
c not in 'abc'}`` generates the set of strings ``{'r', 'd'}``. See
:ref:`comprehensions`.
single dispatch
A form of :term:`generic function` dispatch where the implementation is
chosen based on the type of a single argument.
@ -1078,19 +1096,15 @@ Glossary
Type aliases are useful for simplifying :term:`type hints <type hint>`.
For example::
from typing import List, Tuple
def remove_gray_shades(
colors: List[Tuple[int, int, int]]) -> List[Tuple[int, int, int]]:
colors: list[tuple[int, int, int]]) -> list[tuple[int, int, int]]:
pass
could be made more readable like this::
from typing import List, Tuple
Color = tuple[int, int, int]
Color = Tuple[int, int, int]
def remove_gray_shades(colors: List[Color]) -> List[Color]:
def remove_gray_shades(colors: list[Color]) -> list[Color]:
pass
See :mod:`typing` and :pep:`484`, which describe this functionality.

34
Doc/howto/argparse.rst
View File

@ -353,7 +353,7 @@ Our program keeps growing in complexity::
args = parser.parse_args()
answer = args.square**2
if args.verbose:
print("the square of {} equals {}".format(args.square, answer))
print(f"the square of {args.square} equals {answer}")
else:
print(answer)
@ -387,9 +387,9 @@ multiple verbosity values, and actually get to use them::
args = parser.parse_args()
answer = args.square**2
if args.verbosity == 2:
print("the square of {} equals {}".format(args.square, answer))
print(f"the square of {args.square} equals {answer}")
elif args.verbosity == 1:
print("{}^2 == {}".format(args.square, answer))
print(f"{args.square}^2 == {answer}")
else:
print(answer)
@ -421,9 +421,9 @@ Let's fix it by restricting the values the ``--verbosity`` option can accept::
args = parser.parse_args()
answer = args.square**2
if args.verbosity == 2:
print("the square of {} equals {}".format(args.square, answer))
print(f"the square of {args.square} equals {answer}")
elif args.verbosity == 1:
print("{}^2 == {}".format(args.square, answer))
print(f"{args.square}^2 == {answer}")
else:
print(answer)
@ -461,9 +461,9 @@ verbosity argument (check the output of ``python --help``)::
args = parser.parse_args()
answer = args.square**2
if args.verbosity == 2:
print("the square of {} equals {}".format(args.square, answer))
print(f"the square of {args.square} equals {answer}")
elif args.verbosity == 1:
print("{}^2 == {}".format(args.square, answer))
print(f"{args.square}^2 == {answer}")
else:
print(answer)
@ -529,9 +529,9 @@ Let's fix::
# bugfix: replace == with >=
if args.verbosity >= 2:
print("the square of {} equals {}".format(args.square, answer))
print(f"the square of {args.square} equals {answer}")
elif args.verbosity >= 1:
print("{}^2 == {}".format(args.square, answer))
print(f"{args.square}^2 == {answer}")
else:
print(answer)
@ -566,9 +566,9 @@ Let's fix that bug::
args = parser.parse_args()
answer = args.square**2
if args.verbosity >= 2:
print("the square of {} equals {}".format(args.square, answer))
print(f"the square of {args.square} equals {answer}")
elif args.verbosity >= 1:
print("{}^2 == {}".format(args.square, answer))
print(f"{args.square}^2 == {answer}")
else:
print(answer)
@ -606,9 +606,9 @@ not just squares::
args = parser.parse_args()
answer = args.x**args.y
if args.verbosity >= 2:
print("{} to the power {} equals {}".format(args.x, args.y, answer))
print(f"{args.x} to the power {args.y} equals {answer}")
elif args.verbosity >= 1:
print("{}^{} == {}".format(args.x, args.y, answer))
print(f"{args.x}^{args.y} == {answer}")
else:
print(answer)
@ -645,9 +645,9 @@ to display *more* text instead::
args = parser.parse_args()
answer = args.x**args.y
if args.verbosity >= 2:
print("Running '{}'".format(__file__))
print(f"Running '{__file__}'")
if args.verbosity >= 1:
print("{}^{} == ".format(args.x, args.y), end="")
print(f"{args.x}^{args.y} == ", end="")
print(answer)
Output:
@ -688,9 +688,9 @@ which will be the opposite of the ``--verbose`` one::
if args.quiet:
print(answer)
elif args.verbose:
print("{} to the power {} equals {}".format(args.x, args.y, answer))
print(f"{args.x} to the power {args.y} equals {answer}")
else:
print("{}^{} == {}".format(args.x, args.y, answer))
print(f"{args.x}^{args.y} == {answer}")
Our program is now simpler, and we've lost some functionality for the sake of
demonstration. Anyways, here's the output:

6
Doc/howto/descriptor.rst
View File

@ -312,14 +312,12 @@ Running the interpreter shows how the function descriptor works in practice::
>>> d.f
<bound method D.f of <__main__.D object at 0x00B18C90>>
# Internally, the bound method stores the underlying function,
# the bound instance, and the class of the bound instance.
# Internally, the bound method stores the underlying function and
# the bound instance.
>>> d.f.__func__
<function D.f at 0x1012e5ae8>
>>> d.f.__self__
<__main__.D object at 0x1012e1f98>
>>> d.f.__class__
<class 'method'>
Static Methods and Class Methods

6
Doc/howto/functional.rst
View File

@ -1229,9 +1229,9 @@ Text Processing".
Mertz also wrote a 3-part series of articles on functional programming
for IBM's DeveloperWorks site; see
`part 1 <https://www.ibm.com/developerworks/linux/library/l-prog/index.html>`__,
`part 2 <https://www.ibm.com/developerworks/linux/library/l-prog2/index.html>`__, and
`part 3 <https://www.ibm.com/developerworks/linux/library/l-prog3/index.html>`__,
`part 1 <https://developer.ibm.com/articles/l-prog/>`__,
`part 2 <https://developer.ibm.com/tutorials/l-prog2/>`__, and
`part 3 <https://developer.ibm.com/tutorials/l-prog3/>`__,
Python documentation

24
Doc/howto/instrumentation.rst
View File

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

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

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

31
Doc/howto/logging.rst
View File

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

10
Doc/howto/pyporting.rst
View File

@ -125,7 +125,7 @@ Once you have your code well-tested you are ready to begin porting your code to
Python 3! But to fully understand how your code is going to change and what
you want to look out for while you code, you will want to learn what changes
Python 3 makes in terms of Python 2. Typically the two best ways of doing that
is reading the `"What's New"`_ doc for each release of Python 3 and the
is reading the :ref:`"What's New" <whatsnew-index>` doc for each release of Python 3 and the
`Porting to Python 3`_ book (which is free online). There is also a handy
`cheat sheet`_ from the Python-Future project.
@ -308,10 +308,10 @@ If for some reason that doesn't work then you should make the version check be
against Python 2 and not Python 3. To help explain this, let's look at an
example.
Let's pretend that you need access to a feature of importlib_ that
Let's pretend that you need access to a feature of :mod:`importlib` that
is available in Python's standard library since Python 3.3 and available for
Python 2 through importlib2_ on PyPI. You might be tempted to write code to
access e.g. the ``importlib.abc`` module by doing the following::
access e.g. the :mod:`importlib.abc` module by doing the following::
import sys
@ -432,12 +432,10 @@ can also explicitly state whether your APIs use textual or binary data, helping
to make sure everything functions as expected in both versions of Python.
.. _2to3: https://docs.python.org/3/library/2to3.html
.. _caniusepython3: https://pypi.org/project/caniusepython3
.. _cheat sheet: http://python-future.org/compatible_idioms.html
.. _coverage.py: https://pypi.org/project/coverage
.. _Futurize: http://python-future.org/automatic_conversion.html
.. _importlib: https://docs.python.org/3/library/importlib.html#module-importlib
.. _importlib2: https://pypi.org/project/importlib2
.. _Modernize: https://python-modernize.readthedocs.io/
.. _mypy: http://mypy-lang.org/
@ -453,6 +451,4 @@ to make sure everything functions as expected in both versions of Python.
.. _tox: https://pypi.org/project/tox
.. _trove classifier: https://pypi.org/classifiers
.. _"What's New": https://docs.python.org/3/whatsnew/index.html
.. _Why Python 3 exists: https://snarky.ca/why-python-3-exists

2
Doc/howto/sockets.rst
View File

@ -319,7 +319,7 @@ inside-out.
In Python, you use ``socket.setblocking(False)`` to make it non-blocking. In C, it's
more complex, (for one thing, you'll need to choose between the BSD flavor
``O_NONBLOCK`` and the almost indistinguishable Posix flavor ``O_NDELAY``, which
``O_NONBLOCK`` and the almost indistinguishable POSIX flavor ``O_NDELAY``, which
is completely different from ``TCP_NODELAY``), but it's the exact same idea. You
do this after creating the socket, but before using it. (Actually, if you're
nuts, you can switch back and forth.)

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