diff --git a/.azure-pipelines/ci.yml b/.azure-pipelines/ci.yml
index 6302b547982118..63252a76abb69f 100644
--- a/.azure-pipelines/ci.yml
+++ b/.azure-pipelines/ci.yml
@@ -14,20 +14,6 @@ jobs:
- template: ./prebuild-checks.yml
-- job: Docs_PR
- displayName: Docs PR
- dependsOn: Prebuild
- condition: and(succeeded(), eq(dependencies.Prebuild.outputs['docs.run'], 'true'))
-
- pool:
- vmImage: ubuntu-22.04
-
- steps:
- - template: ./docs-steps.yml
- parameters:
- upload: true
-
-
- job: macOS_CI_Tests
displayName: macOS CI Tests
dependsOn: Prebuild
@@ -57,7 +43,7 @@ jobs:
variables:
testRunTitle: '$(build.sourceBranchName)-linux'
testRunPlatform: linux
- openssl_version: 1.1.1t
+ openssl_version: 1.1.1u
steps:
- template: ./posix-steps.yml
@@ -83,7 +69,7 @@ jobs:
variables:
testRunTitle: '$(Build.SourceBranchName)-linux-coverage'
testRunPlatform: linux-coverage
- openssl_version: 1.1.1t
+ openssl_version: 1.1.1u
steps:
- template: ./posix-steps.yml
diff --git a/.azure-pipelines/docs-steps.yml b/.azure-pipelines/docs-steps.yml
deleted file mode 100644
index 647daff7a033a8..00000000000000
--- a/.azure-pipelines/docs-steps.yml
+++ /dev/null
@@ -1,47 +0,0 @@
-parameters:
- latex: false
- upload: false
-
-steps:
-- checkout: self
- clean: true
- fetchDepth: 5
-
-- task: UsePythonVersion@0
- displayName: 'Use Python 3.6 or later'
- inputs:
- versionSpec: '>=3.6'
-
-- script: python -m pip install -r requirements.txt
- workingDirectory: '$(build.sourcesDirectory)/Doc'
- displayName: 'Install build dependencies'
-
-- ${{ if ne(parameters.latex, 'true') }}:
- - script: make check html PYTHON=python
- workingDirectory: '$(build.sourcesDirectory)/Doc'
- displayName: 'Build documentation'
-
-- ${{ if eq(parameters.latex, 'true') }}:
- - script: sudo apt-get update && sudo apt-get install -qy --force-yes texlive-full
- displayName: 'Install LaTeX'
-
- - script: make dist PYTHON=python SPHINXBUILD='python -m sphinx' BLURB='python -m blurb'
- workingDirectory: '$(build.sourcesDirectory)/Doc'
- displayName: 'Build documentation'
-
-- ${{ if eq(parameters.upload, 'true') }}:
- - task: PublishBuildArtifacts@1
- displayName: 'Publish docs'
-
- inputs:
- PathToPublish: '$(build.sourcesDirectory)/Doc/build'
- ArtifactName: docs
- publishLocation: Container
-
- - ${{ if eq(parameters.latex, 'true') }}:
- - task: PublishBuildArtifacts@1
- displayName: 'Publish dist'
- inputs:
- PathToPublish: '$(build.sourcesDirectory)/Doc/dist'
- ArtifactName: docs_dist
- publishLocation: Container
diff --git a/.azure-pipelines/pr.yml b/.azure-pipelines/pr.yml
index 5f7218768c18af..939c9b4249a3c2 100644
--- a/.azure-pipelines/pr.yml
+++ b/.azure-pipelines/pr.yml
@@ -14,18 +14,6 @@ jobs:
- template: ./prebuild-checks.yml
-- job: Docs_PR
- displayName: Docs PR
- dependsOn: Prebuild
- condition: and(succeeded(), eq(dependencies.Prebuild.outputs['docs.run'], 'true'))
-
- pool:
- vmImage: ubuntu-22.04
-
- steps:
- - template: ./docs-steps.yml
-
-
- job: macOS_PR_Tests
displayName: macOS PR Tests
dependsOn: Prebuild
@@ -57,7 +45,7 @@ jobs:
variables:
testRunTitle: '$(system.pullRequest.TargetBranch)-linux'
testRunPlatform: linux
- openssl_version: 1.1.1t
+ openssl_version: 1.1.1u
steps:
- template: ./posix-steps.yml
@@ -83,7 +71,7 @@ jobs:
variables:
testRunTitle: '$(Build.SourceBranchName)-linux-coverage'
testRunPlatform: linux-coverage
- openssl_version: 1.1.1t
+ openssl_version: 1.1.1u
steps:
- template: ./posix-steps.yml
diff --git a/.azure-pipelines/prebuild-checks.yml b/.azure-pipelines/prebuild-checks.yml
index 30ff642d1267a1..2c6460d2386735 100644
--- a/.azure-pipelines/prebuild-checks.yml
+++ b/.azure-pipelines/prebuild-checks.yml
@@ -11,18 +11,6 @@ steps:
displayName: Fetch comparison tree
condition: and(succeeded(), variables['System.PullRequest.TargetBranch'])
-- script: |
- if ! git diff --name-only $(diffTarget) | grep -qE '(\.rst$|^Doc|^Misc)'
- then
- echo "No docs were updated: docs.run=false"
- echo "##vso[task.setvariable variable=run;isOutput=true]false"
- else
- echo "Docs were updated: docs.run=true"
- echo "##vso[task.setvariable variable=run;isOutput=true]true"
- fi
- displayName: Detect documentation changes
- name: docs
-
- script: |
if ! git diff --name-only $(diffTarget) | grep -qvE '(\.rst$|^Doc|^Misc)'
then
diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS
index 32ba5355a5853f..95fd51b743cd33 100644
--- a/.github/CODEOWNERS
+++ b/.github/CODEOWNERS
@@ -164,4 +164,4 @@ Lib/ast.py @isidentical
**/*pathlib* @barneygale
# zipfile.Path
-**/*zipfile/*_path.py @jaraco
+**/*zipfile/_path/* @jaraco
diff --git a/.github/problem-matchers/sphinx.json b/.github/problem-matchers/sphinx.json
deleted file mode 100644
index 09848608a7b034..00000000000000
--- a/.github/problem-matchers/sphinx.json
+++ /dev/null
@@ -1,40 +0,0 @@
-{
- "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
- }
- ]
- }
- ]
-}
\ No newline at end of file
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
index 41abddffa5d648..ea6d43947449f1 100644
--- a/.github/workflows/build.yml
+++ b/.github/workflows/build.yml
@@ -8,6 +8,7 @@ on:
push:
branches:
- 'main'
+ - '3.12'
- '3.11'
- '3.10'
- '3.9'
@@ -16,6 +17,7 @@ on:
pull_request:
branches:
- 'main'
+ - '3.12'
- '3.11'
- '3.10'
- '3.9'
@@ -26,7 +28,7 @@ permissions:
contents: read
concurrency:
- group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
+ group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}-reusable
cancel-in-progress: true
jobs:
@@ -35,8 +37,10 @@ jobs:
runs-on: ubuntu-latest
timeout-minutes: 10
outputs:
+ run-docs: ${{ steps.docs-changes.outputs.run-docs || false }}
run_tests: ${{ steps.check.outputs.run_tests }}
run_hypothesis: ${{ steps.check.outputs.run_hypothesis }}
+ config_hash: ${{ steps.config_hash.outputs.hash }}
steps:
- uses: actions/checkout@v3
- name: Check for source changes
@@ -72,6 +76,76 @@ jobs:
echo "Run hypothesis tests"
echo "run_hypothesis=true" >> $GITHUB_OUTPUT
fi
+ - name: Compute hash for config cache key
+ id: config_hash
+ run: |
+ echo "hash=${{ hashFiles('configure', 'configure.ac', '.github/workflows/build.yml') }}" >> $GITHUB_OUTPUT
+ - name: Get a list of the changed documentation-related files
+ if: github.event_name == 'pull_request'
+ id: changed-docs-files
+ uses: Ana06/get-changed-files@v2.2.0
+ with:
+ filter: |
+ Doc/**
+ Misc/**
+ .github/workflows/reusable-docs.yml
+ format: csv # works for paths with spaces
+ - name: Check for docs changes
+ if: >-
+ github.event_name == 'pull_request'
+ && steps.changed-docs-files.outputs.added_modified_renamed != ''
+ id: docs-changes
+ run: |
+ echo "run-docs=true" >> "${GITHUB_OUTPUT}"
+
+ check-docs:
+ name: Docs
+ needs: check_source
+ if: fromJSON(needs.check_source.outputs.run-docs)
+ uses: ./.github/workflows/reusable-docs.yml
+
+ check_abi:
+ name: 'Check if the ABI has changed'
+ runs-on: ubuntu-22.04
+ needs: check_source
+ if: needs.check_source.outputs.run_tests == 'true'
+ steps:
+ - uses: actions/checkout@v3
+ - uses: actions/setup-python@v4
+ - name: Install dependencies
+ run: |
+ sudo ./.github/workflows/posix-deps-apt.sh
+ sudo apt-get install -yq abigail-tools
+ - name: Build CPython
+ env:
+ CFLAGS: -g3 -O0
+ run: |
+ # Build Python with the libpython dynamic library
+ ./configure --enable-shared
+ make -j4
+ - name: Check for changes in the ABI
+ id: check
+ run: |
+ if ! make check-abidump; then
+ echo "Generated ABI file is not up to date."
+ echo "Please add the release manager of this branch as a reviewer of this PR."
+ echo ""
+ echo "The up to date ABI file should be attached to this build as an artifact."
+ echo ""
+ echo "To learn more about this check: https://devguide.python.org/setup/#regenerate-the-abi-dump"
+ echo ""
+ exit 1
+ fi
+ - name: Generate updated ABI files
+ if: ${{ failure() && steps.check.conclusion == 'failure' }}
+ run: |
+ make regen-abidump
+ - uses: actions/upload-artifact@v3
+ name: Publish updated ABI files
+ if: ${{ failure() && steps.check.conclusion == 'failure' }}
+ with:
+ name: abi-data
+ path: ./Doc/data/*.abi
check_generated_files:
name: 'Check if generated files are up to date'
@@ -81,6 +155,11 @@ jobs:
if: needs.check_source.outputs.run_tests == 'true'
steps:
- uses: actions/checkout@v3
+ - name: Restore config.cache
+ uses: actions/cache@v3
+ with:
+ path: config.cache
+ key: ${{ github.job }}-${{ runner.os }}-${{ needs.check_source.outputs.config_hash }}
- uses: actions/setup-python@v3
- name: Install Dependencies
run: sudo ./.github/workflows/posix-deps-apt.sh
@@ -88,16 +167,16 @@ jobs:
run: echo "PATH=/usr/lib/ccache:$PATH" >> $GITHUB_ENV
- name: Configure ccache action
uses: hendrikmuhs/ccache-action@v1.2
- - name: Check Autoconf version 2.69 and aclocal 1.16.3
+ - name: Check Autoconf and aclocal versions
run: |
- grep "Generated by GNU Autoconf 2.69" configure
- grep "aclocal 1.16.3" aclocal.m4
+ grep "Generated by GNU Autoconf 2.71" configure
+ grep "aclocal 1.16.4" aclocal.m4
grep -q "runstatedir" configure
grep -q "PKG_PROG_PKG_CONFIG" aclocal.m4
- name: Configure CPython
run: |
# Build Python with the libpython dynamic library
- ./configure --with-pydebug --enable-shared
+ ./configure --config-cache --with-pydebug --enable-shared
- name: Regenerate autoconf files with container image
run: make regen-configure
- name: Build CPython
@@ -178,17 +257,22 @@ jobs:
PYTHONSTRICTEXTENSIONBUILD: 1
steps:
- uses: actions/checkout@v3
+ - name: Restore config.cache
+ uses: actions/cache@v3
+ with:
+ path: config.cache
+ key: ${{ github.job }}-${{ runner.os }}-${{ needs.check_source.outputs.config_hash }}
- name: Install Homebrew dependencies
- run: brew install pkg-config openssl@1.1 xz gdbm tcl-tk
+ run: brew install pkg-config openssl@3.0 xz gdbm tcl-tk
- name: Configure CPython
run: |
- CFLAGS="-I$(brew --prefix gdbm)/include -I$(brew --prefix xz)/include" \
- LDFLAGS="-L$(brew --prefix gdbm)/lib -I$(brew --prefix xz)/lib" \
- PKG_CONFIG_PATH="$(brew --prefix tcl-tk)/lib/pkgconfig" \
+ GDBM_CFLAGS="-I$(brew --prefix gdbm)/include" \
+ GDBM_LIBS="-L$(brew --prefix gdbm)/lib -lgdbm" \
./configure \
+ --config-cache \
--with-pydebug \
--prefix=/opt/python-dev \
- --with-openssl="$(brew --prefix openssl@1.1)"
+ --with-openssl="$(brew --prefix openssl@3.0)"
- name: Build CPython
run: make -j4
- name: Display build info
@@ -203,7 +287,7 @@ jobs:
needs: check_source
if: needs.check_source.outputs.run_tests == 'true'
env:
- OPENSSL_VER: 1.1.1t
+ OPENSSL_VER: 1.1.1v
PYTHONSTRICTEXTENSIONBUILD: 1
steps:
- uses: actions/checkout@v3
@@ -238,9 +322,18 @@ jobs:
run: mkdir -p $CPYTHON_RO_SRCDIR $CPYTHON_BUILDDIR
- name: Bind mount sources read-only
run: sudo mount --bind -o ro $GITHUB_WORKSPACE $CPYTHON_RO_SRCDIR
+ - name: Restore config.cache
+ uses: actions/cache@v3
+ with:
+ path: ${{ env.CPYTHON_BUILDDIR }}/config.cache
+ key: ${{ github.job }}-${{ runner.os }}-${{ needs.check_source.outputs.config_hash }}
- name: Configure CPython out-of-tree
working-directory: ${{ env.CPYTHON_BUILDDIR }}
- run: ../cpython-ro-srcdir/configure --with-pydebug --with-openssl=$OPENSSL_DIR
+ run: |
+ ../cpython-ro-srcdir/configure \
+ --config-cache \
+ --with-pydebug \
+ --with-openssl=$OPENSSL_DIR
- name: Build CPython out-of-tree
working-directory: ${{ env.CPYTHON_BUILDDIR }}
run: make -j4
@@ -263,7 +356,7 @@ jobs:
strategy:
fail-fast: false
matrix:
- openssl_ver: [1.1.1t, 3.0.8, 3.1.0-beta1]
+ openssl_ver: [1.1.1v, 3.0.10, 3.1.2]
env:
OPENSSL_VER: ${{ matrix.openssl_ver }}
MULTISSL_DIR: ${{ github.workspace }}/multissl
@@ -271,6 +364,11 @@ jobs:
LD_LIBRARY_PATH: ${{ github.workspace }}/multissl/openssl/${{ matrix.openssl_ver }}/lib
steps:
- uses: actions/checkout@v3
+ - name: Restore config.cache
+ uses: actions/cache@v3
+ with:
+ path: config.cache
+ key: ${{ github.job }}-${{ runner.os }}-${{ needs.check_source.outputs.config_hash }}
- name: Register gcc problem matcher
run: echo "::add-matcher::.github/problem-matchers/gcc.json"
- name: Install Dependencies
@@ -295,7 +393,7 @@ jobs:
- name: Configure ccache action
uses: hendrikmuhs/ccache-action@v1.2
- name: Configure CPython
- run: ./configure --with-pydebug --with-openssl=$OPENSSL_DIR
+ run: ./configure --config-cache --with-pydebug --with-openssl=$OPENSSL_DIR
- name: Build CPython
run: make -j4
- name: Display build info
@@ -304,13 +402,13 @@ jobs:
run: ./python Lib/test/ssltests.py
test_hypothesis:
- name: "Hypothesis Tests on Ubuntu"
+ name: "Hypothesis tests on Ubuntu"
runs-on: ubuntu-20.04
timeout-minutes: 60
needs: check_source
if: needs.check_source.outputs.run_tests == 'true' && needs.check_source.outputs.run_hypothesis == 'true'
env:
- OPENSSL_VER: 1.1.1t
+ OPENSSL_VER: 1.1.1v
PYTHONSTRICTEXTENSIONBUILD: 1
steps:
- uses: actions/checkout@v3
@@ -345,9 +443,18 @@ jobs:
run: mkdir -p $CPYTHON_RO_SRCDIR $CPYTHON_BUILDDIR
- name: Bind mount sources read-only
run: sudo mount --bind -o ro $GITHUB_WORKSPACE $CPYTHON_RO_SRCDIR
+ - name: Restore config.cache
+ uses: actions/cache@v3
+ with:
+ path: ${{ env.CPYTHON_BUILDDIR }}/config.cache
+ key: ${{ github.job }}-${{ runner.os }}-${{ needs.check_source.outputs.config_hash }}
- name: Configure CPython out-of-tree
working-directory: ${{ env.CPYTHON_BUILDDIR }}
- run: ../cpython-ro-srcdir/configure --with-pydebug --with-openssl=$OPENSSL_DIR
+ run: |
+ ../cpython-ro-srcdir/configure \
+ --config-cache \
+ --with-pydebug \
+ --with-openssl=$OPENSSL_DIR
- name: Build CPython out-of-tree
working-directory: ${{ env.CPYTHON_BUILDDIR }}
run: make -j4
@@ -410,11 +517,16 @@ jobs:
needs: check_source
if: needs.check_source.outputs.run_tests == 'true'
env:
- OPENSSL_VER: 1.1.1t
+ OPENSSL_VER: 1.1.1v
PYTHONSTRICTEXTENSIONBUILD: 1
ASAN_OPTIONS: detect_leaks=0:allocator_may_return_null=1:handle_segv=0
steps:
- uses: actions/checkout@v3
+ - name: Restore config.cache
+ uses: actions/cache@v3
+ with:
+ path: config.cache
+ key: ${{ github.job }}-${{ runner.os }}-${{ needs.check_source.outputs.config_hash }}
- name: Register gcc problem matcher
run: echo "::add-matcher::.github/problem-matchers/gcc.json"
- name: Install Dependencies
@@ -443,10 +555,67 @@ jobs:
- name: Configure ccache action
uses: hendrikmuhs/ccache-action@v1.2
- name: Configure CPython
- run: ./configure --with-address-sanitizer --without-pymalloc
+ run: ./configure --config-cache --with-address-sanitizer --without-pymalloc
- name: Build CPython
run: make -j4
- name: Display build info
run: make pythoninfo
- name: Tests
run: xvfb-run make buildbottest TESTOPTS="-j4 -uall,-cpu"
+
+ all-required-green: # This job does nothing and is only used for the branch protection
+ name: All required checks pass
+ if: always()
+
+ needs:
+ - check_source # Transitive dependency, needed to access `run_tests` value
+ - check-docs
+ - check_generated_files
+ - build_win32
+ - build_win_amd64
+ - build_macos
+ - build_ubuntu
+ - build_ubuntu_ssltests
+ - test_hypothesis
+ - build_asan
+
+ runs-on: ubuntu-latest
+
+ steps:
+ - name: Check whether the needed jobs succeeded or failed
+ uses: re-actors/alls-green@05ac9388f0aebcb5727afa17fcccfecd6f8ec5fe
+ with:
+ allowed-failures: >-
+ build_macos,
+ build_ubuntu_ssltests,
+ build_win32,
+ test_hypothesis,
+ allowed-skips: >-
+ ${{
+ !fromJSON(needs.check_source.outputs.run-docs)
+ && '
+ check-docs,
+ '
+ || ''
+ }}
+ ${{
+ needs.check_source.outputs.run_tests != 'true'
+ && '
+ check_generated_files,
+ build_win32,
+ build_win_amd64,
+ build_macos,
+ build_ubuntu,
+ build_ubuntu_ssltests,
+ build_asan,
+ '
+ || ''
+ }}
+ ${{
+ !fromJSON(needs.check_source.outputs.run_hypothesis)
+ && '
+ test_hypothesis,
+ '
+ || ''
+ }}
+ jobs: ${{ toJSON(needs) }}
diff --git a/.github/workflows/build_msi.yml b/.github/workflows/build_msi.yml
index 2bed09014e0ff2..22f613a88aa11e 100644
--- a/.github/workflows/build_msi.yml
+++ b/.github/workflows/build_msi.yml
@@ -8,12 +8,14 @@ on:
- '3.*'
paths:
- 'Tools/msi/**'
+ - '.github/workflows/build_msi.yml'
pull_request:
branches:
- 'main'
- '3.*'
paths:
- 'Tools/msi/**'
+ - '.github/workflows/build_msi.yml'
permissions:
contents: read
@@ -33,4 +35,4 @@ jobs:
steps:
- uses: actions/checkout@v3
- name: Build CPython installer
- run: .\Tools\msi\build.bat -${{ matrix.type }}
+ run: .\Tools\msi\build.bat --doc -${{ matrix.type }}
diff --git a/.github/workflows/doc.yml b/.github/workflows/reusable-docs.yml
similarity index 55%
rename from .github/workflows/doc.yml
rename to .github/workflows/reusable-docs.yml
index 3f7550cc72943b..6150b1a7d416a3 100644
--- a/.github/workflows/doc.yml
+++ b/.github/workflows/reusable-docs.yml
@@ -1,29 +1,8 @@
name: Docs
on:
+ workflow_call:
workflow_dispatch:
- #push:
- # branches:
- # - 'main'
- # - '3.11'
- # - '3.10'
- # - '3.9'
- # - '3.8'
- # - '3.7'
- # paths:
- # - 'Doc/**'
- pull_request:
- branches:
- - 'main'
- - '3.11'
- - '3.10'
- - '3.9'
- - '3.8'
- - '3.7'
- paths:
- - 'Doc/**'
- - 'Misc/**'
- - '.github/workflows/doc.yml'
permissions:
contents: read
@@ -37,10 +16,30 @@ jobs:
name: 'Docs'
runs-on: ubuntu-latest
timeout-minutes: 60
+ env:
+ branch_base: 'origin/${{ github.event.pull_request.base.ref }}'
+ branch_pr: 'origin/${{ github.event.pull_request.head.ref }}'
+ refspec_base: '+${{ github.event.pull_request.base.sha }}:remotes/origin/${{ github.event.pull_request.base.ref }}'
+ refspec_pr: '+${{ github.event.pull_request.head.sha }}:remotes/origin/${{ github.event.pull_request.head.ref }}'
steps:
- - uses: actions/checkout@v3
- - name: Register Sphinx problem matcher
- run: echo "::add-matcher::.github/problem-matchers/sphinx.json"
+ - name: 'Check out latest PR branch commit'
+ uses: actions/checkout@v3
+ with:
+ ref: ${{ github.event.pull_request.head.sha }}
+ # Adapted from https://github.com/actions/checkout/issues/520#issuecomment-1167205721
+ - name: 'Fetch commits to get branch diff'
+ run: |
+ # Fetch enough history to find a common ancestor commit (aka merge-base):
+ git fetch origin ${{ env.refspec_pr }} --depth=$(( ${{ github.event.pull_request.commits }} + 1 )) \
+ --no-tags --prune --no-recurse-submodules
+
+ # This should get the oldest commit in the local fetched history (which may not be the commit the PR branched from):
+ COMMON_ANCESTOR=$( git rev-list --first-parent --max-parents=0 --max-count=1 ${{ env.branch_pr }} )
+ DATE=$( git log --date=iso8601 --format=%cd "${COMMON_ANCESTOR}" )
+
+ # Get all commits since that commit date from the base branch (eg: master or main):
+ git fetch origin ${{ env.refspec_base }} --shallow-since="${DATE}" \
+ --no-tags --prune --no-recurse-submodules
- name: 'Set up Python'
uses: actions/setup-python@v4
with:
@@ -49,39 +48,23 @@ jobs:
cache-dependency-path: 'Doc/requirements.txt'
- name: 'Install build dependencies'
run: make -C Doc/ venv
- - name: 'Check documentation'
- run: make -C Doc/ check
- - name: 'Build HTML documentation'
- run: make -C Doc/ SPHINXOPTS="-q" SPHINXERRORHANDLING="-W --keep-going" html
- # Add pull request annotations for Sphinx nitpicks (missing references)
- - name: 'Get list of changed files'
- if: github.event_name == 'pull_request'
- id: changed_files
- uses: Ana06/get-changed-files@v2.2.0
- with:
- filter: "Doc/**"
- - name: 'Build changed files in nit-picky mode'
- if: github.event_name == 'pull_request'
+ # To annotate PRs with Sphinx nitpicks (missing references)
+ - name: 'Build HTML documentation'
continue-on-error: true
run: |
- # Mark files the pull request modified
- touch ${{ steps.changed_files.outputs.added_modified }}
- # Build docs with the '-n' (nit-picky) option; convert warnings to annotations
- make -C Doc/ PYTHON=../python SPHINXOPTS="-q -n --keep-going" html 2>&1 |
- python Doc/tools/warnings-to-gh-actions.py
-
- # Ensure some files always pass Sphinx nit-picky mode (no missing references)
- - name: 'Build known-good files in nit-picky mode'
+ set -Eeuo pipefail
+ # Build docs with the '-n' (nit-picky) option; write warnings to file
+ make -C Doc/ PYTHON=../python SPHINXOPTS="-q -n -W --keep-going -w sphinx-warnings.txt" html
+ - name: 'Check warnings'
+ if: github.event_name == 'pull_request'
run: |
- # Mark files that must pass nit-picky
- python Doc/tools/touch-clean-files.py
- # Build docs with the '-n' (nit-picky) option, convert warnings to errors (-W)
- make -C Doc/ PYTHON=../python SPHINXOPTS="-q -n -W --keep-going" html 2>&1
+ python Doc/tools/check-warnings.py \
+ --annotate-diff '${{ env.branch_base }}' '${{ env.branch_pr }}' \
+ --fail-if-regression \
+ --fail-if-improved
# This build doesn't use problem matchers or check annotations
- # It also does not run 'make check', as sphinx-lint is not installed into the
- # environment.
build_doc_oldest_supported_sphinx:
name: 'Docs (Oldest Sphinx)'
runs-on: ubuntu-latest
@@ -106,8 +89,6 @@ jobs:
timeout-minutes: 60
steps:
- uses: actions/checkout@v3
- - name: Register Sphinx problem matcher
- run: echo "::add-matcher::.github/problem-matchers/sphinx.json"
- uses: actions/cache@v3
with:
path: ~/.cache/pip
diff --git a/.gitignore b/.gitignore
index ef7642b09bc5d2..bde596a7a0298b 100644
--- a/.gitignore
+++ b/.gitignore
@@ -156,6 +156,3 @@ Python/frozen_modules/MANIFEST
# Ignore ./python binary on Unix but still look into ./Python/ directory.
/python
!/Python/
-
-# main branch only: ABI files are not checked/maintained
-Doc/data/python*.abi
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 808622f19a3dbf..451cbe8bc84820 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -3,5 +3,16 @@ repos:
rev: v4.4.0
hooks:
- id: check-yaml
+ - id: end-of-file-fixer
+ types: [python]
+ exclude: Lib/test/coding20731.py
- id: trailing-whitespace
types_or: [c, python, rst]
+
+ - repo: https://github.com/sphinx-contrib/sphinx-lint
+ rev: v0.6.8
+ hooks:
+ - id: sphinx-lint
+ args: [--enable=default-role]
+ files: ^Doc/|^Misc/NEWS.d/next/
+ types: [rst]
diff --git a/Doc/Makefile b/Doc/Makefile
index c11ea6ce03e8a4..22691895068fea 100644
--- a/Doc/Makefile
+++ b/Doc/Makefile
@@ -216,11 +216,9 @@ dist:
rm dist/python-$(DISTVERSION)-docs-texinfo.tar
.PHONY: check
-check:
- # Check the docs and NEWS files with sphinx-lint.
- # Ignore the tools and venv dirs and check that the default role is not used.
- $(SPHINXLINT) -i tools -i $(VENVDIR) --enable default-role
- $(SPHINXLINT) --enable default-role ../Misc/NEWS.d/next/
+check: venv
+ $(VENVDIR)/bin/python3 -m pre_commit --version > /dev/null || $(VENVDIR)/bin/python3 -m pip install pre-commit
+ $(VENVDIR)/bin/python3 -m pre_commit run --all-files
.PHONY: serve
serve:
diff --git a/Doc/c-api/allocation.rst b/Doc/c-api/allocation.rst
index 0a8fcc5ae5fcdf..b3609c233156b6 100644
--- a/Doc/c-api/allocation.rst
+++ b/Doc/c-api/allocation.rst
@@ -27,22 +27,26 @@ Allocating Objects on the Heap
length information for a variable-size object.
-.. c:function:: TYPE* PyObject_New(TYPE, PyTypeObject *type)
+.. c:macro:: PyObject_New(TYPE, typeobj)
- Allocate a new Python object using the C structure type *TYPE* and the
- Python type object *type*. Fields not defined by the Python object header
- are not initialized; the object's reference count will be one. The size of
- the memory allocation is determined from the :c:member:`~PyTypeObject.tp_basicsize` field of
- the type object.
+ Allocate a new Python object using the C structure type *TYPE*
+ and the Python type object *typeobj* (``PyTypeObject*``).
+ Fields not defined by the Python object header are not initialized.
+ The caller will own the only reference to the object
+ (i.e. its reference count will be one).
+ The size of the memory allocation is determined from the
+ :c:member:`~PyTypeObject.tp_basicsize` field of the type object.
-.. c:function:: TYPE* PyObject_NewVar(TYPE, PyTypeObject *type, Py_ssize_t size)
+.. c:macro:: PyObject_NewVar(TYPE, typeobj, size)
Allocate a new Python object using the C structure type *TYPE* and the
- Python type object *type*. Fields not defined by the Python object header
+ Python type object *typeobj* (``PyTypeObject*``).
+ Fields not defined by the Python object header
are not initialized. The allocated memory allows for the *TYPE* structure
- plus *size* fields of the size given by the :c:member:`~PyTypeObject.tp_itemsize` field of
- *type*. This is useful for implementing objects like tuples, which are
+ plus *size* (``Py_ssize_t``) fields of the size
+ given by the :c:member:`~PyTypeObject.tp_itemsize` field of
+ *typeobj*. This is useful for implementing objects like tuples, which are
able to determine their size at construction time. Embedding the array of
fields into the same allocation decreases the number of allocations,
improving the memory management efficiency.
@@ -50,8 +54,8 @@ Allocating Objects on the Heap
.. c:function:: void PyObject_Del(void *op)
- Releases memory allocated to an object using :c:func:`PyObject_New` or
- :c:func:`PyObject_NewVar`. This is normally called from the
+ Releases memory allocated to an object using :c:macro:`PyObject_New` or
+ :c:macro:`PyObject_NewVar`. This is normally called from the
:c:member:`~PyTypeObject.tp_dealloc` handler specified in the object's type. The fields of
the object should not be accessed after this call as the memory is no
longer a valid Python object.
diff --git a/Doc/c-api/apiabiversion.rst b/Doc/c-api/apiabiversion.rst
index 62d542966622ce..f6c8284daeacb0 100644
--- a/Doc/c-api/apiabiversion.rst
+++ b/Doc/c-api/apiabiversion.rst
@@ -60,7 +60,7 @@ See :ref:`stable` for a discussion of API and ABI stability across versions.
Use this for numeric comparisons, e.g. ``#if PY_VERSION_HEX >= ...``.
- This version is also available via the symbol :data:`Py_Version`.
+ This version is also available via the symbol :c:var:`Py_Version`.
.. c:var:: const unsigned long Py_Version
diff --git a/Doc/c-api/arg.rst b/Doc/c-api/arg.rst
index 9713431688d499..657b10d3e0ac48 100644
--- a/Doc/c-api/arg.rst
+++ b/Doc/c-api/arg.rst
@@ -293,8 +293,10 @@ Other objects
``O`` (object) [PyObject \*]
Store a Python object (without any conversion) in a C object pointer. The C
- program thus receives the actual object that was passed. The object's reference
- count is not increased. The pointer stored is not ``NULL``.
+ program thus receives the actual object that was passed. A new
+ :term:`strong reference` to the object is not created
+ (i.e. its reference count is not increased).
+ The pointer stored is not ``NULL``.
``O!`` (object) [*typeobject*, PyObject \*]
Store a Python object in a C object pointer. This is similar to ``O``, but
@@ -343,7 +345,7 @@ Other objects
*items*. Format units for sequences may be nested.
It is possible to pass "long" integers (integers whose value exceeds the
-platform's :const:`LONG_MAX`) however no proper range checking is done --- the
+platform's :c:macro:`LONG_MAX`) however no proper range checking is done --- the
most significant bits are silently truncated when the receiving field is too
small to receive the value (actually, the semantics are inherited from downcasts
in C --- your mileage may vary).
@@ -378,7 +380,8 @@ inside nested parentheses. They are:
mutually exclude each other.
Note that any Python object references which are provided to the caller are
-*borrowed* references; do not decrement their reference count!
+*borrowed* references; do not release them
+(i.e. do not decrement their reference count)!
Additional arguments passed to these functions must be addresses of variables
whose type is determined by the format string; these are used to store values
@@ -455,7 +458,7 @@ API Functions
A simpler form of parameter retrieval which does not use a format string to
specify the types of the arguments. Functions which use this method to retrieve
- their parameters should be declared as :const:`METH_VARARGS` in function or
+ their parameters should be declared as :c:macro:`METH_VARARGS` in function or
method tables. The tuple containing the actual parameters should be passed as
*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
@@ -469,7 +472,7 @@ API Functions
will be set if there was a failure.
This is an example of the use of this function, taken from the sources for the
- :mod:`_weakref` helper module for weak references::
+ :mod:`!_weakref` helper module for weak references::
static PyObject *
weakref_ref(PyObject *self, PyObject *args)
@@ -547,7 +550,7 @@ Building values
Same as ``s#``.
``u`` (:class:`str`) [const wchar_t \*]
- Convert a null-terminated :c:expr:`wchar_t` buffer of Unicode (UTF-16 or UCS-4)
+ Convert a null-terminated :c:type:`wchar_t` buffer of Unicode (UTF-16 or UCS-4)
data to a Python Unicode object. If the Unicode buffer pointer is ``NULL``,
``None`` is returned.
@@ -613,8 +616,10 @@ Building values
Convert a C :c:type:`Py_complex` structure to a Python complex number.
``O`` (object) [PyObject \*]
- Pass a Python object untouched (except for its reference count, which is
- incremented by one). If the object passed in is a ``NULL`` pointer, it is assumed
+ Pass a Python object untouched but create a new
+ :term:`strong reference` to it
+ (i.e. its reference count is incremented by one).
+ If the object passed in is a ``NULL`` pointer, it is assumed
that this was caused because the call producing the argument found an error and
set an exception. Therefore, :c:func:`Py_BuildValue` will return ``NULL`` but won't
raise an exception. If no exception has been raised yet, :exc:`SystemError` is
@@ -624,7 +629,7 @@ Building values
Same as ``O``.
``N`` (object) [PyObject \*]
- Same as ``O``, except it doesn't increment the reference count on the object.
+ Same as ``O``, except it doesn't create a new :term:`strong reference`.
Useful when the object is created by a call to an object constructor in the
argument list.
diff --git a/Doc/c-api/bool.rst b/Doc/c-api/bool.rst
index c197d447e9618c..b14fa6a0a982e2 100644
--- a/Doc/c-api/bool.rst
+++ b/Doc/c-api/bool.rst
@@ -6,11 +6,17 @@ Boolean Objects
---------------
Booleans in Python are implemented as a subclass of integers. There are only
-two booleans, :const:`Py_False` and :const:`Py_True`. As such, the normal
+two booleans, :c:data:`Py_False` and :c:data:`Py_True`. As such, the normal
creation and deletion functions don't apply to booleans. The following macros
are available, however.
+.. c:var:: PyTypeObject PyBool_Type
+
+ This instance of :c:type:`PyTypeObject` represents the Python boolean type; it
+ is the same object as :class:`bool` in the Python layer.
+
+
.. c:function:: int PyBool_Check(PyObject *o)
Return true if *o* is of type :c:data:`PyBool_Type`. This function always
@@ -19,29 +25,32 @@ are available, however.
.. c:var:: PyObject* Py_False
- The Python ``False`` object. This object has no methods. It needs to be
- treated just like any other object with respect to reference counts.
+ The Python ``False`` object. This object has no methods and is
+ `immortal `_.
+
+.. versionchanged:: 3.12
+ :c:data:`Py_False` is immortal.
.. c:var:: PyObject* Py_True
- The Python ``True`` object. This object has no methods. It needs to be treated
- just like any other object with respect to reference counts.
+ The Python ``True`` object. This object has no methods and is
+ `immortal `_.
+
+.. versionchanged:: 3.12
+ :c:data:`Py_True` is immortal.
.. c:macro:: Py_RETURN_FALSE
- Return :const:`Py_False` from a function, properly incrementing its reference
- count.
+ Return :c:data:`Py_False` from a function.
.. c:macro:: Py_RETURN_TRUE
- Return :const:`Py_True` from a function, properly incrementing its reference
- count.
+ Return :c:data:`Py_True` from a function.
.. c:function:: PyObject* PyBool_FromLong(long v)
- Return a new reference to :const:`Py_True` or :const:`Py_False` depending on the
- truth value of *v*.
+ Return :c:data:`Py_True` or :c:data:`Py_False`, depending on the truth value of *v*.
diff --git a/Doc/c-api/buffer.rst b/Doc/c-api/buffer.rst
index 91d1edd9b2ec46..e572815ffd6259 100644
--- a/Doc/c-api/buffer.rst
+++ b/Doc/c-api/buffer.rst
@@ -44,7 +44,7 @@ the elements exposed by an :class:`array.array` can be multi-byte values.
An example consumer of the buffer interface is the :meth:`~io.BufferedIOBase.write`
method of file objects: any object that can export a series of bytes through
-the buffer interface can be written to a file. While :meth:`write` only
+the buffer interface can be written to a file. While :meth:`!write` only
needs read-only access to the internal contents of the object passed to it,
other methods such as :meth:`~io.BufferedIOBase.readinto` need write access
to the contents of their argument. The buffer interface allows objects to
@@ -102,7 +102,9 @@ a buffer, see :c:func:`PyObject_GetBuffer`.
.. c:member:: PyObject *obj
A new reference to the exporting object. The reference is owned by
- the consumer and automatically decremented and set to ``NULL`` by
+ the consumer and automatically released
+ (i.e. reference count decremented)
+ and set to ``NULL`` by
:c:func:`PyBuffer_Release`. The field is the equivalent of the return
value of any standard C-API function.
@@ -159,10 +161,7 @@ a buffer, see :c:func:`PyObject_GetBuffer`.
If it is ``0``, :c:member:`~Py_buffer.buf` points to a single item representing
a scalar. In this case, :c:member:`~Py_buffer.shape`, :c:member:`~Py_buffer.strides`
and :c:member:`~Py_buffer.suboffsets` MUST be ``NULL``.
-
- The macro :c:macro:`PyBUF_MAX_NDIM` limits the maximum number of dimensions
- 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.
+ The maximum number of dimensions is given by :c:macro:`PyBUF_MAX_NDIM`.
.. c:member:: Py_ssize_t *shape
@@ -215,6 +214,17 @@ a buffer, see :c:func:`PyObject_GetBuffer`.
freed when the buffer is released. The consumer MUST NOT alter this
value.
+
+Constants:
+
+.. c:macro:: PyBUF_MAX_NDIM
+
+ The maximum number of dimensions the memory represents.
+ Exporters MUST respect this limit, consumers of multi-dimensional
+ buffers SHOULD be able to handle up to :c:macro:`!PyBUF_MAX_NDIM` dimensions.
+ Currently set to 64.
+
+
.. _buffer-request-types:
Buffer request types
@@ -225,7 +235,7 @@ object via :c:func:`PyObject_GetBuffer`. Since the complexity of the logical
structure of the memory can vary drastically, the consumer uses the *flags*
argument to specify the exact buffer type it can handle.
-All :c:data:`Py_buffer` fields are unambiguously defined by the request
+All :c:type:`Py_buffer` fields are unambiguously defined by the request
type.
request-independent fields
@@ -438,7 +448,7 @@ 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 ``view->obj`` to ``NULL`` and
+ :exc:`BufferError`, set ``view->obj`` to ``NULL`` and
return ``-1``.
On success, fill in *view*, set ``view->obj`` to a new reference
@@ -454,7 +464,8 @@ Buffer-related functions
.. c:function:: void PyBuffer_Release(Py_buffer *view)
- Release the buffer *view* and decrement the reference count for
+ Release the buffer *view* and release the :term:`strong reference`
+ (i.e. decrement the reference count) to the view's supporting object,
``view->obj``. This function MUST be called when the buffer
is no longer being used, otherwise reference leaks may occur.
@@ -464,7 +475,7 @@ Buffer-related functions
.. c:function:: Py_ssize_t PyBuffer_SizeFromFormat(const char *format)
- Return the implied :c:data:`~Py_buffer.itemsize` from :c:data:`~Py_buffer.format`.
+ Return the implied :c:member:`~Py_buffer.itemsize` from :c:member:`~Py_buffer.format`.
On error, raise an exception and return -1.
.. versionadded:: 3.9
@@ -524,7 +535,7 @@ Buffer-related functions
and :c:macro:`PyBUF_WRITABLE` is set in *flags*.
On success, set ``view->obj`` to a new reference to *exporter* and
- return 0. Otherwise, raise :c:data:`PyExc_BufferError`, set
+ return 0. Otherwise, raise :exc:`BufferError`, set
``view->obj`` to ``NULL`` and return ``-1``;
If this function is used as part of a :ref:`getbufferproc `,
diff --git a/Doc/c-api/bytes.rst b/Doc/c-api/bytes.rst
index 9f48f2ffafe170..61a68f52773882 100644
--- a/Doc/c-api/bytes.rst
+++ b/Doc/c-api/bytes.rst
@@ -64,39 +64,39 @@ called with a non-bytes parameter.
+-------------------+---------------+--------------------------------+
| Format Characters | Type | Comment |
+===================+===============+================================+
- | :attr:`%%` | *n/a* | The literal % character. |
+ | ``%%`` | *n/a* | The literal % character. |
+-------------------+---------------+--------------------------------+
- | :attr:`%c` | int | A single byte, |
+ | ``%c`` | int | A single byte, |
| | | represented as a C int. |
+-------------------+---------------+--------------------------------+
- | :attr:`%d` | int | Equivalent to |
+ | ``%d`` | int | Equivalent to |
| | | ``printf("%d")``. [1]_ |
+-------------------+---------------+--------------------------------+
- | :attr:`%u` | unsigned int | Equivalent to |
+ | ``%u`` | unsigned int | Equivalent to |
| | | ``printf("%u")``. [1]_ |
+-------------------+---------------+--------------------------------+
- | :attr:`%ld` | long | Equivalent to |
+ | ``%ld`` | long | Equivalent to |
| | | ``printf("%ld")``. [1]_ |
+-------------------+---------------+--------------------------------+
- | :attr:`%lu` | unsigned long | Equivalent to |
+ | ``%lu`` | unsigned long | Equivalent to |
| | | ``printf("%lu")``. [1]_ |
+-------------------+---------------+--------------------------------+
- | :attr:`%zd` | :c:type:`\ | Equivalent to |
+ | ``%zd`` | :c:type:`\ | Equivalent to |
| | Py_ssize_t` | ``printf("%zd")``. [1]_ |
+-------------------+---------------+--------------------------------+
- | :attr:`%zu` | size_t | Equivalent to |
+ | ``%zu`` | size_t | Equivalent to |
| | | ``printf("%zu")``. [1]_ |
+-------------------+---------------+--------------------------------+
- | :attr:`%i` | int | Equivalent to |
+ | ``%i`` | int | Equivalent to |
| | | ``printf("%i")``. [1]_ |
+-------------------+---------------+--------------------------------+
- | :attr:`%x` | int | Equivalent to |
+ | ``%x`` | int | Equivalent to |
| | | ``printf("%x")``. [1]_ |
+-------------------+---------------+--------------------------------+
- | :attr:`%s` | const char\* | A null-terminated C character |
+ | ``%s`` | const char\* | A null-terminated C character |
| | | array. |
+-------------------+---------------+--------------------------------+
- | :attr:`%p` | const void\* | The hex representation of a C |
+ | ``%p`` | const void\* | The hex representation of a C |
| | | pointer. Mostly equivalent to |
| | | ``printf("%p")`` except that |
| | | it is guaranteed to start with |
@@ -184,8 +184,8 @@ called with a non-bytes parameter.
.. c:function:: void PyBytes_ConcatAndDel(PyObject **bytes, PyObject *newpart)
Create a new bytes object in *\*bytes* containing the contents of *newpart*
- appended to *bytes*. This version decrements the reference count of
- *newpart*.
+ appended to *bytes*. This version releases the :term:`strong reference`
+ to *newpart* (i.e. decrements its reference count).
.. c:function:: int _PyBytes_Resize(PyObject **bytes, Py_ssize_t newsize)
diff --git a/Doc/c-api/call.rst b/Doc/c-api/call.rst
index 4dc66e318cd12e..f4e401442c3d27 100644
--- a/Doc/c-api/call.rst
+++ b/Doc/c-api/call.rst
@@ -59,12 +59,12 @@ This bears repeating:
.. versionchanged:: 3.12
- The :const:`Py_TPFLAGS_HAVE_VECTORCALL` flag is now removed from a class
+ The :c:macro:`Py_TPFLAGS_HAVE_VECTORCALL` flag is now removed from a class
when the class's :py:meth:`~object.__call__` method is reassigned.
(This internally sets :c:member:`~PyTypeObject.tp_call` only, and thus
may make it behave differently than the vectorcall function.)
In earlier Python versions, vectorcall should only be used with
- :const:`immutable ` or static types.
+ :c:macro:`immutable ` or static types.
A class should not implement vectorcall if that would be slower
than *tp_call*. For example, if the callee needs to convert
@@ -72,7 +72,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
+:c:macro:`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:
@@ -84,7 +84,7 @@ This is a pointer to a function with the following signature:
values of the keyword arguments.
This can be *NULL* if there are no arguments.
- *nargsf* is the number of positional arguments plus possibly the
- :const:`PY_VECTORCALL_ARGUMENTS_OFFSET` flag.
+ :c:macro:`PY_VECTORCALL_ARGUMENTS_OFFSET` flag.
To get the actual number of positional arguments from *nargsf*,
use :c:func:`PyVectorcall_NARGS`.
- *kwnames* is a tuple containing the names of the keyword arguments;
@@ -93,7 +93,7 @@ This is a pointer to a function with the following signature:
and they must be unique.
If there are no keyword arguments, then *kwnames* can instead be *NULL*.
-.. data:: 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
@@ -104,7 +104,7 @@ This is a pointer to a function with the following signature:
``args[0]`` may be changed.
Whenever they can do so cheaply (without additional allocation), callers
- are encouraged to use :const:`PY_VECTORCALL_ARGUMENTS_OFFSET`.
+ are encouraged to use :c:macro:`PY_VECTORCALL_ARGUMENTS_OFFSET`.
Doing so will allow callables such as bound methods to make their onward
calls (which include a prepended *self* argument) very efficiently.
@@ -165,7 +165,7 @@ Vectorcall Support API
This is mostly useful to check whether or not *op* supports vectorcall,
which can be done by checking ``PyVectorcall_Function(op) != NULL``.
- .. versionadded:: 3.8
+ .. versionadded:: 3.9
.. c:function:: PyObject* PyVectorcall_Call(PyObject *callable, PyObject *tuple, PyObject *dict)
@@ -174,7 +174,7 @@ 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 :c:macro:`Py_TPFLAGS_HAVE_VECTORCALL` flag
and it does not fall back to ``tp_call``.
.. versionadded:: 3.8
@@ -392,11 +392,11 @@ please see individual documentation for details.
*args[0]*, and the *args* array starting at *args[1]* represents the arguments
of the call. There must be at least one positional argument.
*nargsf* is the number of positional arguments including *args[0]*,
- plus :const:`PY_VECTORCALL_ARGUMENTS_OFFSET` if the value of ``args[0]`` may
+ plus :c:macro:`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`.
- If the object has the :const:`Py_TPFLAGS_METHOD_DESCRIPTOR` feature,
+ If the object has the :c:macro:`Py_TPFLAGS_METHOD_DESCRIPTOR` feature,
this will call the unbound method object with the full
*args* vector as arguments.
diff --git a/Doc/c-api/capsule.rst b/Doc/c-api/capsule.rst
index 427ed959c58568..cdb8aa33e9fd32 100644
--- a/Doc/c-api/capsule.rst
+++ b/Doc/c-api/capsule.rst
@@ -64,7 +64,7 @@ Refer to :ref:`using-capsules` for more information on using these objects.
The *name* parameter must compare exactly to the name stored in the capsule.
If the name stored in the capsule is ``NULL``, the *name* passed in must also
- be ``NULL``. Python uses the C function :c:func:`strcmp` to compare capsule
+ be ``NULL``. Python uses the C function :c:func:`!strcmp` to compare capsule
names.
@@ -121,7 +121,7 @@ Refer to :ref:`using-capsules` for more information on using these objects.
compared.)
In other words, if :c:func:`PyCapsule_IsValid` returns a true value, calls to
- any of the accessors (any function starting with :c:func:`PyCapsule_Get`) are
+ any of the accessors (any function starting with ``PyCapsule_Get``) are
guaranteed to succeed.
Return a nonzero value if the object is valid and matches the name passed in.
diff --git a/Doc/c-api/cell.rst b/Doc/c-api/cell.rst
index ac4ef5adc5cc20..f8cd0344fdd1c0 100644
--- a/Doc/c-api/cell.rst
+++ b/Doc/c-api/cell.rst
@@ -25,7 +25,7 @@ Cell objects are not likely to be useful elsewhere.
The type object corresponding to cell objects.
-.. c:function:: int PyCell_Check(ob)
+.. c:function:: int PyCell_Check(PyObject *ob)
Return true if *ob* is a cell object; *ob* must not be ``NULL``. This
function always succeeds.
diff --git a/Doc/c-api/code.rst b/Doc/c-api/code.rst
index a99de9904c0740..5082b0cb6ad3f3 100644
--- a/Doc/c-api/code.rst
+++ b/Doc/c-api/code.rst
@@ -33,20 +33,20 @@ bound into a function.
Return the number of free variables in *co*.
-.. c:function:: PyCodeObject* PyUnstable_Code_New(int argcount, 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 *linetable, PyObject *exceptiontable)
+.. c:function:: PyCodeObject* PyUnstable_Code_New(int argcount, int kwonlyargcount, int nlocals, int stacksize, int flags, PyObject *code, PyObject *consts, PyObject *names, PyObject *varnames, PyObject *freevars, PyObject *cellvars, PyObject *filename, PyObject *name, PyObject *qualname, int firstlineno, PyObject *linetable, PyObject *exceptiontable)
Return a new code object. If you need a dummy code object to create a frame,
use :c:func:`PyCode_NewEmpty` instead.
Since the definition of the bytecode changes often, calling
- :c:func:`PyCode_New` directly can bind you to a precise Python version.
+ :c:func:`PyUnstable_Code_New` directly can bind you to a precise Python version.
The many arguments of this function are inter-dependent in complex
ways, meaning that subtle changes to values are likely to result in incorrect
execution or VM crashes. Use this function only with extreme care.
.. versionchanged:: 3.11
- Added ``exceptiontable`` parameter.
+ Added ``qualname`` and ``exceptiontable`` parameters.
.. index:: single: PyCode_New
@@ -56,17 +56,17 @@ bound into a function.
The old name is deprecated, but will remain available until the
signature changes again.
-.. c:function:: PyCodeObject* PyUnstable_Code_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 *linetable, PyObject *exceptiontable)
+.. c:function:: PyCodeObject* PyUnstable_Code_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, PyObject *qualname, int firstlineno, PyObject *linetable, PyObject *exceptiontable)
- Similar to :c:func:`PyCode_New`, but with an extra "posonlyargcount" for positional-only arguments.
- The same caveats that apply to ``PyCode_New`` also apply to this function.
+ Similar to :c:func:`PyUnstable_Code_New`, but with an extra "posonlyargcount" for positional-only arguments.
+ The same caveats that apply to ``PyUnstable_Code_New`` also apply to this function.
.. index:: single: PyCode_NewWithPosOnlyArgs
.. versionadded:: 3.8 as ``PyCode_NewWithPosOnlyArgs``
.. versionchanged:: 3.11
- Added ``exceptiontable`` parameter.
+ Added ``qualname`` and ``exceptiontable`` parameters.
.. versionchanged:: 3.12
diff --git a/Doc/c-api/codec.rst b/Doc/c-api/codec.rst
index 235c77c945cc5b..8ae5c4fecd6248 100644
--- a/Doc/c-api/codec.rst
+++ b/Doc/c-api/codec.rst
@@ -7,7 +7,7 @@ Codec registry and support functions
Register a new codec search function.
- As side effect, this tries to load the :mod:`encodings` package, if not yet
+ 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)
diff --git a/Doc/c-api/complex.rst b/Doc/c-api/complex.rst
index 344da903da4c1a..e3fd001c599c80 100644
--- a/Doc/c-api/complex.rst
+++ b/Doc/c-api/complex.rst
@@ -64,7 +64,7 @@ pointers. This is consistent throughout the API.
representation.
If *divisor* is null, this method returns zero and sets
- :c:data:`errno` to :c:data:`EDOM`.
+ :c:data:`errno` to :c:macro:`!EDOM`.
.. c:function:: Py_complex _Py_c_pow(Py_complex num, Py_complex exp)
@@ -73,7 +73,7 @@ pointers. This is consistent throughout the API.
representation.
If *num* is null and *exp* is not a positive real number,
- this method returns zero and sets :c:data:`errno` to :c:data:`EDOM`.
+ this method returns zero and sets :c:data:`errno` to :c:macro:`!EDOM`.
Complex Numbers as Python Objects
@@ -127,12 +127,12 @@ Complex Numbers as Python Objects
Return the :c:type:`Py_complex` value of the complex number *op*.
- If *op* is not a Python complex number object but has a :meth:`__complex__`
+ If *op* is not a Python complex number object but has a :meth:`~object.__complex__`
method, this method will first be called to convert *op* to a Python complex
- number object. If ``__complex__()`` is not defined then it falls back to
- :meth:`__float__`. If ``__float__()`` is not defined then it falls back
- to :meth:`__index__`. Upon failure, this method returns ``-1.0`` as a real
+ number object. If :meth:`!__complex__` is not defined then it falls back to
+ :meth:`~object.__float__`. If :meth:`!__float__` is not defined then it falls back
+ to :meth:`~object.__index__`. Upon failure, this method returns ``-1.0`` as a real
value.
.. versionchanged:: 3.8
- Use :meth:`__index__` if available.
+ Use :meth:`~object.__index__` if available.
diff --git a/Doc/c-api/conversion.rst b/Doc/c-api/conversion.rst
index fdb321fe7ab3f2..c5350123dfdfdc 100644
--- a/Doc/c-api/conversion.rst
+++ b/Doc/c-api/conversion.rst
@@ -119,10 +119,10 @@ The following functions provide locale-independent string to number conversions.
.. c:function:: int PyOS_stricmp(const char *s1, const char *s2)
Case insensitive comparison of strings. The function works almost
- identically to :c:func:`strcmp` except that it ignores the case.
+ identically to :c:func:`!strcmp` except that it ignores the case.
.. c:function:: int PyOS_strnicmp(const char *s1, const char *s2, Py_ssize_t size)
Case insensitive comparison of strings. The function works almost
- identically to :c:func:`strncmp` except that it ignores the case.
+ identically to :c:func:`!strncmp` except that it ignores the case.
diff --git a/Doc/c-api/datetime.rst b/Doc/c-api/datetime.rst
index 72fc07afbf1f4d..97522da773477e 100644
--- a/Doc/c-api/datetime.rst
+++ b/Doc/c-api/datetime.rst
@@ -8,11 +8,54 @@ DateTime Objects
Various date and time objects are supplied by the :mod:`datetime` module.
Before using any of these functions, the header file :file:`datetime.h` must be
included in your source (note that this is not included by :file:`Python.h`),
-and the macro :c:macro:`PyDateTime_IMPORT` must be invoked, usually as part of
+and the macro :c:macro:`!PyDateTime_IMPORT` must be invoked, usually as part of
the module initialisation function. The macro puts a pointer to a C structure
-into a static variable, :c:data:`PyDateTimeAPI`, that is used by the following
+into a static variable, :c:data:`!PyDateTimeAPI`, that is used by the following
macros.
+.. c:type:: PyDateTime_Date
+
+ This subtype of :c:type:`PyObject` represents a Python date object.
+
+.. c:type:: PyDateTime_DateTime
+
+ This subtype of :c:type:`PyObject` represents a Python datetime object.
+
+.. c:type:: PyDateTime_Time
+
+ This subtype of :c:type:`PyObject` represents a Python time object.
+
+.. c:type:: PyDateTime_Delta
+
+ This subtype of :c:type:`PyObject` represents the difference between two datetime values.
+
+.. c:var:: PyTypeObject PyDateTime_DateType
+
+ This instance of :c:type:`PyTypeObject` represents the Python date type;
+ it is the same object as :class:`datetime.date` in the Python layer.
+
+.. c:var:: PyTypeObject PyDateTime_DateTimeType
+
+ This instance of :c:type:`PyTypeObject` represents the Python datetime type;
+ it is the same object as :class:`datetime.datetime` in the Python layer.
+
+.. c:var:: PyTypeObject PyDateTime_TimeType
+
+ This instance of :c:type:`PyTypeObject` represents the Python time type;
+ it is the same object as :class:`datetime.time` in the Python layer.
+
+.. c:var:: PyTypeObject PyDateTime_DeltaType
+
+ This instance of :c:type:`PyTypeObject` represents Python type for
+ the difference between two datetime values;
+ it is the same object as :class:`datetime.timedelta` in the Python layer.
+
+.. c:var:: PyTypeObject PyDateTime_TZInfoType
+
+ This instance of :c:type:`PyTypeObject` represents the Python time zone info type;
+ it is the same object as :class:`datetime.tzinfo` in the Python layer.
+
+
Macro for access to the UTC singleton:
.. c:var:: PyObject* PyDateTime_TimeZone_UTC
@@ -28,7 +71,7 @@ Type-check macros:
.. c:function:: int PyDate_Check(PyObject *ob)
Return true if *ob* is of type :c:data:`PyDateTime_DateType` or a subtype of
- :c:data:`PyDateTime_DateType`. *ob* must not be ``NULL``. This function always
+ :c:data:`!PyDateTime_DateType`. *ob* must not be ``NULL``. This function always
succeeds.
@@ -41,7 +84,7 @@ Type-check macros:
.. c:function:: int PyDateTime_Check(PyObject *ob)
Return true if *ob* is of type :c:data:`PyDateTime_DateTimeType` or a subtype of
- :c:data:`PyDateTime_DateTimeType`. *ob* must not be ``NULL``. This function always
+ :c:data:`!PyDateTime_DateTimeType`. *ob* must not be ``NULL``. This function always
succeeds.
@@ -54,7 +97,7 @@ Type-check macros:
.. c:function:: int PyTime_Check(PyObject *ob)
Return true if *ob* is of type :c:data:`PyDateTime_TimeType` or a subtype of
- :c:data:`PyDateTime_TimeType`. *ob* must not be ``NULL``. This function always
+ :c:data:`!PyDateTime_TimeType`. *ob* must not be ``NULL``. This function always
succeeds.
@@ -67,7 +110,7 @@ Type-check macros:
.. c:function:: int PyDelta_Check(PyObject *ob)
Return true if *ob* is of type :c:data:`PyDateTime_DeltaType` or a subtype of
- :c:data:`PyDateTime_DeltaType`. *ob* must not be ``NULL``. This function always
+ :c:data:`!PyDateTime_DeltaType`. *ob* must not be ``NULL``. This function always
succeeds.
@@ -80,7 +123,7 @@ Type-check macros:
.. c:function:: int PyTZInfo_Check(PyObject *ob)
Return true if *ob* is of type :c:data:`PyDateTime_TZInfoType` or a subtype of
- :c:data:`PyDateTime_TZInfoType`. *ob* must not be ``NULL``. This function always
+ :c:data:`!PyDateTime_TZInfoType`. *ob* must not be ``NULL``. This function always
succeeds.
@@ -133,7 +176,7 @@ Macros to create objects:
:class:`datetime.timedelta` objects.
-.. c:function:: PyObject* PyTimeZone_FromOffset(PyDateTime_DeltaType* offset)
+.. c:function:: PyObject* PyTimeZone_FromOffset(PyObject *offset)
Return a :class:`datetime.timezone` object with an unnamed fixed offset
represented by the *offset* argument.
@@ -141,7 +184,7 @@ Macros to create objects:
.. versionadded:: 3.7
-.. c:function:: PyObject* PyTimeZone_FromOffsetAndName(PyDateTime_DeltaType* offset, PyUnicode* name)
+.. c:function:: PyObject* PyTimeZone_FromOffsetAndName(PyObject *offset, PyObject *name)
Return a :class:`datetime.timezone` object with a fixed offset represented
by the *offset* argument and with tzname *name*.
@@ -150,8 +193,8 @@ Macros to create objects:
Macros to extract fields from date objects. The argument must be an instance of
-:c:data:`PyDateTime_Date`, including subclasses (such as
-:c:data:`PyDateTime_DateTime`). The argument must not be ``NULL``, and the type is
+:c:type:`PyDateTime_Date`, including subclasses (such as
+:c:type:`PyDateTime_DateTime`). The argument must not be ``NULL``, and the type is
not checked:
.. c:function:: int PyDateTime_GET_YEAR(PyDateTime_Date *o)
@@ -170,7 +213,7 @@ not checked:
Macros to extract fields from datetime objects. The argument must be an
-instance of :c:data:`PyDateTime_DateTime`, including subclasses. The argument
+instance of :c:type:`PyDateTime_DateTime`, including subclasses. The argument
must not be ``NULL``, and the type is not checked:
.. c:function:: int PyDateTime_DATE_GET_HOUR(PyDateTime_DateTime *o)
@@ -208,7 +251,7 @@ must not be ``NULL``, and the type is not checked:
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``,
+:c:type:`PyDateTime_Time`, including subclasses. The argument must not be ``NULL``,
and the type is not checked:
.. c:function:: int PyDateTime_TIME_GET_HOUR(PyDateTime_Time *o)
@@ -246,7 +289,7 @@ and the type is not checked:
Macros to extract fields from time delta objects. The argument must be an
-instance of :c:data:`PyDateTime_Delta`, including subclasses. The argument must
+instance of :c:type:`PyDateTime_Delta`, including subclasses. The argument must
not be ``NULL``, and the type is not checked:
.. c:function:: int PyDateTime_DELTA_GET_DAYS(PyDateTime_Delta *o)
diff --git a/Doc/c-api/dict.rst b/Doc/c-api/dict.rst
index 0ca8ad624b2034..f668f845de610e 100644
--- a/Doc/c-api/dict.rst
+++ b/Doc/c-api/dict.rst
@@ -73,7 +73,7 @@ Dictionary Objects
.. index:: single: PyUnicode_FromString()
Insert *val* into the dictionary *p* using *key* as a key. *key* should
- be a :c:expr:`const char*`. The key object is created using
+ be a :c:expr:`const char*` UTF-8 encoded bytes string. The key object is created using
``PyUnicode_FromString(key)``. Return ``0`` on success or ``-1`` on
failure. This function *does not* steal a reference to *val*.
@@ -88,7 +88,8 @@ Dictionary Objects
.. 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*.
+ Remove the entry in dictionary *p* which has a key specified by the UTF-8
+ encoded bytes string *key*.
If *key* is not in the dictionary, :exc:`KeyError` is raised.
Return ``0`` on success or ``-1`` on failure.
@@ -98,9 +99,11 @@ Dictionary Objects
Return the object from dictionary *p* which has a key *key*. Return ``NULL``
if the key *key* is not present, but *without* setting an exception.
- Note that exceptions which occur while calling :meth:`__hash__` and
- :meth:`__eq__` methods will get suppressed.
- To get error reporting use :c:func:`PyDict_GetItemWithError()` instead.
+ .. note::
+
+ Exceptions that occur while this calls :meth:`~object.__hash__` and
+ :meth:`~object.__eq__` methods are silently ignored.
+ Prefer the :c:func:`PyDict_GetItemWithError` function instead.
.. versionchanged:: 3.10
Calling this API without :term:`GIL` held had been allowed for historical
@@ -118,12 +121,16 @@ 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:expr:`const char*`, rather than a :c:expr:`PyObject*`.
+ :c:expr:`const char*` UTF-8 encoded bytes string, rather than a
+ :c:expr:`PyObject*`.
+
+ .. note::
- Note that exceptions which occur while calling :meth:`__hash__` and
- :meth:`__eq__` methods and creating a temporary string object
- will get suppressed.
- To get error reporting use :c:func:`PyDict_GetItemWithError()` instead.
+ Exceptions that occur while this calls :meth:`~object.__hash__` and
+ :meth:`~object.__eq__` methods or while creating the temporary :class:`str`
+ object are silently ignored.
+ Prefer using the :c:func:`PyDict_GetItemWithError` function with your own
+ :c:func:`PyUnicode_FromString` *key* instead.
.. c:function:: PyObject* PyDict_SetDefault(PyObject *p, PyObject *key, PyObject *defaultobj)
diff --git a/Doc/c-api/exceptions.rst b/Doc/c-api/exceptions.rst
index 4ed96f01dbbc3e..6e2ac0a40a5f1b 100644
--- a/Doc/c-api/exceptions.rst
+++ b/Doc/c-api/exceptions.rst
@@ -60,9 +60,14 @@ Printing and clearing
Call this function **only** when the error indicator is set. Otherwise it
will cause a fatal error!
- If *set_sys_last_vars* is nonzero, the variables :data:`sys.last_type`,
- :data:`sys.last_value` and :data:`sys.last_traceback` will be set to the
- type, value and traceback of the printed exception, respectively.
+ If *set_sys_last_vars* is nonzero, the variable :data:`sys.last_exc` is
+ set to the printed exception. For backwards compatibility, the
+ deprecated variables :data:`sys.last_type`, :data:`sys.last_value` and
+ :data:`sys.last_traceback` are also set to the type, value and traceback
+ of this exception, respectively.
+
+ .. versionchanged:: 3.12
+ The setting of :data:`sys.last_exc` was added.
.. c:function:: void PyErr_Print()
@@ -78,7 +83,7 @@ Printing and clearing
This utility function prints a warning message to ``sys.stderr`` when an
exception has been set but it is impossible for the interpreter to actually
raise the exception. It is used, for example, when an exception occurs in an
- :meth:`__del__` method.
+ :meth:`~object.__del__` method.
The function is called with a single argument *obj* that identifies the context
in which the unraisable exception occurred. If possible,
@@ -105,7 +110,8 @@ For convenience, some of these functions will always return a
This is the most common way to set the error indicator. The first argument
specifies the exception type; it is normally one of the standard exceptions,
- e.g. :c:data:`PyExc_RuntimeError`. You need not increment its reference count.
+ e.g. :c:data:`PyExc_RuntimeError`. You need not create a new
+ :term:`strong reference` to it (e.g. with :c:func:`Py_INCREF`).
The second argument is an error message; it is decoded from ``'utf-8'``.
@@ -158,9 +164,9 @@ For convenience, some of these functions will always return a
This is a convenience function to raise an exception when a C library function
has returned an error and set the C variable :c:data:`errno`. It constructs a
tuple object whose first item is the integer :c:data:`errno` value and whose
- second item is the corresponding error message (gotten from :c:func:`strerror`),
+ second item is the corresponding error message (gotten from :c:func:`!strerror`),
and then calls ``PyErr_SetObject(type, object)``. On Unix, when the
- :c:data:`errno` value is :const:`EINTR`, indicating an interrupted system call,
+ :c:data:`errno` value is :c:macro:`!EINTR`, indicating an interrupted system call,
this calls :c:func:`PyErr_CheckSignals`, and if that set the error indicator,
leaves it set to that. The function always returns ``NULL``, so a wrapper
function around a system call can write ``return PyErr_SetFromErrno(type);``
@@ -172,7 +178,7 @@ For convenience, some of these functions will always return a
Similar to :c:func:`PyErr_SetFromErrno`, with the additional behavior that if
*filenameObject* is not ``NULL``, it is passed to the constructor of *type* as
a third parameter. In the case of :exc:`OSError` exception,
- this is used to define the :attr:`filename` attribute of the
+ this is used to define the :attr:`!filename` attribute of the
exception instance.
@@ -195,12 +201,12 @@ For convenience, some of these functions will always return a
.. c:function:: PyObject* PyErr_SetFromWindowsErr(int ierr)
This is a convenience function to raise :exc:`WindowsError`. If called with
- *ierr* of ``0``, the error code returned by a call to :c:func:`GetLastError`
- is used instead. It calls the Win32 function :c:func:`FormatMessage` to retrieve
- the Windows description of error code given by *ierr* or :c:func:`GetLastError`,
+ *ierr* of ``0``, the error code returned by a call to :c:func:`!GetLastError`
+ is used instead. It calls the Win32 function :c:func:`!FormatMessage` to retrieve
+ the Windows description of error code given by *ierr* or :c:func:`!GetLastError`,
then it constructs a tuple object whose first item is the *ierr* value and whose
second item is the corresponding error message (gotten from
- :c:func:`FormatMessage`), and then calls ``PyErr_SetObject(PyExc_WindowsError,
+ :c:func:`!FormatMessage`), and then calls ``PyErr_SetObject(PyExc_WindowsError,
object)``. This function always returns ``NULL``.
.. availability:: Windows.
@@ -216,17 +222,21 @@ For convenience, some of these functions will always return a
.. c:function:: PyObject* PyErr_SetFromWindowsErrWithFilename(int ierr, const char *filename)
- Similar to :c:func:`PyErr_SetFromWindowsErrWithFilenameObject`, but the
- filename is given as a C string. *filename* is decoded from the filesystem
- encoding (:func:`os.fsdecode`).
+ Similar to :c:func:`PyErr_SetFromWindowsErr`, with the additional behavior
+ that if *filename* is not ``NULL``, it is decoded from the filesystem
+ encoding (:func:`os.fsdecode`) and passed to the constructor of
+ :exc:`OSError` as a third parameter to be used to define the
+ :attr:`!filename` attribute of the exception instance.
.. availability:: Windows.
.. c:function:: PyObject* PyErr_SetExcFromWindowsErrWithFilenameObject(PyObject *type, int ierr, PyObject *filename)
- Similar to :c:func:`PyErr_SetFromWindowsErrWithFilenameObject`, with an
- additional parameter specifying the exception type to be raised.
+ Similar to :c:func:`PyErr_SetExcFromWindowsErr`, with the additional behavior
+ that if *filename* is not ``NULL``, it is passed to the constructor of
+ :exc:`OSError` as a third parameter to be used to define the
+ :attr:`!filename` attribute of the exception instance.
.. availability:: Windows.
@@ -626,7 +636,7 @@ Signal Handling
be interruptible by user requests (such as by pressing Ctrl-C).
.. note::
- The default Python signal handler for :const:`SIGINT` raises the
+ The default Python signal handler for :c:macro:`!SIGINT` raises the
:exc:`KeyboardInterrupt` exception.
@@ -637,7 +647,7 @@ Signal Handling
single: SIGINT
single: KeyboardInterrupt (built-in exception)
- Simulate the effect of a :const:`SIGINT` signal arriving.
+ Simulate the effect of a :c:macro:`!SIGINT` signal arriving.
This is equivalent to ``PyErr_SetInterruptEx(SIGINT)``.
.. note::
@@ -661,7 +671,7 @@ Signal Handling
to interrupt an operation).
If the given signal isn't handled by Python (it was set to
- :data:`signal.SIG_DFL` or :data:`signal.SIG_IGN`), it will be ignored.
+ :py:const:`signal.SIG_DFL` or :py:const:`signal.SIG_IGN`), it will be ignored.
If *signum* is outside of the allowed range of signal numbers, ``-1``
is returned. Otherwise, ``0`` is returned. The error indicator is
@@ -749,7 +759,7 @@ Exception Objects
.. c:function:: PyObject* PyException_GetCause(PyObject *ex)
- Return the cause (either an exception instance, or :const:`None`,
+ Return the cause (either an exception instance, or ``None``,
set by ``raise ... from ...``) associated with the exception as a new
reference, as accessible from Python through :attr:`__cause__`.
@@ -758,7 +768,7 @@ Exception Objects
Set the cause associated with the exception to *cause*. Use ``NULL`` to clear
it. There is no type check to make sure that *cause* is either an exception
- instance or :const:`None`. This steals a reference to *cause*.
+ instance or ``None``. This steals a reference to *cause*.
:attr:`__suppress_context__` is implicitly set to ``True`` by this function.
@@ -772,6 +782,18 @@ Exception Objects
Set :attr:`~BaseException.args` of exception *ex* to *args*.
+.. c:function:: PyObject* PyUnstable_Exc_PrepReraiseStar(PyObject *orig, PyObject *excs)
+
+ Implement part of the interpreter's implementation of :keyword:`!except*`.
+ *orig* is the original exception that was caught, and *excs* is the list of
+ the exceptions that need to be raised. This list contains the the unhandled
+ part of *orig*, if any, as well as the exceptions that were raised from the
+ :keyword:`!except*` clauses (so they have a different traceback from *orig*) and
+ those that were reraised (and have the same traceback as *orig*).
+ Return the :exc:`ExceptionGroup` that needs to be reraised in the end, or
+ ``None`` if there is nothing to reraise.
+
+ .. versionadded:: 3.12
.. _unicodeexceptions:
@@ -857,7 +879,7 @@ because the :ref:`call protocol ` takes care of recursion handling.
Marks a point where a recursive C-level call is about to be performed.
- If :const:`USE_STACKCHECK` is defined, this function checks if the OS
+ If :c:macro:`USE_STACKCHECK` is defined, this function checks if the OS
stack overflowed using :c:func:`PyOS_CheckStack`. In this is the case, it
sets a :exc:`MemoryError` and returns a nonzero value.
@@ -870,7 +892,7 @@ because the :ref:`call protocol ` takes care of recursion handling.
depth limit.
.. versionchanged:: 3.9
- This function is now also available in the limited API.
+ This function is now also available in the :ref:`limited API `.
.. c:function:: void Py_LeaveRecursiveCall(void)
@@ -878,7 +900,7 @@ because the :ref:`call protocol ` takes care of recursion handling.
*successful* invocation of :c:func:`Py_EnterRecursiveCall`.
.. versionchanged:: 3.9
- This function is now also available in the limited API.
+ This function is now also available in the :ref:`limited API `.
Properly implementing :c:member:`~PyTypeObject.tp_repr` for container types requires
special recursion handling. In addition to protecting the stack,
diff --git a/Doc/c-api/file.rst b/Doc/c-api/file.rst
index f32ecba9f27029..b36c800e00444a 100644
--- a/Doc/c-api/file.rst
+++ b/Doc/c-api/file.rst
@@ -93,7 +93,7 @@ the :mod:`io` APIs instead.
.. index:: single: Py_PRINT_RAW
Write object *obj* to file object *p*. The only supported flag for *flags* is
- :const:`Py_PRINT_RAW`; if given, the :func:`str` of the object is written
+ :c:macro:`Py_PRINT_RAW`; if given, the :func:`str` of the object is written
instead of the :func:`repr`. Return ``0`` on success or ``-1`` on failure; the
appropriate exception will be set.
diff --git a/Doc/c-api/float.rst b/Doc/c-api/float.rst
index 05b2d100d575cb..4f6ac0d8175c6b 100644
--- a/Doc/c-api/float.rst
+++ b/Doc/c-api/float.rst
@@ -3,7 +3,7 @@
.. _floatobjects:
Floating Point Objects
-----------------------
+======================
.. index:: pair: object; floating point
@@ -45,14 +45,14 @@ Floating Point Objects
.. c:function:: double PyFloat_AsDouble(PyObject *pyfloat)
Return a C :c:expr:`double` representation of the contents of *pyfloat*. If
- *pyfloat* is not a Python floating point object but has a :meth:`__float__`
+ *pyfloat* is not a Python floating point object but has a :meth:`~object.__float__`
method, this method will first be called to convert *pyfloat* into a float.
- If ``__float__()`` is not defined then it falls back to :meth:`__index__`.
+ If :meth:`!__float__` is not defined then it falls back to :meth:`~object.__index__`.
This method returns ``-1.0`` upon failure, so one should call
:c:func:`PyErr_Occurred` to check for errors.
.. versionchanged:: 3.8
- Use :meth:`__index__` if available.
+ Use :meth:`~object.__index__` if available.
.. c:function:: double PyFloat_AS_DOUBLE(PyObject *pyfloat)
@@ -79,7 +79,7 @@ Floating Point Objects
Pack and Unpack functions
-=========================
+-------------------------
The pack and unpack functions provide an efficient platform-independent way to
store floating-point values as byte strings. The Pack routines produce a bytes
@@ -104,12 +104,12 @@ happens in such cases is partly accidental (alas).
.. versionadded:: 3.11
Pack functions
---------------
+^^^^^^^^^^^^^^
The pack routines write 2, 4 or 8 bytes, starting at *p*. *le* is an
:c:expr:`int` argument, non-zero if you want the bytes string in little-endian
format (exponent last, at ``p+1``, ``p+3``, or ``p+6`` ``p+7``), zero if you
-want big-endian format (exponent first, at *p*). The :c:data:`PY_BIG_ENDIAN`
+want big-endian format (exponent first, at *p*). The :c:macro:`PY_BIG_ENDIAN`
constant can be used to use the native endian: it is equal to ``1`` on big
endian processor, or ``0`` on little endian processor.
@@ -135,12 +135,12 @@ There are two problems on non-IEEE platforms:
Unpack functions
-----------------
+^^^^^^^^^^^^^^^^
The unpack routines read 2, 4 or 8 bytes, starting at *p*. *le* is an
:c:expr:`int` argument, non-zero if the bytes string is in little-endian format
(exponent last, at ``p+1``, ``p+3`` or ``p+6`` and ``p+7``), zero if big-endian
-(exponent first, at *p*). The :c:data:`PY_BIG_ENDIAN` constant can be used to
+(exponent first, at *p*). The :c:macro:`PY_BIG_ENDIAN` constant can be used to
use the native endian: it is equal to ``1`` on big endian processor, or ``0``
on little endian processor.
diff --git a/Doc/c-api/frame.rst b/Doc/c-api/frame.rst
index 9f7addfbbf3cb4..1accee2767a485 100644
--- a/Doc/c-api/frame.rst
+++ b/Doc/c-api/frame.rst
@@ -134,7 +134,7 @@ See also :ref:`Reflection `.
Internal Frames
----------------
+^^^^^^^^^^^^^^^
Unless using :pep:`523`, you will not need this.
diff --git a/Doc/c-api/gcsupport.rst b/Doc/c-api/gcsupport.rst
index c3260a21bc7f8b..6b2494ee4f0ed4 100644
--- a/Doc/c-api/gcsupport.rst
+++ b/Doc/c-api/gcsupport.rst
@@ -13,22 +13,20 @@ or strings), do not need to provide any explicit support for garbage
collection.
To create a container type, the :c:member:`~PyTypeObject.tp_flags` field of the type object must
-include the :const:`Py_TPFLAGS_HAVE_GC` and provide an implementation of the
+include the :c:macro:`Py_TPFLAGS_HAVE_GC` and provide an implementation of the
:c:member:`~PyTypeObject.tp_traverse` handler. If instances of the type are mutable, a
:c:member:`~PyTypeObject.tp_clear` implementation must also be provided.
-.. data:: Py_TPFLAGS_HAVE_GC
- :noindex:
-
+:c:macro:`Py_TPFLAGS_HAVE_GC`
Objects with a type with this flag set must conform with the rules
documented here. For convenience these objects will be referred to as
container objects.
Constructors for container types must conform to two rules:
-#. The memory for the object must be allocated using :c:func:`PyObject_GC_New`
- or :c:func:`PyObject_GC_NewVar`.
+#. The memory for the object must be allocated using :c:macro:`PyObject_GC_New`
+ or :c:macro:`PyObject_GC_NewVar`.
#. Once all the fields which may contain references to other containers are
initialized, it must call :c:func:`PyObject_GC_Track`.
@@ -52,21 +50,21 @@ rules:
:c:member:`~PyTypeObject.tp_flags`, :c:member:`~PyTypeObject.tp_traverse`
and :c:member:`~PyTypeObject.tp_clear` fields if the type inherits from a
class that implements the garbage collector protocol and the child class
- does *not* include the :const:`Py_TPFLAGS_HAVE_GC` flag.
+ does *not* include the :c:macro:`Py_TPFLAGS_HAVE_GC` flag.
-.. c:function:: TYPE* PyObject_GC_New(TYPE, PyTypeObject *type)
+.. c:macro:: PyObject_GC_New(TYPE, typeobj)
- Analogous to :c:func:`PyObject_New` but for container objects with the
- :const:`Py_TPFLAGS_HAVE_GC` flag set.
+ Analogous to :c:macro:`PyObject_New` but for container objects with the
+ :c:macro:`Py_TPFLAGS_HAVE_GC` flag set.
-.. c:function:: TYPE* PyObject_GC_NewVar(TYPE, PyTypeObject *type, Py_ssize_t size)
+.. c:macro:: PyObject_GC_NewVar(TYPE, typeobj, size)
- Analogous to :c:func:`PyObject_NewVar` but for container objects with the
- :const:`Py_TPFLAGS_HAVE_GC` flag set.
+ Analogous to :c:macro:`PyObject_NewVar` but for container objects with the
+ :c:macro:`Py_TPFLAGS_HAVE_GC` flag set.
.. c:function:: PyObject* PyUnstable_Object_GC_NewWithExtraData(PyTypeObject *type, size_t extra_size)
- Analogous to :c:func:`PyObject_GC_New` but allocates *extra_size*
+ Analogous to :c:macro:`PyObject_GC_New` but allocates *extra_size*
bytes at the end of the object (at offset
:c:member:`~PyTypeObject.tp_basicsize`).
The allocated memory is initialized to zeros,
@@ -87,7 +85,7 @@ rules:
.. c:function:: TYPE* PyObject_GC_Resize(TYPE, PyVarObject *op, Py_ssize_t newsize)
- Resize an object allocated by :c:func:`PyObject_NewVar`. Returns the
+ Resize an object allocated by :c:macro:`PyObject_NewVar`. Returns the
resized object or ``NULL`` on failure. *op* must not be tracked by the collector yet.
@@ -130,8 +128,8 @@ rules:
.. c:function:: void PyObject_GC_Del(void *op)
- Releases memory allocated to an object using :c:func:`PyObject_GC_New` or
- :c:func:`PyObject_GC_NewVar`.
+ Releases memory allocated to an object using :c:macro:`PyObject_GC_New` or
+ :c:macro:`PyObject_GC_NewVar`.
.. c:function:: void PyObject_GC_UnTrack(void *op)
@@ -145,7 +143,7 @@ rules:
.. versionchanged:: 3.8
- The :c:func:`_PyObject_GC_TRACK` and :c:func:`_PyObject_GC_UNTRACK` macros
+ The :c:func:`!_PyObject_GC_TRACK` and :c:func:`!_PyObject_GC_UNTRACK` macros
have been removed from the public C API.
The :c:member:`~PyTypeObject.tp_traverse` handler accepts a function parameter of this type:
diff --git a/Doc/c-api/import.rst b/Doc/c-api/import.rst
index 79843ba521ab93..7bc93a81e2c780 100644
--- a/Doc/c-api/import.rst
+++ b/Doc/c-api/import.rst
@@ -126,19 +126,19 @@ Importing Modules
read from a Python bytecode file or obtained from the built-in function
:func:`compile`, load the module. Return a new reference to the module object,
or ``NULL`` with an exception set if an error occurred. *name*
- is removed from :attr:`sys.modules` in error cases, even if *name* was already
- in :attr:`sys.modules` on entry to :c:func:`PyImport_ExecCodeModule`. Leaving
- incompletely initialized modules in :attr:`sys.modules` is dangerous, as imports of
+ is removed from :data:`sys.modules` in error cases, even if *name* was already
+ in :data:`sys.modules` on entry to :c:func:`PyImport_ExecCodeModule`. Leaving
+ incompletely initialized modules in :data:`sys.modules` is dangerous, as imports of
such modules have no way to know that the module object is an unknown (and
probably damaged with respect to the module author's intents) state.
The module's :attr:`__spec__` and :attr:`__loader__` will be set, if
not set already, with the appropriate values. The spec's loader will
be set to the module's ``__loader__`` (if set) and to an instance of
- :class:`SourceFileLoader` otherwise.
+ :class:`~importlib.machinery.SourceFileLoader` otherwise.
The module's :attr:`__file__` attribute will be set to the code object's
- :c:member:`co_filename`. If applicable, :attr:`__cached__` will also
+ :attr:`!co_filename`. If applicable, :attr:`__cached__` will also
be set.
This function will reload the module if it was already imported. See
@@ -225,7 +225,7 @@ Importing Modules
.. c:function:: PyObject* PyImport_GetImporter(PyObject *path)
- Return a finder object for a :data:`sys.path`/:attr:`pkg.__path__` item
+ Return a finder object for a :data:`sys.path`/:attr:`!pkg.__path__` item
*path*, possibly by fetching it from the :data:`sys.path_importer_cache`
dict. If it wasn't yet cached, traverse :data:`sys.path_hooks` until a hook
is found that can handle the path item. Return ``None`` if no hook could;
@@ -294,23 +294,25 @@ Importing Modules
.. c:struct:: _inittab
- Structure describing a single entry in the list of built-in modules. Each of
- these structures gives the name and initialization function for a module built
- into the interpreter. The name is an ASCII encoded string. Programs which
+ Structure describing a single entry in the list of built-in modules.
+ Programs which
embed Python may use an array of these structures in conjunction with
:c:func:`PyImport_ExtendInittab` to provide additional built-in modules.
- The structure is defined in :file:`Include/import.h` as::
+ The structure consists of two members:
- struct _inittab {
- const char *name; /* ASCII encoded string */
- PyObject* (*initfunc)(void);
- };
+ .. c:member:: const char *name
+
+ The module name, as an ASCII encoded string.
+
+ .. c: member:: PyObject* (*initfunc)(void)
+
+ Initialization function for a module built into the interpreter.
.. c:function:: int PyImport_ExtendInittab(struct _inittab *newtab)
Add a collection of modules to the table of built-in modules. The *newtab*
- array must end with a sentinel entry which contains ``NULL`` for the :attr:`name`
+ array must end with a sentinel entry which contains ``NULL`` for the :c:member:`~_inittab.name`
field; failure to provide the sentinel value can result in a memory fault.
Returns ``0`` on success or ``-1`` if insufficient memory could be allocated to
extend the internal table. In the event of failure, no modules are added to the
diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst
index 26762969ef8eba..8b960b06871b17 100644
--- a/Doc/c-api/init.rst
+++ b/Doc/c-api/init.rst
@@ -25,7 +25,7 @@ The following functions can be safely called before Python is initialized:
* :c:func:`PyImport_AppendInittab`
* :c:func:`PyImport_ExtendInittab`
- * :c:func:`PyInitFrozenExtensions`
+ * :c:func:`!PyInitFrozenExtensions`
* :c:func:`PyMem_SetAllocator`
* :c:func:`PyMem_SetupDebugHooks`
* :c:func:`PyObject_SetArenaAllocator`
@@ -157,7 +157,7 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
:c:member:`PyConfig.use_environment` should be used instead, see
:ref:`Python Initialization Configuration `.
- Ignore all :envvar:`PYTHON*` environment variables, e.g.
+ 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.
@@ -230,7 +230,7 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
:ref:`Python Initialization Configuration `.
If the flag is non-zero, use :class:`io.FileIO` instead of
- :class:`WindowsConsoleIO` for :mod:`sys` standard streams.
+ :class:`!io._WindowsConsoleIO` for :mod:`sys` standard streams.
Set to ``1`` if the :envvar:`PYTHONLEGACYWINDOWSSTDIO` environment
variable is set to a non-empty string.
@@ -401,7 +401,7 @@ Initializing and finalizing the interpreter
the application.
**Bugs and caveats:** The destruction of modules and objects in modules is done
- in random order; this may cause destructors (:meth:`__del__` methods) to fail
+ in random order; this may cause destructors (:meth:`~object.__del__` methods) to fail
when they depend on other objects (even functions) or modules. Dynamically
loaded extension modules loaded by Python are not unloaded. Small amounts of
memory allocated by the Python interpreter may not be freed (if you find a leak,
@@ -485,12 +485,12 @@ Process-wide parameters
interpreter will change the contents of this storage.
Use :c:func:`Py_DecodeLocale` to decode a bytes string to get a
- :c:expr:`wchar_*` string.
+ :c:expr:`wchar_t *` string.
.. deprecated:: 3.11
-.. c:function:: wchar* Py_GetProgramName()
+.. c:function:: wchar_t* Py_GetProgramName()
.. index:: single: Py_SetProgramName()
@@ -981,7 +981,7 @@ the fork, and releasing them afterwards. In addition, it resets any
:ref:`lock-objects` in the child. When extending or embedding Python, there
is no way to inform Python of additional (non-Python) locks that need to be
acquired before or reset after a fork. OS facilities such as
-:c:func:`pthread_atfork` would need to be used to accomplish the same thing.
+:c:func:`!pthread_atfork` would need to be used to accomplish the same thing.
Additionally, when extending or embedding Python, calling :c:func:`fork`
directly rather than through :func:`os.fork` (and returning to or calling
into Python) may result in a deadlock by one of Python's internal locks
@@ -1023,8 +1023,11 @@ 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 :attr:`interp` (:c:expr:`PyInterpreterState *`), which points to
- this thread's interpreter state.
+ data member is:
+
+ .. c:member:: PyInterpreterState *interp
+
+ This thread's interpreter state.
.. c:function:: void PyEval_InitThreads()
@@ -1084,7 +1087,7 @@ code, or when embedding the Python interpreter:
.. note::
Calling this function from a thread when the runtime is finalizing
will terminate the thread, even if the thread was not created by Python.
- You can use :c:func:`_Py_IsFinalizing` or :func:`sys.is_finalizing` to
+ You can use :c:func:`!_Py_IsFinalizing` or :func:`sys.is_finalizing` to
check if the interpreter is in process of being finalized before calling
this function to avoid unwanted termination.
@@ -1130,7 +1133,7 @@ with sub-interpreters:
.. note::
Calling this function from a thread when the runtime is finalizing
will terminate the thread, even if the thread was not created by Python.
- You can use :c:func:`_Py_IsFinalizing` or :func:`sys.is_finalizing` to
+ You can use :c:func:`!_Py_IsFinalizing` or :func:`sys.is_finalizing` to
check if the interpreter is in process of being finalized before calling
this function to avoid unwanted termination.
@@ -1396,7 +1399,7 @@ All of the following functions must be called after :c:func:`Py_Initialize`.
function does not steal any references to *exc*. To prevent naive misuse, you
must write your own C extension to call this. Must be called with the GIL held.
Returns the number of thread states modified; this is normally one, but will be
- zero if the thread id isn't found. If *exc* is :const:`NULL`, the pending
+ zero if the thread id isn't found. If *exc* is ``NULL``, the pending
exception (if any) for the thread is cleared. This raises no exceptions.
.. versionchanged:: 3.7
@@ -1412,7 +1415,7 @@ All of the following functions must be called after :c:func:`Py_Initialize`.
.. note::
Calling this function from a thread when the runtime is finalizing
will terminate the thread, even if the thread was not created by Python.
- You can use :c:func:`_Py_IsFinalizing` or :func:`sys.is_finalizing` to
+ You can use :c:func:`!_Py_IsFinalizing` or :func:`sys.is_finalizing` to
check if the interpreter is in process of being finalized before calling
this function to avoid unwanted termination.
@@ -1491,7 +1494,96 @@ You can switch between sub-interpreters using the :c:func:`PyThreadState_Swap`
function. You can create and destroy them using the following functions:
-.. c:function:: PyThreadState* Py_NewInterpreter()
+.. c:type:: PyInterpreterConfig
+
+ Structure containing most parameters to configure a sub-interpreter.
+ Its values are used only in :c:func:`Py_NewInterpreterFromConfig` and
+ never modified by the runtime.
+
+ .. versionadded:: 3.12
+
+ Structure fields:
+
+ .. c:member:: int use_main_obmalloc
+
+ If this is ``0`` then the sub-interpreter will use its own
+ "object" allocator state.
+ Otherwise it will use (share) the main interpreter's.
+
+ If this is ``0`` then
+ :c:member:`~PyInterpreterConfig.check_multi_interp_extensions`
+ must be ``1`` (non-zero).
+ If this is ``1`` then :c:member:`~PyInterpreterConfig.gil`
+ must not be :c:macro:`PyInterpreterConfig_OWN_GIL`.
+
+ .. c:member:: int allow_fork
+
+ If this is ``0`` then the runtime will not support forking the
+ process in any thread where the sub-interpreter is currently active.
+ Otherwise fork is unrestricted.
+
+ Note that the :mod:`subprocess` module still works
+ when fork is disallowed.
+
+ .. c:member:: int allow_exec
+
+ If this is ``0`` then the runtime will not support replacing the
+ current process via exec (e.g. :func:`os.execv`) in any thread
+ where the sub-interpreter is currently active.
+ Otherwise exec is unrestricted.
+
+ Note that the :mod:`subprocess` module still works
+ when exec is disallowed.
+
+ .. c:member:: int allow_threads
+
+ If this is ``0`` then the sub-interpreter's :mod:`threading` module
+ won't create threads.
+ Otherwise threads are allowed.
+
+ .. c:member:: int allow_daemon_threads
+
+ If this is ``0`` then the sub-interpreter's :mod:`threading` module
+ won't create daemon threads.
+ Otherwise daemon threads are allowed (as long as
+ :c:member:`~PyInterpreterConfig.allow_threads` is non-zero).
+
+ .. c:member:: int check_multi_interp_extensions
+
+ If this is ``0`` then all extension modules may be imported,
+ including legacy (single-phase init) modules,
+ in any thread where the sub-interpreter is currently active.
+ Otherwise only multi-phase init extension modules
+ (see :pep:`489`) may be imported.
+ (Also see :c:macro:`Py_mod_multiple_interpreters`.)
+
+ This must be ``1`` (non-zero) if
+ :c:member:`~PyInterpreterConfig.use_main_obmalloc` is ``0``.
+
+ .. c:member:: int gil
+
+ This determines the operation of the GIL for the sub-interpreter.
+ It may be one of the following:
+
+ .. c:namespace:: NULL
+
+ .. c:macro:: PyInterpreterConfig_DEFAULT_GIL
+
+ Use the default selection (:c:macro:`PyInterpreterConfig_SHARED_GIL`).
+
+ .. c:macro:: PyInterpreterConfig_SHARED_GIL
+
+ Use (share) the main interpreter's GIL.
+
+ .. c:macro:: PyInterpreterConfig_OWN_GIL
+
+ Use the sub-interpreter's own GIL.
+
+ If this is :c:macro:`PyInterpreterConfig_OWN_GIL` then
+ :c:member:`PyInterpreterConfig.use_main_obmalloc` must be ``0``.
+
+
+.. c:function:: PyStatus Py_NewInterpreterFromConfig(PyThreadState **tstate_p, const PyInterpreterConfig *config)
.. index::
pair: module; builtins
@@ -1511,16 +1603,47 @@ function. You can create and destroy them using the following functions:
``sys.stdout`` and ``sys.stderr`` (however these refer to the same underlying
file descriptors).
- The return value points to the first thread state created in the new
+ The given *config* controls the options with which the interpreter
+ is initialized.
+
+ Upon success, *tstate_p* will be set to the first thread state
+ created in the new
sub-interpreter. This thread state is made in the current thread state.
Note that no actual thread is created; see the discussion of thread states
- below. If creation of the new interpreter is unsuccessful, ``NULL`` is
- returned; no exception is set since the exception state is stored in the
- current thread state and there may not be a current thread state. (Like all
- other Python/C API functions, the global interpreter lock must be held before
- calling this function and is still held when it returns; however, unlike most
- other Python/C API functions, there needn't be a current thread state on
- entry.)
+ below. If creation of the new interpreter is unsuccessful,
+ *tstate_p* is set to ``NULL``;
+ no exception is set since the exception state is stored in the
+ current thread state and there may not be a current thread state.
+
+ Like all other Python/C API functions, the global interpreter lock
+ must be held before calling this function and is still held when it
+ returns. Likewise a current thread state must be set on entry. On
+ success, the returned thread state will be set as current. If the
+ sub-interpreter is created with its own GIL then the GIL of the
+ calling interpreter will be released. When the function returns,
+ the new interpreter's GIL will be held by the current thread and
+ the previously interpreter's GIL will remain released here.
+
+ .. versionadded:: 3.12
+
+ Sub-interpreters are most effective when isolated from each other,
+ with certain functionality restricted::
+
+ PyInterpreterConfig config = {
+ .use_main_obmalloc = 0,
+ .allow_fork = 0,
+ .allow_exec = 0,
+ .allow_threads = 1,
+ .allow_daemon_threads = 0,
+ .check_multi_interp_extensions = 1,
+ .gil = PyInterpreterConfig_OWN_GIL,
+ };
+ PyThreadState *tstate = Py_NewInterpreterFromConfig(&config);
+
+ Note that the config is used only briefly and does not get modified.
+ During initialization the config's values are converted into various
+ :c:type:`PyInterpreterState` values. A read-only copy of the config
+ may be stored internally on the :c:type:`PyInterpreterState`.
.. index::
single: Py_FinalizeEx()
@@ -1555,19 +1678,79 @@ function. You can create and destroy them using the following functions:
.. index:: single: close() (in module os)
+.. c:function:: PyThreadState* Py_NewInterpreter(void)
+
+ .. index::
+ pair: module; builtins
+ pair: module; __main__
+ pair: module; sys
+ single: stdout (in module sys)
+ single: stderr (in module sys)
+ single: stdin (in module sys)
+
+ Create a new sub-interpreter. This is essentially just a wrapper
+ around :c:func:`Py_NewInterpreterFromConfig` with a config that
+ preserves the existing behavior. The result is an unisolated
+ sub-interpreter that shares the main interpreter's GIL, allows
+ fork/exec, allows daemon threads, and allows single-phase init
+ modules.
+
+
.. c:function:: void Py_EndInterpreter(PyThreadState *tstate)
.. index:: single: Py_FinalizeEx()
- Destroy the (sub-)interpreter represented by the given thread state. The given
- thread state must be the current thread state. See the discussion of thread
- states below. When the call returns, the current thread state is ``NULL``. All
- thread states associated with this interpreter are destroyed. (The global
- interpreter lock must be held before calling this function and is still held
- when it returns.) :c:func:`Py_FinalizeEx` will destroy all sub-interpreters that
+ Destroy the (sub-)interpreter represented by the given thread state.
+ The given thread state must be the current thread state. See the
+ discussion of thread states below. When the call returns,
+ the current thread state is ``NULL``. All thread states associated
+ with this interpreter are destroyed. The global interpreter lock
+ used by the target interpreter must be held before calling this
+ function. No GIL is held when it returns.
+
+ :c:func:`Py_FinalizeEx` will destroy all sub-interpreters that
haven't been explicitly destroyed at that point.
+A Per-Interpreter GIL
+---------------------
+
+Using :c:func:`Py_NewInterpreterFromConfig` you can create
+a sub-interpreter that is completely isolated from other interpreters,
+including having its own GIL. The most important benefit of this
+isolation is that such an interpreter can execute Python code without
+being blocked by other interpreters or blocking any others. Thus a
+single Python process can truly take advantage of multiple CPU cores
+when running Python code. The isolation also encourages a different
+approach to concurrency than that of just using threads.
+(See :pep:`554`.)
+
+Using an isolated interpreter requires vigilance in preserving that
+isolation. That especially means not sharing any objects or mutable
+state without guarantees about thread-safety. Even objects that are
+otherwise immutable (e.g. ``None``, ``(1, 5)``) can't normally be shared
+because of the refcount. One simple but less-efficient approach around
+this is to use a global lock around all use of some state (or object).
+Alternately, effectively immutable objects (like integers or strings)
+can be made safe in spite of their refcounts by making them "immortal".
+In fact, this has been done for the builtin singletons, small integers,
+and a number of other builtin objects.
+
+If you preserve isolation then you will have access to proper multi-core
+computing without the complications that come with free-threading.
+Failure to preserve isolation will expose you to the full consequences
+of free-threading, including races and hard-to-debug crashes.
+
+Aside from that, one of the main challenges of using multiple isolated
+interpreters is how to communicate between them safely (not break
+isolation) and efficiently. The runtime and stdlib do not provide
+any standard approach to this yet. A future stdlib module would help
+mitigate the effort of preserving isolation and expose effective tools
+for communicating (and sharing) data between interpreters.
+
+.. versionadded:: 3.12
+
+
Bugs and caveats
----------------
@@ -1675,32 +1858,32 @@ Python-level trace functions in previous versions.
The type of the trace function registered using :c:func:`PyEval_SetProfile` and
:c:func:`PyEval_SetTrace`. The first parameter is the object passed to the
registration function as *obj*, *frame* is the frame object to which the event
- pertains, *what* is one of the constants :const:`PyTrace_CALL`,
- :const:`PyTrace_EXCEPTION`, :const:`PyTrace_LINE`, :const:`PyTrace_RETURN`,
- :const:`PyTrace_C_CALL`, :const:`PyTrace_C_EXCEPTION`, :const:`PyTrace_C_RETURN`,
- or :const:`PyTrace_OPCODE`, and *arg* depends on the value of *what*:
-
- +------------------------------+----------------------------------------+
- | Value of *what* | Meaning of *arg* |
- +==============================+========================================+
- | :const:`PyTrace_CALL` | Always :c:data:`Py_None`. |
- +------------------------------+----------------------------------------+
- | :const:`PyTrace_EXCEPTION` | Exception information as returned by |
- | | :func:`sys.exc_info`. |
- +------------------------------+----------------------------------------+
- | :const:`PyTrace_LINE` | Always :c:data:`Py_None`. |
- +------------------------------+----------------------------------------+
- | :const:`PyTrace_RETURN` | Value being returned to the caller, |
- | | or ``NULL`` if caused by an exception. |
- +------------------------------+----------------------------------------+
- | :const:`PyTrace_C_CALL` | Function object being called. |
- +------------------------------+----------------------------------------+
- | :const:`PyTrace_C_EXCEPTION` | Function object being called. |
- +------------------------------+----------------------------------------+
- | :const:`PyTrace_C_RETURN` | Function object being called. |
- +------------------------------+----------------------------------------+
- | :const:`PyTrace_OPCODE` | Always :c:data:`Py_None`. |
- +------------------------------+----------------------------------------+
+ pertains, *what* is one of the constants :c:data:`PyTrace_CALL`,
+ :c:data:`PyTrace_EXCEPTION`, :c:data:`PyTrace_LINE`, :c:data:`PyTrace_RETURN`,
+ :c:data:`PyTrace_C_CALL`, :c:data:`PyTrace_C_EXCEPTION`, :c:data:`PyTrace_C_RETURN`,
+ or :c:data:`PyTrace_OPCODE`, and *arg* depends on the value of *what*:
+
+ +-------------------------------+----------------------------------------+
+ | Value of *what* | Meaning of *arg* |
+ +===============================+========================================+
+ | :c:data:`PyTrace_CALL` | Always :c:data:`Py_None`. |
+ +-------------------------------+----------------------------------------+
+ | :c:data:`PyTrace_EXCEPTION` | Exception information as returned by |
+ | | :func:`sys.exc_info`. |
+ +-------------------------------+----------------------------------------+
+ | :c:data:`PyTrace_LINE` | Always :c:data:`Py_None`. |
+ +-------------------------------+----------------------------------------+
+ | :c:data:`PyTrace_RETURN` | Value being returned to the caller, |
+ | | or ``NULL`` if caused by an exception. |
+ +-------------------------------+----------------------------------------+
+ | :c:data:`PyTrace_C_CALL` | Function object being called. |
+ +-------------------------------+----------------------------------------+
+ | :c:data:`PyTrace_C_EXCEPTION` | Function object being called. |
+ +-------------------------------+----------------------------------------+
+ | :c:data:`PyTrace_C_RETURN` | Function object being called. |
+ +-------------------------------+----------------------------------------+
+ | :c:data:`PyTrace_OPCODE` | Always :c:data:`Py_None`. |
+ +-------------------------------+----------------------------------------+
.. c:var:: int PyTrace_CALL
@@ -1767,8 +1950,8 @@ Python-level trace functions in previous versions.
function as its first parameter, and may be any Python object, or ``NULL``. If
the profile function needs to maintain state, using a different value for *obj*
for each thread provides a convenient and thread-safe place to store it. The
- profile function is called for all monitored events except :const:`PyTrace_LINE`
- :const:`PyTrace_OPCODE` and :const:`PyTrace_EXCEPTION`.
+ profile function is called for all monitored events except :c:data:`PyTrace_LINE`
+ :c:data:`PyTrace_OPCODE` and :c:data:`PyTrace_EXCEPTION`.
See also the :func:`sys.setprofile` function.
@@ -1793,8 +1976,8 @@ Python-level trace functions in previous versions.
:c:func:`PyEval_SetProfile`, except the tracing function does receive line-number
events and per-opcode events, but does not receive any event related to C function
objects being called. Any trace function registered using :c:func:`PyEval_SetTrace`
- will not receive :const:`PyTrace_C_CALL`, :const:`PyTrace_C_EXCEPTION` or
- :const:`PyTrace_C_RETURN` as a value for the *what* parameter.
+ will not receive :c:data:`PyTrace_C_CALL`, :c:data:`PyTrace_C_EXCEPTION` or
+ :c:data:`PyTrace_C_RETURN` as a value for the *what* parameter.
See also the :func:`sys.settrace` function.
diff --git a/Doc/c-api/init_config.rst b/Doc/c-api/init_config.rst
index 161def0b4baf3a..7c5465b5bfa204 100644
--- a/Doc/c-api/init_config.rst
+++ b/Doc/c-api/init_config.rst
@@ -82,6 +82,8 @@ PyWideStringList
If *length* is non-zero, *items* must be non-``NULL`` and all strings must be
non-``NULL``.
+ .. c:namespace:: NULL
+
Methods:
.. c:function:: PyStatus PyWideStringList_Append(PyWideStringList *list, const wchar_t *item)
@@ -101,6 +103,8 @@ PyWideStringList
Python must be preinitialized to call this function.
+ .. c:namespace:: PyWideStringList
+
Structure fields:
.. c:member:: Py_ssize_t length
@@ -135,6 +139,8 @@ PyStatus
Name of the function which created an error, can be ``NULL``.
+ .. c:namespace:: NULL
+
Functions to create a status:
.. c:function:: PyStatus PyStatus_Ok(void)
@@ -210,6 +216,8 @@ PyPreConfig
Structure used to preinitialize Python.
+ .. c:namespace:: NULL
+
Function to initialize a preconfiguration:
.. c:function:: void PyPreConfig_InitPythonConfig(PyPreConfig *preconfig)
@@ -222,6 +230,8 @@ PyPreConfig
Initialize the preconfiguration with :ref:`Isolated Configuration
`.
+ .. c:namespace:: PyPreConfig
+
Structure fields:
.. c:member:: int allocator
@@ -429,6 +439,8 @@ PyConfig
When done, the :c:func:`PyConfig_Clear` function must be used to release the
configuration memory.
+ .. c:namespace:: NULL
+
Structure methods:
.. c:function:: void PyConfig_InitPythonConfig(PyConfig *config)
@@ -522,11 +534,13 @@ PyConfig
Moreover, if :c:func:`PyConfig_SetArgv` or :c:func:`PyConfig_SetBytesArgv`
is used, this method must be called before other methods, since the
preinitialization configuration depends on command line arguments (if
- :c:member:`parse_argv` is non-zero).
+ :c:member:`~PyConfig.parse_argv` is non-zero).
The caller of these methods is responsible to handle exceptions (error or
exit) using ``PyStatus_Exception()`` and ``Py_ExitStatusException()``.
+ .. c:namespace:: PyConfig
+
Structure fields:
.. c:member:: PyWideStringList argv
@@ -871,7 +885,7 @@ PyConfig
.. c:member:: int legacy_windows_stdio
If non-zero, use :class:`io.FileIO` instead of
- :class:`io.WindowsConsoleIO` for :data:`sys.stdin`, :data:`sys.stdout`
+ :class:`!io._WindowsConsoleIO` for :data:`sys.stdin`, :data:`sys.stdout`
and :data:`sys.stderr`.
Set to ``1`` if the :envvar:`PYTHONLEGACYWINDOWSSTDIO` environment
@@ -920,7 +934,7 @@ PyConfig
.. c:member:: wchar_t* pythonpath_env
Module search paths (:data:`sys.path`) as a string separated by ``DELIM``
- (:data:`os.path.pathsep`).
+ (:data:`os.pathsep`).
Set by the :envvar:`PYTHONPATH` environment variable.
@@ -1099,7 +1113,7 @@ PyConfig
.. c:member:: int show_ref_count
- Show total reference count at exit?
+ Show total reference count at exit (excluding immortal objects)?
Set to ``1`` by :option:`-X showrefcount <-X>` command line option.
@@ -1120,7 +1134,7 @@ PyConfig
Set to ``0`` by the :option:`-S` command line option.
- :data:`sys.flags.no_site` is set to the inverted value of
+ :data:`sys.flags.no_site ` is set to the inverted value of
:c:member:`~PyConfig.site_import`.
Default: ``1``.
diff --git a/Doc/c-api/intro.rst b/Doc/c-api/intro.rst
index 8de76e55cd0586..4a6cb7ab3b8381 100644
--- a/Doc/c-api/intro.rst
+++ b/Doc/c-api/intro.rst
@@ -287,52 +287,58 @@ true if (and only if) the object pointed to by *a* is a Python list.
Reference Counts
----------------
-The reference count is important because today's computers have a finite (and
-often severely limited) memory size; it counts how many different places there
-are that have a reference to an object. Such a place could be another object,
-or a global (or static) C variable, or a local variable in some C function.
-When an object's reference count becomes zero, the object is deallocated. If
-it contains references to other objects, their reference count is decremented.
-Those other objects may be deallocated in turn, if this decrement makes their
-reference count become zero, and so on. (There's an obvious problem with
-objects that reference each other here; for now, the solution is "don't do
-that.")
+The reference count is important because today's computers have a finite
+(and often severely limited) memory size; it counts how many different
+places there are that have a :term:`strong reference` to an object.
+Such a place could be another object, or a global (or static) C variable,
+or a local variable in some C function.
+When the last :term:`strong reference` to an object is released
+(i.e. its reference count becomes zero), the object is deallocated.
+If it contains references to other objects, those references are released.
+Those other objects may be deallocated in turn, if there are no more
+references to them, and so on. (There's an obvious problem with
+objects that reference each other here; for now, the solution
+is "don't do that.")
.. index::
single: Py_INCREF()
single: Py_DECREF()
-Reference counts are always manipulated explicitly. The normal way is to use
-the macro :c:func:`Py_INCREF` to increment an object's reference count by one,
-and :c:func:`Py_DECREF` to decrement it by one. The :c:func:`Py_DECREF` macro
+Reference counts are always manipulated explicitly. The normal way is
+to use the macro :c:func:`Py_INCREF` to take a new reference to an
+object (i.e. increment its reference count by one),
+and :c:func:`Py_DECREF` to release that reference (i.e. decrement the
+reference count by one). The :c:func:`Py_DECREF` macro
is considerably more complex than the incref one, since it must check whether
the reference count becomes zero and then cause the object's deallocator to be
-called. The deallocator is a function pointer contained in the object's type
-structure. The type-specific deallocator takes care of decrementing the
-reference counts for other objects contained in the object if this is a compound
+called. The deallocator is a function pointer contained in the object's type
+structure. The type-specific deallocator takes care of releasing references
+for other objects contained in the object if this is a compound
object type, such as a list, as well as performing any additional finalization
that's needed. There's no chance that the reference count can overflow; at
least as many bits are used to hold the reference count as there are distinct
memory locations in virtual memory (assuming ``sizeof(Py_ssize_t) >= sizeof(void*)``).
Thus, the reference count increment is a simple operation.
-It is not necessary to increment an object's reference count for every local
-variable that contains a pointer to an object. In theory, the object's
+It is not necessary to hold a :term:`strong reference` (i.e. increment
+the reference count) for every local variable that contains a pointer
+to an object. In theory, the object's
reference count goes up by one when the variable is made to point to it and it
goes down by one when the variable goes out of scope. However, these two
cancel each other out, so at the end the reference count hasn't changed. The
only real reason to use the reference count is to prevent the object from being
deallocated as long as our variable is pointing to it. If we know that there
is at least one other reference to the object that lives at least as long as
-our variable, there is no need to increment the reference count temporarily.
+our variable, there is no need to take a new :term:`strong reference`
+(i.e. increment the reference count) temporarily.
An important situation where this arises is in objects that are passed as
arguments to C functions in an extension module that are called from Python;
the call mechanism guarantees to hold a reference to every argument for the
duration of the call.
However, a common pitfall is to extract an object from a list and hold on to it
-for a while without incrementing its reference count. Some other operation might
-conceivably remove the object from the list, decrementing its reference count
+for a while without taking a new reference. Some other operation might
+conceivably remove the object from the list, releasing that reference,
and possibly deallocating it. The real danger is that innocent-looking
operations may invoke arbitrary Python code which could do this; there is a code
path which allows control to flow back to the user from a :c:func:`Py_DECREF`, so
@@ -340,7 +346,8 @@ almost any operation is potentially dangerous.
A safe approach is to always use the generic operations (functions whose name
begins with ``PyObject_``, ``PyNumber_``, ``PySequence_`` or ``PyMapping_``).
-These operations always increment the reference count of the object they return.
+These operations always create a new :term:`strong reference`
+(i.e. increment the reference count) of the object they return.
This leaves the caller with the responsibility to call :c:func:`Py_DECREF` when
they are done with the result; this soon becomes second nature.
@@ -356,7 +363,7 @@ to objects (objects are not owned: they are always shared). "Owning a
reference" means being responsible for calling Py_DECREF on it when the
reference is no longer needed. Ownership can also be transferred, meaning that
the code that receives ownership of the reference then becomes responsible for
-eventually decref'ing it by calling :c:func:`Py_DECREF` or :c:func:`Py_XDECREF`
+eventually releasing it by calling :c:func:`Py_DECREF` or :c:func:`Py_XDECREF`
when it's no longer needed---or passing on this responsibility (usually to its
caller). When a function passes ownership of a reference on to its caller, the
caller is said to receive a *new* reference. When no ownership is transferred,
@@ -414,9 +421,9 @@ For example, the above two blocks of code could be replaced by the following
It is much more common to use :c:func:`PyObject_SetItem` and friends with items
whose references you are only borrowing, like arguments that were passed in to
-the function you are writing. In that case, their behaviour regarding reference
-counts is much saner, since you don't have to increment a reference count so you
-can give a reference away ("have it be stolen"). For example, this function
+the function you are writing. In that case, their behaviour regarding references
+is much saner, since you don't have to take a new reference just so you
+can give that reference away ("have it be stolen"). For example, this function
sets all items of a list (actually, any mutable sequence) to a given item::
int
@@ -616,7 +623,7 @@ and lose important information about the exact cause of the error.
.. index:: single: sum_sequence()
A simple example of detecting exceptions and passing them on is shown in the
-:c:func:`sum_sequence` example above. It so happens that this example doesn't
+:c:func:`!sum_sequence` example above. It so happens that this example doesn't
need to clean up any owned references when it detects an error. The following
example function shows some error cleanup. First, to remind you why you like
Python, we show the equivalent Python code::
diff --git a/Doc/c-api/iterator.rst b/Doc/c-api/iterator.rst
index 3fcf099134d4dd..6b7ba8c9979163 100644
--- a/Doc/c-api/iterator.rst
+++ b/Doc/c-api/iterator.rst
@@ -6,7 +6,7 @@ Iterator Objects
----------------
Python provides two general-purpose iterator objects. The first, a sequence
-iterator, works with an arbitrary sequence supporting the :meth:`__getitem__`
+iterator, works with an arbitrary sequence supporting the :meth:`~object.__getitem__`
method. The second works with a callable object and a sentinel value, calling
the callable for each item in the sequence, and ending the iteration when the
sentinel value is returned.
@@ -19,7 +19,7 @@ sentinel value is returned.
types.
-.. c:function:: int PySeqIter_Check(op)
+.. c:function:: int PySeqIter_Check(PyObject *op)
Return true if the type of *op* is :c:data:`PySeqIter_Type`. This function
always succeeds.
@@ -38,7 +38,7 @@ sentinel value is returned.
two-argument form of the :func:`iter` built-in function.
-.. c:function:: int PyCallIter_Check(op)
+.. c:function:: int PyCallIter_Check(PyObject *op)
Return true if the type of *op* is :c:data:`PyCallIter_Type`. This
function always succeeds.
diff --git a/Doc/c-api/long.rst b/Doc/c-api/long.rst
index 5c1d026a330ae7..f1354a34f2b2d5 100644
--- a/Doc/c-api/long.rst
+++ b/Doc/c-api/long.rst
@@ -121,7 +121,7 @@ distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate.
single: OverflowError (built-in exception)
Return a C :c:expr:`long` representation of *obj*. If *obj* is not an
- instance of :c:type:`PyLongObject`, first call its :meth:`__index__` method
+ instance of :c:type:`PyLongObject`, first call its :meth:`~object.__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
@@ -130,30 +130,30 @@ distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate.
Returns ``-1`` on error. Use :c:func:`PyErr_Occurred` to disambiguate.
.. versionchanged:: 3.8
- Use :meth:`__index__` if available.
+ Use :meth:`~object.__index__` if available.
.. versionchanged:: 3.10
- This function will no longer use :meth:`__int__`.
+ This function will no longer use :meth:`~object.__int__`.
.. c:function:: long PyLong_AsLongAndOverflow(PyObject *obj, int *overflow)
Return a C :c:expr:`long` representation of *obj*. If *obj* is not an
- instance of :c:type:`PyLongObject`, first call its :meth:`__index__`
+ instance of :c:type:`PyLongObject`, first call its :meth:`~object.__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
+ If the value of *obj* is greater than :c:macro:`LONG_MAX` or less than
+ :c:macro:`LONG_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.
Returns ``-1`` on error. Use :c:func:`PyErr_Occurred` to disambiguate.
.. versionchanged:: 3.8
- Use :meth:`__index__` if available.
+ Use :meth:`~object.__index__` if available.
.. versionchanged:: 3.10
- This function will no longer use :meth:`__int__`.
+ This function will no longer use :meth:`~object.__int__`.
.. c:function:: long long PyLong_AsLongLong(PyObject *obj)
@@ -162,7 +162,7 @@ distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate.
single: OverflowError (built-in exception)
Return a C :c:expr:`long long` representation of *obj*. If *obj* is not an
- instance of :c:type:`PyLongObject`, first call its :meth:`__index__` method
+ instance of :c:type:`PyLongObject`, first call its :meth:`~object.__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
@@ -171,20 +171,20 @@ distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate.
Returns ``-1`` on error. Use :c:func:`PyErr_Occurred` to disambiguate.
.. versionchanged:: 3.8
- Use :meth:`__index__` if available.
+ Use :meth:`~object.__index__` if available.
.. versionchanged:: 3.10
- This function will no longer use :meth:`__int__`.
+ This function will no longer use :meth:`~object.__int__`.
.. c:function:: long long PyLong_AsLongLongAndOverflow(PyObject *obj, int *overflow)
Return a C :c:expr:`long long` representation of *obj*. If *obj* is not an
- instance of :c:type:`PyLongObject`, first call its :meth:`__index__` method
+ instance of :c:type:`PyLongObject`, first call its :meth:`~object.__index__` method
(if present) to convert it to a :c:type:`PyLongObject`.
- If the value of *obj* is greater than :const:`LLONG_MAX` or less than
- :const:`LLONG_MIN`, set *\*overflow* to ``1`` or ``-1``, respectively,
+ If the value of *obj* is greater than :c:macro:`LLONG_MAX` or less than
+ :c:macro:`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.
@@ -193,10 +193,10 @@ distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate.
.. versionadded:: 3.2
.. versionchanged:: 3.8
- Use :meth:`__index__` if available.
+ Use :meth:`~object.__index__` if available.
.. versionchanged:: 3.10
- This function will no longer use :meth:`__int__`.
+ This function will no longer use :meth:`~object.__int__`.
.. c:function:: Py_ssize_t PyLong_AsSsize_t(PyObject *pylong)
@@ -267,7 +267,7 @@ distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate.
.. c:function:: unsigned long PyLong_AsUnsignedLongMask(PyObject *obj)
Return a C :c:expr:`unsigned long` representation of *obj*. If *obj* is not
- an instance of :c:type:`PyLongObject`, first call its :meth:`__index__`
+ an instance of :c:type:`PyLongObject`, first call its :meth:`~object.__index__`
method (if present) to convert it to a :c:type:`PyLongObject`.
If the value of *obj* is out of range for an :c:expr:`unsigned long`,
@@ -277,17 +277,17 @@ distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate.
disambiguate.
.. versionchanged:: 3.8
- Use :meth:`__index__` if available.
+ Use :meth:`~object.__index__` if available.
.. versionchanged:: 3.10
- This function will no longer use :meth:`__int__`.
+ This function will no longer use :meth:`~object.__int__`.
.. c:function:: unsigned long long PyLong_AsUnsignedLongLongMask(PyObject *obj)
Return a C :c:expr:`unsigned long 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
+ :meth:`~object.__index__` method (if present) to convert it to a
:c:type:`PyLongObject`.
If the value of *obj* is out of range for an :c:expr:`unsigned long long`,
@@ -297,10 +297,10 @@ distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate.
to disambiguate.
.. versionchanged:: 3.8
- Use :meth:`__index__` if available.
+ Use :meth:`~object.__index__` if available.
.. versionchanged:: 3.10
- This function will no longer use :meth:`__int__`.
+ This function will no longer use :meth:`~object.__int__`.
.. c:function:: double PyLong_AsDouble(PyObject *pylong)
diff --git a/Doc/c-api/mapping.rst b/Doc/c-api/mapping.rst
index cffb0ed50fb77d..d94a9dc45b5ebe 100644
--- a/Doc/c-api/mapping.rst
+++ b/Doc/c-api/mapping.rst
@@ -13,7 +13,7 @@ See also :c:func:`PyObject_GetItem`, :c:func:`PyObject_SetItem` and
Return ``1`` if the object provides the mapping protocol or supports slicing,
and ``0`` otherwise. Note that it returns ``1`` for Python classes with
- a :meth:`__getitem__` method, since in general it is impossible to
+ a :meth:`~object.__getitem__` method, since in general it is impossible to
determine what type of keys the class supports. This function always succeeds.
@@ -60,7 +60,7 @@ See also :c:func:`PyObject_GetItem`, :c:func:`PyObject_SetItem` and
This is equivalent to the Python expression ``key in o``.
This function always succeeds.
- Note that exceptions which occur while calling the :meth:`__getitem__`
+ Note that exceptions which occur while calling the :meth:`~object.__getitem__`
method will get suppressed.
To get error reporting use :c:func:`PyObject_GetItem()` instead.
@@ -71,7 +71,7 @@ See also :c:func:`PyObject_GetItem`, :c:func:`PyObject_SetItem` and
This is equivalent to the Python expression ``key in o``.
This function always succeeds.
- Note that exceptions which occur while calling the :meth:`__getitem__`
+ Note that exceptions which occur while calling the :meth:`~object.__getitem__`
method and creating a temporary string object will get suppressed.
To get error reporting use :c:func:`PyMapping_GetItemString()` instead.
diff --git a/Doc/c-api/marshal.rst b/Doc/c-api/marshal.rst
index 8e25968c6909fd..489f1580a414b2 100644
--- a/Doc/c-api/marshal.rst
+++ b/Doc/c-api/marshal.rst
@@ -25,12 +25,16 @@ unmarshalling. Version 2 uses a binary format for floating point numbers.
the least-significant 32 bits of *value*; regardless of the size of the
native :c:expr:`long` type. *version* indicates the file format.
+ This function can fail, in which case it sets the error indicator.
+ Use :c:func:`PyErr_Occurred` to check for that.
.. c:function:: void PyMarshal_WriteObjectToFile(PyObject *value, FILE *file, int version)
Marshal a Python object, *value*, to *file*.
*version* indicates the file format.
+ This function can fail, in which case it sets the error indicator.
+ Use :c:func:`PyErr_Occurred` to check for that.
.. c:function:: PyObject* PyMarshal_WriteObjectToString(PyObject *value, int version)
diff --git a/Doc/c-api/memory.rst b/Doc/c-api/memory.rst
index 7041c15d23fb83..1df8c2b911ca8f 100644
--- a/Doc/c-api/memory.rst
+++ b/Doc/c-api/memory.rst
@@ -136,7 +136,7 @@ need to be held.
The :ref:`default raw memory allocator ` uses
the following functions: :c:func:`malloc`, :c:func:`calloc`, :c:func:`realloc`
-and :c:func:`free`; call ``malloc(1)`` (or ``calloc(1, 1)``) when requesting
+and :c:func:`!free`; call ``malloc(1)`` (or ``calloc(1, 1)``) when requesting
zero bytes.
.. versionadded:: 3.4
@@ -264,14 +264,14 @@ The following type-oriented macros are provided for convenience. Note that
*TYPE* refers to any C type.
-.. c:function:: TYPE* PyMem_New(TYPE, size_t n)
+.. c:macro:: PyMem_New(TYPE, n)
Same as :c:func:`PyMem_Malloc`, but allocates ``(n * sizeof(TYPE))`` bytes of
memory. Returns a pointer cast to :c:expr:`TYPE*`. The memory will not have
been initialized in any way.
-.. c:function:: TYPE* PyMem_Resize(void *p, TYPE, size_t n)
+.. c:macro:: PyMem_Resize(p, TYPE, n)
Same as :c:func:`PyMem_Realloc`, but the memory block is resized to ``(n *
sizeof(TYPE))`` bytes. Returns a pointer cast to :c:expr:`TYPE*`. On return,
@@ -423,7 +423,7 @@ Customize Memory Allocators
+----------------------------------------------------------+---------------------------------------+
.. versionchanged:: 3.5
- The :c:type:`PyMemAllocator` structure was renamed to
+ The :c:type:`!PyMemAllocator` structure was renamed to
:c:type:`PyMemAllocatorEx` and a new ``calloc`` field was added.
@@ -431,6 +431,8 @@ Customize Memory Allocators
Enum used to identify an allocator domain. Domains:
+ .. c:namespace:: NULL
+
.. c:macro:: PYMEM_DOMAIN_RAW
Functions:
@@ -470,10 +472,14 @@ Customize Memory Allocators
The new allocator must return a distinct non-``NULL`` pointer when requesting
zero bytes.
- For the :c:data:`PYMEM_DOMAIN_RAW` domain, the allocator must be
+ For the :c:macro:`PYMEM_DOMAIN_RAW` domain, the allocator must be
thread-safe: the :term:`GIL ` is not held when the
allocator is called.
+ For the remaining domains, the allocator must also be thread-safe:
+ the allocator may be called in different interpreters that do not
+ share a ``GIL``.
+
If the new allocator is not a hook (does not call the previous allocator),
the :c:func:`PyMem_SetupDebugHooks` function must be called to reinstall the
debug hooks on top on the new allocator.
@@ -498,6 +504,8 @@ Customize Memory Allocators
**must** wrap the existing allocator. Substituting the current
allocator for some other arbitrary one is **not supported**.
+ .. versionchanged:: 3.12
+ All allocators must be thread-safe.
.. c:function:: void PyMem_SetupDebugHooks(void)
@@ -536,8 +544,8 @@ Runtime checks:
- Detect write before the start of the buffer (buffer underflow).
- Detect write after the end of the buffer (buffer overflow).
- Check that the :term:`GIL ` is held when
- allocator functions of :c:data:`PYMEM_DOMAIN_OBJ` (ex:
- :c:func:`PyObject_Malloc`) and :c:data:`PYMEM_DOMAIN_MEM` (ex:
+ allocator functions of :c:macro:`PYMEM_DOMAIN_OBJ` (ex:
+ :c:func:`PyObject_Malloc`) and :c:macro:`PYMEM_DOMAIN_MEM` (ex:
:c:func:`PyMem_Malloc`) domains are called.
On error, the debug hooks use the :mod:`tracemalloc` module to get the
@@ -557,9 +565,9 @@ that the treatment of negative indices differs from a Python slice):
``p[-S]``
API identifier (ASCII character):
- * ``'r'`` for :c:data:`PYMEM_DOMAIN_RAW`.
- * ``'m'`` for :c:data:`PYMEM_DOMAIN_MEM`.
- * ``'o'`` for :c:data:`PYMEM_DOMAIN_OBJ`.
+ * ``'r'`` for :c:macro:`PYMEM_DOMAIN_RAW`.
+ * ``'m'`` for :c:macro:`PYMEM_DOMAIN_MEM`.
+ * ``'o'`` for :c:macro:`PYMEM_DOMAIN_OBJ`.
``p[-S+1:0]``
Copies of PYMEM_FORBIDDENBYTE. Used to catch under- writes and reads.
@@ -581,7 +589,7 @@ that the treatment of negative indices differs from a Python slice):
default).
A serial number, incremented by 1 on each call to a malloc-like or
- realloc-like function. Big-endian ``size_t``. If "bad memory" is detected
+ realloc-like function. Big-endian :c:type:`size_t`. If "bad memory" is detected
later, the serial number gives an excellent way to set a breakpoint on the
next run, to capture the instant at which this block was passed out. The
static function bumpserialno() in obmalloc.c is the only place the serial
@@ -601,7 +609,7 @@ PYMEM_CLEANBYTE (meaning uninitialized memory is getting used).
compiled in release mode. On error, the debug hooks now use
:mod:`tracemalloc` to get the traceback where a memory block was allocated.
The debug hooks now also check if the GIL is held when functions of
- :c:data:`PYMEM_DOMAIN_OBJ` and :c:data:`PYMEM_DOMAIN_MEM` domains are
+ :c:macro:`PYMEM_DOMAIN_OBJ` and :c:macro:`PYMEM_DOMAIN_MEM` domains are
called.
.. versionchanged:: 3.8
@@ -622,13 +630,13 @@ with a fixed size of 256 KiB. It falls back to :c:func:`PyMem_RawMalloc` and
:c:func:`PyMem_RawRealloc` for allocations larger than 512 bytes.
*pymalloc* is the :ref:`default allocator ` of the
-:c:data:`PYMEM_DOMAIN_MEM` (ex: :c:func:`PyMem_Malloc`) and
-:c:data:`PYMEM_DOMAIN_OBJ` (ex: :c:func:`PyObject_Malloc`) domains.
+:c:macro:`PYMEM_DOMAIN_MEM` (ex: :c:func:`PyMem_Malloc`) and
+:c:macro:`PYMEM_DOMAIN_OBJ` (ex: :c:func:`PyObject_Malloc`) domains.
The arena allocator uses the following functions:
-* :c:func:`VirtualAlloc` and :c:func:`VirtualFree` on Windows,
-* :c:func:`mmap` and :c:func:`munmap` if available,
+* :c:func:`!VirtualAlloc` and :c:func:`!VirtualFree` on Windows,
+* :c:func:`!mmap` and :c:func:`!munmap` if available,
* :c:func:`malloc` and :c:func:`free` otherwise.
This allocator is disabled if Python is configured with the
@@ -732,8 +740,8 @@ allocators operating on different heaps. ::
free(buf1); /* Fatal -- should be PyMem_Del() */
In addition to the functions aimed at handling raw memory blocks from the Python
-heap, objects in Python are allocated and released with :c:func:`PyObject_New`,
-:c:func:`PyObject_NewVar` and :c:func:`PyObject_Del`.
+heap, objects in Python are allocated and released with :c:macro:`PyObject_New`,
+:c:macro:`PyObject_NewVar` and :c:func:`PyObject_Del`.
These will be explained in the next chapter on defining and implementing new
object types in C.
diff --git a/Doc/c-api/method.rst b/Doc/c-api/method.rst
index 93ad30cd4f7a8d..0d75ab8e1af111 100644
--- a/Doc/c-api/method.rst
+++ b/Doc/c-api/method.rst
@@ -7,8 +7,8 @@ Instance Method Objects
.. index:: pair: object; instancemethod
-An instance method is a wrapper for a :c:data:`PyCFunction` and the new way
-to bind a :c:data:`PyCFunction` to a class object. It replaces the former call
+An instance method is a wrapper for a :c:type:`PyCFunction` and the new way
+to bind a :c:type:`PyCFunction` to a class object. It replaces the former call
``PyMethod_New(func, NULL, class)``.
diff --git a/Doc/c-api/module.rst b/Doc/c-api/module.rst
index 230b471d473be7..f941f0c7d42b2b 100644
--- a/Doc/c-api/module.rst
+++ b/Doc/c-api/module.rst
@@ -119,7 +119,7 @@ Module Objects
encoded to 'utf-8'.
.. deprecated:: 3.2
- :c:func:`PyModule_GetFilename` raises :c:type:`UnicodeEncodeError` on
+ :c:func:`PyModule_GetFilename` raises :exc:`UnicodeEncodeError` on
unencodable filenames, use :c:func:`PyModule_GetFilenameObject` instead.
@@ -145,7 +145,7 @@ or request "multi-phase initialization" by returning the definition struct itsel
.. c:member:: PyModuleDef_Base m_base
- Always initialize this member to :const:`PyModuleDef_HEAD_INIT`.
+ Always initialize this member to :c:macro:`PyModuleDef_HEAD_INIT`.
.. c:member:: const char *m_name
@@ -164,7 +164,7 @@ or request "multi-phase initialization" by returning the definition struct itsel
This memory area is allocated based on *m_size* on module creation,
and freed when the module object is deallocated, after the
- :c:member:`m_free` function has been called, if present.
+ :c:member:`~PyModuleDef.m_free` function has been called, if present.
Setting ``m_size`` to ``-1`` means that the module does not support
sub-interpreters, because it has global state.
@@ -202,7 +202,7 @@ or request "multi-phase initialization" by returning the definition struct itsel
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
+ precisely, this function is not called if :c:member:`~PyModuleDef.m_size` is greater
than 0 and the module state (as returned by :c:func:`PyModule_GetState`)
is ``NULL``.
@@ -217,7 +217,7 @@ or request "multi-phase initialization" by returning the definition struct itsel
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
+ precisely, this function is not called if :c:member:`~PyModuleDef.m_size` is greater
than 0 and the module state (as returned by :c:func:`PyModule_GetState`)
is ``NULL``.
@@ -238,7 +238,7 @@ or request "multi-phase initialization" by returning the definition struct itsel
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
+ precisely, this function is not called if :c:member:`~PyModuleDef.m_size` is greater
than 0 and the module state (as returned by :c:func:`PyModule_GetState`)
is ``NULL``.
@@ -256,7 +256,7 @@ of the following two module creation functions:
Create a new module object, given the definition in *def*. This behaves
like :c:func:`PyModule_Create2` with *module_api_version* set to
- :const:`PYTHON_API_VERSION`.
+ :c:macro:`PYTHON_API_VERSION`.
.. c:function:: PyObject* PyModule_Create2(PyModuleDef *def, int module_api_version)
@@ -282,7 +282,7 @@ An alternate way to specify extensions is to request "multi-phase initialization
Extension modules created this way behave more like Python modules: the
initialization is split between the *creation phase*, when the module object
is created, and the *execution phase*, when it is populated.
-The distinction is similar to the :py:meth:`__new__` and :py:meth:`__init__` methods
+The distinction is similar to the :py:meth:`!__new__` and :py:meth:`!__init__` methods
of classes.
Unlike modules created using single-phase initialization, these modules are not
@@ -293,7 +293,7 @@ By default, multiple modules created from the same definition should be
independent: changes to one should not affect the others.
This means that all state should be specific to the module object (using e.g.
using :c:func:`PyModule_GetState`), or its contents (such as the module's
-:attr:`__dict__` or individual classes created with :c:func:`PyType_FromSpec`).
+:attr:`~object.__dict__` or individual classes created with :c:func:`PyType_FromSpec`).
All modules created using multi-phase initialization are expected to support
:ref:`sub-interpreters `. Making sure multiple modules
@@ -338,6 +338,7 @@ The available slot types are:
The *value* pointer of this slot must point to a function of the signature:
.. c:function:: PyObject* create_module(PyObject *spec, PyModuleDef *def)
+ :noindex:
The function receives a :py:class:`~importlib.machinery.ModuleSpec`
instance, as defined in :PEP:`451`, and the module definition.
@@ -372,10 +373,44 @@ The available slot types are:
The signature of the function is:
.. c:function:: int exec_module(PyObject* module)
+ :noindex:
If multiple ``Py_mod_exec`` slots are specified, they are processed in the
order they appear in the *m_slots* array.
+.. c:macro:: Py_mod_multiple_interpreters
+
+ Specifies one of the following values:
+
+ .. c:namespace:: NULL
+
+ .. c:macro:: Py_MOD_MULTIPLE_INTERPRETERS_NOT_SUPPORTED
+
+ The module does not support being imported in subinterpreters.
+
+ .. c:macro:: Py_MOD_MULTIPLE_INTERPRETERS_SUPPORTED
+
+ The module supports being imported in subinterpreters,
+ but only when they share the main interpreter's GIL.
+ (See :ref:`isolating-extensions-howto`.)
+
+ .. c:macro:: Py_MOD_PER_INTERPRETER_GIL_SUPPORTED
+
+ The module supports being imported in subinterpreters,
+ even when they have their own GIL.
+ (See :ref:`isolating-extensions-howto`.)
+
+ This slot determines whether or not importing this module
+ in a subinterpreter will fail.
+
+ Multiple ``Py_mod_multiple_interpreters`` slots may not be specified
+ in one module definition.
+
+ If ``Py_mod_multiple_interpreters`` is not specified, the import
+ machinery defaults to ``Py_MOD_MULTIPLE_INTERPRETERS_NOT_SUPPORTED``.
+
+ .. versionadded:: 3.12
+
See :PEP:`489` for more details on multi-phase initialization.
Low-level module creation functions
@@ -390,7 +425,7 @@ objects dynamically. Note that both ``PyModule_FromDefAndSpec`` and
Create a new module object, given the definition in *def* and the
ModuleSpec *spec*. This behaves like :c:func:`PyModule_FromDefAndSpec2`
- with *module_api_version* set to :const:`PYTHON_API_VERSION`.
+ with *module_api_version* set to :c:macro:`PYTHON_API_VERSION`.
.. versionadded:: 3.5
@@ -498,7 +533,7 @@ state:
.. note::
Unlike other functions that steal references, ``PyModule_AddObject()``
- only decrements the reference count of *value* **on success**.
+ only releases the reference to *value* **on success**.
This means that its return value must be checked, and calling code must
:c:func:`Py_DECREF` *value* manually on error.
@@ -555,7 +590,7 @@ state:
``NULL``-terminated. Return ``-1`` on error, ``0`` on success.
-.. c:function:: int PyModule_AddIntMacro(PyObject *module, macro)
+.. c:macro:: PyModule_AddIntMacro(module, macro)
Add an int constant to *module*. The name and the value are taken from
*macro*. For example ``PyModule_AddIntMacro(module, AF_INET)`` adds the int
@@ -563,7 +598,7 @@ state:
Return ``-1`` on error, ``0`` on success.
-.. c:function:: int PyModule_AddStringMacro(PyObject *module, macro)
+.. c:macro:: PyModule_AddStringMacro(module, macro)
Add a string constant to *module*.
diff --git a/Doc/c-api/none.rst b/Doc/c-api/none.rst
index b84a16a28ead56..dd8bfb56104251 100644
--- a/Doc/c-api/none.rst
+++ b/Doc/c-api/none.rst
@@ -9,18 +9,18 @@ The ``None`` Object
Note that the :c:type:`PyTypeObject` for ``None`` is not directly exposed in the
Python/C API. Since ``None`` is a singleton, testing for object identity (using
-``==`` in C) is sufficient. There is no :c:func:`PyNone_Check` function for the
+``==`` in C) is sufficient. There is no :c:func:`!PyNone_Check` function for the
same reason.
.. c:var:: PyObject* Py_None
- The Python ``None`` object, denoting lack of value. This object has no methods.
- It needs to be treated just like any other object with respect to reference
- counts.
+ The Python ``None`` object, denoting lack of value. This object has no methods
+ and is `immortal `_.
+.. versionchanged:: 3.12
+ :c:data:`Py_None` is immortal.
.. c:macro:: Py_RETURN_NONE
- Properly handle returning :c:data:`Py_None` from within a C function (that is,
- increment the reference count of ``None`` and return it.)
+ Return :c:data:`Py_None` from a function.
diff --git a/Doc/c-api/object.rst b/Doc/c-api/object.rst
index a25ff244c9f07c..4a3fed1a6087a1 100644
--- a/Doc/c-api/object.rst
+++ b/Doc/c-api/object.rst
@@ -15,15 +15,15 @@ Object Protocol
.. c:macro:: Py_RETURN_NOTIMPLEMENTED
Properly handle returning :c:data:`Py_NotImplemented` from within a C
- function (that is, increment the reference count of NotImplemented and
- return it).
+ function (that is, create a new :term:`strong reference`
+ to NotImplemented and return it).
.. c:function:: int PyObject_Print(PyObject *o, FILE *fp, int flags)
Print an object *o*, on file *fp*. Returns ``-1`` on error. The flags argument
is used to enable certain printing options. The only option currently supported
- is :const:`Py_PRINT_RAW`; if given, the :func:`str` of the object is written
+ is :c:macro:`Py_PRINT_RAW`; if given, the :func:`str` of the object is written
instead of the :func:`repr`.
@@ -33,9 +33,11 @@ Object Protocol
is equivalent to the Python expression ``hasattr(o, attr_name)``. This function
always succeeds.
- Note that exceptions which occur while calling :meth:`__getattr__` and
- :meth:`__getattribute__` methods will get suppressed.
- To get error reporting use :c:func:`PyObject_GetAttr()` instead.
+ .. note::
+
+ Exceptions that occur when this calls :meth:`~object.__getattr__` and
+ :meth:`~object.__getattribute__` methods are silently ignored.
+ For proper error handling, use :c:func:`PyObject_GetAttr` instead.
.. c:function:: int PyObject_HasAttrString(PyObject *o, const char *attr_name)
@@ -44,10 +46,12 @@ Object Protocol
is equivalent to the Python expression ``hasattr(o, attr_name)``. This function
always succeeds.
- Note that exceptions which occur while calling :meth:`__getattr__` and
- :meth:`__getattribute__` methods and creating a temporary string object
- will get suppressed.
- To get error reporting use :c:func:`PyObject_GetAttrString()` instead.
+ .. note::
+
+ Exceptions that occur when this calls :meth:`~object.__getattr__` and
+ :meth:`~object.__getattribute__` methods or while creating the temporary :class:`str`
+ object are silently ignored.
+ For proper error handling, use :c:func:`PyObject_GetAttrString` instead.
.. c:function:: PyObject* PyObject_GetAttr(PyObject *o, PyObject *attr_name)
@@ -158,8 +162,8 @@ Object Protocol
.. c:function:: PyObject* PyObject_RichCompare(PyObject *o1, PyObject *o2, int opid)
Compare the values of *o1* and *o2* using the operation specified by *opid*,
- which must be one of :const:`Py_LT`, :const:`Py_LE`, :const:`Py_EQ`,
- :const:`Py_NE`, :const:`Py_GT`, or :const:`Py_GE`, corresponding to ``<``,
+ which must be one of :c:macro:`Py_LT`, :c:macro:`Py_LE`, :c:macro:`Py_EQ`,
+ :c:macro:`Py_NE`, :c:macro:`Py_GT`, or :c:macro:`Py_GE`, corresponding to ``<``,
``<=``, ``==``, ``!=``, ``>``, or ``>=`` respectively. This is the equivalent of
the Python expression ``o1 op o2``, where ``op`` is the operator corresponding
to *opid*. Returns the value of the comparison on success, or ``NULL`` on failure.
@@ -168,8 +172,8 @@ Object Protocol
.. c:function:: int PyObject_RichCompareBool(PyObject *o1, PyObject *o2, int opid)
Compare the values of *o1* and *o2* using the operation specified by *opid*,
- which must be one of :const:`Py_LT`, :const:`Py_LE`, :const:`Py_EQ`,
- :const:`Py_NE`, :const:`Py_GT`, or :const:`Py_GE`, corresponding to ``<``,
+ which must be one of :c:macro:`Py_LT`, :c:macro:`Py_LE`, :c:macro:`Py_EQ`,
+ :c:macro:`Py_NE`, :c:macro:`Py_GT`, or :c:macro:`Py_GE`, corresponding to ``<``,
``<=``, ``==``, ``!=``, ``>``, or ``>=`` respectively. Returns ``-1`` on error,
``0`` if the result is false, ``1`` otherwise. This is the equivalent of the
Python expression ``o1 op o2``, where ``op`` is the operator corresponding to
@@ -177,7 +181,7 @@ Object Protocol
.. note::
If *o1* and *o2* are the same object, :c:func:`PyObject_RichCompareBool`
- will always return ``1`` for :const:`Py_EQ` and ``0`` for :const:`Py_NE`.
+ will always return ``1`` for :c:macro:`Py_EQ` and ``0`` for :c:macro:`Py_NE`.
.. c:function:: PyObject* PyObject_Format(PyObject *obj, PyObject *format_spec)
@@ -252,7 +256,7 @@ Object Protocol
Normally only class objects, i.e. instances of :class:`type` or a derived
class, are considered classes. However, objects can override this by having
- a :attr:`__bases__` attribute (which must be a tuple of base classes).
+ a :attr:`~class.__bases__` attribute (which must be a tuple of base classes).
.. c:function:: int PyObject_IsInstance(PyObject *inst, PyObject *cls)
@@ -269,10 +273,10 @@ Object Protocol
is an instance of *cls* if its class is a subclass of *cls*.
An instance *inst* can override what is considered its class by having a
- :attr:`__class__` attribute.
+ :attr:`~instance.__class__` attribute.
An object *cls* can override if it is considered a class, and what its base
- classes are, by having a :attr:`__bases__` attribute (which must be a tuple
+ classes are, by having a :attr:`~class.__bases__` attribute (which must be a tuple
of base classes).
@@ -316,11 +320,12 @@ Object Protocol
When *o* is non-``NULL``, returns a type object corresponding to the object type
of object *o*. On failure, raises :exc:`SystemError` and returns ``NULL``. This
- 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
+ is equivalent to the Python expression ``type(o)``.
+ This function creates a new :term:`strong reference` to the return value.
+ There's really no reason to use this
function instead of the :c:func:`Py_TYPE()` function, which returns a
- pointer of type :c:expr:`PyTypeObject*`, except when the incremented reference
- count is needed.
+ pointer of type :c:expr:`PyTypeObject*`, except when a new
+ :term:`strong reference` is needed.
.. c:function:: int PyObject_TypeCheck(PyObject *o, PyTypeObject *type)
@@ -427,10 +432,10 @@ Object Protocol
.. c:function:: void *PyObject_GetItemData(PyObject *o)
Get a pointer to per-item data for a class with
- :const:`Py_TPFLAGS_ITEMS_AT_END`.
+ :c:macro:`Py_TPFLAGS_ITEMS_AT_END`.
On error, set an exception and return ``NULL``.
:py:exc:`TypeError` is raised if *o* does not have
- :const:`Py_TPFLAGS_ITEMS_AT_END` set.
+ :c:macro:`Py_TPFLAGS_ITEMS_AT_END` set.
.. versionadded:: 3.12
diff --git a/Doc/c-api/refcounting.rst b/Doc/c-api/refcounting.rst
index d8e9c2da6f3ff3..4ea0378d02a655 100644
--- a/Doc/c-api/refcounting.rst
+++ b/Doc/c-api/refcounting.rst
@@ -15,6 +15,12 @@ of Python objects.
Get the reference count of the Python object *o*.
+ Note that the returned value may not actually reflect how many
+ references to the object are actually held. For example, some
+ objects are "immortal" and have a very high refcount that does not
+ reflect the actual number of references. Consequently, do not rely
+ on the returned value to be accurate, other than a value of 0 or 1.
+
Use the :c:func:`Py_SET_REFCNT()` function to set an object reference count.
.. versionchanged:: 3.11
@@ -28,36 +34,53 @@ of Python objects.
Set the object *o* reference counter to *refcnt*.
+ Note that this function has no effect on
+ `immortal `_
+ objects.
+
.. versionadded:: 3.9
+ .. versionchanged:: 3.12
+ Immortal objects are not modified.
+
.. c:function:: void Py_INCREF(PyObject *o)
- Increment the reference count for object *o*.
+ Indicate taking a new :term:`strong reference` to object *o*,
+ indicating it is in use and should not be destroyed.
This function is usually used to convert a :term:`borrowed reference` to a
:term:`strong reference` in-place. The :c:func:`Py_NewRef` function can be
used to create a new :term:`strong reference`.
+ When done using the object, release it by calling :c:func:`Py_DECREF`.
+
The object must not be ``NULL``; if you aren't sure that it isn't
``NULL``, use :c:func:`Py_XINCREF`.
+ Do not expect this function to actually modify *o* in any way.
+ For at least `some objects `_,
+ this function has no effect.
+
+ .. versionchanged:: 3.12
+ Immortal objects are not modified.
+
.. c:function:: void Py_XINCREF(PyObject *o)
- Increment the reference count for object *o*. The object may be ``NULL``, in
- which case the macro has no effect.
+ Similar to :c:func:`Py_INCREF`, but the object *o* can be ``NULL``,
+ in which case this has no effect.
See also :c:func:`Py_XNewRef`.
.. c:function:: PyObject* Py_NewRef(PyObject *o)
- Create a new :term:`strong reference` to an object: increment the reference
- count of the object *o* and return the object *o*.
+ Create a new :term:`strong reference` to an object:
+ call :c:func:`Py_INCREF` on *o* and return the object *o*.
When the :term:`strong reference` is no longer needed, :c:func:`Py_DECREF`
- should be called on it to decrement the object reference count.
+ should be called on it to release the reference.
The object *o* must not be ``NULL``; use :c:func:`Py_XNewRef` if *o* can be
``NULL``.
@@ -87,9 +110,12 @@ of Python objects.
.. c:function:: void Py_DECREF(PyObject *o)
- Decrement the reference count for object *o*.
+ Release a :term:`strong reference` to object *o*, indicating the
+ reference is no longer used.
- If the reference count reaches zero, the object's type's deallocation
+ Once the last :term:`strong reference` is released
+ (i.e. the object's reference count reaches 0),
+ the object's type's deallocation
function (which must not be ``NULL``) is invoked.
This function is usually used to delete a :term:`strong reference` before
@@ -98,10 +124,14 @@ of Python objects.
The object must not be ``NULL``; if you aren't sure that it isn't ``NULL``,
use :c:func:`Py_XDECREF`.
+ Do not expect this function to actually modify *o* in any way.
+ For at least `some objects `_,
+ this function has no effect.
+
.. warning::
The deallocation function can cause arbitrary Python code to be invoked (e.g.
- when a class instance with a :meth:`__del__` method is deallocated). While
+ when a class instance with a :meth:`~object.__del__` method is deallocated). While
exceptions in such code are not propagated, the executed code has free access to
all Python global variables. This means that any object that is reachable from
a global variable should be in a consistent state before :c:func:`Py_DECREF` is
@@ -109,25 +139,29 @@ of Python objects.
reference to the deleted object in a temporary variable, update the list data
structure, and then call :c:func:`Py_DECREF` for the temporary variable.
+ .. versionchanged:: 3.12
+ Immortal objects are not modified.
+
.. c:function:: void Py_XDECREF(PyObject *o)
- Decrement the reference count for object *o*. The object may be ``NULL``, in
- which case the macro has no effect; otherwise the effect is the same as for
- :c:func:`Py_DECREF`, and the same warning applies.
+ Similar to :c:func:`Py_DECREF`, but the object *o* can be ``NULL``,
+ in which case this has no effect.
+ The same warning from :c:func:`Py_DECREF` applies here as well.
.. c:function:: void Py_CLEAR(PyObject *o)
- Decrement the reference count for object *o*. The object may be ``NULL``, in
+ Release a :term:`strong reference` for object *o*.
+ The object may be ``NULL``, in
which case the macro has no effect; otherwise the effect is the same as for
:c:func:`Py_DECREF`, except that the argument is also set to ``NULL``. The warning
for :c:func:`Py_DECREF` does not apply with respect to the object passed because
the macro carefully uses a temporary variable and sets the argument to ``NULL``
- before decrementing its reference count.
+ before releasing the reference.
- It is a good idea to use this macro whenever decrementing the reference
- count of an object that might be traversed during garbage collection.
+ It is a good idea to use this macro whenever releasing a reference
+ to an object that might be traversed during garbage collection.
.. versionchanged:: 3.12
The macro argument is now only evaluated once. If the argument has side
@@ -136,20 +170,22 @@ of Python objects.
.. c:function:: void Py_IncRef(PyObject *o)
- Increment the reference count for object *o*. A function version of :c:func:`Py_XINCREF`.
+ Indicate taking a new :term:`strong reference` to object *o*.
+ A function version of :c:func:`Py_XINCREF`.
It can be used for runtime dynamic embedding of Python.
.. c:function:: void Py_DecRef(PyObject *o)
- Decrement the reference count for object *o*. A function version of :c:func:`Py_XDECREF`.
+ Release a :term:`strong reference` to object *o*.
+ A function version of :c:func:`Py_XDECREF`.
It can be used for runtime dynamic embedding of Python.
.. c:macro:: Py_SETREF(dst, src)
- Macro safely decrementing the `dst` reference count and setting `dst` to
- `src`.
+ Macro safely releasing a :term:`strong reference` to object *dst*
+ and setting *dst* to *src*.
As in case of :c:func:`Py_CLEAR`, "the obvious" code can be deadly::
@@ -160,9 +196,10 @@ of Python objects.
Py_SETREF(dst, src);
- That arranges to set `dst` to `src` _before_ decrementing reference count of
- *dst* old value, so that any code triggered as a side-effect of `dst`
- getting torn down no longer believes `dst` points to a valid object.
+ That arranges to set *dst* to *src* _before_ releasing the reference
+ to the old value of *dst*, so that any code triggered as a side-effect
+ of *dst* getting torn down no longer believes *dst* points
+ to a valid object.
.. versionadded:: 3.6
diff --git a/Doc/c-api/sequence.rst b/Doc/c-api/sequence.rst
index 402a3e5e09ff56..ce28839f5ba739 100644
--- a/Doc/c-api/sequence.rst
+++ b/Doc/c-api/sequence.rst
@@ -9,7 +9,7 @@ Sequence Protocol
.. c:function:: int PySequence_Check(PyObject *o)
Return ``1`` if the object provides the sequence protocol, and ``0`` otherwise.
- Note that it returns ``1`` for Python classes with a :meth:`__getitem__`
+ Note that it returns ``1`` for Python classes with a :meth:`~object.__getitem__`
method, unless they are :class:`dict` subclasses, since in general it
is impossible to determine what type of keys the class supports. This
function always succeeds.
diff --git a/Doc/c-api/set.rst b/Doc/c-api/set.rst
index d642a5f1902e2e..1e8a09509032f5 100644
--- a/Doc/c-api/set.rst
+++ b/Doc/c-api/set.rst
@@ -110,7 +110,7 @@ or :class:`frozenset` or instances of their subtypes.
.. index:: pair: built-in function; len
Return the length of a :class:`set` or :class:`frozenset` object. Equivalent to
- ``len(anyset)``. Raises a :exc:`PyExc_SystemError` if *anyset* is not a
+ ``len(anyset)``. Raises a :exc:`SystemError` if *anyset* is not a
:class:`set`, :class:`frozenset`, or an instance of a subtype.
@@ -122,9 +122,9 @@ or :class:`frozenset` or instances of their subtypes.
.. c:function:: int PySet_Contains(PyObject *anyset, PyObject *key)
Return ``1`` if found, ``0`` if not found, and ``-1`` if an error is encountered. Unlike
- the Python :meth:`__contains__` method, this function does not automatically
+ the Python :meth:`~object.__contains__` method, this function does not automatically
convert unhashable sets into temporary frozensets. Raise a :exc:`TypeError` if
- the *key* is unhashable. Raise :exc:`PyExc_SystemError` if *anyset* is not a
+ the *key* is unhashable. Raise :exc:`SystemError` if *anyset* is not a
:class:`set`, :class:`frozenset`, or an instance of a subtype.
@@ -149,7 +149,7 @@ subtypes but not for instances of :class:`frozenset` or its subtypes.
error is encountered. Does not raise :exc:`KeyError` for missing keys. Raise a
:exc:`TypeError` if the *key* is unhashable. Unlike the Python :meth:`~set.discard`
method, this function does not automatically convert unhashable sets into
- temporary frozensets. Raise :exc:`PyExc_SystemError` if *set* is not an
+ temporary frozensets. Raise :exc:`SystemError` if *set* is not an
instance of :class:`set` or its subtype.
diff --git a/Doc/c-api/slice.rst b/Doc/c-api/slice.rst
index 8271d9acfb645e..9e880c6b7f25ad 100644
--- a/Doc/c-api/slice.rst
+++ b/Doc/c-api/slice.rst
@@ -34,7 +34,7 @@ Slice Objects
*length* as errors.
Returns ``0`` on success and ``-1`` on error with no exception set (unless one of
- the indices was not :const:`None` and failed to be converted to an integer,
+ the indices was not ``None`` and failed to be converted to an integer,
in which case ``-1`` is returned with an exception set).
You probably do not want to use this function.
@@ -113,11 +113,14 @@ Slice Objects
Ellipsis Object
----------------
+^^^^^^^^^^^^^^^
.. c:var:: PyObject *Py_Ellipsis
- The Python ``Ellipsis`` object. This object has no methods. It needs to be
- treated just like any other object with respect to reference counts. Like
- :c:data:`Py_None` it is a singleton object.
+ The Python ``Ellipsis`` object. This object has no methods. Like
+ :c:data:`Py_None`, it is an `immortal `_.
+ singleton object.
+
+ .. versionchanged:: 3.12
+ :c:data:`Py_Ellipsis` is immortal.
diff --git a/Doc/c-api/stable.rst b/Doc/c-api/stable.rst
index 3721fc0697f5cd..c66b296d304adc 100644
--- a/Doc/c-api/stable.rst
+++ b/Doc/c-api/stable.rst
@@ -20,9 +20,9 @@ but will need to be compiled separately for 3.9.x and 3.10.x.
There are two tiers of C API with different stability exepectations:
-- *Unstable API*, may change in minor versions without a deprecation period.
- It is marked by the ``PyUnstable`` prefix in names.
-- *Limited API*, is compatible across several minor releases.
+- :ref:`Unstable API `, may change in minor versions without
+ a deprecation period. It is marked by the ``PyUnstable`` prefix in names.
+- :ref:`Limited API `, is compatible across several minor releases.
When :c:macro:`Py_LIMITED_API` is defined, only this subset is exposed
from ``Python.h``.
@@ -55,26 +55,26 @@ CPython development and spend extra effort adjusting to changes.
Stable Application Binary Interface
===================================
+For simplicity, this document talks about *extensions*, but the Limited API
+and Stable ABI work the same way for all uses of the API – for example,
+embedding Python.
+
+.. _limited-c-api:
+
+Limited C API
+-------------
+
Python 3.2 introduced the *Limited API*, a subset of Python's C API.
Extensions that only use the Limited API can be
compiled once and work with multiple versions of Python.
-Contents of the Limited API are :ref:`listed below `.
-
-To enable this, Python provides a *Stable ABI*: a set of symbols that will
-remain compatible across Python 3.x versions. The Stable ABI contains symbols
-exposed in the Limited API, but also other ones – for example, functions
-necessary to support older versions of the Limited API.
-
-(For simplicity, this document talks about *extensions*, but the Limited API
-and Stable ABI work the same way for all uses of the API – for example,
-embedding Python.)
+Contents of the Limited API are :ref:`listed below `.
.. c:macro:: Py_LIMITED_API
Define this macro before including ``Python.h`` to opt in to only use
the Limited API, and to select the Limited API version.
- Define ``Py_LIMITED_API`` to the value of :c:data:`PY_VERSION_HEX`
+ Define ``Py_LIMITED_API`` to the value of :c:macro:`PY_VERSION_HEX`
corresponding to the lowest Python version your extension supports.
The extension will work without recompilation with all Python 3 releases
from the specified one onward, and can use Limited API introduced up to that
@@ -87,6 +87,19 @@ embedding Python.)
You can also define ``Py_LIMITED_API`` to ``3``. This works the same as
``0x03020000`` (Python 3.2, the version that introduced Limited API).
+
+.. _stable-abi:
+
+Stable ABI
+----------
+
+To enable this, Python provides a *Stable ABI*: a set of symbols that will
+remain compatible across Python 3.x versions.
+
+The Stable ABI contains symbols exposed in the :ref:`Limited API
+`, but also other ones – for example, functions necessary to
+support older versions of the Limited API.
+
On Windows, extensions that use the Stable ABI should be linked against
``python3.dll`` rather than a version-specific library such as
``python39.dll``.
@@ -131,9 +144,9 @@ Limited API Caveats
-------------------
Note that compiling with ``Py_LIMITED_API`` is *not* a complete guarantee that
-code conforms to the Limited API or the Stable ABI. ``Py_LIMITED_API`` only
-covers definitions, but an API also includes other issues, such as expected
-semantics.
+code conforms to the :ref:`Limited API ` or the :ref:`Stable ABI
+`. ``Py_LIMITED_API`` only covers definitions, but an API also
+includes other issues, such as expected semantics.
One issue that ``Py_LIMITED_API`` does not guard against is calling a function
with arguments that are invalid in a lower Python version.
@@ -166,9 +179,9 @@ Platform Considerations
=======================
ABI stability depends not only on Python, but also on the compiler used,
-lower-level libraries and compiler options. For the purposes of the Stable ABI,
-these details define a “platform”. They usually depend on the OS
-type and processor architecture
+lower-level libraries and compiler options. For the purposes of
+the :ref:`Stable ABI `, these details define a “platform”. They
+usually depend on the OS type and processor architecture
It is the responsibility of each particular distributor of Python
to ensure that all Python versions on a particular platform are built
@@ -177,12 +190,12 @@ This is the case with Windows and macOS releases from ``python.org`` and many
third-party distributors.
-.. _stable-abi-list:
+.. _limited-api-list:
Contents of Limited API
=======================
-Currently, the Limited API includes the following items:
+Currently, the :ref:`Limited API ` includes the following items:
.. limited-api-list::
diff --git a/Doc/c-api/structures.rst b/Doc/c-api/structures.rst
index aae1b951804491..747cfa62294c21 100644
--- a/Doc/c-api/structures.rst
+++ b/Doc/c-api/structures.rst
@@ -35,7 +35,7 @@ under :ref:`reference counting `.
.. c:type:: PyVarObject
- This is an extension of :c:type:`PyObject` that adds the :attr:`ob_size`
+ This is an extension of :c:type:`PyObject` that adds the :c:member:`~PyVarObject.ob_size`
field. This is only used for objects that have some notion of *length*.
This type does not often appear in the Python/C API.
Access to the members must be done by using the macros
@@ -152,7 +152,7 @@ under :ref:`reference counting `.
.. c:macro:: PyVarObject_HEAD_INIT(type, size)
This is a macro which expands to initialization values for a new
- :c:type:`PyVarObject` type, including the :attr:`ob_size` field.
+ :c:type:`PyVarObject` type, including the :c:member:`~PyVarObject.ob_size` field.
This macro expands to::
_PyObject_EXTRA_INIT
@@ -179,7 +179,7 @@ Implementing functions and methods
.. c:type:: PyCFunctionWithKeywords
Type of the functions used to implement Python callables in C
- with signature :const:`METH_VARARGS | METH_KEYWORDS`.
+ with signature :ref:`METH_VARARGS | METH_KEYWORDS `.
The function signature is::
PyObject *PyCFunctionWithKeywords(PyObject *self,
@@ -190,7 +190,7 @@ Implementing functions and methods
.. c:type:: _PyCFunctionFast
Type of the functions used to implement Python callables in C
- with signature :const:`METH_FASTCALL`.
+ with signature :c:macro:`METH_FASTCALL`.
The function signature is::
PyObject *_PyCFunctionFast(PyObject *self,
@@ -200,7 +200,7 @@ Implementing functions and methods
.. c:type:: _PyCFunctionFastWithKeywords
Type of the functions used to implement Python callables in C
- with signature :const:`METH_FASTCALL | METH_KEYWORDS`.
+ with signature :ref:`METH_FASTCALL | METH_KEYWORDS `.
The function signature is::
PyObject *_PyCFunctionFastWithKeywords(PyObject *self,
@@ -211,7 +211,7 @@ Implementing functions and methods
.. c:type:: PyCMethod
Type of the functions used to implement Python callables in C
- with signature :const:`METH_METHOD | METH_FASTCALL | METH_KEYWORDS`.
+ with signature :ref:`METH_METHOD | METH_FASTCALL | METH_KEYWORDS `.
The function signature is::
PyObject *PyCMethod(PyObject *self,
@@ -228,36 +228,38 @@ Implementing functions and methods
Structure used to describe a method of an extension type. This structure has
four fields:
- .. c:member:: const char* ml_name
+ .. c:member:: const char *ml_name
- name of the method
+ Name of the method.
.. c:member:: PyCFunction ml_meth
- pointer to the C implementation
+ Pointer to the C implementation.
.. c:member:: int ml_flags
- flags bits indicating how the call should be constructed
+ Flags bits indicating how the call should be constructed.
- .. c:member:: const char* ml_doc
+ .. c:member:: const char *ml_doc
- points to the contents of the docstring
+ Points to the contents of the docstring.
-The :c:member:`ml_meth` is a C function pointer. The functions may be of different
+The :c:member:`~PyMethodDef.ml_meth` is a C function pointer.
+The functions may be of different
types, but they always return :c:expr:`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:expr:`PyObject*`, it is common that the method implementation uses the
specific C type of the *self* object.
-The :c:member:`ml_flags` field is a bitfield which can include the following flags.
+The :c:member:`~PyMethodDef.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 these calling conventions:
-.. data:: METH_VARARGS
+.. c:macro:: METH_VARARGS
This is the typical calling convention, where the methods have the type
:c:type:`PyCFunction`. The function expects two :c:expr:`PyObject*` values.
@@ -267,8 +269,17 @@ There are these calling conventions:
using :c:func:`PyArg_ParseTuple` or :c:func:`PyArg_UnpackTuple`.
-.. data:: METH_VARARGS | METH_KEYWORDS
+.. c:macro:: METH_KEYWORDS
+ Can only be used in certain combinations with other flags:
+ :ref:`METH_VARARGS | METH_KEYWORDS `,
+ :ref:`METH_FASTCALL | METH_KEYWORDS ` and
+ :ref:`METH_METHOD | METH_FASTCALL | METH_KEYWORDS `.
+
+
+.. _METH_VARARGS-METH_KEYWORDS:
+
+:c:expr:`METH_VARARGS | METH_KEYWORDS`
Methods with these flags must be of type :c:type:`PyCFunctionWithKeywords`.
The function expects three parameters: *self*, *args*, *kwargs* where
*kwargs* is a dictionary of all the keyword arguments or possibly ``NULL``
@@ -276,7 +287,7 @@ There are these calling conventions:
using :c:func:`PyArg_ParseTupleAndKeywords`.
-.. data:: METH_FASTCALL
+.. c:macro:: METH_FASTCALL
Fast calling convention supporting only positional arguments.
The methods have the type :c:type:`_PyCFunctionFast`.
@@ -288,12 +299,13 @@ There are these calling conventions:
.. versionchanged:: 3.10
- ``METH_FASTCALL`` is now part of the stable ABI.
+ ``METH_FASTCALL`` is now part of the :ref:`stable ABI `.
-.. data:: METH_FASTCALL | METH_KEYWORDS
+.. _METH_FASTCALL-METH_KEYWORDS:
- Extension of :const:`METH_FASTCALL` supporting also keyword arguments,
+:c:expr:`METH_FASTCALL | METH_KEYWORDS`
+ Extension of :c:macro:`METH_FASTCALL` supporting also keyword arguments,
with methods of type :c:type:`_PyCFunctionFastWithKeywords`.
Keyword arguments are passed the same way as in the
:ref:`vectorcall protocol `:
@@ -306,10 +318,18 @@ There are these calling conventions:
.. versionadded:: 3.7
-.. data:: METH_METHOD | METH_FASTCALL | METH_KEYWORDS
+.. c:macro:: METH_METHOD
+
+ Can only be used in the combination with other flags:
+ :ref:`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.
+
+.. _METH_METHOD-METH_FASTCALL-METH_KEYWORDS:
+
+:c:expr:`METH_METHOD | METH_FASTCALL | METH_KEYWORDS`
+ Extension of :ref:`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
@@ -319,10 +339,10 @@ There are these calling conventions:
.. versionadded:: 3.9
-.. data:: METH_NOARGS
+.. c:macro:: METH_NOARGS
Methods without parameters don't need to check whether arguments are given if
- they are listed with the :const:`METH_NOARGS` flag. They need to be of type
+ they are listed with the :c:macro:`METH_NOARGS` flag. They need to be of type
:c:type:`PyCFunction`. The first parameter is typically named *self* and will
hold a reference to the module or object instance. In all cases the second
parameter will be ``NULL``.
@@ -331,9 +351,9 @@ There are these calling conventions:
:c:macro:`Py_UNUSED` can be used to prevent a compiler warning.
-.. data:: METH_O
+.. c:macro:: METH_O
- Methods with a single object argument can be listed with the :const:`METH_O`
+ Methods with a single object argument can be listed with the :c:macro:`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:expr:`PyObject*` parameter representing the single argument.
@@ -345,7 +365,7 @@ defined for modules. At most one of these flags may be set for any given
method.
-.. data:: METH_CLASS
+.. c:macro:: METH_CLASS
.. index:: pair: built-in function; classmethod
@@ -355,7 +375,7 @@ method.
function.
-.. data:: METH_STATIC
+.. c:macro:: METH_STATIC
.. index:: pair: built-in function; staticmethod
@@ -367,13 +387,13 @@ One other constant controls whether a method is loaded in place of another
definition with the same method name.
-.. data:: METH_COEXIST
+.. c:macro:: METH_COEXIST
The method will be loaded in place of existing definitions. Without
*METH_COEXIST*, the default is to skip repeated definitions. Since slot
wrappers are loaded before the method table, the existence of a
*sq_contains* slot, for example, would generate a wrapped method named
- :meth:`__contains__` and preclude the loading of a corresponding
+ :meth:`~object.__contains__` and preclude the loading of a corresponding
PyCFunction with the same name. With the flag defined, the PyCFunction
will be loaded in place of the wrapper object and will co-exist with the
slot. This is helpful because calls to PyCFunctions are optimized more
@@ -395,7 +415,7 @@ Accessing attributes of extension types
The string should be static, no copy is made of it.
- .. c:member:: Py_ssize_t PyMemberDef.offset
+ .. c:member:: Py_ssize_t offset
The offset in bytes that the member is located on the type’s object struct.
@@ -414,7 +434,7 @@ Accessing attributes of extension types
The string should be static, no copy is made of it.
Typically, it is defined using :c:macro:`PyDoc_STR`.
- By default (when :c:member:`flags` is ``0``), members allow
+ By default (when :c:member:`~PyMemberDef.flags` is ``0``), members allow
both read and write access.
Use the :c:macro:`Py_READONLY` flag for read-only access.
Certain types, like :c:macro:`Py_T_STRING`, imply :c:macro:`Py_READONLY`.
@@ -440,8 +460,8 @@ Accessing attributes of extension types
The legacy offsets :c:member:`~PyTypeObject.tp_dictoffset` and
:c:member:`~PyTypeObject.tp_weaklistoffset` can be defined similarly using
``"__dictoffset__"`` and ``"__weaklistoffset__"`` members, but extensions
- are strongly encouraged to use :const:`Py_TPFLAGS_MANAGED_DICT` and
- :const:`Py_TPFLAGS_MANAGED_WEAKREF` instead.
+ are strongly encouraged to use :c:macro:`Py_TPFLAGS_MANAGED_DICT` and
+ :c:macro:`Py_TPFLAGS_MANAGED_WEAKREF` instead.
.. versionchanged:: 3.12
@@ -494,7 +514,7 @@ The following flags can be used with :c:member:`PyMemberDef.flags`:
Can only be used as part of :c:member:`Py_tp_members `
:c:type:`slot ` when creating a class using negative
- :c:member:`~PyTypeDef.basicsize`.
+ :c:member:`~PyType_Spec.basicsize`.
It is mandatory in that case.
This flag is only used in :c:type:`PyTypeSlot`.
@@ -509,19 +529,19 @@ The following flags can be used with :c:member:`PyMemberDef.flags`:
.. versionchanged:: 3.10
- The :const:`!RESTRICTED`, :const:`!READ_RESTRICTED` and
- :const:`!WRITE_RESTRICTED` macros available with
+ The :c:macro:`!RESTRICTED`, :c:macro:`!READ_RESTRICTED` and
+ :c:macro:`!WRITE_RESTRICTED` macros available with
``#include "structmember.h"`` are deprecated.
- :const:`!READ_RESTRICTED` and :const:`!RESTRICTED` are equivalent to
- :const:`Py_AUDIT_READ`; :const:`!WRITE_RESTRICTED` does nothing.
+ :c:macro:`!READ_RESTRICTED` and :c:macro:`!RESTRICTED` are equivalent to
+ :c:macro:`Py_AUDIT_READ`; :c:macro:`!WRITE_RESTRICTED` does nothing.
.. index::
single: READONLY
.. versionchanged:: 3.12
- The :const:`!READONLY` macro was renamed to :const:`Py_READONLY`.
- The :const:`!PY_AUDIT_READ` macro was renamed with the ``Py_`` prefix.
+ The :c:macro:`!READONLY` macro was renamed to :c:macro:`Py_READONLY`.
+ The :c:macro:`!PY_AUDIT_READ` macro was renamed with the ``Py_`` prefix.
The new names are now always available.
Previously, these required ``#include "structmember.h"``.
The header is still available and it provides the old names.
@@ -625,23 +645,23 @@ Defining Getters and Setters
Structure to define property-like access for a type. See also description of
the :c:member:`PyTypeObject.tp_getset` slot.
- .. c:member:: const char* PyGetSetDef.name
+ .. c:member:: const char* name
attribute name
- .. c:member:: getter PyGetSetDef.get
+ .. c:member:: getter get
C function to get the attribute.
- .. c:member:: setter PyGetSetDef.set
+ .. c:member:: setter set
Optional C function to set or delete the attribute, if omitted the attribute is readonly.
- .. c:member:: const char* PyGetSetDef.doc
+ .. c:member:: const char* doc
optional docstring
- .. c:member:: void* PyGetSetDef.closure
+ .. c:member:: void* closure
Optional function pointer, providing additional data for getter and setter.
diff --git a/Doc/c-api/sys.rst b/Doc/c-api/sys.rst
index 6fc8a3aff95686..a8a284e6e1cf95 100644
--- a/Doc/c-api/sys.rst
+++ b/Doc/c-api/sys.rst
@@ -8,8 +8,9 @@ Operating System Utilities
.. c:function:: PyObject* PyOS_FSPath(PyObject *path)
Return the file system representation for *path*. If the object is a
- :class:`str` or :class:`bytes` object, then its reference count is
- incremented. If the object implements the :class:`os.PathLike` interface,
+ :class:`str` or :class:`bytes` object, then a new
+ :term:`strong reference` is returned.
+ If the object implements the :class:`os.PathLike` interface,
then :meth:`~os.PathLike.__fspath__` is returned as long as it is a
:class:`str` or :class:`bytes` object. Otherwise :exc:`TypeError` is raised
and ``NULL`` is returned.
@@ -97,16 +98,16 @@ Operating System Utilities
.. c:function:: int PyOS_CheckStack()
Return true when the interpreter runs out of stack space. This is a reliable
- check, but is only available when :const:`USE_STACKCHECK` is defined (currently
+ check, but is only available when :c:macro:`USE_STACKCHECK` is defined (currently
on certain versions of Windows using the Microsoft Visual C++ compiler).
- :const:`USE_STACKCHECK` will be defined automatically; you should never
+ :c:macro:`USE_STACKCHECK` will be defined automatically; you should never
change the definition in your own code.
.. c:function:: PyOS_sighandler_t PyOS_getsig(int i)
Return the current signal handler for signal *i*. This is a thin wrapper around
- either :c:func:`sigaction` or :c:func:`signal`. Do not call those functions
+ either :c:func:`!sigaction` or :c:func:`!signal`. Do not call those functions
directly! :c:type:`PyOS_sighandler_t` is a typedef alias for :c:expr:`void
(\*)(int)`.
@@ -114,7 +115,7 @@ Operating System Utilities
.. c:function:: PyOS_sighandler_t PyOS_setsig(int i, PyOS_sighandler_t h)
Set the signal handler for signal *i* to be *h*; return the old signal handler.
- This is a thin wrapper around either :c:func:`sigaction` or :c:func:`signal`. Do
+ This is a thin wrapper around either :c:func:`!sigaction` or :c:func:`!signal`. Do
not call those functions directly! :c:type:`PyOS_sighandler_t` is a typedef
alias for :c:expr:`void (\*)(int)`.
@@ -167,7 +168,7 @@ Operating System Utilities
.. versionchanged:: 3.8
The function now uses the UTF-8 encoding on Windows if
- :c:member:`PyConfig.legacy_windows_fs_encoding` is zero;
+ :c:member:`PyPreConfig.legacy_windows_fs_encoding` is zero;
.. c:function:: char* Py_EncodeLocale(const wchar_t *text, size_t *error_pos)
@@ -209,7 +210,7 @@ Operating System Utilities
.. versionchanged:: 3.8
The function now uses the UTF-8 encoding on Windows if
- :c:member:`PyConfig.legacy_windows_fs_encoding` is zero.
+ :c:member:`PyPreConfig.legacy_windows_fs_encoding` is zero.
.. _systemfunctions:
@@ -414,7 +415,7 @@ Process Control
This function should only be invoked when a condition is detected that would
make it dangerous to continue using the Python interpreter; e.g., when the
object administration appears to be corrupted. On Unix, the standard C library
- function :c:func:`abort` is called which will attempt to produce a :file:`core`
+ 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
diff --git a/Doc/c-api/tuple.rst b/Doc/c-api/tuple.rst
index ac62058676eeeb..9bc3dab0c9c12c 100644
--- a/Doc/c-api/tuple.rst
+++ b/Doc/c-api/tuple.rst
@@ -111,6 +111,8 @@ Tuple Objects
raises :exc:`MemoryError` or :exc:`SystemError`.
+.. _struct-sequence-objects:
+
Struct Sequence Objects
-----------------------
@@ -142,39 +144,39 @@ type.
Contains the meta information of a struct sequence type to create.
- +-------------------+------------------------------+--------------------------------------+
- | Field | C Type | Meaning |
- +===================+==============================+======================================+
- | ``name`` | ``const char *`` | name of the struct sequence type |
- +-------------------+------------------------------+--------------------------------------+
- | ``doc`` | ``const char *`` | pointer to docstring for the type |
- | | | or ``NULL`` to omit |
- +-------------------+------------------------------+--------------------------------------+
- | ``fields`` | ``PyStructSequence_Field *`` | pointer to ``NULL``-terminated array |
- | | | with field names of the new type |
- +-------------------+------------------------------+--------------------------------------+
- | ``n_in_sequence`` | ``int`` | number of fields visible to the |
- | | | Python side (if used as tuple) |
- +-------------------+------------------------------+--------------------------------------+
+ .. c:member:: const char *name
+
+ Name of the struct sequence type.
+
+ .. c:member:: const char *doc
+
+ Pointer to docstring for the type or ``NULL`` to omit.
+
+ .. c:member:: PyStructSequence_Field *fields
+
+ Pointer to ``NULL``-terminated array with field names of the new type.
+
+ .. c:member:: int n_in_sequence
+
+ Number of fields visible to the Python side (if used as tuple).
.. 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:expr:`PyObject*`. The index in the
- :attr:`fields` array of the :c:type:`PyStructSequence_Desc` determines which
+ :c:member:`~PyStructSequence_Desc.fields` array of
+ the :c:type:`PyStructSequence_Desc` determines which
field of the struct sequence is described.
- +-----------+------------------+-----------------------------------------+
- | Field | C Type | Meaning |
- +===========+==================+=========================================+
- | ``name`` | ``const char *`` | name for the field or ``NULL`` to end |
- | | | the list of named fields, set to |
- | | | :c:data:`PyStructSequence_UnnamedField` |
- | | | to leave unnamed |
- +-----------+------------------+-----------------------------------------+
- | ``doc`` | ``const char *`` | field docstring or ``NULL`` to omit |
- +-----------+------------------+-----------------------------------------+
+ .. c:member:: const char *name
+
+ Name for the field or ``NULL`` to end the list of named fields,
+ set to :c:data:`PyStructSequence_UnnamedField` to leave unnamed.
+
+ .. c:member:: const char *doc
+
+ Field docstring or ``NULL`` to omit.
.. c:var:: const char * const PyStructSequence_UnnamedField
diff --git a/Doc/c-api/type.rst b/Doc/c-api/type.rst
index fb38935e003336..0f58326f6c06b7 100644
--- a/Doc/c-api/type.rst
+++ b/Doc/c-api/type.rst
@@ -42,7 +42,7 @@ Type Objects
Return the :c:member:`~PyTypeObject.tp_flags` member of *type*. This function is primarily
meant for use with ``Py_LIMITED_API``; the individual flag bits are
guaranteed to be stable across Python releases, but access to
- :c:member:`~PyTypeObject.tp_flags` itself is not part of the limited API.
+ :c:member:`~PyTypeObject.tp_flags` itself is not part of the :ref:`limited API `.
.. versionadded:: 3.2
@@ -50,6 +50,23 @@ Type Objects
The return type is now ``unsigned long`` rather than ``long``.
+.. c:function:: PyObject* PyType_GetDict(PyTypeObject* type)
+
+ Return the type object's internal namespace, which is otherwise only
+ exposed via a read-only proxy (``cls.__dict__``). This is a
+ replacement for accessing :c:member:`~PyTypeObject.tp_dict` directly.
+ The returned dictionary must be treated as read-only.
+
+ This function is meant for specific embedding and language-binding cases,
+ where direct access to the dict is necessary and indirect access
+ (e.g. via the proxy or :c:func:`PyObject_GetAttr`) isn't adequate.
+
+ Extension modules should continue to use ``tp_dict``,
+ directly or indirectly, when setting up their own types.
+
+ .. versionadded:: 3.12
+
+
.. c:function:: void PyType_Modified(PyTypeObject *type)
Invalidate the internal lookup cache for the type and all of its
@@ -86,7 +103,7 @@ Type Objects
:c:func:`PyType_AddWatcher` will be called whenever
:c:func:`PyType_Modified` reports a change to *type*. (The callback may be
called only once for a series of consecutive modifications to *type*, if
- :c:func:`PyType_Lookup` is not called on *type* between the modifications;
+ :c:func:`!_PyType_Lookup` is not called on *type* between the modifications;
this is an implementation detail and subject to change.)
An extension should never call ``PyType_Watch`` with a *watcher_id* that was
@@ -115,7 +132,7 @@ Type Objects
.. c:function:: int PyType_IS_GC(PyTypeObject *o)
Return true if the type object includes support for the cycle detector; this
- tests the type flag :const:`Py_TPFLAGS_HAVE_GC`.
+ tests the type flag :c:macro:`Py_TPFLAGS_HAVE_GC`.
.. c:function:: int PyType_IsSubtype(PyTypeObject *a, PyTypeObject *b)
@@ -148,10 +165,10 @@ Type Objects
.. note::
If some of the base classes implements the GC protocol and the provided
- type does not include the :const:`Py_TPFLAGS_HAVE_GC` in its flags, then
+ type does not include the :c:macro:`Py_TPFLAGS_HAVE_GC` in its flags, then
the GC protocol will be automatically implemented from its parents. On
the contrary, if the type being created does include
- :const:`Py_TPFLAGS_HAVE_GC` in its flags then it **must** implement the
+ :c:macro:`Py_TPFLAGS_HAVE_GC` in its flags then it **must** implement the
GC protocol itself by at least implementing the
:c:member:`~PyTypeObject.tp_traverse` handle.
@@ -198,7 +215,7 @@ Type Objects
``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.
- See :c:func:`PyType_GetModuleByDef` for cases when ``PyCMethod`` cannot
+ See :c:func:`PyType_GetModuleByDef` for cases when :c:type:`!PyCMethod` cannot
be used.
.. versionadded:: 3.9
@@ -251,14 +268,14 @@ The following functions and structs are used to create
.. c:function:: PyObject* PyType_FromMetaclass(PyTypeObject *metaclass, PyObject *module, PyType_Spec *spec, PyObject *bases)
Create and return a :ref:`heap type ` from the *spec*
- (see :const:`Py_TPFLAGS_HEAPTYPE`).
+ (see :c:macro:`Py_TPFLAGS_HEAPTYPE`).
The metaclass *metaclass* is used to construct the resulting type object.
When *metaclass* is ``NULL``, the metaclass is derived from *bases*
(or *Py_tp_base[s]* slots if *bases* is ``NULL``, see below).
Metaclasses that override :c:member:`~PyTypeObject.tp_new` are not
- supported.
+ supported, except if ``tp_new`` is ``NULL``.
(For backwards compatibility, other ``PyType_From*`` functions allow
such metaclasses. They ignore ``tp_new``, which may result in incomplete
initialization. This is deprecated and in Python 3.14+ such metaclasses will
@@ -349,6 +366,15 @@ The following functions and structs are used to create
:c:member:`~PyTypeObject.tp_new` is deprecated and in Python 3.14+ it
will be no longer allowed.
+.. raw:: html
+
+
+
+
+
+
+
+
.. c:type:: PyType_Spec
Structure defining a type's behavior.
@@ -394,7 +420,7 @@ The following functions and structs are used to create
- The requested :c:member:`PyType_Spec.basicsize` is zero,
suggesting that the subclass does not access the instance's memory
directly.
- - With the :const:`Py_TPFLAGS_ITEMS_AT_END` flag.
+ - With the :c:macro:`Py_TPFLAGS_ITEMS_AT_END` flag.
.. c:member:: unsigned int flags
@@ -410,12 +436,18 @@ The following functions and structs are used to create
Each slot ID should be specified at most once.
+.. raw:: html
+
+
+
+
+
.. c:type:: PyType_Slot
Structure defining optional functionality of a type, containing a slot ID
and a value pointer.
- .. c:member:: int PyType_Slot.slot
+ .. c:member:: int slot
A slot ID.
@@ -439,16 +471,16 @@ The following functions and structs are used to create
* :c:member:`~PyTypeObject.tp_weaklist`
* :c:member:`~PyTypeObject.tp_vectorcall`
* :c:member:`~PyTypeObject.tp_weaklistoffset`
- (use :const:`Py_TPFLAGS_MANAGED_WEAKREF` instead)
+ (use :c:macro:`Py_TPFLAGS_MANAGED_WEAKREF` instead)
* :c:member:`~PyTypeObject.tp_dictoffset`
- (use :const:`Py_TPFLAGS_MANAGED_DICT` instead)
+ (use :c:macro:`Py_TPFLAGS_MANAGED_DICT` instead)
* :c:member:`~PyTypeObject.tp_vectorcall_offset`
(see :ref:`PyMemberDef `)
Setting :c:data:`Py_tp_bases` or :c:data:`Py_tp_base` may be
problematic on some platforms.
To avoid issues, use the *bases* argument of
- :py:func:`PyType_FromSpecWithBases` instead.
+ :c:func:`PyType_FromSpecWithBases` instead.
.. versionchanged:: 3.9
@@ -457,9 +489,9 @@ The following functions and structs are used to create
.. versionchanged:: 3.11
:c:member:`~PyBufferProcs.bf_getbuffer` and
:c:member:`~PyBufferProcs.bf_releasebuffer` are now available
- under the limited API.
+ under the :ref:`limited API `.
- .. c:member:: void *PyType_Slot.pfunc
+ .. c:member:: void *pfunc
The desired value of the slot. In most cases, this is a pointer
to a function.
diff --git a/Doc/c-api/typehints.rst b/Doc/c-api/typehints.rst
index 4c1957a2a1dbca..98fe68737deb81 100644
--- a/Doc/c-api/typehints.rst
+++ b/Doc/c-api/typehints.rst
@@ -35,7 +35,7 @@ two types exist -- :ref:`GenericAlias ` and
...
}
- .. seealso:: The data model method :meth:`__class_getitem__`.
+ .. seealso:: The data model method :meth:`~object.__class_getitem__`.
.. versionadded:: 3.9
diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst
index 0584989233de3f..cd037b4de882e1 100644
--- a/Doc/c-api/typeobj.rst
+++ b/Doc/c-api/typeobj.rst
@@ -147,7 +147,7 @@ Quick Reference
+------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+
| :c:member:`~PyTypeObject.tp_vectorcall` | :c:type:`vectorcallfunc` | | | | | |
+------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+
- | [:c:member:`~PyTypeObject.tp_watched`] | char | | | | | |
+ | [:c:member:`~PyTypeObject.tp_watched`] | unsigned char | | | | | |
+------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+
.. [#slots]
@@ -163,9 +163,9 @@ Quick Reference
.. [#cols] Columns:
- **"O"**: set on :c:type:`PyBaseObject_Type`
+ **"O"**: set on :c:data:`PyBaseObject_Type`
- **"T"**: set on :c:type:`PyType_Type`
+ **"T"**: set on :c:data:`PyType_Type`
**"D"**: default (if slot is set to ``NULL``)
@@ -485,17 +485,17 @@ PyObject Slots
--------------
The type object structure extends the :c:type:`PyVarObject` structure. The
-:attr:`ob_size` field is used for dynamic types (created by :func:`type_new`,
+:c:member:`~PyVarObject.ob_size` field is used for dynamic types (created by :c:func:`!type_new`,
usually called from a class statement). Note that :c:data:`PyType_Type` (the
metatype) initializes :c:member:`~PyTypeObject.tp_itemsize`, which means that its instances (i.e.
-type objects) *must* have the :attr:`ob_size` field.
+type objects) *must* have the :c:member:`~PyVarObject.ob_size` field.
.. c:member:: Py_ssize_t PyObject.ob_refcnt
This is the type object's reference count, initialized to ``1`` by the
``PyObject_HEAD_INIT`` macro. Note that for :ref:`statically allocated type
- objects `, the type's instances (objects whose :attr:`ob_type`
+ objects `, the type's instances (objects whose :c:member:`~PyObject.ob_type`
points back to the type) do *not* count as references. But for
:ref:`dynamically allocated type objects `, the instances *do*
count as references.
@@ -519,8 +519,8 @@ type objects) *must* have the :attr:`ob_size` field.
Foo_Type.ob_type = &PyType_Type;
This should be done before any instances of the type are created.
- :c:func:`PyType_Ready` checks if :attr:`ob_type` is ``NULL``, and if so,
- initializes it to the :attr:`ob_type` field of the base class.
+ :c:func:`PyType_Ready` checks if :c:member:`~PyObject.ob_type` is ``NULL``, and if so,
+ initializes it to the :c:member:`~PyObject.ob_type` field of the base class.
:c:func:`PyType_Ready` will not change this field if it is non-zero.
**Inheritance:**
@@ -569,8 +569,8 @@ PyTypeObject Slots
Each slot has a section describing inheritance. If :c:func:`PyType_Ready`
may set a value when the field is set to ``NULL`` then there will also be
-a "Default" section. (Note that many fields set on :c:type:`PyBaseObject_Type`
-and :c:type:`PyType_Type` effectively act as defaults.)
+a "Default" section. (Note that many fields set on :c:data:`PyBaseObject_Type`
+and :c:data:`PyType_Type` effectively act as defaults.)
.. c:member:: const char* PyTypeObject.tp_name
@@ -579,7 +579,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
name, followed by a dot, followed by the type name; for built-in types, it
should be just the type name. If the module is a submodule of a package, the
full package name is part of the full module name. For example, a type named
- :class:`T` defined in module :mod:`M` in subpackage :mod:`Q` in package :mod:`P`
+ :class:`!T` defined in module :mod:`!M` in subpackage :mod:`!Q` in package :mod:`!P`
should have the :c:member:`~PyTypeObject.tp_name` initializer ``"P.Q.M.T"``.
For :ref:`dynamically allocated type objects `,
@@ -619,20 +619,20 @@ and :c:type:`PyType_Type` effectively act as defaults.)
instances have the same size, given in :c:member:`~PyTypeObject.tp_basicsize`.
For a type with variable-length instances, the instances must have an
- :attr:`ob_size` field, and the instance size is :c:member:`~PyTypeObject.tp_basicsize` plus N
+ :c:member:`~PyVarObject.ob_size` field, and the instance size is :c:member:`~PyTypeObject.tp_basicsize` plus N
times :c:member:`~PyTypeObject.tp_itemsize`, where N is the "length" of the object. The value of
- N is typically stored in the instance's :attr:`ob_size` field. There are
- exceptions: for example, ints use a negative :attr:`ob_size` to indicate a
+ N is typically stored in the instance's :c:member:`~PyVarObject.ob_size` field. There are
+ exceptions: for example, ints use a negative :c:member:`~PyVarObject.ob_size` to indicate a
negative number, and N is ``abs(ob_size)`` there. Also, the presence of an
- :attr:`ob_size` field in the instance layout doesn't mean that the instance
+ :c:member:`~PyVarObject.ob_size` field in the instance layout doesn't mean that the instance
structure is variable-length (for example, the structure for the list type has
- fixed-length instances, yet those instances have a meaningful :attr:`ob_size`
+ fixed-length instances, yet those instances have a meaningful :c:member:`~PyVarObject.ob_size`
field).
The basic size includes the fields in the instance declared by the macro
:c:macro:`PyObject_HEAD` or :c:macro:`PyObject_VAR_HEAD` (whichever is used to
- declare the instance struct) and this in turn includes the :attr:`_ob_prev` and
- :attr:`_ob_next` fields if they are present. This means that the only correct
+ declare the instance struct) and this in turn includes the :c:member:`~PyObject._ob_prev` and
+ :c:member:`~PyObject._ob_next` fields if they are present. This means that the only correct
way to get an initializer for the :c:member:`~PyTypeObject.tp_basicsize` is to use the
``sizeof`` operator on the struct used to declare the instance layout.
The basic size does not include the GC header size.
@@ -669,15 +669,15 @@ and :c:type:`PyType_Type` effectively act as defaults.)
memory buffers owned by the instance (using the freeing function corresponding
to the allocation function used to allocate the buffer), and call the type's
:c:member:`~PyTypeObject.tp_free` function. If the type is not subtypable
- (doesn't have the :const:`Py_TPFLAGS_BASETYPE` flag bit set), it is
+ (doesn't have the :c:macro:`Py_TPFLAGS_BASETYPE` flag bit set), it is
permissible to call the object deallocator directly instead of via
:c:member:`~PyTypeObject.tp_free`. The object deallocator should be the one used to allocate the
instance; this is normally :c:func:`PyObject_Del` if the instance was allocated
- using :c:func:`PyObject_New` or :c:func:`PyObject_VarNew`, or
+ using :c:macro:`PyObject_New` or :c:macro:`PyObject_NewVar`, or
:c:func:`PyObject_GC_Del` if the instance was allocated using
- :c:func:`PyObject_GC_New` or :c:func:`PyObject_GC_NewVar`.
+ :c:macro:`PyObject_GC_New` or :c:macro:`PyObject_GC_NewVar`.
- If the type supports garbage collection (has the :const:`Py_TPFLAGS_HAVE_GC`
+ If the type supports garbage collection (has the :c:macro:`Py_TPFLAGS_HAVE_GC`
flag bit set), the destructor should call :c:func:`PyObject_GC_UnTrack`
before clearing any member fields.
@@ -689,8 +689,9 @@ and :c:type:`PyType_Type` effectively act as defaults.)
Py_TYPE(self)->tp_free((PyObject *)self);
}
- Finally, if the type is heap allocated (:const:`Py_TPFLAGS_HEAPTYPE`), the
- deallocator should decrement the reference count for its type object after
+ Finally, if the type is heap allocated (:c:macro:`Py_TPFLAGS_HEAPTYPE`), the
+ deallocator should release the owned reference to its type object
+ (via :c:func:`Py_DECREF`) after
calling the type deallocator. In order to avoid dangling pointers, the
recommended way to achieve this is:
@@ -716,12 +717,12 @@ 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 :c:macro:`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 :c:macro:`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
@@ -740,15 +741,15 @@ and :c:type:`PyType_Type` effectively act as defaults.)
Before version 3.12, it was not recommended for
:ref:`mutable heap types ` to implement the vectorcall
protocol.
- When a user sets :attr:`~type.__call__` in Python code, only *tp_call* is
+ When a user sets :attr:`~object.__call__` in Python code, only *tp_call* is
updated, likely making it inconsistent with the vectorcall function.
Since 3.12, setting ``__call__`` will disable vectorcall optimization
- by clearing the :const:`Py_TPFLAGS_HAVE_VECTORCALL` flag.
+ by clearing the :c:macro:`Py_TPFLAGS_HAVE_VECTORCALL` flag.
**Inheritance:**
This field is always inherited.
- However, the :const:`Py_TPFLAGS_HAVE_VECTORCALL` flag is not
+ However, the :c:macro:`Py_TPFLAGS_HAVE_VECTORCALL` flag is not
always inherited. If it's not set, then the subclass won't use
:ref:`vectorcall `, except when
:c:func:`PyVectorcall_Call` is explicitly called.
@@ -764,7 +765,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
**Inheritance:**
- Group: :attr:`tp_getattr`, :attr:`tp_getattro`
+ Group: :c:member:`~PyTypeObject.tp_getattr`, :c:member:`~PyTypeObject.tp_getattro`
This field is inherited by subtypes together with :c:member:`~PyTypeObject.tp_getattro`: a subtype
inherits both :c:member:`~PyTypeObject.tp_getattr` and :c:member:`~PyTypeObject.tp_getattro` from its base type when
@@ -781,7 +782,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
**Inheritance:**
- Group: :attr:`tp_setattr`, :attr:`tp_setattro`
+ Group: :c:member:`~PyTypeObject.tp_setattr`, :c:member:`~PyTypeObject.tp_setattro`
This field is inherited by subtypes together with :c:member:`~PyTypeObject.tp_setattro`: a subtype
inherits both :c:member:`~PyTypeObject.tp_setattr` and :c:member:`~PyTypeObject.tp_setattro` from its base type when
@@ -883,7 +884,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
normal return value; when an error occurs during the computation of the hash
value, the function should set an exception and return ``-1``.
- When this field is not set (*and* :attr:`tp_richcompare` is not set),
+ When this field is not set (*and* :c:member:`~PyTypeObject.tp_richcompare` is not set),
an attempt to take the hash of the object raises :exc:`TypeError`.
This is the same as setting it to :c:func:`PyObject_HashNotImplemented`.
@@ -897,7 +898,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
**Inheritance:**
- Group: :attr:`tp_hash`, :attr:`tp_richcompare`
+ Group: :c:member:`~PyTypeObject.tp_hash`, :c:member:`~PyTypeObject.tp_richcompare`
This field is inherited by subtypes together with
:c:member:`~PyTypeObject.tp_richcompare`: a subtype inherits both of
@@ -956,7 +957,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
**Inheritance:**
- Group: :attr:`tp_getattr`, :attr:`tp_getattro`
+ Group: :c:member:`~PyTypeObject.tp_getattr`, :c:member:`~PyTypeObject.tp_getattro`
This field is inherited by subtypes together with :c:member:`~PyTypeObject.tp_getattr`: a subtype
inherits both :c:member:`~PyTypeObject.tp_getattr` and :c:member:`~PyTypeObject.tp_getattro` from its base type when
@@ -964,7 +965,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
**Default:**
- :c:type:`PyBaseObject_Type` uses :c:func:`PyObject_GenericGetAttr`.
+ :c:data:`PyBaseObject_Type` uses :c:func:`PyObject_GenericGetAttr`.
.. c:member:: setattrofunc PyTypeObject.tp_setattro
@@ -982,7 +983,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
**Inheritance:**
- Group: :attr:`tp_setattr`, :attr:`tp_setattro`
+ Group: :c:member:`~PyTypeObject.tp_setattr`, :c:member:`~PyTypeObject.tp_setattro`
This field is inherited by subtypes together with :c:member:`~PyTypeObject.tp_setattr`: a subtype
inherits both :c:member:`~PyTypeObject.tp_setattr` and :c:member:`~PyTypeObject.tp_setattro` from its base type when
@@ -990,7 +991,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
**Default:**
- :c:type:`PyBaseObject_Type` uses :c:func:`PyObject_GenericSetAttr`.
+ :c:data:`PyBaseObject_Type` uses :c:func:`PyObject_GenericSetAttr`.
.. c:member:: PyBufferProcs* PyTypeObject.tp_as_buffer
@@ -1022,30 +1023,32 @@ and :c:type:`PyType_Type` effectively act as defaults.)
this flag bit. The flag bits that pertain to extension structures are strictly
inherited if the extension structure is inherited, i.e. the base type's value of
the flag bit is copied into the subtype together with a pointer to the extension
- structure. The :const:`Py_TPFLAGS_HAVE_GC` flag bit is inherited together with
+ structure. The :c:macro:`Py_TPFLAGS_HAVE_GC` flag bit is inherited together with
the :c:member:`~PyTypeObject.tp_traverse` and :c:member:`~PyTypeObject.tp_clear` fields, i.e. if the
- :const:`Py_TPFLAGS_HAVE_GC` flag bit is clear in the subtype and the
+ :c:macro:`Py_TPFLAGS_HAVE_GC` flag bit is clear in the subtype and the
:c:member:`~PyTypeObject.tp_traverse` and :c:member:`~PyTypeObject.tp_clear` fields in the subtype exist and have
``NULL`` values.
.. XXX are most flag bits *really* inherited individually?
**Default:**
- :c:type:`PyBaseObject_Type` uses
+ :c:data:`PyBaseObject_Type` uses
``Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE``.
**Bit Masks:**
+ .. c:namespace:: NULL
+
The following bit masks are currently defined; these can be ORed together using
the ``|`` operator to form the value of the :c:member:`~PyTypeObject.tp_flags` field. The macro
:c:func:`PyType_HasFeature` takes a type and a flags value, *tp* and *f*, and
checks whether ``tp->tp_flags & f`` is non-zero.
- .. data:: Py_TPFLAGS_HEAPTYPE
+ .. c:macro:: Py_TPFLAGS_HEAPTYPE
This bit is set when the type object itself is allocated on the heap, for
example, types created dynamically using :c:func:`PyType_FromSpec`. In this
- case, the :attr:`ob_type` field of its instances is considered a reference to
+ case, the :c:member:`~PyObject.ob_type` field of its instances is considered a reference to
the type, and the type object is INCREF'ed when a new instance is created, and
DECREF'ed when an instance is destroyed (this does not apply to instances of
subtypes; only the type referenced by the instance's ob_type gets INCREF'ed or
@@ -1056,7 +1059,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
???
- .. data:: Py_TPFLAGS_BASETYPE
+ .. c:macro:: Py_TPFLAGS_BASETYPE
This bit is set when the type can be used as the base type of another type. If
this bit is clear, the type cannot be subtyped (similar to a "final" class in
@@ -1067,7 +1070,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
???
- .. data:: Py_TPFLAGS_READY
+ .. c:macro:: Py_TPFLAGS_READY
This bit is set when the type object has been fully initialized by
:c:func:`PyType_Ready`.
@@ -1077,7 +1080,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
???
- .. data:: Py_TPFLAGS_READYING
+ .. c:macro:: Py_TPFLAGS_READYING
This bit is set while :c:func:`PyType_Ready` is in the process of initializing
the type object.
@@ -1087,10 +1090,10 @@ and :c:type:`PyType_Type` effectively act as defaults.)
???
- .. data:: Py_TPFLAGS_HAVE_GC
+ .. c:macro:: Py_TPFLAGS_HAVE_GC
This bit is set when the object supports garbage collection. If this bit
- is set, instances must be created using :c:func:`PyObject_GC_New` and
+ is set, instances must be created using :c:macro:`PyObject_GC_New` and
destroyed using :c:func:`PyObject_GC_Del`. More information in section
:ref:`supporting-cycle-detection`. This bit also implies that the
GC-related fields :c:member:`~PyTypeObject.tp_traverse` and :c:member:`~PyTypeObject.tp_clear` are present in
@@ -1098,28 +1101,28 @@ and :c:type:`PyType_Type` effectively act as defaults.)
**Inheritance:**
- Group: :const:`Py_TPFLAGS_HAVE_GC`, :attr:`tp_traverse`, :attr:`tp_clear`
+ Group: :c:macro:`Py_TPFLAGS_HAVE_GC`, :c:member:`~PyTypeObject.tp_traverse`, :c:member:`~PyTypeObject.tp_clear`
- The :const:`Py_TPFLAGS_HAVE_GC` flag bit is inherited
- together with the :attr:`tp_traverse` and :attr:`tp_clear`
- fields, i.e. if the :const:`Py_TPFLAGS_HAVE_GC` flag bit is
- clear in the subtype and the :attr:`tp_traverse` and
- :attr:`tp_clear` fields in the subtype exist and have ``NULL``
+ The :c:macro:`Py_TPFLAGS_HAVE_GC` flag bit is inherited
+ together with the :c:member:`~PyTypeObject.tp_traverse` and :c:member:`~PyTypeObject.tp_clear`
+ fields, i.e. if the :c:macro:`Py_TPFLAGS_HAVE_GC` flag bit is
+ clear in the subtype and the :c:member:`~PyTypeObject.tp_traverse` and
+ :c:member:`~PyTypeObject.tp_clear` fields in the subtype exist and have ``NULL``
values.
- .. data:: Py_TPFLAGS_DEFAULT
+ .. c:macro:: Py_TPFLAGS_DEFAULT
This is a bitmask of all the bits that pertain to the existence of certain
fields in the type object and its extension structures. Currently, it includes
- the following bits: :const:`Py_TPFLAGS_HAVE_STACKLESS_EXTENSION`.
+ the following bits: :c:macro:`Py_TPFLAGS_HAVE_STACKLESS_EXTENSION`.
**Inheritance:**
???
- .. data:: Py_TPFLAGS_METHOD_DESCRIPTOR
+ .. c:macro:: Py_TPFLAGS_METHOD_DESCRIPTOR
This bit indicates that objects behave like unbound methods.
@@ -1140,17 +1143,17 @@ and :c:type:`PyType_Type` effectively act as defaults.)
**Inheritance:**
This flag is never inherited by types without the
- :const:`Py_TPFLAGS_IMMUTABLETYPE` flag set. For extension types, it is
+ :c:macro:`Py_TPFLAGS_IMMUTABLETYPE` flag set. For extension types, it is
inherited whenever :c:member:`~PyTypeObject.tp_descr_get` is inherited.
- .. data:: Py_TPFLAGS_MANAGED_DICT
+ .. c:macro:: Py_TPFLAGS_MANAGED_DICT
- This bit indicates that instances of the class have a ``__dict__``
- attribute, and that the space for the dictionary is managed by the VM.
+ This bit indicates that instances of the class have a ``__dict__``
+ attribute, and that the space for the dictionary is managed by the VM.
- If this flag is set, :const:`Py_TPFLAGS_HAVE_GC` should also be set.
+ If this flag is set, :c:macro:`Py_TPFLAGS_HAVE_GC` should also be set.
- .. versionadded:: 3.12
+ .. versionadded:: 3.12
**Inheritance:**
@@ -1158,12 +1161,12 @@ and :c:type:`PyType_Type` effectively act as defaults.)
:c:member:`~PyTypeObject.tp_dictoffset` field is set in a superclass.
- .. data:: Py_TPFLAGS_MANAGED_WEAKREF
+ .. c:macro:: Py_TPFLAGS_MANAGED_WEAKREF
- This bit indicates that instances of the class should be weakly
- referenceable.
+ This bit indicates that instances of the class should be weakly
+ referenceable.
- .. versionadded:: 3.12
+ .. versionadded:: 3.12
**Inheritance:**
@@ -1171,14 +1174,14 @@ and :c:type:`PyType_Type` effectively act as defaults.)
:c:member:`~PyTypeObject.tp_weaklistoffset` field is set in a superclass.
- .. data:: Py_TPFLAGS_ITEMS_AT_END
+ .. c:macro:: Py_TPFLAGS_ITEMS_AT_END
Only usable with variable-size types, i.e. ones with non-zero
- :c:member:`~PyObject.tp_itemsize`.
+ :c:member:`~PyTypeObject.tp_itemsize`.
Indicates that the variable-sized portion of an instance of this type is
at the end of the instance's memory area, at an offset of
- :c:expr:`Py_TYPE(obj)->tp_basicsize` (which may be different in each
+ ``Py_TYPE(obj)->tp_basicsize`` (which may be different in each
subclass).
When setting this flag, be sure that all superclasses either
@@ -1194,14 +1197,14 @@ and :c:type:`PyType_Type` effectively act as defaults.)
.. XXX Document more flags here?
- .. data:: Py_TPFLAGS_LONG_SUBCLASS
- .. data:: Py_TPFLAGS_LIST_SUBCLASS
- .. data:: Py_TPFLAGS_TUPLE_SUBCLASS
- .. data:: Py_TPFLAGS_BYTES_SUBCLASS
- .. data:: Py_TPFLAGS_UNICODE_SUBCLASS
- .. data:: Py_TPFLAGS_DICT_SUBCLASS
- .. data:: Py_TPFLAGS_BASE_EXC_SUBCLASS
- .. data:: Py_TPFLAGS_TYPE_SUBCLASS
+ .. c:macro:: Py_TPFLAGS_LONG_SUBCLASS
+ .. c:macro:: Py_TPFLAGS_LIST_SUBCLASS
+ .. c:macro:: Py_TPFLAGS_TUPLE_SUBCLASS
+ .. c:macro:: Py_TPFLAGS_BYTES_SUBCLASS
+ .. c:macro:: Py_TPFLAGS_UNICODE_SUBCLASS
+ .. c:macro:: Py_TPFLAGS_DICT_SUBCLASS
+ .. c:macro:: Py_TPFLAGS_BASE_EXC_SUBCLASS
+ .. c:macro:: Py_TPFLAGS_TYPE_SUBCLASS
These flags are used by functions such as
:c:func:`PyLong_Check` to quickly determine if a type is a subclass
@@ -1212,7 +1215,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
will behave differently depending on what kind of check is used.
- .. data:: Py_TPFLAGS_HAVE_FINALIZE
+ .. c:macro:: Py_TPFLAGS_HAVE_FINALIZE
This bit is set when the :c:member:`~PyTypeObject.tp_finalize` slot is present in the
type structure.
@@ -1225,7 +1228,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
type structure.
- .. data:: Py_TPFLAGS_HAVE_VECTORCALL
+ .. c:macro:: Py_TPFLAGS_HAVE_VECTORCALL
This bit is set when the class implements
the :ref:`vectorcall protocol `.
@@ -1245,7 +1248,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
This flag can now be inherited by mutable classes.
- .. data:: Py_TPFLAGS_IMMUTABLETYPE
+ .. c:macro:: Py_TPFLAGS_IMMUTABLETYPE
This bit is set for type objects that are immutable: type attributes cannot be set nor deleted.
@@ -1258,7 +1261,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
.. versionadded:: 3.10
- .. data:: Py_TPFLAGS_DISALLOW_INSTANTIATION
+ .. c:macro:: Py_TPFLAGS_DISALLOW_INSTANTIATION
Disallow creating instances of the type: set
:c:member:`~PyTypeObject.tp_new` to NULL and don't create the ``__new__``
@@ -1289,7 +1292,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
.. versionadded:: 3.10
- .. data:: Py_TPFLAGS_MAPPING
+ .. c:macro:: Py_TPFLAGS_MAPPING
This bit indicates that instances of the class may match mapping patterns
when used as the subject of a :keyword:`match` block. It is automatically
@@ -1298,20 +1301,20 @@ and :c:type:`PyType_Type` effectively act as defaults.)
.. note::
- :const:`Py_TPFLAGS_MAPPING` and :const:`Py_TPFLAGS_SEQUENCE` are
+ :c:macro:`Py_TPFLAGS_MAPPING` and :c:macro:`Py_TPFLAGS_SEQUENCE` are
mutually exclusive; it is an error to enable both flags simultaneously.
**Inheritance:**
This flag is inherited by types that do not already set
- :const:`Py_TPFLAGS_SEQUENCE`.
+ :c:macro:`Py_TPFLAGS_SEQUENCE`.
.. seealso:: :pep:`634` -- Structural Pattern Matching: Specification
.. versionadded:: 3.10
- .. data:: Py_TPFLAGS_SEQUENCE
+ .. c:macro:: Py_TPFLAGS_SEQUENCE
This bit indicates that instances of the class may match sequence patterns
when used as the subject of a :keyword:`match` block. It is automatically
@@ -1320,20 +1323,20 @@ and :c:type:`PyType_Type` effectively act as defaults.)
.. note::
- :const:`Py_TPFLAGS_MAPPING` and :const:`Py_TPFLAGS_SEQUENCE` are
+ :c:macro:`Py_TPFLAGS_MAPPING` and :c:macro:`Py_TPFLAGS_SEQUENCE` are
mutually exclusive; it is an error to enable both flags simultaneously.
**Inheritance:**
This flag is inherited by types that do not already set
- :const:`Py_TPFLAGS_MAPPING`.
+ :c:macro:`Py_TPFLAGS_MAPPING`.
.. seealso:: :pep:`634` -- Structural Pattern Matching: Specification
.. versionadded:: 3.10
- .. data:: Py_TPFLAGS_VALID_VERSION_TAG
+ .. c:macro:: Py_TPFLAGS_VALID_VERSION_TAG
Internal. Do not set or unset this flag.
To indicate that a class has changed call :c:func:`PyType_Modified`
@@ -1357,7 +1360,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
.. c:member:: traverseproc PyTypeObject.tp_traverse
An optional pointer to a traversal function for the garbage collector. This is
- only used if the :const:`Py_TPFLAGS_HAVE_GC` flag bit is set. The signature is::
+ only used if the :c:macro:`Py_TPFLAGS_HAVE_GC` flag bit is set. The signature is::
int tp_traverse(PyObject *self, visitproc visit, void *arg);
@@ -1367,8 +1370,8 @@ 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 that the instance owns. For example, this is function :c:func:`local_traverse` from the
- :mod:`_thread` extension module::
+ objects that the instance owns. For example, this is function :c:func:`!local_traverse` from the
+ :mod:`!_thread` extension module::
static int
local_traverse(localobject *self, visitproc visit, void *arg)
@@ -1419,10 +1422,10 @@ and :c:type:`PyType_Type` effectively act as defaults.)
**Inheritance:**
- Group: :const:`Py_TPFLAGS_HAVE_GC`, :attr:`tp_traverse`, :attr:`tp_clear`
+ Group: :c:macro:`Py_TPFLAGS_HAVE_GC`, :c:member:`~PyTypeObject.tp_traverse`, :c:member:`~PyTypeObject.tp_clear`
This field is inherited by subtypes together with :c:member:`~PyTypeObject.tp_clear` and the
- :const:`Py_TPFLAGS_HAVE_GC` flag bit: the flag bit, :c:member:`~PyTypeObject.tp_traverse`, and
+ :c:macro:`Py_TPFLAGS_HAVE_GC` flag bit: the flag bit, :c:member:`~PyTypeObject.tp_traverse`, and
:c:member:`~PyTypeObject.tp_clear` are all inherited from the base type if they are all zero in
the subtype.
@@ -1430,7 +1433,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
.. c:member:: inquiry PyTypeObject.tp_clear
An optional pointer to a clear function for the garbage collector. This is only
- used if the :const:`Py_TPFLAGS_HAVE_GC` flag bit is set. The signature is::
+ used if the :c:macro:`Py_TPFLAGS_HAVE_GC` flag bit is set. The signature is::
int tp_clear(PyObject *);
@@ -1459,9 +1462,10 @@ and :c:type:`PyType_Type` effectively act as defaults.)
}
The :c:func:`Py_CLEAR` macro should be used, because clearing references is
- delicate: the reference to the contained object must not be decremented until
+ delicate: the reference to the contained object must not be released
+ (via :c:func:`Py_DECREF`) until
after the pointer to the contained object is set to ``NULL``. This is because
- decrementing the reference count may cause the contained object to become trash,
+ releasing the reference may cause the contained object to become trash,
triggering a chain of reclamation activity that may include invoking arbitrary
Python code (due to finalizers, or weakref callbacks, associated with the
contained object). If it's possible for such code to reference *self* again,
@@ -1486,10 +1490,10 @@ and :c:type:`PyType_Type` effectively act as defaults.)
**Inheritance:**
- Group: :const:`Py_TPFLAGS_HAVE_GC`, :attr:`tp_traverse`, :attr:`tp_clear`
+ Group: :c:macro:`Py_TPFLAGS_HAVE_GC`, :c:member:`~PyTypeObject.tp_traverse`, :c:member:`~PyTypeObject.tp_clear`
This field is inherited by subtypes together with :c:member:`~PyTypeObject.tp_traverse` and the
- :const:`Py_TPFLAGS_HAVE_GC` flag bit: the flag bit, :c:member:`~PyTypeObject.tp_traverse`, and
+ :c:macro:`Py_TPFLAGS_HAVE_GC` flag bit: the flag bit, :c:member:`~PyTypeObject.tp_traverse`, and
:c:member:`~PyTypeObject.tp_clear` are all inherited from the base type if they are all zero in
the subtype.
@@ -1511,21 +1515,23 @@ and :c:type:`PyType_Type` effectively act as defaults.)
The following constants are defined to be used as the third argument for
:c:member:`~PyTypeObject.tp_richcompare` and for :c:func:`PyObject_RichCompare`:
- +----------------+------------+
- | Constant | Comparison |
- +================+============+
- | :const:`Py_LT` | ``<`` |
- +----------------+------------+
- | :const:`Py_LE` | ``<=`` |
- +----------------+------------+
- | :const:`Py_EQ` | ``==`` |
- +----------------+------------+
- | :const:`Py_NE` | ``!=`` |
- +----------------+------------+
- | :const:`Py_GT` | ``>`` |
- +----------------+------------+
- | :const:`Py_GE` | ``>=`` |
- +----------------+------------+
+ .. c:namespace:: NULL
+
+ +--------------------+------------+
+ | Constant | Comparison |
+ +====================+============+
+ | .. c:macro:: Py_LT | ``<`` |
+ +--------------------+------------+
+ | .. c:macro:: Py_LE | ``<=`` |
+ +--------------------+------------+
+ | .. c:macro:: Py_EQ | ``==`` |
+ +--------------------+------------+
+ | .. c:macro:: Py_NE | ``!=`` |
+ +--------------------+------------+
+ | .. c:macro:: Py_GT | ``>`` |
+ +--------------------+------------+
+ | .. c:macro:: Py_GE | ``>=`` |
+ +--------------------+------------+
The following macro is defined to ease writing rich comparison functions:
@@ -1537,7 +1543,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
they may be C ints or floats). The third argument specifies the requested
operation, as for :c:func:`PyObject_RichCompare`.
- The return value's reference count is properly incremented.
+ The returned value is a new :term:`strong reference`.
On error, sets an exception and returns ``NULL`` from the function.
@@ -1545,7 +1551,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
**Inheritance:**
- Group: :attr:`tp_hash`, :attr:`tp_richcompare`
+ Group: :c:member:`~PyTypeObject.tp_hash`, :c:member:`~PyTypeObject.tp_richcompare`
This field is inherited by subtypes together with :c:member:`~PyTypeObject.tp_hash`:
a subtype inherits :c:member:`~PyTypeObject.tp_richcompare` and :c:member:`~PyTypeObject.tp_hash` when
@@ -1554,16 +1560,16 @@ and :c:type:`PyType_Type` effectively act as defaults.)
**Default:**
- :c:type:`PyBaseObject_Type` provides a :attr:`tp_richcompare`
+ :c:data:`PyBaseObject_Type` provides a :c:member:`~PyTypeObject.tp_richcompare`
implementation, which may be inherited. However, if only
- :attr:`tp_hash` is defined, not even the inherited function is used
+ :c:member:`~PyTypeObject.tp_hash` is defined, not even the inherited function is used
and instances of the type will not be able to participate in any
comparisons.
.. c:member:: Py_ssize_t PyTypeObject.tp_weaklistoffset
- While this field is still supported, :const:`Py_TPFLAGS_MANAGED_WEAKREF`
+ While this field is still supported, :c:macro:`Py_TPFLAGS_MANAGED_WEAKREF`
should be used instead, if at all possible.
If the instances of this type are weakly referenceable, this field is greater
@@ -1576,7 +1582,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
Do not confuse this field with :c:member:`~PyTypeObject.tp_weaklist`; that is the list head for
weak references to the type object itself.
- It is an error to set both the :const:`Py_TPFLAGS_MANAGED_WEAKREF` bit and
+ It is an error to set both the :c:macro:`Py_TPFLAGS_MANAGED_WEAKREF` bit and
:c:member:`~PyTypeObject.tp_weaklist`.
**Inheritance:**
@@ -1588,7 +1594,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
**Default:**
- If the :const:`Py_TPFLAGS_MANAGED_WEAKREF` bit is set in the
+ If the :c:macro:`Py_TPFLAGS_MANAGED_WEAKREF` bit is set in the
:c:member:`~PyTypeObject.tp_dict` field, then
:c:member:`~PyTypeObject.tp_weaklistoffset` will be set to a negative value,
to indicate that it is unsafe to use this field.
@@ -1691,7 +1697,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
to a pointer, are valid C99 address constants.
However, the unary '&' operator applied to a non-static variable
- like :c:func:`PyBaseObject_Type` is not required to produce an address
+ like :c:data:`PyBaseObject_Type` is not required to produce an address
constant. Compilers may support this (gcc does), MSVC does not.
Both compilers are strictly standard conforming in this particular
behavior.
@@ -1717,7 +1723,19 @@ and :c:type:`PyType_Type` effectively act as defaults.)
called; it may also be initialized to a dictionary containing initial attributes
for the type. Once :c:func:`PyType_Ready` has initialized the type, extra
attributes for the type may be added to this dictionary only if they don't
- correspond to overloaded operations (like :meth:`__add__`).
+ correspond to overloaded operations (like :meth:`~object.__add__`). Once
+ initialization for the type has finished, this field should be
+ treated as read-only.
+
+ Some types may not store their dictionary in this slot.
+ Use :c:func:`PyType_GetDict` to retreive the dictionary for an arbitrary
+ type.
+
+ .. versionchanged:: 3.12
+
+ Internals detail: For static builtin types, this is always ``NULL``.
+ Instead, the dict for such types is stored on ``PyInterpreterState``.
+ Use :c:func:`PyType_GetDict` to get the dict for an arbitrary type.
**Inheritance:**
@@ -1770,7 +1788,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
.. c:member:: Py_ssize_t PyTypeObject.tp_dictoffset
- While this field is still supported, :const:`Py_TPFLAGS_MANAGED_DICT` should be
+ While this field is still supported, :c:macro:`Py_TPFLAGS_MANAGED_DICT` should be
used instead, if at all possible.
If the instances of this type have a dictionary containing instance variables,
@@ -1789,7 +1807,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
dictionary, so it is may be more efficient to call :c:func:`PyObject_GetAttr`
when accessing an attribute on the object.
- It is an error to set both the :const:`Py_TPFLAGS_MANAGED_WEAKREF` bit and
+ It is an error to set both the :c:macro:`Py_TPFLAGS_MANAGED_WEAKREF` bit and
:c:member:`~PyTypeObject.tp_dictoffset`.
**Inheritance:**
@@ -1797,14 +1815,14 @@ and :c:type:`PyType_Type` effectively act as defaults.)
This field is inherited by subtypes. A subtype should not override this offset;
doing so could be unsafe, if C code tries to access the dictionary at the
previous offset.
- To properly support inheritance, use :const:`Py_TPFLAGS_MANAGED_DICT`.
+ To properly support inheritance, use :c:macro:`Py_TPFLAGS_MANAGED_DICT`.
**Default:**
This slot has no default. For :ref:`static types `, if the
- field is ``NULL`` then no :attr:`__dict__` gets created for instances.
+ field is ``NULL`` then no :attr:`~object.__dict__` gets created for instances.
- If the :const:`Py_TPFLAGS_MANAGED_DICT` bit is set in the
+ If the :c:macro:`Py_TPFLAGS_MANAGED_DICT` bit is set in the
:c:member:`~PyTypeObject.tp_dict` field, then
:c:member:`~PyTypeObject.tp_dictoffset` will be set to ``-1``, to indicate
that it is unsafe to use this field.
@@ -1814,10 +1832,10 @@ and :c:type:`PyType_Type` effectively act as defaults.)
An optional pointer to an instance initialization function.
- This function corresponds to the :meth:`__init__` method of classes. Like
- :meth:`__init__`, it is possible to create an instance without calling
- :meth:`__init__`, and it is possible to reinitialize an instance by calling its
- :meth:`__init__` method again.
+ This function corresponds to the :meth:`~object.__init__` method of classes. Like
+ :meth:`!__init__`, it is possible to create an instance without calling
+ :meth:`!__init__`, and it is possible to reinitialize an instance by calling its
+ :meth:`!__init__` method again.
The function signature is::
@@ -1825,7 +1843,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
The self argument is the instance to be initialized; the *args* and *kwds*
arguments represent positional and keyword arguments of the call to
- :meth:`__init__`.
+ :meth:`~object.__init__`.
The :c:member:`~PyTypeObject.tp_init` function, if not ``NULL``, is called when an instance is
created normally by calling its type, after the type's :c:member:`~PyTypeObject.tp_new` function
@@ -1864,7 +1882,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
:c:func:`PyType_GenericAlloc`, to force a standard heap
allocation strategy.
- For static subtypes, :c:type:`PyBaseObject_Type` uses
+ For static subtypes, :c:data:`PyBaseObject_Type` uses
:c:func:`PyType_GenericAlloc`. That is the recommended value
for all statically defined types.
@@ -1891,7 +1909,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
in :c:member:`~PyTypeObject.tp_new`, while for mutable types, most initialization should be
deferred to :c:member:`~PyTypeObject.tp_init`.
- Set the :const:`Py_TPFLAGS_DISALLOW_INSTANTIATION` flag to disallow creating
+ Set the :c:macro:`Py_TPFLAGS_DISALLOW_INSTANTIATION` flag to disallow creating
instances of the type in Python.
**Inheritance:**
@@ -1925,9 +1943,9 @@ and :c:type:`PyType_Type` effectively act as defaults.)
In dynamic subtypes, this field is set to a deallocator suitable to
match :c:func:`PyType_GenericAlloc` and the value of the
- :const:`Py_TPFLAGS_HAVE_GC` flag bit.
+ :c:macro:`Py_TPFLAGS_HAVE_GC` flag bit.
- For static subtypes, :c:type:`PyBaseObject_Type` uses PyObject_Del.
+ For static subtypes, :c:data:`PyBaseObject_Type` uses :c:func:`PyObject_Del`.
.. c:member:: inquiry PyTypeObject.tp_is_gc
@@ -1936,7 +1954,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
The garbage collector needs to know whether a particular object is collectible
or not. Normally, it is sufficient to look at the object's type's
- :c:member:`~PyTypeObject.tp_flags` field, and check the :const:`Py_TPFLAGS_HAVE_GC` flag bit. But
+ :c:member:`~PyTypeObject.tp_flags` field, and check the :c:macro:`Py_TPFLAGS_HAVE_GC` flag bit. But
some types have a mixture of statically and dynamically allocated instances, and
the statically allocated instances are not collectible. Such types should
define this function; it should return ``1`` for a collectible instance, and
@@ -1955,7 +1973,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
**Default:**
This slot has no default. If this field is ``NULL``,
- :const:`Py_TPFLAGS_HAVE_GC` is used as the functional equivalent.
+ :c:macro:`Py_TPFLAGS_HAVE_GC` is used as the functional equivalent.
.. c:member:: PyObject* PyTypeObject.tp_bases
@@ -2102,7 +2120,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
.. versionchanged:: 3.8
Before version 3.8 it was necessary to set the
- :const:`Py_TPFLAGS_HAVE_FINALIZE` flags bit in order for this field to be
+ :c:macro:`Py_TPFLAGS_HAVE_FINALIZE` flags bit in order for this field to be
used. This is no longer required.
.. seealso:: "Safe object finalization" (:pep:`442`)
@@ -2114,7 +2132,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
In other words, it is used to implement
:ref:`vectorcall ` for ``type.__call__``.
If ``tp_vectorcall`` is ``NULL``, the default call implementation
- using :attr:`__new__` and :attr:`__init__` is used.
+ using :meth:`~object.__new__` and :meth:`~object.__init__` is used.
**Inheritance:**
@@ -2123,7 +2141,7 @@ 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)
-.. c:member:: char PyTypeObject.tp_watched
+.. c:member:: unsigned char PyTypeObject.tp_watched
Internal. Do not use.
@@ -2150,7 +2168,7 @@ This results in types that are limited relative to types defined in Python:
include any subinterpreter-specific state.
Also, since :c:type:`PyTypeObject` is only part of the :ref:`Limited API
-` as an opaque struct, any extension modules using static types must be
+` as an opaque struct, any extension modules using static types must be
compiled for a specific Python minor version.
@@ -2161,7 +2179,7 @@ Heap Types
An alternative to :ref:`static types ` is *heap-allocated types*,
or *heap types* for short, which correspond closely to classes created by
-Python's ``class`` statement. Heap types have the :const:`Py_TPFLAGS_HEAPTYPE`
+Python's ``class`` statement. Heap types have the :c:macro:`Py_TPFLAGS_HEAPTYPE`
flag set.
This is done by filling a :c:type:`PyType_Spec` structure and calling
@@ -2241,8 +2259,8 @@ Number Object Structures
.. note::
- The :c:data:`nb_reserved` field should always be ``NULL``. It
- was previously called :c:data:`nb_long`, and was renamed in
+ The :c:member:`~PyNumberMethods.nb_reserved` field should always be ``NULL``. It
+ was previously called :c:member:`!nb_long`, and was renamed in
Python 3.0.1.
.. c:member:: binaryfunc PyNumberMethods.nb_add
@@ -2313,8 +2331,8 @@ Mapping Object Structures
.. c:member:: objobjargproc PyMappingMethods.mp_ass_subscript
This function is used by :c:func:`PyObject_SetItem`,
- :c:func:`PyObject_DelItem`, :c:func:`PyObject_SetSlice` and
- :c:func:`PyObject_DelSlice`. It has the same signature as
+ :c:func:`PyObject_DelItem`, :c:func:`PySequence_SetSlice` and
+ :c:func:`PySequence_DelSlice`. It has the same signature as
:c:func:`!PyObject_SetItem`, but *v* can also be set to ``NULL`` to delete
an item. If this slot is ``NULL``, the object does not support item
assignment and deletion.
@@ -2360,9 +2378,9 @@ Sequence Object Structures
This slot must be filled for the :c:func:`PySequence_Check`
function to return ``1``, it can be ``NULL`` otherwise.
- Negative indexes are handled as follows: if the :attr:`sq_length` slot is
+ Negative indexes are handled as follows: if the :c:member:`~PySequenceMethods.sq_length` slot is
filled, it is called and the sequence length is used to compute a positive
- index which is passed to :attr:`sq_item`. If :attr:`sq_length` is ``NULL``,
+ index which is passed to :c:member:`~PySequenceMethods.sq_item`. If :c:member:`!sq_length` is ``NULL``,
the index is passed as is to the function.
.. c:member:: ssizeobjargproc PySequenceMethods.sq_ass_item
@@ -2425,7 +2443,7 @@ Buffer Object Structures
Except for point (3), an implementation of this function MUST take these
steps:
- (1) Check if the request can be met. If not, raise :c:data:`PyExc_BufferError`,
+ (1) Check if the request can be met. If not, raise :exc:`BufferError`,
set :c:expr:`view->obj` to ``NULL`` and return ``-1``.
(2) Fill in the requested fields.
@@ -2536,7 +2554,7 @@ Async Object Structures
PyObject *am_aiter(PyObject *self);
Must return an :term:`asynchronous iterator` object.
- See :meth:`__anext__` for details.
+ See :meth:`~object.__anext__` for details.
This slot may be set to ``NULL`` if an object does not implement
asynchronous iteration protocol.
@@ -2547,7 +2565,8 @@ Async Object Structures
PyObject *am_anext(PyObject *self);
- Must return an :term:`awaitable` object. See :meth:`__anext__` for details.
+ Must return an :term:`awaitable` object.
+ See :meth:`~object.__anext__` for details.
This slot may be set to ``NULL``.
.. c:member:: sendfunc PyAsyncMethods.am_send
@@ -2572,8 +2591,8 @@ Slot Type typedefs
The purpose of this function is to separate memory allocation from memory
initialization. It should return a pointer to a block of memory of adequate
length for the instance, suitably aligned, and initialized to zeros, but with
- :attr:`ob_refcnt` set to ``1`` and :attr:`ob_type` set to the type argument. If
- the type's :c:member:`~PyTypeObject.tp_itemsize` is non-zero, the object's :attr:`ob_size` field
+ :c:member:`~PyObject.ob_refcnt` set to ``1`` and :c:member:`~PyObject.ob_type` set to the type argument. If
+ the type's :c:member:`~PyTypeObject.tp_itemsize` is non-zero, the object's :c:member:`~PyVarObject.ob_size` field
should be initialized to *nitems* and the length of the allocated memory block
should be ``tp_basicsize + nitems*tp_itemsize``, rounded up to a multiple of
``sizeof(void*)``; otherwise, *nitems* is not used and the length of the block
@@ -2769,7 +2788,7 @@ A type that supports weakrefs, instance dicts, and hashing::
A str subclass that cannot be subclassed and cannot be called
to create instances (e.g. uses a separate factory func) using
-:c:data:`Py_TPFLAGS_DISALLOW_INSTANTIATION` flag::
+:c:macro:`Py_TPFLAGS_DISALLOW_INSTANTIATION` flag::
typedef struct {
PyUnicodeObject raw;
diff --git a/Doc/c-api/unicode.rst b/Doc/c-api/unicode.rst
index 6771f378bfbc31..c10c15111cd908 100644
--- a/Doc/c-api/unicode.rst
+++ b/Doc/c-api/unicode.rst
@@ -44,7 +44,7 @@ Python:
.. c:type:: Py_UNICODE
- This is a typedef of :c:expr:`wchar_t`, which is a 16-bit type or 32-bit type
+ This is a typedef of :c:type:`wchar_t`, which is a 16-bit type or 32-bit type
depending on the platform.
.. versionchanged:: 3.3
@@ -444,11 +444,11 @@ APIs:
+----------+-----------------------------------------------------+
| ``ll`` | :c:expr:`long long` or :c:expr:`unsigned long long` |
+----------+-----------------------------------------------------+
- | ``j`` | :c:expr:`intmax_t` or :c:expr:`uintmax_t` |
+ | ``j`` | :c:type:`intmax_t` or :c:type:`uintmax_t` |
+----------+-----------------------------------------------------+
- | ``z`` | :c:expr:`size_t` or :c:expr:`ssize_t` |
+ | ``z`` | :c:type:`size_t` or :c:type:`ssize_t` |
+----------+-----------------------------------------------------+
- | ``t`` | :c:expr:`ptrdiff_t` |
+ | ``t`` | :c:type:`ptrdiff_t` |
+----------+-----------------------------------------------------+
The length modifier ``l`` for following conversions ``s`` or ``V`` specify
@@ -527,7 +527,7 @@ APIs:
.. note::
The width formatter unit is number of characters rather than bytes.
- The precision formatter unit is number of bytes or :c:expr:`wchar_t`
+ The precision formatter unit is number of bytes or :c:type:`wchar_t`
items (if the length modifier ``l`` is used) for ``"%s"`` and
``"%V"`` (if the ``PyObject*`` argument is ``NULL``), and a number of
characters for ``"%A"``, ``"%U"``, ``"%S"``, ``"%R"`` and ``"%V"``
@@ -571,7 +571,7 @@ APIs:
Copy an instance of a Unicode subtype to a new true Unicode object if
necessary. If *obj* is already a true Unicode object (not a subtype),
- return the reference with incremented refcount.
+ return a new :term:`strong reference` to the object.
Objects other than Unicode or its subtypes will cause a :exc:`TypeError`.
@@ -608,7 +608,7 @@ APIs:
Py_ssize_t how_many)
Copy characters from one Unicode object into another. This function performs
- character conversion when necessary and falls back to :c:func:`memcpy` if
+ character conversion when necessary and falls back to :c:func:`!memcpy` if
possible. Returns ``-1`` and sets an exception on error, otherwise returns
the number of copied characters.
@@ -721,7 +721,7 @@ system.
.. c:function:: PyObject* PyUnicode_DecodeLocale(const char *str, const char *errors)
Similar to :c:func:`PyUnicode_DecodeLocaleAndSize`, but compute the string
- length using :c:func:`strlen`.
+ length using :c:func:`!strlen`.
.. versionadded:: 3.3
@@ -846,11 +846,11 @@ conversion function:
wchar_t Support
"""""""""""""""
-:c:expr:`wchar_t` support for platforms which support it:
+:c:type:`wchar_t` support for platforms which support it:
.. c:function:: PyObject* PyUnicode_FromWideChar(const wchar_t *w, Py_ssize_t size)
- Create a Unicode object from the :c:expr:`wchar_t` buffer *w* of the given *size*.
+ Create a Unicode object from the :c:type:`wchar_t` buffer *w* of the given *size*.
Passing ``-1`` as the *size* indicates that the function must itself compute the length,
using wcslen.
Return ``NULL`` on failure.
@@ -858,9 +858,9 @@ wchar_t Support
.. c:function:: Py_ssize_t PyUnicode_AsWideChar(PyObject *unicode, wchar_t *w, Py_ssize_t size)
- Copy the Unicode object contents into the :c:expr:`wchar_t` buffer *w*. At most
- *size* :c:expr:`wchar_t` characters are copied (excluding a possibly trailing
- null termination character). Return the number of :c:expr:`wchar_t` characters
+ Copy the Unicode object contents into the :c:type:`wchar_t` buffer *w*. At most
+ *size* :c:type:`wchar_t` characters are copied (excluding a possibly trailing
+ null termination character). Return the number of :c:type:`wchar_t` characters
copied or ``-1`` in case of an error. Note that the resulting :c:expr:`wchar_t*`
string may or may not be null-terminated. It is the responsibility of the caller
to make sure that the :c:expr:`wchar_t*` string is null-terminated in case this is
@@ -874,12 +874,12 @@ wchar_t Support
Convert the Unicode object to a wide character string. The output string
always ends with a null character. If *size* is not ``NULL``, write the number
of wide characters (excluding the trailing null termination character) into
- *\*size*. Note that the resulting :c:expr:`wchar_t` string might contain
+ *\*size*. Note that the resulting :c:type:`wchar_t` string might contain
null characters, which would cause the string to be truncated when used with
most C functions. If *size* is ``NULL`` and the :c:expr:`wchar_t*` string
contains null characters a :exc:`ValueError` is raised.
- Returns a buffer allocated by :c:func:`PyMem_New` (use
+ Returns a buffer allocated by :c:macro:`PyMem_New` (use
:c:func:`PyMem_Free` to free it) on success. On error, returns ``NULL``
and *\*size* is undefined. Raises a :exc:`MemoryError` if memory allocation
is failed.
@@ -992,7 +992,7 @@ These are the UTF-8 codec APIs:
The return type is now ``const char *`` rather of ``char *``.
.. versionchanged:: 3.10
- This function is a part of the :ref:`limited API `.
+ This function is a part of the :ref:`limited API `.
.. c:function:: const char* PyUnicode_AsUTF8(PyObject *unicode)
@@ -1212,9 +1212,9 @@ Character Map Codecs
This codec is special in that it can be used to implement many different codecs
(and this is in fact what was done to obtain most of the standard codecs
-included in the :mod:`encodings` package). The codec uses mappings to encode and
+included in the :mod:`!encodings` package). The codec uses mappings to encode and
decode characters. The mapping objects provided must support the
-:meth:`__getitem__` mapping interface; dictionaries and sequences work well.
+:meth:`~object.__getitem__` mapping interface; dictionaries and sequences work well.
These are the mapping codec APIs:
@@ -1257,7 +1257,7 @@ The following codec API is special in that maps Unicode to Unicode.
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
+ Mapping tables need only provide the :meth:`~object.__getitem__` interface; dictionaries
and sequences work well. Unmapped character ordinals (ones which cause a
:exc:`LookupError`) are left untouched and are copied as-is.
@@ -1299,7 +1299,7 @@ the user settings on the machine running the codec.
Encode the Unicode object using the specified code page and return a Python
bytes object. Return ``NULL`` if an exception was raised by the codec. Use
- :c:data:`CP_ACP` code page to get the MBCS encoder.
+ :c:macro:`!CP_ACP` code page to get the MBCS encoder.
.. versionadded:: 3.3
@@ -1418,11 +1418,11 @@ They all return ``NULL`` or ``-1`` if an exception occurs.
Rich compare two Unicode strings and return one of the following:
* ``NULL`` in case an exception was raised
- * :const:`Py_True` or :const:`Py_False` for successful comparisons
- * :const:`Py_NotImplemented` in case the type combination is unknown
+ * :c:data:`Py_True` or :c:data:`Py_False` for successful comparisons
+ * :c:data:`Py_NotImplemented` in case the type combination is unknown
- Possible values for *op* are :const:`Py_GT`, :const:`Py_GE`, :const:`Py_EQ`,
- :const:`Py_NE`, :const:`Py_LT`, and :const:`Py_LE`.
+ Possible values for *op* are :c:macro:`Py_GT`, :c:macro:`Py_GE`, :c:macro:`Py_EQ`,
+ :c:macro:`Py_NE`, :c:macro:`Py_LT`, and :c:macro:`Py_LE`.
.. c:function:: PyObject* PyUnicode_Format(PyObject *format, PyObject *args)
@@ -1445,11 +1445,11 @@ They all return ``NULL`` or ``-1`` if an exception occurs.
Intern the argument *\*string* in place. The argument must be the address of a
pointer variable pointing to a Python Unicode string object. If there is an
existing interned string that is the same as *\*string*, it sets *\*string* to
- it (decrementing the reference count of the old string object and incrementing
- the reference count of the interned string object), otherwise it leaves
- *\*string* alone and interns it (incrementing its reference count).
- (Clarification: even though there is a lot of talk about reference counts, think
- of this function as reference-count-neutral; you own the object after the call
+ it (releasing the reference to the old string object and creating a new
+ :term:`strong reference` to the interned string object), otherwise it leaves
+ *\*string* alone and interns it (creating a new :term:`strong reference`).
+ (Clarification: even though there is a lot of talk about references, think
+ of this function as reference-neutral; you own the object after the call
if and only if you owned it before the call.)
diff --git a/Doc/c-api/veryhigh.rst b/Doc/c-api/veryhigh.rst
index 513856d8a48d70..324518c035096b 100644
--- a/Doc/c-api/veryhigh.rst
+++ b/Doc/c-api/veryhigh.rst
@@ -12,12 +12,12 @@ file or a buffer, but they will not let you interact in a more detailed way with
the interpreter.
Several of these functions accept a start symbol from the grammar as a
-parameter. The available start symbols are :const:`Py_eval_input`,
-:const:`Py_file_input`, and :const:`Py_single_input`. These are described
+parameter. The available start symbols are :c:data:`Py_eval_input`,
+:c:data:`Py_file_input`, and :c:data:`Py_single_input`. These are described
following the functions which accept them as parameters.
Note also that several of these functions take :c:expr:`FILE*` parameters. One
-particular issue which needs to be handled carefully is that the :c:expr:`FILE`
+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:expr:`FILE*` parameters
@@ -167,6 +167,10 @@ the same library that the Python runtime is using.
event loops, as done in the :file:`Modules/_tkinter.c` in the
Python source code.
+ .. versionchanged:: 3.12
+ This function is only called from the
+ :ref:`main interpreter `.
+
.. c:var:: char* (*PyOS_ReadlineFunctionPointer)(FILE *, FILE *, const char *)
@@ -187,6 +191,10 @@ the same library that the Python runtime is using.
:c:func:`PyMem_RawRealloc`, instead of being allocated by
:c:func:`PyMem_Malloc` or :c:func:`PyMem_Realloc`.
+ .. versionchanged:: 3.12
+ This function is only called from the
+ :ref:`main interpreter `.
+
.. c:function:: PyObject* PyRun_String(const char *str, int start, PyObject *globals, PyObject *locals)
This is a simplified interface to :c:func:`PyRun_StringFlags` below, leaving
@@ -248,8 +256,8 @@ the same library that the Python runtime is using.
Parse and compile the Python source code in *str*, returning the resulting code
object. The start token is given by *start*; this can be used to constrain the
- code which can be compiled and should be :const:`Py_eval_input`,
- :const:`Py_file_input`, or :const:`Py_single_input`. The filename specified by
+ code which can be compiled and should be :c:data:`Py_eval_input`,
+ :c:data:`Py_file_input`, or :c:data:`Py_single_input`. The filename specified by
*filename* is used to construct the code object and may appear in tracebacks or
:exc:`SyntaxError` exception messages. This returns ``NULL`` if the code
cannot be parsed or compiled.
@@ -345,7 +353,7 @@ the same library that the Python runtime is using.
executed, it is passed as ``PyCompilerFlags *flags``. In this case, ``from
__future__ import`` can modify *flags*.
- Whenever ``PyCompilerFlags *flags`` is ``NULL``, :attr:`cf_flags` is treated as
+ Whenever ``PyCompilerFlags *flags`` is ``NULL``, :c:member:`~PyCompilerFlags.cf_flags` is treated as
equal to ``0``, and any modification due to ``from __future__ import`` is
discarded.
@@ -359,7 +367,7 @@ the same library that the Python runtime is using.
initialized to ``PY_MINOR_VERSION``.
The field is ignored by default, it is used if and only if
- ``PyCF_ONLY_AST`` flag is set in *cf_flags*.
+ ``PyCF_ONLY_AST`` flag is set in :c:member:`~PyCompilerFlags.cf_flags`.
.. versionchanged:: 3.8
Added *cf_feature_version* field.
diff --git a/Doc/c-api/weakref.rst b/Doc/c-api/weakref.rst
index f27ec4411b4a26..f46507608606b9 100644
--- a/Doc/c-api/weakref.rst
+++ b/Doc/c-api/weakref.rst
@@ -11,18 +11,18 @@ simple reference object, and the second acts as a proxy for the original object
as much as it can.
-.. c:function:: int PyWeakref_Check(ob)
+.. c:function:: int PyWeakref_Check(PyObject *ob)
Return true if *ob* is either a reference or proxy object. This function
always succeeds.
-.. c:function:: int PyWeakref_CheckRef(ob)
+.. c:function:: int PyWeakref_CheckRef(PyObject *ob)
Return true if *ob* is a reference object. This function always succeeds.
-.. c:function:: int PyWeakref_CheckProxy(ob)
+.. c:function:: int PyWeakref_CheckProxy(PyObject *ob)
Return true if *ob* is a proxy object. This function always succeeds.
@@ -54,7 +54,7 @@ as much as it can.
.. c:function:: PyObject* PyWeakref_GetObject(PyObject *ref)
Return the referenced object from a weak reference, *ref*. If the referent is
- no longer live, returns :const:`Py_None`.
+ no longer live, returns ``Py_None``.
.. note::
diff --git a/Doc/conf.py b/Doc/conf.py
index 485c0bdf84df2e..a8805bd4653a8a 100644
--- a/Doc/conf.py
+++ b/Doc/conf.py
@@ -77,12 +77,172 @@
exclude_patterns.append(venvdir + '/*')
nitpick_ignore = [
+ # Standard C functions
+ ('c:func', 'calloc'),
+ ('c:func', 'dlopen'),
+ ('c:func', 'exec'),
+ ('c:func', 'fcntl'),
+ ('c:func', 'fork'),
+ ('c:func', 'free'),
+ ('c:func', 'gmtime'),
+ ('c:func', 'localtime'),
+ ('c:func', 'main'),
+ ('c:func', 'malloc'),
+ ('c:func', 'printf'),
+ ('c:func', 'realloc'),
+ ('c:func', 'snprintf'),
+ ('c:func', 'sprintf'),
+ ('c:func', 'stat'),
+ ('c:func', 'system'),
+ ('c:func', 'time'),
+ ('c:func', 'vsnprintf'),
+ # Standard C types
+ ('c:type', 'FILE'),
+ ('c:type', 'int64_t'),
+ ('c:type', 'intmax_t'),
+ ('c:type', 'off_t'),
+ ('c:type', 'ptrdiff_t'),
+ ('c:type', 'siginfo_t'),
+ ('c:type', 'size_t'),
+ ('c:type', 'ssize_t'),
+ ('c:type', 'time_t'),
+ ('c:type', 'uint64_t'),
+ ('c:type', 'uintmax_t'),
+ ('c:type', 'uintptr_t'),
+ ('c:type', 'va_list'),
+ ('c:type', 'wchar_t'),
+ ('c:type', '__int64'),
+ ('c:type', 'unsigned __int64'),
+ # Standard C structures
+ ('c:struct', 'in6_addr'),
+ ('c:struct', 'in_addr'),
+ ('c:struct', 'stat'),
+ ('c:struct', 'statvfs'),
+ # Standard C macros
+ ('c:macro', 'LLONG_MAX'),
+ ('c:macro', 'LLONG_MIN'),
+ ('c:macro', 'LONG_MAX'),
+ ('c:macro', 'LONG_MIN'),
+ # Standard C variables
+ ('c:data', 'errno'),
+ # Standard environment variables
+ ('envvar', 'BROWSER'),
+ ('envvar', 'COLUMNS'),
+ ('envvar', 'COMSPEC'),
+ ('envvar', 'DISPLAY'),
+ ('envvar', 'HOME'),
+ ('envvar', 'HOMEDRIVE'),
+ ('envvar', 'HOMEPATH'),
+ ('envvar', 'IDLESTARTUP'),
+ ('envvar', 'LANG'),
+ ('envvar', 'LANGUAGE'),
+ ('envvar', 'LC_ALL'),
+ ('envvar', 'LC_CTYPE'),
+ ('envvar', 'LC_COLLATE'),
+ ('envvar', 'LC_MESSAGES'),
+ ('envvar', 'LC_MONETARY'),
+ ('envvar', 'LC_NUMERIC'),
+ ('envvar', 'LC_TIME'),
+ ('envvar', 'LINES'),
+ ('envvar', 'LOGNAME'),
+ ('envvar', 'PAGER'),
+ ('envvar', 'PATH'),
+ ('envvar', 'PATHEXT'),
+ ('envvar', 'SOURCE_DATE_EPOCH'),
+ ('envvar', 'TEMP'),
+ ('envvar', 'TERM'),
+ ('envvar', 'TMP'),
+ ('envvar', 'TMPDIR'),
+ ('envvar', 'TZ'),
+ ('envvar', 'USER'),
+ ('envvar', 'USERNAME'),
+ ('envvar', 'USERPROFILE'),
+]
+
+# Temporary undocumented names.
+# In future this list must be empty.
+nitpick_ignore += [
+ # C API: Standard Python exception classes
+ ('c:data', 'PyExc_ArithmeticError'),
+ ('c:data', 'PyExc_AssertionError'),
+ ('c:data', 'PyExc_AttributeError'),
+ ('c:data', 'PyExc_BaseException'),
+ ('c:data', 'PyExc_BlockingIOError'),
+ ('c:data', 'PyExc_BrokenPipeError'),
+ ('c:data', 'PyExc_BufferError'),
+ ('c:data', 'PyExc_ChildProcessError'),
+ ('c:data', 'PyExc_ConnectionAbortedError'),
+ ('c:data', 'PyExc_ConnectionError'),
+ ('c:data', 'PyExc_ConnectionRefusedError'),
+ ('c:data', 'PyExc_ConnectionResetError'),
+ ('c:data', 'PyExc_EOFError'),
+ ('c:data', 'PyExc_Exception'),
+ ('c:data', 'PyExc_FileExistsError'),
+ ('c:data', 'PyExc_FileNotFoundError'),
+ ('c:data', 'PyExc_FloatingPointError'),
+ ('c:data', 'PyExc_GeneratorExit'),
+ ('c:data', 'PyExc_ImportError'),
+ ('c:data', 'PyExc_IndentationError'),
+ ('c:data', 'PyExc_IndexError'),
+ ('c:data', 'PyExc_InterruptedError'),
+ ('c:data', 'PyExc_IsADirectoryError'),
+ ('c:data', 'PyExc_KeyboardInterrupt'),
+ ('c:data', 'PyExc_KeyError'),
+ ('c:data', 'PyExc_LookupError'),
+ ('c:data', 'PyExc_MemoryError'),
+ ('c:data', 'PyExc_ModuleNotFoundError'),
+ ('c:data', 'PyExc_NameError'),
+ ('c:data', 'PyExc_NotADirectoryError'),
+ ('c:data', 'PyExc_NotImplementedError'),
+ ('c:data', 'PyExc_OSError'),
+ ('c:data', 'PyExc_OverflowError'),
+ ('c:data', 'PyExc_PermissionError'),
+ ('c:data', 'PyExc_ProcessLookupError'),
+ ('c:data', 'PyExc_RecursionError'),
+ ('c:data', 'PyExc_ReferenceError'),
+ ('c:data', 'PyExc_RuntimeError'),
+ ('c:data', 'PyExc_StopAsyncIteration'),
+ ('c:data', 'PyExc_StopIteration'),
+ ('c:data', 'PyExc_SyntaxError'),
+ ('c:data', 'PyExc_SystemError'),
+ ('c:data', 'PyExc_SystemExit'),
+ ('c:data', 'PyExc_TabError'),
+ ('c:data', 'PyExc_TimeoutError'),
+ ('c:data', 'PyExc_TypeError'),
+ ('c:data', 'PyExc_UnboundLocalError'),
+ ('c:data', 'PyExc_UnicodeDecodeError'),
+ ('c:data', 'PyExc_UnicodeEncodeError'),
+ ('c:data', 'PyExc_UnicodeError'),
+ ('c:data', 'PyExc_UnicodeTranslateError'),
+ ('c:data', 'PyExc_ValueError'),
+ ('c:data', 'PyExc_ZeroDivisionError'),
+ # C API: Standard Python warning classes
+ ('c:data', 'PyExc_BytesWarning'),
+ ('c:data', 'PyExc_DeprecationWarning'),
+ ('c:data', 'PyExc_FutureWarning'),
+ ('c:data', 'PyExc_ImportWarning'),
+ ('c:data', 'PyExc_PendingDeprecationWarning'),
+ ('c:data', 'PyExc_ResourceWarning'),
+ ('c:data', 'PyExc_RuntimeWarning'),
+ ('c:data', 'PyExc_SyntaxWarning'),
+ ('c:data', 'PyExc_UnicodeWarning'),
+ ('c:data', 'PyExc_UserWarning'),
+ ('c:data', 'PyExc_Warning'),
# Do not error nit-picky mode builds when _SubParsersAction.add_parser cannot
# be resolved, as the method is currently undocumented. For context, see
# https://github.com/python/cpython/pull/103289.
('py:meth', '_SubParsersAction.add_parser'),
]
+# gh-106948: Copy standard C types declared in the "c:type" domain to the
+# "c:identifier" domain, since "c:function" markup looks for types in the
+# "c:identifier" domain. Use list() to not iterate on items which are being
+# added
+for role, name in list(nitpick_ignore):
+ if role == 'c:type':
+ nitpick_ignore.append(('c:identifier', name))
+del role, name
+
# Disable Docutils smartquotes for several translations
smartquotes_excludes = {
'languages': ['ja', 'fr', 'zh_TW', 'zh_CN'], 'builders': ['man', 'text'],
@@ -194,8 +354,6 @@
latex_documents = [
('c-api/index', 'c-api.tex',
'The Python/C API', _stdauthor, 'manual'),
- ('distributing/index', 'distributing.tex',
- 'Distributing Python Modules', _stdauthor, 'manual'),
('extending/index', 'extending.tex',
'Extending and Embedding Python', _stdauthor, 'manual'),
('installing/index', 'installing.tex',
diff --git a/Doc/constraints.txt b/Doc/constraints.txt
index 66c748eb092d83..54888eaab242ee 100644
--- a/Doc/constraints.txt
+++ b/Doc/constraints.txt
@@ -23,7 +23,3 @@ sphinxcontrib-serializinghtml<1.2
# Direct dependencies of Jinja2 (Jinja is a dependency of Sphinx, see above)
MarkupSafe<2.2
-
-# Direct dependencies of sphinx-lint
-polib<1.3
-regex<2024
diff --git a/Doc/contents.rst b/Doc/contents.rst
index 464f93bdf85f95..24ceacb0076b5e 100644
--- a/Doc/contents.rst
+++ b/Doc/contents.rst
@@ -11,7 +11,6 @@
library/index.rst
extending/index.rst
c-api/index.rst
- distributing/index.rst
installing/index.rst
howto/index.rst
faq/index.rst
@@ -21,10 +20,3 @@
bugs.rst
copyright.rst
license.rst
-
-.. to include legacy packaging docs in build
-
-.. toctree::
- :hidden:
-
- install/index.rst
diff --git a/Doc/data/python3.12.abi b/Doc/data/python3.12.abi
new file mode 100644
index 00000000000000..cdefda782b9c6f
--- /dev/null
+++ b/Doc/data/python3.12.abi
@@ -0,0 +1,26457 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/Doc/distributing/index.rst b/Doc/distributing/index.rst
index d237f8f082d87b..2430564b45d6d2 100644
--- a/Doc/distributing/index.rst
+++ b/Doc/distributing/index.rst
@@ -1,174 +1,19 @@
+:orphan:
+
+.. This page is retained solely for existing links to /distributing/index.html.
+ Direct readers to the PPUG instead.
+
.. _distributing-index:
###############################
Distributing Python Modules
###############################
-:Email: distutils-sig@python.org
-
-
-As a popular open source development project, Python has an active
-supporting community of contributors and users that also make their software
-available for other Python developers to use under open source license terms.
-
-This allows Python users to share and collaborate effectively, benefiting
-from the solutions others have already created to common (and sometimes
-even rare!) problems, as well as potentially contributing their own
-solutions to the common pool.
-
-This guide covers the distribution part of the process. For a guide to
-installing other Python projects, refer to the
-:ref:`installation guide `.
-
.. note::
- For corporate and other institutional users, be aware that many
- organisations have their own policies around using and contributing to
- open source software. Please take such policies into account when making
- use of the distribution and installation tools provided with Python.
-
-
-Key terms
-=========
-
-* the `Python Package Index `__ is a public
- repository of open source licensed packages made available for use by
- other Python users
-* the `Python Packaging Authority
- `__ are the group of
- developers and documentation authors responsible for the maintenance and
- evolution of the standard packaging tools and the associated metadata and
- file format standards. They maintain a variety of tools, documentation
- and issue trackers on `GitHub `__.
-* ``distutils`` is the original build and distribution system first added
- to the Python standard library in 1998. While direct use of ``distutils``
- is being phased out, it still laid the foundation for the current packaging
- and distribution infrastructure, and it not only remains part of the
- standard library, but its name lives on in other ways (such as the name
- of the mailing list used to coordinate Python packaging standards
- development).
-* `setuptools`_ is a (largely) drop-in replacement for ``distutils`` first
- published in 2004. Its most notable addition over the unmodified
- ``distutils`` tools was the ability to declare dependencies on other
- packages. It is currently recommended as a more regularly updated
- alternative to ``distutils`` that offers consistent support for more
- recent packaging standards across a wide range of Python versions.
-* `wheel`_ (in this context) is a project that adds the ``bdist_wheel``
- command to ``distutils``/`setuptools`_. This produces a cross platform
- binary packaging format (called "wheels" or "wheel files" and defined in
- :pep:`427`) that allows Python libraries, even those including binary
- extensions, to be installed on a system without needing to be built
- locally.
-
-.. _setuptools: https://setuptools.readthedocs.io/en/latest/
-.. _wheel: https://wheel.readthedocs.io/
-
-Open source licensing and collaboration
-=======================================
-
-In most parts of the world, software is automatically covered by copyright.
-This means that other developers require explicit permission to copy, use,
-modify and redistribute the software.
-
-Open source licensing is a way of explicitly granting such permission in a
-relatively consistent way, allowing developers to share and collaborate
-efficiently by making common solutions to various problems freely available.
-This leaves many developers free to spend more time focusing on the problems
-that are relatively unique to their specific situation.
-
-The distribution tools provided with Python are designed to make it
-reasonably straightforward for developers to make their own contributions
-back to that common pool of software if they choose to do so.
-
-The same distribution tools can also be used to distribute software within
-an organisation, regardless of whether that software is published as open
-source software or not.
-
-
-Installing the tools
-====================
-
-The standard library does not include build tools that support modern
-Python packaging standards, as the core development team has found that it
-is important to have standard tools that work consistently, even on older
-versions of Python.
-
-The currently recommended build and distribution tools can be installed
-by invoking the ``pip`` module at the command line::
-
- python -m pip install setuptools wheel twine
-
-.. note::
-
- For POSIX users (including macOS and Linux users), these instructions
- assume the use of a :term:`virtual environment`.
-
- For Windows users, these instructions assume that the option to
- adjust the system PATH environment variable was selected when installing
- Python.
-
-The Python Packaging User Guide includes more details on the `currently
-recommended tools`_.
-
-.. _currently recommended tools: https://packaging.python.org/guides/tool-recommendations/#packaging-tool-recommendations
-
-.. index::
- single: Python Package Index (PyPI)
- single: PyPI; (see Python Package Index (PyPI))
-
-.. _publishing-python-packages:
-
-Reading the Python Packaging User Guide
-=======================================
-
-The Python Packaging User Guide covers the various key steps and elements
-involved in creating and publishing a project:
-
-* `Project structure`_
-* `Building and packaging the project`_
-* `Uploading the project to the Python Package Index`_
-* `The .pypirc file`_
-
-.. _Project structure: https://packaging.python.org/tutorials/packaging-projects/#packaging-python-projects
-.. _Building and packaging the project: https://packaging.python.org/tutorials/packaging-projects/#creating-the-package-files
-.. _Uploading the project to the Python Package Index: https://packaging.python.org/tutorials/packaging-projects/#uploading-the-distribution-archives
-.. _The .pypirc file: https://packaging.python.org/specifications/pypirc/
-
-
-How do I...?
-============
-
-These are quick answers or links for some common tasks.
-
-... choose a name for my project?
----------------------------------
-
-This isn't an easy topic, but here are a few tips:
-
-* check the Python Package Index to see if the name is already in use
-* check popular hosting sites like GitHub, Bitbucket, etc to see if there
- is already a project with that name
-* check what comes up in a web search for the name you're considering
-* avoid particularly common words, especially ones with multiple meanings,
- as they can make it difficult for users to find your software when
- searching for it
-
-
-... create and distribute binary extensions?
---------------------------------------------
-
-This is actually quite a complex topic, with a variety of alternatives
-available depending on exactly what you're aiming to achieve. See the
-Python Packaging User Guide for more information and recommendations.
-
-.. seealso::
-
- `Python Packaging User Guide: Binary Extensions
- `__
-
-.. other topics:
+ Information and guidance on distributing Python modules and packages
+ has been moved to the `Python Packaging User Guide`_,
+ and the tutorial on `packaging Python projects`_.
- Once the Development & Deployment part of PPUG is fleshed out, some of
- those sections should be linked from new questions here (most notably,
- we should have a question about avoiding depending on PyPI that links to
- https://packaging.python.org/en/latest/mirrors/)
+ .. _Python Packaging User Guide: https://packaging.python.org/
+ .. _packaging Python projects: https://packaging.python.org/en/latest/tutorials/packaging-projects/
diff --git a/Doc/extending/building.rst b/Doc/extending/building.rst
index 880bb33ee56718..ddde567f6f3efa 100644
--- a/Doc/extending/building.rst
+++ b/Doc/extending/building.rst
@@ -45,6 +45,7 @@ See the *"Multiple modules in one library"* section in :pep:`489` for details.
.. highlight:: c
+.. _install-index:
.. _setuptools-index:
Building C and C++ Extensions with setuptools
diff --git a/Doc/extending/embedding.rst b/Doc/extending/embedding.rst
index e64db373344038..4c7c7ec98a6c95 100644
--- a/Doc/extending/embedding.rst
+++ b/Doc/extending/embedding.rst
@@ -250,7 +250,7 @@ following two statements before the call to :c:func:`Py_Initialize`::
PyImport_AppendInittab("emb", &PyInit_emb);
These two lines initialize the ``numargs`` variable, and make the
-:func:`emb.numargs` function accessible to the embedded Python interpreter.
+:func:`!emb.numargs` function accessible to the embedded Python interpreter.
With these extensions, the Python script can do things like
.. code-block:: python
diff --git a/Doc/extending/extending.rst b/Doc/extending/extending.rst
index d9bf4fd6c7ae0e..68f8e0c6674657 100644
--- a/Doc/extending/extending.rst
+++ b/Doc/extending/extending.rst
@@ -195,7 +195,7 @@ The choice of which exception to raise is entirely yours. There are predeclared
C objects corresponding to all built-in Python exceptions, such as
:c:data:`PyExc_ZeroDivisionError`, which you can use directly. Of course, you
should choose exceptions wisely --- don't use :c:data:`PyExc_TypeError` to mean
-that a file couldn't be opened (that should probably be :c:data:`PyExc_IOError`).
+that a file couldn't be opened (that should probably be :c:data:`PyExc_OSError`).
If something's wrong with the argument list, the :c:func:`PyArg_ParseTuple`
function usually raises :c:data:`PyExc_TypeError`. If you have an argument whose
value must be in a particular range or must satisfy other conditions,
@@ -206,7 +206,7 @@ usually declare a static object variable at the beginning of your file::
static PyObject *SpamError;
-and initialize it in your module's initialization function (:c:func:`PyInit_spam`)
+and initialize it in your module's initialization function (:c:func:`!PyInit_spam`)
with an exception object::
PyMODINIT_FUNC
@@ -230,22 +230,22 @@ with an exception object::
return m;
}
-Note that the Python name for the exception object is :exc:`spam.error`. The
+Note that the Python name for the exception object is :exc:`!spam.error`. The
:c:func:`PyErr_NewException` function may create a class with the base class
being :exc:`Exception` (unless another class is passed in instead of ``NULL``),
described in :ref:`bltin-exceptions`.
-Note also that the :c:data:`SpamError` variable retains a reference to the newly
+Note also that the :c:data:`!SpamError` variable retains a reference to the newly
created exception class; this is intentional! Since the exception could be
removed from the module by external code, an owned reference to the class is
-needed to ensure that it will not be discarded, causing :c:data:`SpamError` to
+needed to ensure that it will not be discarded, causing :c:data:`!SpamError` to
become a dangling pointer. Should it become a dangling pointer, C code which
raises the exception could cause a core dump or other unintended side effects.
-We discuss the use of ``PyMODINIT_FUNC`` as a function return type later in this
+We discuss the use of :c:macro:`PyMODINIT_FUNC` as a function return type later in this
sample.
-The :exc:`spam.error` exception can be raised in your extension module using a
+The :exc:`!spam.error` exception can be raised in your extension module using a
call to :c:func:`PyErr_SetString` as shown below::
static PyObject *
@@ -279,9 +279,9 @@ statement::
It returns ``NULL`` (the error indicator for functions returning object pointers)
if an error is detected in the argument list, relying on the exception set by
:c:func:`PyArg_ParseTuple`. Otherwise the string value of the argument has been
-copied to the local variable :c:data:`command`. This is a pointer assignment and
+copied to the local variable :c:data:`!command`. This is a pointer assignment and
you are not supposed to modify the string to which it points (so in Standard C,
-the variable :c:data:`command` should properly be declared as ``const char
+the variable :c:data:`!command` should properly be declared as ``const char
*command``).
The next statement is a call to the Unix function :c:func:`system`, passing it
@@ -289,7 +289,7 @@ the string we just got from :c:func:`PyArg_ParseTuple`::
sts = system(command);
-Our :func:`spam.system` function must return the value of :c:data:`sts` as a
+Our :func:`!spam.system` function must return the value of :c:data:`!sts` as a
Python object. This is done using the function :c:func:`PyLong_FromLong`. ::
return PyLong_FromLong(sts);
@@ -315,7 +315,7 @@ contexts, as we have seen.
The Module's Method Table and Initialization Function
=====================================================
-I promised to show how :c:func:`spam_system` is called from Python programs.
+I promised to show how :c:func:`!spam_system` is called from Python programs.
First, we need to list its name and address in a "method table"::
static PyMethodDef SpamMethods[] = {
@@ -335,7 +335,7 @@ When using only ``METH_VARARGS``, the function should expect the Python-level
parameters to be passed in as a tuple acceptable for parsing via
:c:func:`PyArg_ParseTuple`; more information on this function is provided below.
-The :const:`METH_KEYWORDS` bit may be set in the third field if keyword
+The :c:macro:`METH_KEYWORDS` bit may be set in the third field if keyword
arguments should be passed to the function. In this case, the C function should
accept a third ``PyObject *`` parameter which will be a dictionary of keywords.
Use :c:func:`PyArg_ParseTupleAndKeywords` to parse the arguments to such a
@@ -354,7 +354,7 @@ The method table must be referenced in the module definition structure::
This structure, in turn, must be passed to the interpreter in the module's
initialization function. The initialization function must be named
-:c:func:`PyInit_name`, where *name* is the name of the module, and should be the
+:c:func:`!PyInit_name`, where *name* is the name of the module, and should be the
only non-\ ``static`` item defined in the module file::
PyMODINIT_FUNC
@@ -363,12 +363,12 @@ only non-\ ``static`` item defined in the module file::
return PyModule_Create(&spammodule);
}
-Note that PyMODINIT_FUNC declares the function as ``PyObject *`` return type,
+Note that :c:macro:`PyMODINIT_FUNC` declares the function as ``PyObject *`` return type,
declares any special linkage declarations required by the platform, and for C++
declares the function as ``extern "C"``.
-When the Python program imports module :mod:`spam` for the first time,
-:c:func:`PyInit_spam` is called. (See below for comments about embedding Python.)
+When the Python program imports module :mod:`!spam` for the first time,
+:c:func:`!PyInit_spam` is called. (See below for comments about embedding Python.)
It calls :c:func:`PyModule_Create`, which returns a module object, and
inserts built-in function objects into the newly created module based upon the
table (an array of :c:type:`PyMethodDef` structures) found in the module definition.
@@ -378,7 +378,7 @@ certain errors, or return ``NULL`` if the module could not be initialized
satisfactorily. The init function must return the module object to its caller,
so that it then gets inserted into ``sys.modules``.
-When embedding Python, the :c:func:`PyInit_spam` function is not called
+When embedding Python, the :c:func:`!PyInit_spam` function is not called
automatically unless there's an entry in the :c:data:`PyImport_Inittab` table.
To add the module to the initialization table, use :c:func:`PyImport_AppendInittab`,
optionally followed by an import of the module::
@@ -527,7 +527,7 @@ be part of a module definition::
}
This function must be registered with the interpreter using the
-:const:`METH_VARARGS` flag; this is described in section :ref:`methodtable`. The
+:c:macro:`METH_VARARGS` flag; this is described in section :ref:`methodtable`. The
:c:func:`PyArg_ParseTuple` function and its arguments are documented in section
:ref:`parsetuple`.
@@ -1030,13 +1030,13 @@ Let's follow the control flow into :c:func:`PyList_SetItem`. The list owns
references to all its items, so when item 1 is replaced, it has to dispose of
the original item 1. Now let's suppose the original item 1 was an instance of a
user-defined class, and let's further suppose that the class defined a
-:meth:`__del__` method. If this class instance has a reference count of 1,
-disposing of it will call its :meth:`__del__` method.
+:meth:`!__del__` method. If this class instance has a reference count of 1,
+disposing of it will call its :meth:`!__del__` method.
-Since it is written in Python, the :meth:`__del__` method can execute arbitrary
+Since it is written in Python, the :meth:`!__del__` method can execute arbitrary
Python code. Could it perhaps do something to invalidate the reference to
-``item`` in :c:func:`bug`? You bet! Assuming that the list passed into
-:c:func:`bug` is accessible to the :meth:`__del__` method, it could execute a
+``item`` in :c:func:`!bug`? You bet! Assuming that the list passed into
+:c:func:`!bug` is accessible to the :meth:`!__del__` method, it could execute a
statement to the effect of ``del list[0]``, and assuming this was the last
reference to that object, it would free the memory associated with it, thereby
invalidating ``item``.
@@ -1057,7 +1057,7 @@ increment the reference count. The correct version of the function reads::
This is a true story. An older version of Python contained variants of this bug
and someone spent a considerable amount of time in a C debugger to figure out
-why his :meth:`__del__` methods would fail...
+why his :meth:`!__del__` methods would fail...
The second case of problems with a borrowed reference is a variant involving
threads. Normally, multiple threads in the Python interpreter can't get in each
@@ -1208,14 +1208,14 @@ file corresponding to the module provides a macro that takes care of importing
the module and retrieving its C API pointers; client modules only have to call
this macro before accessing the C API.
-The exporting module is a modification of the :mod:`spam` module from section
-:ref:`extending-simpleexample`. The function :func:`spam.system` does not call
+The exporting module is a modification of the :mod:`!spam` module from section
+:ref:`extending-simpleexample`. The function :func:`!spam.system` does not call
the C library function :c:func:`system` directly, but a function
-:c:func:`PySpam_System`, which would of course do something more complicated in
+:c:func:`!PySpam_System`, which would of course do something more complicated in
reality (such as adding "spam" to every command). This function
-:c:func:`PySpam_System` is also exported to other extension modules.
+:c:func:`!PySpam_System` is also exported to other extension modules.
-The function :c:func:`PySpam_System` is a plain C function, declared
+The function :c:func:`!PySpam_System` is a plain C function, declared
``static`` like everything else::
static int
@@ -1224,7 +1224,7 @@ The function :c:func:`PySpam_System` is a plain C function, declared
return system(command);
}
-The function :c:func:`spam_system` is modified in a trivial way::
+The function :c:func:`!spam_system` is modified in a trivial way::
static PyObject *
spam_system(PyObject *self, PyObject *args)
@@ -1278,7 +1278,7 @@ function must take care of initializing the C API pointer array::
}
Note that ``PySpam_API`` is declared ``static``; otherwise the pointer
-array would disappear when :func:`PyInit_spam` terminates!
+array would disappear when :c:func:`!PyInit_spam` terminates!
The bulk of the work is in the header file :file:`spammodule.h`, which looks
like this::
@@ -1332,8 +1332,8 @@ like this::
#endif /* !defined(Py_SPAMMODULE_H) */
All that a client module must do in order to have access to the function
-:c:func:`PySpam_System` is to call the function (or rather macro)
-:c:func:`import_spam` in its initialization function::
+:c:func:`!PySpam_System` is to call the function (or rather macro)
+:c:func:`!import_spam` in its initialization function::
PyMODINIT_FUNC
PyInit_client(void)
diff --git a/Doc/extending/newtypes.rst b/Doc/extending/newtypes.rst
index 6852a385f0c63c..9f166eb8a4c3ff 100644
--- a/Doc/extending/newtypes.rst
+++ b/Doc/extending/newtypes.rst
@@ -168,7 +168,7 @@ representation of the instance for which it is called. Here is a simple
example::
static PyObject *
- newdatatype_repr(newdatatypeobject * obj)
+ newdatatype_repr(newdatatypeobject *obj)
{
return PyUnicode_FromFormat("Repr-ified_newdatatype{{size:%d}}",
obj->obj_UnderlyingDatatypePtr->size);
@@ -188,7 +188,7 @@ used instead.
Here is a simple example::
static PyObject *
- newdatatype_str(newdatatypeobject * obj)
+ newdatatype_str(newdatatypeobject *obj)
{
return PyUnicode_FromFormat("Stringified_newdatatype{{size:%d}}",
obj->obj_UnderlyingDatatypePtr->size);
@@ -270,7 +270,7 @@ structure::
One entry should be defined for each method provided by the type; no entries are
needed for methods inherited from a base type. One additional entry is needed
at the end; it is a sentinel that marks the end of the array. The
-:attr:`ml_name` field of the sentinel must be ``NULL``.
+:c:member:`~PyMethodDef.ml_name` field of the sentinel must be ``NULL``.
The second table is used to define attributes which map directly to data stored
in the instance. A variety of primitive C types are supported, and access may
@@ -286,9 +286,9 @@ be read-only or read-write. The structures in the table are defined as::
For each entry in the table, a :term:`descriptor` will be constructed and added to the
type which will be able to extract a value from the instance structure. The
-:attr:`type` field should contain a type code like :c:macro:`Py_T_INT` or
+:c:member:`~PyMemberDef.type` field should contain a type code like :c:macro:`Py_T_INT` or
:c:macro:`Py_T_DOUBLE`; the value will be used to determine how to
-convert Python values to and from C values. The :attr:`flags` field is used to
+convert Python values to and from C values. The :c:member:`~PyMemberDef.flags` field is used to
store flags which control how the attribute can be accessed: you can set it to
:c:macro:`Py_READONLY` to prevent Python code from setting it.
@@ -298,7 +298,7 @@ have an associated doc string simply by providing the text in the table. An
application can use the introspection API to retrieve the descriptor from the
class object, and get the doc string using its :attr:`__doc__` attribute.
-As with the :c:member:`~PyTypeObject.tp_methods` table, a sentinel entry with a :attr:`name` value
+As with the :c:member:`~PyTypeObject.tp_methods` table, a sentinel entry with a :c:member:`~PyMethodDef.ml_name` value
of ``NULL`` is required.
.. XXX Descriptors need to be explained in more detail somewhere, but not here.
@@ -323,7 +323,7 @@ called, so that if you do need to extend their functionality, you'll understand
what needs to be done.
The :c:member:`~PyTypeObject.tp_getattr` handler is called when the object requires an attribute
-look-up. It is called in the same situations where the :meth:`__getattr__`
+look-up. It is called in the same situations where the :meth:`~object.__getattr__`
method of a class would be called.
Here is an example::
@@ -338,12 +338,12 @@ Here is an example::
PyErr_Format(PyExc_AttributeError,
"'%.100s' object has no attribute '%.400s'",
- tp->tp_name, name);
+ Py_TYPE(obj)->tp_name, name);
return NULL;
}
-The :c:member:`~PyTypeObject.tp_setattr` handler is called when the :meth:`__setattr__` or
-:meth:`__delattr__` method of a class instance would be called. When an
+The :c:member:`~PyTypeObject.tp_setattr` handler is called when the :meth:`~object.__setattr__` or
+:meth:`~object.__delattr__` method of a class instance would be called. When an
attribute should be deleted, the third parameter will be ``NULL``. Here is an
example that simply raises an exception; if this were really all you wanted, the
:c:member:`~PyTypeObject.tp_setattr` handler should be set to ``NULL``. ::
@@ -364,7 +364,7 @@ Object Comparison
The :c:member:`~PyTypeObject.tp_richcompare` handler is called when comparisons are needed. It is
analogous to the :ref:`rich comparison methods `, like
-:meth:`__lt__`, and also called by :c:func:`PyObject_RichCompare` and
+:meth:`!__lt__`, and also called by :c:func:`PyObject_RichCompare` and
:c:func:`PyObject_RichCompareBool`.
This function is called with two Python objects and the operator as arguments,
@@ -379,7 +379,7 @@ Here is a sample implementation, for a datatype that is considered equal if the
size of an internal pointer is equal::
static PyObject *
- newdatatype_richcmp(PyObject *obj1, PyObject *obj2, int op)
+ newdatatype_richcmp(newdatatypeobject *obj1, newdatatypeobject *obj2, int op)
{
PyObject *result;
int c, size1, size2;
@@ -478,7 +478,7 @@ This function takes three arguments:
Here is a toy ``tp_call`` implementation::
static PyObject *
- newdatatype_call(newdatatypeobject *self, PyObject *args, PyObject *kwds)
+ newdatatype_call(newdatatypeobject *obj, PyObject *args, PyObject *kwds)
{
PyObject *result;
const char *arg1;
@@ -505,7 +505,7 @@ These functions provide support for the iterator protocol. Both handlers
take exactly one parameter, the instance for which they are being called,
and return a new reference. In the case of an error, they should set an
exception and return ``NULL``. :c:member:`~PyTypeObject.tp_iter` corresponds
-to the Python :meth:`__iter__` method, while :c:member:`~PyTypeObject.tp_iternext`
+to the Python :meth:`~object.__iter__` method, while :c:member:`~PyTypeObject.tp_iternext`
corresponds to the Python :meth:`~iterator.__next__` method.
Any :term:`iterable` object must implement the :c:member:`~PyTypeObject.tp_iter`
diff --git a/Doc/extending/newtypes_tutorial.rst b/Doc/extending/newtypes_tutorial.rst
index f89934a11f12a8..c2bc5f699a1599 100644
--- a/Doc/extending/newtypes_tutorial.rst
+++ b/Doc/extending/newtypes_tutorial.rst
@@ -36,8 +36,8 @@ So, if you want to define a new extension type, you need to create a new type
object.
This sort of thing can only be explained by example, so here's a minimal, but
-complete, module that defines a new type named :class:`Custom` inside a C
-extension module :mod:`custom`:
+complete, module that defines a new type named :class:`!Custom` inside a C
+extension module :mod:`!custom`:
.. note::
What we're showing here is the traditional way of defining *static*
@@ -45,17 +45,17 @@ extension module :mod:`custom`:
allows defining heap-allocated extension types using the
:c:func:`PyType_FromSpec` function, which isn't covered in this tutorial.
-.. literalinclude:: ../includes/custom.c
+.. literalinclude:: ../includes/newtypes/custom.c
Now that's quite a bit to take in at once, but hopefully bits will seem familiar
from the previous chapter. This file defines three things:
-#. What a :class:`Custom` **object** contains: this is the ``CustomObject``
- struct, which is allocated once for each :class:`Custom` instance.
-#. How the :class:`Custom` **type** behaves: this is the ``CustomType`` struct,
+#. What a :class:`!Custom` **object** contains: this is the ``CustomObject``
+ struct, which is allocated once for each :class:`!Custom` instance.
+#. How the :class:`!Custom` **type** behaves: this is the ``CustomType`` struct,
which defines a set of flags and function pointers that the interpreter
inspects when specific operations are requested.
-#. How to initialize the :mod:`custom` module: this is the ``PyInit_custom``
+#. How to initialize the :mod:`!custom` module: this is the ``PyInit_custom``
function and the associated ``custommodule`` struct.
The first bit is::
@@ -127,8 +127,8 @@ our objects and in some error messages, for example:
TypeError: can only concatenate str (not "custom.Custom") to str
Note that the name is a dotted name that includes both the module name and the
-name of the type within the module. The module in this case is :mod:`custom` and
-the type is :class:`Custom`, so we set the type name to :class:`custom.Custom`.
+name of the type within the module. The module in this case is :mod:`!custom` and
+the type is :class:`!Custom`, so we set the type name to :class:`!custom.Custom`.
Using the real dotted import path is important to make your type compatible
with the :mod:`pydoc` and :mod:`pickle` modules. ::
@@ -136,7 +136,7 @@ with the :mod:`pydoc` and :mod:`pickle` modules. ::
.tp_itemsize = 0,
This is so that Python knows how much memory to allocate when creating
-new :class:`Custom` instances. :c:member:`~PyTypeObject.tp_itemsize` is
+new :class:`!Custom` instances. :c:member:`~PyTypeObject.tp_itemsize` is
only used for variable-sized objects and should otherwise be zero.
.. note::
@@ -145,13 +145,13 @@ only used for variable-sized objects and should otherwise be zero.
:c:member:`~PyTypeObject.tp_basicsize` as its base type, you may have problems with multiple
inheritance. A Python subclass of your type will have to list your type first
in its :attr:`~class.__bases__`, or else it will not be able to call your type's
- :meth:`__new__` method without getting an error. You can avoid this problem by
+ :meth:`~object.__new__` method without getting an error. You can avoid this problem by
ensuring that your type has a larger value for :c:member:`~PyTypeObject.tp_basicsize` than its
base type does. Most of the time, this will be true anyway, because either your
base type will be :class:`object`, or else you will be adding data members to
your base type, and therefore increasing its size.
-We set the class flags to :const:`Py_TPFLAGS_DEFAULT`. ::
+We set the class flags to :c:macro:`Py_TPFLAGS_DEFAULT`. ::
.tp_flags = Py_TPFLAGS_DEFAULT,
@@ -164,20 +164,20 @@ We provide a doc string for the type in :c:member:`~PyTypeObject.tp_doc`. ::
.tp_doc = PyDoc_STR("Custom objects"),
To enable object creation, we have to provide a :c:member:`~PyTypeObject.tp_new`
-handler. This is the equivalent of the Python method :meth:`__new__`, but
+handler. This is the equivalent of the Python method :meth:`~object.__new__`, but
has to be specified explicitly. In this case, we can just use the default
implementation provided by the API function :c:func:`PyType_GenericNew`. ::
.tp_new = PyType_GenericNew,
Everything else in the file should be familiar, except for some code in
-:c:func:`PyInit_custom`::
+:c:func:`!PyInit_custom`::
if (PyType_Ready(&CustomType) < 0)
return;
-This initializes the :class:`Custom` type, filling in a number of members
-to the appropriate default values, including :attr:`ob_type` that we initially
+This initializes the :class:`!Custom` type, filling in a number of members
+to the appropriate default values, including :c:member:`~PyObject.ob_type` that we initially
set to ``NULL``. ::
Py_INCREF(&CustomType);
@@ -188,7 +188,7 @@ set to ``NULL``. ::
}
This adds the type to the module dictionary. This allows us to create
-:class:`Custom` instances by calling the :class:`Custom` class:
+:class:`!Custom` instances by calling the :class:`!Custom` class:
.. code-block:: pycon
@@ -196,50 +196,46 @@ This adds the type to the module dictionary. This allows us to create
>>> mycustom = custom.Custom()
That's it! All that remains is to build it; put the above code in a file called
-:file:`custom.c` and:
+:file:`custom.c`,
+
+.. literalinclude:: ../includes/newtypes/pyproject.toml
+
+in a file called :file:`pyproject.toml`, and
.. code-block:: python
- from distutils.core import setup, Extension
- setup(name="custom", version="1.0",
- ext_modules=[Extension("custom", ["custom.c"])])
+ from setuptools import Extension, setup
+ setup(ext_modules=[Extension("custom", ["custom.c"])])
in a file called :file:`setup.py`; then typing
.. code-block:: shell-session
- $ python setup.py build
+ $ python -m pip install .
-at a shell should produce a file :file:`custom.so` in a subdirectory; move to
-that directory and fire up Python --- you should be able to ``import custom`` and
-play around with Custom objects.
+in a shell should produce a file :file:`custom.so` in a subdirectory
+and install it; now fire up Python --- you should be able to ``import custom``
+and play around with ``Custom`` objects.
That wasn't so hard, was it?
Of course, the current Custom type is pretty uninteresting. It has no data and
doesn't do anything. It can't even be subclassed.
-.. note::
- While this documentation showcases the standard :mod:`distutils` module
- for building C extensions, it is recommended in real-world use cases to
- use the newer and better-maintained ``setuptools`` library. Documentation
- on how to do this is out of scope for this document and can be found in
- the `Python Packaging User's Guide `_.
-
Adding data and methods to the Basic example
============================================
Let's extend the basic example to add some data and methods. Let's also make
-the type usable as a base class. We'll create a new module, :mod:`custom2` that
+the type usable as a base class. We'll create a new module, :mod:`!custom2` that
adds these capabilities:
-.. literalinclude:: ../includes/custom2.c
+.. literalinclude:: ../includes/newtypes/custom2.c
This version of the module has a number of changes.
-The :class:`Custom` type now has three data attributes in its C struct,
+The :class:`!Custom` type now has three data attributes in its C struct,
*first*, *last*, and *number*. The *first* and *last* variables are Python
strings containing first and last names. The *number* attribute is a C integer.
@@ -272,7 +268,7 @@ This method first clears the reference counts of the two Python attributes.
``NULL`` (which might happen here if ``tp_new`` failed midway). It then
calls the :c:member:`~PyTypeObject.tp_free` member of the object's type
(computed by ``Py_TYPE(self)``) to free the object's memory. Note that
-the object's type might not be :class:`CustomType`, because the object may
+the object's type might not be :class:`!CustomType`, because the object may
be an instance of a subclass.
.. note::
@@ -311,10 +307,10 @@ and install it in the :c:member:`~PyTypeObject.tp_new` member::
.tp_new = Custom_new,
The ``tp_new`` handler is responsible for creating (as opposed to initializing)
-objects of the type. It is exposed in Python as the :meth:`__new__` method.
+objects of the type. It is exposed in Python as the :meth:`~object.__new__` method.
It is not required to define a ``tp_new`` member, and indeed many extension
types will simply reuse :c:func:`PyType_GenericNew` as done in the first
-version of the ``Custom`` type above. In this case, we use the ``tp_new``
+version of the :class:`!Custom` type above. In this case, we use the ``tp_new``
handler to initialize the ``first`` and ``last`` attributes to non-``NULL``
default values.
@@ -345,7 +341,7 @@ result against ``NULL`` before proceeding.
.. note::
If you are creating a co-operative :c:member:`~PyTypeObject.tp_new` (one
- that calls a base type's :c:member:`~PyTypeObject.tp_new` or :meth:`__new__`),
+ that calls a base type's :c:member:`~PyTypeObject.tp_new` or :meth:`~object.__new__`),
you must *not* try to determine what method to call using method resolution
order at runtime. Always statically determine what type you are going to
call, and call its :c:member:`~PyTypeObject.tp_new` directly, or via
@@ -388,14 +384,14 @@ by filling the :c:member:`~PyTypeObject.tp_init` slot. ::
.tp_init = (initproc) Custom_init,
The :c:member:`~PyTypeObject.tp_init` slot is exposed in Python as the
-:meth:`__init__` method. It is used to initialize an object after it's
+:meth:`~object.__init__` method. It is used to initialize an object after it's
created. Initializers always accept positional and keyword arguments,
and they should return either ``0`` on success or ``-1`` on error.
Unlike the ``tp_new`` handler, there is no guarantee that ``tp_init``
is called at all (for example, the :mod:`pickle` module by default
-doesn't call :meth:`__init__` on unpickled instances). It can also be
-called multiple times. Anyone can call the :meth:`__init__` method on
+doesn't call :meth:`~object.__init__` on unpickled instances). It can also be
+called multiple times. Anyone can call the :meth:`!__init__` method on
our objects. For this reason, we have to be extra careful when assigning
the new attribute values. We might be tempted, for example to assign the
``first`` member like this::
@@ -453,7 +449,7 @@ Further, the attributes can be deleted, setting the C pointers to ``NULL``. Eve
though we can make sure the members are initialized to non-``NULL`` values, the
members can be set to ``NULL`` if the attributes are deleted.
-We define a single method, :meth:`Custom.name()`, that outputs the objects name as the
+We define a single method, :meth:`!Custom.name()`, that outputs the objects name as the
concatenation of the first and last names. ::
static PyObject *
@@ -470,8 +466,8 @@ concatenation of the first and last names. ::
return PyUnicode_FromFormat("%S %S", self->first, self->last);
}
-The method is implemented as a C function that takes a :class:`Custom` (or
-:class:`Custom` subclass) instance as the first argument. Methods always take an
+The method is implemented as a C function that takes a :class:`!Custom` (or
+:class:`!Custom` subclass) instance as the first argument. Methods always take an
instance as the first argument. Methods often take positional and keyword
arguments as well, but in this case we don't take any and don't need to accept
a positional argument tuple or keyword argument dictionary. This method is
@@ -482,8 +478,8 @@ equivalent to the Python method:
def name(self):
return "%s %s" % (self.first, self.last)
-Note that we have to check for the possibility that our :attr:`first` and
-:attr:`last` members are ``NULL``. This is because they can be deleted, in which
+Note that we have to check for the possibility that our :attr:`!first` and
+:attr:`!last` members are ``NULL``. This is because they can be deleted, in which
case they are set to ``NULL``. It would be better to prevent deletion of these
attributes and to restrict the attribute values to be strings. We'll see how to
do that in the next section.
@@ -498,7 +494,7 @@ definitions::
{NULL} /* Sentinel */
};
-(note that we used the :const:`METH_NOARGS` flag to indicate that the method
+(note that we used the :c:macro:`METH_NOARGS` flag to indicate that the method
is expecting no arguments other than *self*)
and assign it to the :c:member:`~PyTypeObject.tp_methods` slot::
@@ -508,41 +504,45 @@ and assign it to the :c:member:`~PyTypeObject.tp_methods` slot::
Finally, we'll make our type usable as a base class for subclassing. We've
written our methods carefully so far so that they don't make any assumptions
about the type of the object being created or used, so all we need to do is
-to add the :const:`Py_TPFLAGS_BASETYPE` to our class flag definition::
+to add the :c:macro:`Py_TPFLAGS_BASETYPE` to our class flag definition::
.tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE,
-We rename :c:func:`PyInit_custom` to :c:func:`PyInit_custom2`, update the
+We rename :c:func:`!PyInit_custom` to :c:func:`!PyInit_custom2`, update the
module name in the :c:type:`PyModuleDef` struct, and update the full class
name in the :c:type:`PyTypeObject` struct.
-Finally, we update our :file:`setup.py` file to build the new module:
+Finally, we update our :file:`setup.py` file to include the new module,
.. code-block:: python
- from distutils.core import setup, Extension
- setup(name="custom", version="1.0",
- ext_modules=[
- Extension("custom", ["custom.c"]),
- Extension("custom2", ["custom2.c"]),
- ])
+ from setuptools import Extension, setup
+ setup(ext_modules=[
+ Extension("custom", ["custom.c"]),
+ Extension("custom2", ["custom2.c"]),
+ ])
+
+and then we re-install so that we can ``import custom2``:
+
+.. code-block:: shell-session
+ $ python -m pip install .
Providing finer control over data attributes
============================================
-In this section, we'll provide finer control over how the :attr:`first` and
-:attr:`last` attributes are set in the :class:`Custom` example. In the previous
-version of our module, the instance variables :attr:`first` and :attr:`last`
+In this section, we'll provide finer control over how the :attr:`!first` and
+:attr:`!last` attributes are set in the :class:`!Custom` example. In the previous
+version of our module, the instance variables :attr:`!first` and :attr:`!last`
could be set to non-string values or even deleted. We want to make sure that
these attributes always contain strings.
-.. literalinclude:: ../includes/custom3.c
+.. literalinclude:: ../includes/newtypes/custom3.c
-To provide greater control, over the :attr:`first` and :attr:`last` attributes,
+To provide greater control, over the :attr:`!first` and :attr:`!last` attributes,
we'll use custom getter and setter functions. Here are the functions for
-getting and setting the :attr:`first` attribute::
+getting and setting the :attr:`!first` attribute::
static PyObject *
Custom_getfirst(CustomObject *self, void *closure)
@@ -571,13 +571,13 @@ getting and setting the :attr:`first` attribute::
return 0;
}
-The getter function is passed a :class:`Custom` object and a "closure", which is
+The getter function is passed a :class:`!Custom` object and a "closure", which is
a void pointer. In this case, the closure is ignored. (The closure supports an
advanced usage in which definition data is passed to the getter and setter. This
could, for example, be used to allow a single set of getter and setter functions
that decide the attribute to get or set based on data in the closure.)
-The setter function is passed the :class:`Custom` object, the new value, and the
+The setter function is passed the :class:`!Custom` object, the new value, and the
closure. The new value may be ``NULL``, in which case the attribute is being
deleted. In our setter, we raise an error if the attribute is deleted or if its
new value is not a string.
@@ -666,11 +666,11 @@ still has a reference from itself. Its reference count doesn't drop to zero.
Fortunately, Python's cyclic garbage collector will eventually figure out that
the list is garbage and free it.
-In the second version of the :class:`Custom` example, we allowed any kind of
-object to be stored in the :attr:`first` or :attr:`last` attributes [#]_.
+In the second version of the :class:`!Custom` example, we allowed any kind of
+object to be stored in the :attr:`!first` or :attr:`!last` attributes [#]_.
Besides, in the second and third versions, we allowed subclassing
-:class:`Custom`, and subclasses may add arbitrary attributes. For any of
-those two reasons, :class:`Custom` objects can participate in cycles:
+:class:`!Custom`, and subclasses may add arbitrary attributes. For any of
+those two reasons, :class:`!Custom` objects can participate in cycles:
.. code-block:: pycon
@@ -680,11 +680,11 @@ those two reasons, :class:`Custom` objects can participate in cycles:
>>> n = Derived()
>>> n.some_attribute = n
-To allow a :class:`Custom` instance participating in a reference cycle to
-be properly detected and collected by the cyclic GC, our :class:`Custom` type
+To allow a :class:`!Custom` instance participating in a reference cycle to
+be properly detected and collected by the cyclic GC, our :class:`!Custom` type
needs to fill two additional slots and to enable a flag that enables these slots:
-.. literalinclude:: ../includes/custom4.c
+.. literalinclude:: ../includes/newtypes/custom4.c
First, the traversal method lets the cyclic GC know about subobjects that could
@@ -708,8 +708,8 @@ participate in cycles::
}
For each subobject that can participate in cycles, we need to call the
-:c:func:`visit` function, which is passed to the traversal method. The
-:c:func:`visit` function takes as arguments the subobject and the extra argument
+:c:func:`!visit` function, which is passed to the traversal method. The
+:c:func:`!visit` function takes as arguments the subobject and the extra argument
*arg* passed to the traversal method. It returns an integer value that must be
returned if it is non-zero.
@@ -774,7 +774,7 @@ and ``Custom_clear``::
Py_TYPE(self)->tp_free((PyObject *) self);
}
-Finally, we add the :const:`Py_TPFLAGS_HAVE_GC` flag to the class flags::
+Finally, we add the :c:macro:`Py_TPFLAGS_HAVE_GC` flag to the class flags::
.tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE | Py_TPFLAGS_HAVE_GC,
@@ -791,9 +791,9 @@ types. It is easiest to inherit from the built in types, since an extension can
easily use the :c:type:`PyTypeObject` it needs. It can be difficult to share
these :c:type:`PyTypeObject` structures between extension modules.
-In this example we will create a :class:`SubList` type that inherits from the
+In this example we will create a :class:`!SubList` type that inherits from the
built-in :class:`list` type. The new type will be completely compatible with
-regular lists, but will have an additional :meth:`increment` method that
+regular lists, but will have an additional :meth:`!increment` method that
increases an internal counter:
.. code-block:: pycon
@@ -808,10 +808,10 @@ increases an internal counter:
>>> print(s.increment())
2
-.. literalinclude:: ../includes/sublist.c
+.. literalinclude:: ../includes/newtypes/sublist.c
-As you can see, the source code closely resembles the :class:`Custom` examples in
+As you can see, the source code closely resembles the :class:`!Custom` examples in
previous sections. We will break down the main differences between them. ::
typedef struct {
@@ -823,7 +823,7 @@ The primary difference for derived type objects is that the base type's
object structure must be the first value. The base type will already include
the :c:func:`PyObject_HEAD` at the beginning of its structure.
-When a Python object is a :class:`SubList` instance, its ``PyObject *`` pointer
+When a Python object is a :class:`!SubList` instance, its ``PyObject *`` pointer
can be safely cast to both ``PyListObject *`` and ``SubListObject *``::
static int
@@ -835,7 +835,7 @@ can be safely cast to both ``PyListObject *`` and ``SubListObject *``::
return 0;
}
-We see above how to call through to the :attr:`__init__` method of the base
+We see above how to call through to the :meth:`~object.__init__` method of the base
type.
This pattern is important when writing a type with custom
@@ -879,7 +879,7 @@ slot with :c:func:`PyType_GenericNew` -- the allocation function from the base
type will be inherited.
After that, calling :c:func:`PyType_Ready` and adding the type object to the
-module is the same as with the basic :class:`Custom` examples.
+module is the same as with the basic :class:`!Custom` examples.
.. rubric:: Footnotes
diff --git a/Doc/faq/design.rst b/Doc/faq/design.rst
index 11d01374dc1e79..ae02c443e5938b 100644
--- a/Doc/faq/design.rst
+++ b/Doc/faq/design.rst
@@ -584,9 +584,9 @@ exhaustive test suites that exercise every line of code in a module.
An appropriate testing discipline can help build large complex applications in
Python as well as having interface specifications would. In fact, it can be
better because an interface specification cannot test certain properties of a
-program. For example, the :meth:`list.append` method is expected to add new elements
+program. For example, the :meth:`!list.append` method is expected to add new elements
to the end of some internal list; an interface specification cannot test that
-your :meth:`list.append` implementation will actually do this correctly, but it's
+your :meth:`!list.append` implementation will actually do this correctly, but it's
trivial to check this property in a test suite.
Writing test suites is very helpful, and you might want to design your code to
diff --git a/Doc/faq/extending.rst b/Doc/faq/extending.rst
index bc3080f60ee237..2a8b976925d042 100644
--- a/Doc/faq/extending.rst
+++ b/Doc/faq/extending.rst
@@ -81,13 +81,13 @@ How do I extract C values from a Python object?
That depends on the object's type. If it's a tuple, :c:func:`PyTuple_Size`
returns its length and :c:func:`PyTuple_GetItem` returns the item at a specified
-index. Lists have similar functions, :c:func:`PyListSize` and
+index. Lists have similar functions, :c:func:`PyList_Size` and
:c:func:`PyList_GetItem`.
For bytes, :c:func:`PyBytes_Size` returns its length and
:c:func:`PyBytes_AsStringAndSize` provides a pointer to its value and its
length. Note that Python bytes objects may contain null bytes so C's
-:c:func:`strlen` should not be used.
+:c:func:`!strlen` should not be used.
To test the type of an object, first make sure it isn't ``NULL``, and then use
:c:func:`PyBytes_Check`, :c:func:`PyTuple_Check`, :c:func:`PyList_Check`, etc.
diff --git a/Doc/faq/general.rst b/Doc/faq/general.rst
index a9b2622e02ef3b..8727332594bda6 100644
--- a/Doc/faq/general.rst
+++ b/Doc/faq/general.rst
@@ -135,7 +135,7 @@ Python versions are numbered "A.B.C" or "A.B":
See :pep:`6` for more information about bugfix releases.
-Not all releases are bugfix releases. In the run-up to a new major release, a
+Not all releases are bugfix releases. In the run-up to a new feature release, a
series of development releases are made, denoted as alpha, beta, or release
candidate. Alphas are early releases in which interfaces aren't yet finalized;
it's not unexpected to see an interface change between two alpha releases.
@@ -297,9 +297,9 @@ 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. As of version 3.9,
-Python will have a major new release every 12 months (:pep:`602`).
+Python will have a new feature release every 12 months (:pep:`602`).
-The developers issue "bugfix" releases of older versions, so the stability of
+The developers issue bugfix releases of older versions, so the stability of
existing releases gradually improves. Bugfix releases, indicated by a third
component of the version number (e.g. 3.5.3, 3.6.2), are managed for stability;
only fixes for known problems are included in a bugfix release, and it's
diff --git a/Doc/faq/library.rst b/Doc/faq/library.rst
index 597caaa778e1c8..c69910718f0c92 100644
--- a/Doc/faq/library.rst
+++ b/Doc/faq/library.rst
@@ -111,7 +111,7 @@ Is there an equivalent to C's onexit() in Python?
-------------------------------------------------
The :mod:`atexit` module provides a register function that is similar to C's
-:c:func:`onexit`.
+:c:func:`!onexit`.
Why don't my signal handlers work?
@@ -397,7 +397,7 @@ These aren't::
D[x] = D[x] + 1
Operations that replace other objects may invoke those other objects'
-:meth:`__del__` method when their reference count reaches zero, and that can
+:meth:`~object.__del__` method when their reference count reaches zero, and that can
affect things. This is especially true for the mass updates to dictionaries and
lists. When in doubt, use a mutex!
@@ -566,7 +566,7 @@ use ``p.read(n)``.
Note on a bug in popen2: unless your program calls ``wait()`` or
``waitpid()``, finished child processes are never removed, and eventually
calls to popen2 will fail because of a limit on the number of child
- processes. Calling :func:`os.waitpid` with the :data:`os.WNOHANG` option can
+ processes. Calling :func:`os.waitpid` with the :const:`os.WNOHANG` option can
prevent this; a good place to insert such a call would be before calling
``popen2`` again.
@@ -765,14 +765,17 @@ The :mod:`select` module is commonly used to help with asynchronous I/O on
sockets.
To prevent the TCP connect from blocking, you can set the socket to non-blocking
-mode. Then when you do the :meth:`socket.connect`, you will either connect immediately
+mode. Then when you do the :meth:`~socket.socket.connect`,
+you will either connect immediately
(unlikely) or get an exception that contains the error number as ``.errno``.
``errno.EINPROGRESS`` indicates that the connection is in progress, but hasn't
finished yet. Different OSes will return different values, so you're going to
have to check what's returned on your system.
-You can use the :meth:`socket.connect_ex` method to avoid creating an exception. It will
-just return the errno value. To poll, you can call :meth:`socket.connect_ex` again later
+You can use the :meth:`~socket.socket.connect_ex` method
+to avoid creating an exception.
+It will just return the errno value.
+To poll, you can call :meth:`~socket.socket.connect_ex` again later
-- ``0`` or ``errno.EISCONN`` indicate that you're connected -- or you can pass this
socket to :meth:`select.select` to check if it's writable.
diff --git a/Doc/faq/programming.rst b/Doc/faq/programming.rst
index ab5618db84f77e..f43f69b8a1ea91 100644
--- a/Doc/faq/programming.rst
+++ b/Doc/faq/programming.rst
@@ -454,7 +454,7 @@ There are two factors that produce this result:
(the list), and both ``x`` and ``y`` refer to it.
2) Lists are :term:`mutable`, which means that you can change their content.
-After the call to :meth:`~list.append`, the content of the mutable object has
+After the call to :meth:`!append`, the content of the mutable object has
changed from ``[]`` to ``[10]``. Since both the variables refer to the same
object, using either name accesses the modified value ``[10]``.
@@ -1397,7 +1397,7 @@ To see why this happens, you need to know that (a) if an object implements an
:meth:`~object.__iadd__` magic method, it gets called when the ``+=`` augmented
assignment
is executed, and its return value is what gets used in the assignment statement;
-and (b) for lists, :meth:`!__iadd__` is equivalent to calling :meth:`~list.extend` on the list
+and (b) for lists, :meth:`!__iadd__` is equivalent to calling :meth:`!extend` on the list
and returning the list. That's why we say that for lists, ``+=`` is a
"shorthand" for :meth:`!list.extend`::
@@ -1903,7 +1903,7 @@ identity tests. This prevents the code from being confused by objects such as
``float('NaN')`` that are not equal to themselves.
For example, here is the implementation of
-:meth:`collections.abc.Sequence.__contains__`::
+:meth:`!collections.abc.Sequence.__contains__`::
def __contains__(self, value):
for v in self:
diff --git a/Doc/glossary.rst b/Doc/glossary.rst
index 53e8cdcae1cd66..f3d5c5eede9701 100644
--- a/Doc/glossary.rst
+++ b/Doc/glossary.rst
@@ -92,8 +92,8 @@ Glossary
asynchronous context manager
An object which controls the environment seen in an
- :keyword:`async with` statement by defining :meth:`__aenter__` and
- :meth:`__aexit__` methods. Introduced by :pep:`492`.
+ :keyword:`async with` statement by defining :meth:`~object.__aenter__` and
+ :meth:`~object.__aexit__` methods. Introduced by :pep:`492`.
asynchronous generator
A function which returns an :term:`asynchronous generator iterator`. It
@@ -113,26 +113,26 @@ Glossary
An object created by a :term:`asynchronous generator` function.
This is an :term:`asynchronous iterator` which when called using the
- :meth:`__anext__` method returns an awaitable object which will execute
+ :meth:`~object.__anext__` method returns an awaitable object which will execute
the body of the asynchronous generator function until the next
:keyword:`yield` expression.
Each :keyword:`yield` temporarily suspends processing, remembering the
location execution state (including local variables and pending
try-statements). When the *asynchronous generator iterator* effectively
- resumes with another awaitable returned by :meth:`__anext__`, it
+ resumes with another awaitable returned by :meth:`~object.__anext__`, it
picks up where it left off. See :pep:`492` and :pep:`525`.
asynchronous iterable
An object, that can be used in an :keyword:`async for` statement.
Must return an :term:`asynchronous iterator` from its
- :meth:`__aiter__` method. Introduced by :pep:`492`.
+ :meth:`~object.__aiter__` method. Introduced by :pep:`492`.
asynchronous iterator
- An object that implements the :meth:`__aiter__` and :meth:`__anext__`
- methods. ``__anext__`` must return an :term:`awaitable` object.
+ An object that implements the :meth:`~object.__aiter__` and :meth:`~object.__anext__`
+ methods. :meth:`~object.__anext__` must return an :term:`awaitable` object.
:keyword:`async for` resolves the awaitables returned by an asynchronous
- iterator's :meth:`__anext__` method until it raises a
+ iterator's :meth:`~object.__anext__` method until it raises a
:exc:`StopAsyncIteration` exception. Introduced by :pep:`492`.
attribute
@@ -149,7 +149,7 @@ Glossary
awaitable
An object that can be used in an :keyword:`await` expression. Can be
- a :term:`coroutine` or an object with an :meth:`__await__` method.
+ a :term:`coroutine` or an object with an :meth:`~object.__await__` method.
See also :pep:`492`.
BDFL
@@ -168,8 +168,9 @@ Glossary
:class:`str` objects.
borrowed reference
- In Python's C API, a borrowed reference is a reference to an object.
- It does not modify the object reference count. It becomes a dangling
+ In Python's C API, a borrowed reference is a reference to an object,
+ where the code using the object does not own the reference.
+ It becomes a dangling
pointer if the object is destroyed. For example, a garbage collection can
remove the last :term:`strong reference` to the object and so destroy it.
@@ -1063,7 +1064,9 @@ Glossary
reference count
The number of references to an object. When the reference count of an
- object drops to zero, it is deallocated. Reference counting is
+ object drops to zero, it is deallocated. Some objects are
+ "immortal" and have reference counts that are never modified, and
+ therefore the objects are never deallocated. Reference counting is
generally not visible to Python code, but it is a key element of the
:term:`CPython` implementation. Programmers can call the
:func:`sys.getrefcount` function to return the
@@ -1131,8 +1134,10 @@ Glossary
strong reference
In Python's C API, a strong reference is a reference to an object
- which increments the object's reference count when it is created and
- decrements the object's reference count when it is deleted.
+ which is owned by the code holding the reference. The strong
+ reference is taken by calling :c:func:`Py_INCREF` when the
+ reference is created and released with :c:func:`Py_DECREF`
+ when the reference is deleted.
The :c:func:`Py_NewRef` function can be used to create a strong reference
to an object. Usually, the :c:func:`Py_DECREF` function must be called on
diff --git a/Doc/howto/annotations.rst b/Doc/howto/annotations.rst
index 472069032d6509..1134686c947d66 100644
--- a/Doc/howto/annotations.rst
+++ b/Doc/howto/annotations.rst
@@ -32,201 +32,201 @@ Annotations Best Practices
Accessing The Annotations Dict Of An Object In Python 3.10 And Newer
====================================================================
- Python 3.10 adds a new function to the standard library:
- :func:`inspect.get_annotations`. In Python versions 3.10
- and newer, calling this function is the best practice for
- accessing the annotations dict of any object that supports
- annotations. This function can also "un-stringize"
- stringized annotations for you.
-
- If for some reason :func:`inspect.get_annotations` isn't
- viable for your use case, you may access the
- ``__annotations__`` data member manually. Best practice
- for this changed in Python 3.10 as well: as of Python 3.10,
- ``o.__annotations__`` is guaranteed to *always* work
- on Python functions, classes, and modules. If you're
- certain the object you're examining is one of these three
- *specific* objects, you may simply use ``o.__annotations__``
- to get at the object's annotations dict.
-
- However, other types of callables--for example,
- callables created by :func:`functools.partial`--may
- not have an ``__annotations__`` attribute defined. When
- accessing the ``__annotations__`` of a possibly unknown
- object, best practice in Python versions 3.10 and
- newer is to call :func:`getattr` with three arguments,
- for example ``getattr(o, '__annotations__', None)``.
-
- Before Python 3.10, accessing ``__annotations__`` on a class that
- defines no annotations but that has a parent class with
- annotations would return the parent's ``__annotations__``.
- In Python 3.10 and newer, the child class's annotations
- will be an empty dict instead.
+Python 3.10 adds a new function to the standard library:
+:func:`inspect.get_annotations`. In Python versions 3.10
+and newer, calling this function is the best practice for
+accessing the annotations dict of any object that supports
+annotations. This function can also "un-stringize"
+stringized annotations for you.
+
+If for some reason :func:`inspect.get_annotations` isn't
+viable for your use case, you may access the
+``__annotations__`` data member manually. Best practice
+for this changed in Python 3.10 as well: as of Python 3.10,
+``o.__annotations__`` is guaranteed to *always* work
+on Python functions, classes, and modules. If you're
+certain the object you're examining is one of these three
+*specific* objects, you may simply use ``o.__annotations__``
+to get at the object's annotations dict.
+
+However, other types of callables--for example,
+callables created by :func:`functools.partial`--may
+not have an ``__annotations__`` attribute defined. When
+accessing the ``__annotations__`` of a possibly unknown
+object, best practice in Python versions 3.10 and
+newer is to call :func:`getattr` with three arguments,
+for example ``getattr(o, '__annotations__', None)``.
+
+Before Python 3.10, accessing ``__annotations__`` on a class that
+defines no annotations but that has a parent class with
+annotations would return the parent's ``__annotations__``.
+In Python 3.10 and newer, the child class's annotations
+will be an empty dict instead.
Accessing The Annotations Dict Of An Object In Python 3.9 And Older
===================================================================
- In Python 3.9 and older, accessing the annotations dict
- of an object is much more complicated than in newer versions.
- The problem is a design flaw in these older versions of Python,
- specifically to do with class annotations.
+In Python 3.9 and older, accessing the annotations dict
+of an object is much more complicated than in newer versions.
+The problem is a design flaw in these older versions of Python,
+specifically to do with class annotations.
- Best practice for accessing the annotations dict of other
- objects--functions, other callables, and modules--is the same
- as best practice for 3.10, assuming you aren't calling
- :func:`inspect.get_annotations`: you should use three-argument
- :func:`getattr` to access the object's ``__annotations__``
- attribute.
+Best practice for accessing the annotations dict of other
+objects--functions, other callables, and modules--is the same
+as best practice for 3.10, assuming you aren't calling
+:func:`inspect.get_annotations`: you should use three-argument
+:func:`getattr` to access the object's ``__annotations__``
+attribute.
- Unfortunately, this isn't best practice for classes. The problem
- is that, since ``__annotations__`` is optional on classes, and
- because classes can inherit attributes from their base classes,
- accessing the ``__annotations__`` attribute of a class may
- inadvertently return the annotations dict of a *base class.*
- As an example::
+Unfortunately, this isn't best practice for classes. The problem
+is that, since ``__annotations__`` is optional on classes, and
+because classes can inherit attributes from their base classes,
+accessing the ``__annotations__`` attribute of a class may
+inadvertently return the annotations dict of a *base class.*
+As an example::
- class Base:
- a: int = 3
- b: str = 'abc'
+ class Base:
+ a: int = 3
+ b: str = 'abc'
- class Derived(Base):
- pass
+ class Derived(Base):
+ pass
- print(Derived.__annotations__)
+ print(Derived.__annotations__)
- This will print the annotations dict from ``Base``, not
- ``Derived``.
+This will print the annotations dict from ``Base``, not
+``Derived``.
- Your code will have to have a separate code path if the object
- you're examining is a class (``isinstance(o, type)``).
- In that case, best practice relies on an implementation detail
- of Python 3.9 and before: if a class has annotations defined,
- they are stored in the class's ``__dict__`` dictionary. Since
- the class may or may not have annotations defined, best practice
- is to call the ``get`` method on the class dict.
+Your code will have to have a separate code path if the object
+you're examining is a class (``isinstance(o, type)``).
+In that case, best practice relies on an implementation detail
+of Python 3.9 and before: if a class has annotations defined,
+they are stored in the class's ``__dict__`` dictionary. Since
+the class may or may not have annotations defined, best practice
+is to call the ``get`` method on the class dict.
- To put it all together, here is some sample code that safely
- accesses the ``__annotations__`` attribute on an arbitrary
- object in Python 3.9 and before::
+To put it all together, here is some sample code that safely
+accesses the ``__annotations__`` attribute on an arbitrary
+object in Python 3.9 and before::
- if isinstance(o, type):
- ann = o.__dict__.get('__annotations__', None)
- else:
- ann = getattr(o, '__annotations__', None)
+ if isinstance(o, type):
+ ann = o.__dict__.get('__annotations__', None)
+ else:
+ ann = getattr(o, '__annotations__', None)
- After running this code, ``ann`` should be either a
- dictionary or ``None``. You're encouraged to double-check
- the type of ``ann`` using :func:`isinstance` before further
- examination.
+After running this code, ``ann`` should be either a
+dictionary or ``None``. You're encouraged to double-check
+the type of ``ann`` using :func:`isinstance` before further
+examination.
- Note that some exotic or malformed type objects may not have
- a ``__dict__`` attribute, so for extra safety you may also wish
- to use :func:`getattr` to access ``__dict__``.
+Note that some exotic or malformed type objects may not have
+a ``__dict__`` attribute, so for extra safety you may also wish
+to use :func:`getattr` to access ``__dict__``.
Manually Un-Stringizing Stringized Annotations
==============================================
- In situations where some annotations may be "stringized",
- and you wish to evaluate those strings to produce the
- Python values they represent, it really is best to
- call :func:`inspect.get_annotations` to do this work
- for you.
-
- If you're using Python 3.9 or older, or if for some reason
- you can't use :func:`inspect.get_annotations`, you'll need
- to duplicate its logic. You're encouraged to examine the
- implementation of :func:`inspect.get_annotations` in the
- current Python version and follow a similar approach.
-
- In a nutshell, if you wish to evaluate a stringized annotation
- on an arbitrary object ``o``:
-
- * If ``o`` is a module, use ``o.__dict__`` as the
- ``globals`` when calling :func:`eval`.
- * If ``o`` is a class, use ``sys.modules[o.__module__].__dict__``
- as the ``globals``, and ``dict(vars(o))`` as the ``locals``,
- when calling :func:`eval`.
- * If ``o`` is a wrapped callable using :func:`functools.update_wrapper`,
- :func:`functools.wraps`, or :func:`functools.partial`, iteratively
- unwrap it by accessing either ``o.__wrapped__`` or ``o.func`` as
- appropriate, until you have found the root unwrapped function.
- * If ``o`` is a callable (but not a class), use
- ``o.__globals__`` as the globals when calling :func:`eval`.
-
- However, not all string values used as annotations can
- be successfully turned into Python values by :func:`eval`.
- String values could theoretically contain any valid string,
- and in practice there are valid use cases for type hints that
- require annotating with string values that specifically
- *can't* be evaluated. For example:
-
- * :pep:`604` union types using ``|``, before support for this
- was added to Python 3.10.
- * Definitions that aren't needed at runtime, only imported
- when :const:`typing.TYPE_CHECKING` is true.
-
- If :func:`eval` attempts to evaluate such values, it will
- fail and raise an exception. So, when designing a library
- API that works with annotations, it's recommended to only
- attempt to evaluate string values when explicitly requested
- to by the caller.
+In situations where some annotations may be "stringized",
+and you wish to evaluate those strings to produce the
+Python values they represent, it really is best to
+call :func:`inspect.get_annotations` to do this work
+for you.
+
+If you're using Python 3.9 or older, or if for some reason
+you can't use :func:`inspect.get_annotations`, you'll need
+to duplicate its logic. You're encouraged to examine the
+implementation of :func:`inspect.get_annotations` in the
+current Python version and follow a similar approach.
+
+In a nutshell, if you wish to evaluate a stringized annotation
+on an arbitrary object ``o``:
+
+* If ``o`` is a module, use ``o.__dict__`` as the
+ ``globals`` when calling :func:`eval`.
+* If ``o`` is a class, use ``sys.modules[o.__module__].__dict__``
+ as the ``globals``, and ``dict(vars(o))`` as the ``locals``,
+ when calling :func:`eval`.
+* If ``o`` is a wrapped callable using :func:`functools.update_wrapper`,
+ :func:`functools.wraps`, or :func:`functools.partial`, iteratively
+ unwrap it by accessing either ``o.__wrapped__`` or ``o.func`` as
+ appropriate, until you have found the root unwrapped function.
+* If ``o`` is a callable (but not a class), use
+ ``o.__globals__`` as the globals when calling :func:`eval`.
+
+However, not all string values used as annotations can
+be successfully turned into Python values by :func:`eval`.
+String values could theoretically contain any valid string,
+and in practice there are valid use cases for type hints that
+require annotating with string values that specifically
+*can't* be evaluated. For example:
+
+* :pep:`604` union types using ``|``, before support for this
+ was added to Python 3.10.
+* Definitions that aren't needed at runtime, only imported
+ when :const:`typing.TYPE_CHECKING` is true.
+
+If :func:`eval` attempts to evaluate such values, it will
+fail and raise an exception. So, when designing a library
+API that works with annotations, it's recommended to only
+attempt to evaluate string values when explicitly requested
+to by the caller.
Best Practices For ``__annotations__`` In Any Python Version
============================================================
- * You should avoid assigning to the ``__annotations__`` member
- of objects directly. Let Python manage setting ``__annotations__``.
+* You should avoid assigning to the ``__annotations__`` member
+ of objects directly. Let Python manage setting ``__annotations__``.
- * If you do assign directly to the ``__annotations__`` member
- of an object, you should always set it to a ``dict`` object.
+* If you do assign directly to the ``__annotations__`` member
+ of an object, you should always set it to a ``dict`` object.
- * If you directly access the ``__annotations__`` member
- of an object, you should ensure that it's a
- dictionary before attempting to examine its contents.
+* If you directly access the ``__annotations__`` member
+ of an object, you should ensure that it's a
+ dictionary before attempting to examine its contents.
- * You should avoid modifying ``__annotations__`` dicts.
+* You should avoid modifying ``__annotations__`` dicts.
- * You should avoid deleting the ``__annotations__`` attribute
- of an object.
+* You should avoid deleting the ``__annotations__`` attribute
+ of an object.
``__annotations__`` Quirks
==========================
- In all versions of Python 3, function
- objects lazy-create an annotations dict if no annotations
- are defined on that object. You can delete the ``__annotations__``
- attribute using ``del fn.__annotations__``, but if you then
- access ``fn.__annotations__`` the object will create a new empty dict
- that it will store and return as its annotations. Deleting the
- annotations on a function before it has lazily created its annotations
- dict will throw an ``AttributeError``; using ``del fn.__annotations__``
- twice in a row is guaranteed to always throw an ``AttributeError``.
-
- Everything in the above paragraph also applies to class and module
- objects in Python 3.10 and newer.
-
- In all versions of Python 3, you can set ``__annotations__``
- on a function object to ``None``. However, subsequently
- accessing the annotations on that object using ``fn.__annotations__``
- will lazy-create an empty dictionary as per the first paragraph of
- this section. This is *not* true of modules and classes, in any Python
- version; those objects permit setting ``__annotations__`` to any
- Python value, and will retain whatever value is set.
-
- If Python stringizes your annotations for you
- (using ``from __future__ import annotations``), and you
- specify a string as an annotation, the string will
- itself be quoted. In effect the annotation is quoted
- *twice.* For example::
-
- from __future__ import annotations
- def foo(a: "str"): pass
-
- print(foo.__annotations__)
-
- This prints ``{'a': "'str'"}``. This shouldn't really be considered
- a "quirk"; it's mentioned here simply because it might be surprising.
+In all versions of Python 3, function
+objects lazy-create an annotations dict if no annotations
+are defined on that object. You can delete the ``__annotations__``
+attribute using ``del fn.__annotations__``, but if you then
+access ``fn.__annotations__`` the object will create a new empty dict
+that it will store and return as its annotations. Deleting the
+annotations on a function before it has lazily created its annotations
+dict will throw an ``AttributeError``; using ``del fn.__annotations__``
+twice in a row is guaranteed to always throw an ``AttributeError``.
+
+Everything in the above paragraph also applies to class and module
+objects in Python 3.10 and newer.
+
+In all versions of Python 3, you can set ``__annotations__``
+on a function object to ``None``. However, subsequently
+accessing the annotations on that object using ``fn.__annotations__``
+will lazy-create an empty dictionary as per the first paragraph of
+this section. This is *not* true of modules and classes, in any Python
+version; those objects permit setting ``__annotations__`` to any
+Python value, and will retain whatever value is set.
+
+If Python stringizes your annotations for you
+(using ``from __future__ import annotations``), and you
+specify a string as an annotation, the string will
+itself be quoted. In effect the annotation is quoted
+*twice.* For example::
+
+ from __future__ import annotations
+ def foo(a: "str"): pass
+
+ print(foo.__annotations__)
+
+This prints ``{'a': "'str'"}``. This shouldn't really be considered
+a "quirk"; it's mentioned here simply because it might be surprising.
diff --git a/Doc/howto/argparse.rst b/Doc/howto/argparse.rst
index 52e98fa9620194..ae5bab90bf8131 100644
--- a/Doc/howto/argparse.rst
+++ b/Doc/howto/argparse.rst
@@ -788,6 +788,59 @@ but not both at the same time:
-q, --quiet
+How to translate the argparse output
+====================================
+
+The output of the :mod:`argparse` module such as its help text and error
+messages are all made translatable using the :mod:`gettext` module. This
+allows applications to easily localize messages produced by
+:mod:`argparse`. See also :ref:`i18n-howto`.
+
+For instance, in this :mod:`argparse` output:
+
+.. code-block:: shell-session
+
+ $ python prog.py --help
+ usage: prog.py [-h] [-v | -q] x y
+
+ calculate X to the power of Y
+
+ positional arguments:
+ x the base
+ y the exponent
+
+ options:
+ -h, --help show this help message and exit
+ -v, --verbose
+ -q, --quiet
+
+The strings ``usage:``, ``positional arguments:``, ``options:`` and
+``show this help message and exit`` are all translatable.
+
+In order to translate these strings, they must first be extracted
+into a ``.po`` file. For example, using `Babel `__,
+run this command:
+
+.. code-block:: shell-session
+
+ $ pybabel extract -o messages.po /usr/lib/python3.12/argparse.py
+
+This command will extract all translatable strings from the :mod:`argparse`
+module and output them into a file named ``messages.po``. This command assumes
+that your Python installation is in ``/usr/lib``.
+
+You can find out the location of the :mod:`argparse` module on your system
+using this script::
+
+ import argparse
+ print(argparse.__file__)
+
+Once the messages in the ``.po`` file are translated and the translations are
+installed using :mod:`gettext`, :mod:`argparse` will be able to display the
+translated messages.
+
+To translate your own strings in the :mod:`argparse` output, use :mod:`gettext`.
+
Conclusion
==========
diff --git a/Doc/howto/clinic.rst b/Doc/howto/clinic.rst
index 4620b4617e3450..e8e6aace350e0c 100644
--- a/Doc/howto/clinic.rst
+++ b/Doc/howto/clinic.rst
@@ -8,17 +8,30 @@ Argument Clinic How-To
:author: Larry Hastings
+**Source code:** :source:`Tools/clinic/clinic.py`.
.. topic:: Abstract
Argument Clinic is a preprocessor for CPython C files.
- Its purpose is to automate all the boilerplate involved
- with writing argument parsing code for "builtins".
- This document shows you how to convert your first C
- function to work with Argument Clinic, and then introduces
- some advanced topics on Argument Clinic usage.
+ It was introduced in Python 3.4 with :pep:`436`,
+ in order to provide introspection signatures,
+ and to generate performant and tailor-made boilerplate code
+ for argument parsing in CPython builtins,
+ module level functions, and class methods.
+ This document is divided in four major sections:
- Currently Argument Clinic is considered internal-only
+ * :ref:`clinic-background` talks about the basic concepts and goals of
+ Argument Clinic.
+ * :ref:`clinic-reference` describes the command-line interface and Argument
+ Clinic terminology.
+ * :ref:`clinic-tutorial` guides you through all the steps required to
+ adapt an existing C function to Argument Clinic.
+ * :ref:`clinic-howtos` details how to handle specific tasks.
+
+
+.. note::
+
+ Argument Clinic is considered internal-only
for CPython. Its use is not supported for files outside
CPython, and no guarantees are made regarding backwards
compatibility for future versions. In other words: if you
@@ -27,89 +40,35 @@ Argument Clinic How-To
version of Argument Clinic that ships with the next version
of CPython *could* be totally incompatible and break all your code.
-The Goals Of Argument Clinic
-============================
-
-Argument Clinic's primary goal
-is to take over responsibility for all argument parsing code
-inside CPython. This means that, when you convert a function
-to work with Argument Clinic, that function should no longer
-do any of its own argument parsing—the code generated by
-Argument Clinic should be a "black box" to you, where CPython
-calls in at the top, and your code gets called at the bottom,
-with ``PyObject *args`` (and maybe ``PyObject *kwargs``)
-magically converted into the C variables and types you need.
-
-In order for Argument Clinic to accomplish its primary goal,
-it must be easy to use. Currently, working with CPython's
-argument parsing library is a chore, requiring maintaining
-redundant information in a surprising number of places.
-When you use Argument Clinic, you don't have to repeat yourself.
-
-Obviously, no one would want to use Argument Clinic unless
-it's solving their problem—and without creating new problems of
-its own.
-So it's paramount that Argument Clinic generate correct code.
-It'd be nice if the code was faster, too, but at the very least
-it should not introduce a major speed regression. (Eventually Argument
-Clinic *should* make a major speedup possible—we could
-rewrite its code generator to produce tailor-made argument
-parsing code, rather than calling the general-purpose CPython
-argument parsing library. That would make for the fastest
-argument parsing possible!)
-
-Additionally, Argument Clinic must be flexible enough to
-work with any approach to argument parsing. Python has
-some functions with some very strange parsing behaviors;
-Argument Clinic's goal is to support all of them.
-
-Finally, the original motivation for Argument Clinic was
-to provide introspection "signatures" for CPython builtins.
-It used to be, the introspection query functions would throw
-an exception if you passed in a builtin. With Argument
-Clinic, that's a thing of the past!
-
-One idea you should keep in mind, as you work with
-Argument Clinic: the more information you give it, the
-better job it'll be able to do.
-Argument Clinic is admittedly relatively simple right
-now. But as it evolves it will get more sophisticated,
-and it should be able to do many interesting and smart
-things with all the information you give it.
-
-
-Basic Concepts And Usage
-========================
-
-Argument Clinic ships with CPython; you'll find it in ``Tools/clinic/clinic.py``.
-If you run that script, specifying a C file as an argument:
-.. code-block:: shell-session
+.. _clinic-background:
+
+Background
+==========
- $ python Tools/clinic/clinic.py foo.c
+Basic concepts
+--------------
-Argument Clinic will scan over the file looking for lines that
-look exactly like this:
+When Argument Clinic is run on a file, either via the :ref:`clinic-cli`
+or via ``make clinic``, it will scan over the input files looking for
+:term:`start lines `:
.. code-block:: none
/*[clinic input]
-When it finds one, it reads everything up to a line that looks
-exactly like this:
+When it finds one, it reads everything up to the :term:`end line`:
.. code-block:: none
[clinic start generated code]*/
-Everything in between these two lines is input for Argument Clinic.
-All of these lines, including the beginning and ending comment
-lines, are collectively called an Argument Clinic "block".
-
-When Argument Clinic parses one of these blocks, it
-generates output. This output is rewritten into the C file
-immediately after the block, followed by a comment containing a checksum.
-The Argument Clinic block now looks like this:
+Everything in between these two lines is Argument Clinic :term:`input`.
+When Argument Clinic parses input, it generates :term:`output`.
+The output is rewritten into the C file immediately after the input,
+followed by a :term:`checksum line`.
+All of these lines, including the :term:`start line` and :term:`checksum line`,
+are collectively called an Argument Clinic :term:`block`:
.. code-block:: none
@@ -117,472 +76,606 @@ The Argument Clinic block now looks like this:
... clinic input goes here ...
[clinic start generated code]*/
... clinic output goes here ...
- /*[clinic end generated code: checksum=...]*/
+ /*[clinic end generated code: ...]*/
If you run Argument Clinic on the same file a second time, Argument Clinic
-will discard the old output and write out the new output with a fresh checksum
-line. However, if the input hasn't changed, the output won't change either.
+will discard the old :term:`output` and write out the new output with a fresh
+:term:`checksum line`.
+If the :term:`input` hasn't changed, the output won't change either.
-You should never modify the output portion of an Argument Clinic block. Instead,
-change the input until it produces the output you want. (That's the purpose of the
-checksum—to detect if someone changed the output, as these edits would be lost
-the next time Argument Clinic writes out fresh output.)
+.. note::
-For the sake of clarity, here's the terminology we'll use with Argument Clinic:
+ You should never modify the output of an Argument Clinic block,
+ as any change will be lost in future Argument Clinic runs;
+ Argument Clinic will detect an output checksum mismatch and regenerate the
+ correct output.
+ If you are not happy with the generated output,
+ you should instead change the input until it produces the output you want.
-* The first line of the comment (``/*[clinic input]``) is the *start line*.
-* The last line of the initial comment (``[clinic start generated code]*/``) is the *end line*.
-* The last line (``/*[clinic end generated code: checksum=...]*/``) is the *checksum line*.
-* In between the start line and the end line is the *input*.
-* In between the end line and the checksum line is the *output*.
-* All the text collectively, from the start line to the checksum line inclusively,
- is the *block*. (A block that hasn't been successfully processed by Argument
- Clinic yet doesn't have output or a checksum line, but it's still considered
- a block.)
+.. _clinic-reference:
-Converting Your First Function
-==============================
+Reference
+=========
-The best way to get a sense of how Argument Clinic works is to
-convert a function to work with it. Here, then, are the bare
-minimum steps you'd need to follow to convert a function to
-work with Argument Clinic. Note that for code you plan to
-check in to CPython, you really should take the conversion farther,
-using some of the advanced concepts you'll see later on in
-the document (like "return converters" and "self converters").
-But we'll keep it simple for this walkthrough so you can learn.
-Let's dive in!
+.. _clinic-terminology:
-0. Make sure you're working with a freshly updated checkout
- of the CPython trunk.
+Terminology
+-----------
-1. Find a Python builtin that calls either :c:func:`PyArg_ParseTuple`
- or :c:func:`PyArg_ParseTupleAndKeywords`, and hasn't been converted
- to work with Argument Clinic yet.
- For my example I'm using ``_pickle.Pickler.dump()``.
+.. glossary::
-2. If the call to the ``PyArg_Parse`` function uses any of the
- following format units:
+ start line
+ The line ``/*[clinic input]``.
+ This line marks the beginning of Argument Clinic input.
+ Note that the *start line* opens a C block comment.
- .. code-block:: none
+ end line
+ The line ``[clinic start generated code]*/``.
+ The *end line* marks the _end_ of Argument Clinic :term:`input`,
+ but at the same time marks the _start_ of Argument Clinic :term:`output`,
+ thus the text *"clinic start start generated code"*
+ Note that the *end line* closes the C block comment opened
+ by the *start line*.
- O&
- O!
- es
- es#
- et
- et#
+ checksum
+ A hash to distinguish unique :term:`inputs `
+ and :term:`outputs