python-3.6.zip added from Github

README.cosmo contains the necessary links.

third_party/python/.azure-pipelines/ci.yml

@@ -0,0 +1,137 @@
+variables:
+  manylinux: false
+  coverage: false
+
+jobs:
+- job: Prebuild
+  displayName: Pre-build checks
+
+  pool:
+    vmImage: ubuntu-16.04
+
+  steps:
+  - 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-16.04
+
+  steps:
+  - template: ./docs-steps.yml
+    parameters:
+      upload: true
+
+
+- job: macOS_CI_Tests
+  displayName: macOS CI Tests
+  dependsOn: Prebuild
+  #condition: and(succeeded(), eq(dependencies.Prebuild.outputs['tests.run'], 'true'))
+  # bpo-39837: macOS tests on Azure Pipelines are disabled
+
+  variables:
+    testRunTitle: '$(build.sourceBranchName)-macos'
+    testRunPlatform: macos
+
+  pool:
+    vmImage: macos-10.14
+
+  steps:
+  - template: ./macos-steps.yml
+
+
+- job: Ubuntu_CI_Tests
+  displayName: Ubuntu CI Tests
+  dependsOn: Prebuild
+  condition: and(succeeded(), eq(dependencies.Prebuild.outputs['tests.run'], 'true'))
+
+  pool:
+    vmImage: ubuntu-16.04
+
+  variables:
+    testRunTitle: '$(build.sourceBranchName)-linux'
+    testRunPlatform: linux
+    openssl_version: 1.1.0g
+
+  steps:
+  - template: ./posix-steps.yml
+
+
+- job: ManyLinux1_CI_Tests
+  displayName: ManyLinux1 CI Tests
+  dependsOn: Prebuild
+  condition: |
+    and(
+        and(
+            succeeded(),
+            eq(variables['manylinux'], 'true')
+        ),
+        eq(dependencies.Prebuild.outputs['tests.run'], 'true')
+    )
+
+  pool:
+    vmImage: ubuntu-16.04
+
+  variables:
+    testRunTitle: '$(build.sourceBranchName)-manylinux1'
+    testRunPlatform: manylinux1
+    imageName: 'dockcross/manylinux-x64'
+
+  steps:
+  - template: ./docker-steps.yml
+
+
+- job: Ubuntu_Coverage_CI_Tests
+  displayName: Ubuntu CI Tests (coverage)
+  dependsOn: Prebuild
+  condition: |
+    and(
+        and(
+            succeeded(),
+            eq(variables['coverage'], 'true')
+        ),
+        eq(dependencies.Prebuild.outputs['tests.run'], 'true')
+    )
+
+  pool:
+    vmImage: ubuntu-16.04
+
+  variables:
+    testRunTitle: '$(Build.SourceBranchName)-linux-coverage'
+    testRunPlatform: linux-coverage
+    openssl_version: 1.1.0g
+
+  steps:
+  - template: ./posix-steps.yml
+    parameters:
+      coverage: true
+
+
+- job: Windows_CI_Tests
+  displayName: Windows CI Tests
+  dependsOn: Prebuild
+  condition: and(succeeded(), eq(dependencies.Prebuild.outputs['tests.run'], 'true'))
+
+  pool:
+    vmImage: vs2017-win2016
+
+  strategy:
+    matrix:
+      win32:
+        arch: win32
+        buildOpt:
+        testRunTitle: '$(Build.SourceBranchName)-win32'
+        testRunPlatform: win32
+      win64:
+        arch: amd64
+        buildOpt: '-p x64'
+        testRunTitle: '$(Build.SourceBranchName)-win64'
+        testRunPlatform: win64
+    maxParallel: 2
+
+  steps:
+  - template: ./windows-steps.yml

third_party/python/.azure-pipelines/docker-steps.yml

@@ -0,0 +1,76 @@
+steps:
+- checkout: self
+  clean: true
+  fetchDepth: 5
+
+- ${{ if ne(parameters.targetBranch, '') }}:
+  - script: |
+     git fetch -q origin ${{ parameters.targetbranch }}
+     if ! git diff --name-only HEAD $(git merge-base HEAD FETCH_HEAD) | grep -qvE '(\.rst$|^Doc|^Misc)'
+     then
+       echo "Only docs were updated, stopping build process."
+       echo "##vso[task.setvariable variable=DocOnly]true"
+       exit
+     fi
+    displayName: Detect doc-only changes
+
+- task: docker@0
+  displayName: 'Configure CPython (debug)'
+  inputs:
+    action: 'Run an image'
+    imageName: $(imageName)
+    volumes: |
+      $(build.sourcesDirectory):/src
+      $(build.binariesDirectory):/build
+    workDir: '/src'
+    containerCommand: './configure --with-pydebug'
+    detached: false
+  condition: and(succeeded(), ne(variables['DocOnly'], 'true'))
+
+- task: docker@0
+  displayName: 'Build CPython'
+  inputs:
+    action: 'Run an image'
+    imageName: $(imageName)
+    volumes: |
+      $(build.sourcesDirectory):/src
+      $(build.binariesDirectory):/build
+    workDir: '/src'
+    containerCommand: 'make -s -j4'
+    detached: false
+  condition: and(succeeded(), ne(variables['DocOnly'], 'true'))
+
+- task: docker@0
+  displayName: 'Display build info'
+  inputs:
+    action: 'Run an image'
+    imageName: $(imageName)
+    volumes: |
+      $(build.sourcesDirectory):/src
+      $(build.binariesDirectory):/build
+    workDir: '/src'
+    containerCommand: 'make pythoninfo'
+    detached: false
+  condition: and(succeeded(), ne(variables['DocOnly'], 'true'))
+
+- task: docker@0
+  displayName: 'Tests'
+  inputs:
+    action: 'Run an image'
+    imageName: $(imageName)
+    volumes: |
+      $(build.sourcesDirectory):/src
+      $(build.binariesDirectory):/build
+    workDir: '/src'
+    containerCommand: 'make buildbottest TESTOPTS="-j4 -uall,-cpu --junit-xml=/build/test-results.xml"'
+    detached: false
+  condition: and(succeeded(), ne(variables['DocOnly'], 'true'))
+
+- task: PublishTestResults@2
+  displayName: 'Publish Test Results'
+  inputs:
+    testResultsFiles: '$(build.binariesDirectory)/test-results.xml'
+    mergeTestResults: true
+    testRunTitle: $(testRunTitle)
+    platform: $(testRunPlatform)
+  condition: and(succeededOrFailed(), ne(variables['DocOnly'], 'true'))

third_party/python/.azure-pipelines/docs-steps.yml

@@ -0,0 +1,46 @@
+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 sphinx==1.8.2 blurb python-docs-theme
+  displayName: 'Install build dependencies'
+
+- ${{ if ne(parameters.latex, 'true') }}:
+  - script: make check suspicious 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

third_party/python/.azure-pipelines/macos-steps.yml

@@ -0,0 +1,27 @@
+steps:
+- checkout: self
+  clean: true
+  fetchDepth: 5
+
+- script: ./configure --with-pydebug --with-openssl=/usr/local/opt/openssl --prefix=/opt/python-azdev
+  displayName: 'Configure CPython (debug)'
+
+- script: make -j4
+  displayName: 'Build CPython'
+
+- script: make pythoninfo
+  displayName: 'Display build info'
+
+- script: make buildbottest TESTOPTS="-j4 -uall,-cpu --junit-xml=$(build.binariesDirectory)/test-results.xml"
+  displayName: 'Tests'
+  continueOnError: true
+  timeoutInMinutes: 30
+
+- task: PublishTestResults@2
+  displayName: 'Publish Test Results'
+  inputs:
+    testResultsFiles: '$(build.binariesDirectory)/test-results.xml'
+    mergeTestResults: true
+    testRunTitle: $(testRunTitle)
+    platform: $(testRunPlatform)
+  condition: succeededOrFailed()

third_party/python/.azure-pipelines/posix-deps.sh

@@ -0,0 +1,26 @@
+sudo apt-get update
+
+sudo apt-get -yq install \
+    build-essential \
+    zlib1g-dev \
+    libbz2-dev \
+    liblzma-dev \
+    libncurses5-dev \
+    libreadline6-dev \
+    libsqlite3-dev \
+    libssl-dev \
+    libgdbm-dev \
+    tk-dev \
+    lzma \
+    lzma-dev \
+    liblzma-dev \
+    libffi-dev \
+    uuid-dev \
+    xvfb
+
+if [ ! -z "$1" ]
+then
+  echo ##vso[task.prependpath]$PWD/multissl/openssl/$1
+  echo ##vso[task.setvariable variable=OPENSSL_DIR]$PWD/multissl/openssl/$1
+  python3 Tools/ssl/multissltests.py --steps=library --base-directory $PWD/multissl --openssl $1 --system Linux
+fi

third_party/python/.azure-pipelines/posix-steps.yml

@@ -0,0 +1,63 @@
+parameters:
+  coverage: false
+
+steps:
+- checkout: self
+  clean: true
+  fetchDepth: 5
+
+- script: ./.azure-pipelines/posix-deps.sh $(openssl_version)
+  displayName: 'Install dependencies'
+
+- script: ./configure --with-pydebug
+  displayName: 'Configure CPython (debug)'
+
+- script: make -s -j4
+  displayName: 'Build CPython'
+
+- ${{ if eq(parameters.coverage, 'true') }}:
+  - script: ./python -m venv venv && ./venv/bin/python -m pip install -U coverage
+    displayName: 'Set up virtual environment'
+
+  - script: ./venv/bin/python -m test.pythoninfo
+    displayName: 'Display build info'
+
+  - script: |
+      xvfb-run ./venv/bin/python -m coverage run --pylib -m test \
+                --fail-env-changed \
+                -uall,-cpu \
+                --junit-xml=$(build.binariesDirectory)/test-results.xml" \
+                -x test_multiprocessing_fork \
+                -x test_multiprocessing_forkserver \
+                -x test_multiprocessing_spawn \
+                -x test_concurrent_futures
+    displayName: 'Tests with coverage'
+
+  - script: ./venv/bin/python -m coverage xml
+    displayName: 'Generate coverage.xml'
+
+  - script: source ./venv/bin/activate && bash <(curl -s https://codecov.io/bash)
+    displayName: 'Publish code coverage results'
+
+
+- ${{ if ne(parameters.coverage, 'true') }}:
+  - script: make pythoninfo
+    displayName: 'Display build info'
+
+  - script: xvfb-run make buildbottest TESTOPTS="-j4 -uall,-cpu --junit-xml=$(build.binariesDirectory)/test-results.xml"
+    displayName: 'Tests'
+
+
+- script: ./python Tools/scripts/patchcheck.py --travis true
+  displayName: 'Run patchcheck.py'
+  condition: and(succeeded(), eq(variables['Build.Reason'], 'PullRequest'))
+
+
+- task: PublishTestResults@2
+  displayName: 'Publish Test Results'
+  inputs:
+    testResultsFiles: '$(build.binariesDirectory)/test-results.xml'
+    mergeTestResults: true
+    testRunTitle: $(testRunTitle)
+    platform: $(testRunPlatform)
+  condition: succeededOrFailed()

third_party/python/.azure-pipelines/pr.yml

@@ -0,0 +1,88 @@
+jobs:
+- job: Prebuild
+  displayName: Pre-build checks
+
+  pool:
+    vmImage: ubuntu-16.04
+
+  steps:
+  - 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-16.04
+
+  steps:
+  - template: ./docs-steps.yml
+
+
+- job: macOS_PR_Tests
+  displayName: macOS PR Tests
+  dependsOn: Prebuild
+  condition: and(succeeded(), eq(dependencies.Prebuild.outputs['tests.run'], 'true'))
+  #condition: and(succeeded(), eq(dependencies.Prebuild.outputs['tests.run'], 'true'))
+  # bpo-39837: macOS tests on Azure Pipelines are disabled
+
+  variables:
+    testRunTitle: '$(system.pullRequest.TargetBranch)-macos'
+    testRunPlatform: macos
+
+  pool:
+    vmImage: macos-10.14
+
+  steps:
+  - template: ./macos-steps.yml
+    parameters:
+      targetBranch: $(System.PullRequest.TargetBranch)
+
+
+- job: Ubuntu_PR_Tests
+  displayName: Ubuntu PR Tests
+  dependsOn: Prebuild
+  condition: and(succeeded(), eq(dependencies.Prebuild.outputs['tests.run'], 'true'))
+
+  pool:
+    vmImage: ubuntu-16.04
+
+  variables:
+    testRunTitle: '$(system.pullRequest.TargetBranch)-linux'
+    testRunPlatform: linux
+    openssl_version: 1.1.0g
+
+  steps:
+  - template: ./posix-steps.yml
+    parameters:
+      targetBranch: $(System.PullRequest.TargetBranch)
+
+
+- job: Windows_PR_Tests
+  displayName: Windows PR Tests
+  dependsOn: Prebuild
+  condition: and(succeeded(), eq(dependencies.Prebuild.outputs['tests.run'], 'true'))
+
+  pool:
+    vmImage: vs2017-win2016
+
+  strategy:
+    matrix:
+      win32:
+        arch: win32
+        buildOpt:
+        testRunTitle: '$(System.PullRequest.TargetBranch)-win32'
+        testRunPlatform: win32
+      win64:
+        arch: amd64
+        buildOpt: '-p x64'
+        testRunTitle: '$(System.PullRequest.TargetBranch)-win64'
+        testRunPlatform: win64
+    maxParallel: 2
+
+  steps:
+  - template: ./windows-steps.yml
+    parameters:
+      targetBranch: $(System.PullRequest.TargetBranch)

third_party/python/.azure-pipelines/prebuild-checks.yml

@@ -0,0 +1,36 @@
+steps:
+- checkout: self
+  fetchDepth: 5
+
+- script: echo "##vso[task.setvariable variable=diffTarget]HEAD~1"
+  displayName: Set default diff target
+
+- script: |
+    git fetch -q origin $(System.PullRequest.TargetBranch)
+    echo "##vso[task.setvariable variable=diffTarget]HEAD \$(git merge-base HEAD FETCH_HEAD)"
+  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
+     echo "Only docs were updated: tests.run=false"
+     echo "##vso[task.setvariable variable=run;isOutput=true]false"
+   else
+     echo "Code was updated: tests.run=true"
+     echo "##vso[task.setvariable variable=run;isOutput=true]true"
+   fi
+  displayName: Detect source changes
+  name: tests

third_party/python/.azure-pipelines/windows-steps.yml

@@ -0,0 +1,32 @@
+steps:
+- checkout: self
+  clean: true
+  fetchDepth: 5
+
+- powershell: |
+    # Relocate build outputs outside of source directory to make cleaning faster
+    Write-Host '##vso[task.setvariable variable=Py_IntDir]$(Build.BinariesDirectory)\obj'
+    # UNDONE: Do not build to a different directory because of broken tests
+    Write-Host '##vso[task.setvariable variable=Py_OutDir]$(Build.SourcesDirectory)\PCbuild'
+    Write-Host '##vso[task.setvariable variable=EXTERNAL_DIR]$(Build.BinariesDirectory)\externals'
+  displayName: Update build locations
+
+- script: PCbuild\build.bat -e $(buildOpt)
+  displayName: 'Build CPython'
+
+- script: python.bat -m test.pythoninfo
+  displayName: 'Display build info'
+
+- script: PCbuild\rt.bat -q -uall -u-cpu -rwW --slowest --timeout=1200 -j0 --junit-xml="$(Build.BinariesDirectory)\test-results.xml"
+  displayName: 'Tests'
+  env:
+    PREFIX: $(Py_OutDir)\$(arch)
+
+- task: PublishTestResults@2
+  displayName: 'Publish Test Results'
+  inputs:
+    testResultsFiles: '$(Build.BinariesDirectory)\test-results.xml'
+    mergeTestResults: true
+    testRunTitle: $(testRunTitle)
+    platform: $(testRunPlatform)
+  condition: succeededOrFailed()

third_party/python/.bzrignore

@@ -0,0 +1,42 @@
+.purify
+autom4te.cache
+config.log
+config.cache
+config.status
+config.status.lineno
+db_home
+Makefile
+buildno
+python
+build
+Makefile.pre
+platform
+pybuilddir.txt
+pyconfig.h
+libpython*.a
+libpython*.so*
+python.exe
+python-gdb.py
+reflog.txt
+tags
+TAGS
+.gdb_history
+Doc/tools/sphinx
+Doc/tools/jinja
+Doc/tools/jinja2
+Doc/tools/pygments
+Doc/tools/docutils
+Misc/python.pc
+Modules/Setup
+Modules/Setup.config
+Modules/Setup.local
+Modules/config.c
+Modules/ld_so_aix
+Parser/pgen
+Lib/test/data/*
+Lib/lib2to3/Grammar*.pickle
+Lib/lib2to3/PatternGrammar*.pickle
+__pycache__
+.coverage
+coverage/*
+htmlcov/*

third_party/python/.gitattributes

@@ -0,0 +1,58 @@
+# Binary data types
+*.aif binary
+*.aifc binary
+*.aiff binary
+*.au binary
+*.bmp binary
+*.exe binary
+*.icns binary
+*.gif binary
+*.ico binary
+*.jpg binary
+*.pck binary
+*.png binary
+*.psd binary
+*.tar binary
+*.wav binary
+*.whl binary
+*.zip binary
+
+# Specific binary files
+Lib/test/sndhdrdata/sndhdr.* binary
+
+# Text files that should not be subject to eol conversion
+Lib/test/cjkencodings/* -text
+Lib/test/decimaltestdata/*.decTest -text
+Lib/test/test_email/data/*.txt -text
+Lib/test/xmltestdata/* -text
+Lib/test/coding20731.py -text
+
+# Special files in third party code
+Modules/zlib/zlib.map -text
+
+# CRLF files
+*.bat text eol=crlf
+*.ps1 text eol=crlf
+*.sln text eol=crlf
+*.vcxproj* text eol=crlf
+*.props text eol=crlf
+*.proj text eol=crlf
+PCbuild/readme.txt text eol=crlf
+PC/readme.txt text eol=crlf
+
+# Generated files
+# https://github.com/github/linguist#generated-code
+Include/graminit.h          linguist-generated=true
+Python/graminit.h           linguist-generated=true
+Modules/clinic/*.h          linguist-generated=true
+Objects/clinic/*.h          linguist-generated=true
+PC/clinic/*.h               linguist-generated=true
+Python/clinic/*.h           linguist-generated=true
+Python/importlib.h          linguist-generated=true
+Python/importlib_external.h linguist-generated=true
+Include/Python-ast.h        linguist-generated=true
+Python/Python-ast.c         linguist-generated=true
+Include/opcode.h            linguist-generated=true
+Python/opcode_targets.h     linguist-generated=true
+Objects/typeslots.inc       linguist-generated=true
+Modules/unicodedata_db.h    linguist-generated=true

third_party/python/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,9 @@
+## CPython Mirror
+
+https://github.com/python/cpython is a cpython mirror repository. Pull requests
+are not accepted on this repo and will be automatically closed.
+
+### Submit patches at https://bugs.python.org
+
+For additional information about contributing to CPython, see the
+[developer's guide](https://docs.python.org/devguide/#contributing).

third_party/python/.github/appveyor.yml

@@ -0,0 +1,38 @@
+version: 3.6build{build}
+clone_depth: 5
+branches:
+  only:
+    - master
+    - /\d\.\d/
+    - buildbot-custom
+cache:
+  - externals -> PCbuild\*
+before_build:
+  - ps: |+
+      if ($env:APPVEYOR_RE_BUILD) {
+        echo 'Doing full build due to re-build request.'
+      } elseif (!$env:APPVEYOR_PULL_REQUEST_HEAD_COMMIT) {
+        echo 'Not a PR, doing full build.'
+      } else {
+        git fetch -q origin +refs/heads/$env:APPVEYOR_REPO_BRANCH
+        $mergebase = git merge-base HEAD FETCH_HEAD
+        $changes = git diff --name-only HEAD $mergebase | grep -vE '(\.rst$)|(^Doc)|(^Misc)'
+        If (!$changes) {
+          echo 'Only docs were updated, stopping build process.'
+          Exit-AppveyorBuild
+        } else {
+          echo 'Doing full build due to non-doc changes in these files:'
+          echo $changes
+        }
+      }
+
+
+build_script:
+  - cmd: PCbuild\build.bat -e
+  - cmd: PCbuild\win32\python.exe -m test.pythoninfo
+test_script:
+  - cmd: PCbuild\rt.bat -q -uall -u-cpu -u-largefile -rwW --slowest --timeout=1200 -j0
+environment:
+  HOST_PYTHON: C:\Python36\python.exe
+image:
+  - Visual Studio 2015

third_party/python/.github/codecov.yml

@@ -0,0 +1,30 @@
+codecov:
+  strict_yaml_branch: master
+  notify:
+    require_ci_to_pass: true
+comment: off
+ignore:
+  - "Doc/**/*"
+  - "Misc/**/*"
+  - "Mac/**/*"
+  - "PC/**/*"
+  - "PCbuild/**/*"
+  - "Tools/**/*"
+  - "Grammar/*"
+coverage:
+  precision: 2
+  range: 70...90
+  round: down
+  status:
+    changes: off
+    project: off
+    patch: off
+parsers:
+  gcov:
+    branch_detection:
+      conditional: true
+      loop: true
+      macro: false
+      method: false
+  javascript:
+    enable_partials: false

third_party/python/.gitignore

@@ -0,0 +1,103 @@
+# Two-trick pony for OSX and other case insensitive file systems:
+# Ignore ./python binary on Unix but still look into ./Python/ directory.
+/python
+!/Python/
+*.cover
+*.o
+*.orig
+*.pyc
+*.pyd
+*.pyo
+*.rej
+*.swp
+*~
+*.gc??
+*.profclang?
+*.profraw
+*.dyn
+.gdb_history
+Doc/build/
+Doc/venv/
+Doc/.venv/
+Doc/env/
+Doc/.env/
+Include/pydtrace_probes.h
+Lib/distutils/command/*.pdb
+Lib/lib2to3/*.pickle
+Lib/test/data/*
+Makefile
+Makefile.pre
+Misc/python.pc
+Misc/python-config.sh
+Modules/Setup
+Modules/Setup.config
+Modules/Setup.local
+Modules/config.c
+Modules/ld_so_aix
+Programs/_freeze_importlib
+Programs/_testembed
+PC/python_nt*.h
+PC/pythonnt_rc*.h
+PC/*/*.exe
+PC/*/*.exp
+PC/*/*.lib
+PC/*/*.bsc
+PC/*/*.dll
+PC/*/*.pdb
+PC/*/*.user
+PC/*/*.ncb
+PC/*/*.suo
+PC/*/Win32-temp-*
+PC/*/x64-temp-*
+PC/*/amd64
+PCbuild/*.user
+PCbuild/*.suo
+PCbuild/*.*sdf
+PCbuild/*-pgi
+PCbuild/*-pgo
+PCbuild/*.VC.db
+PCbuild/*.VC.opendb
+PCbuild/.vs/
+PCbuild/amd64/
+PCbuild/obj/
+PCbuild/win32/
+.purify
+Parser/pgen
+__pycache__
+autom4te.cache
+build/
+buildno
+config.cache
+config.log
+config.status
+config.status.lineno
+core
+db_home
+.hg/
+ipch/
+libpython*.a
+libpython*.so*
+libpython*.dylib
+platform
+pybuilddir.txt
+pyconfig.h
+python-config
+python-config.py
+python.bat
+python.exe
+python-gdb.py
+python.exe-gdb.py
+reflog.txt
+.svn/
+tags
+TAGS
+.coverage
+coverage/
+externals/
+htmlcov/
+Tools/msi/obj
+Tools/ssl/amd64
+Tools/ssl/win32
+.vs/
+.vscode/
+gmon.out

third_party/python/.hgignore

@@ -0,0 +1,105 @@
+.gdb_history
+.purify
+.svn/
+^.idea/
+^.vscode/
+.DS_Store
+Makefile$
+Makefile.pre$
+TAGS$
+autom4te.cache$
+^build/
+^Doc/build/
+^Doc/venv/
+buildno$
+config.cache
+config.log
+config.status
+config.status.lineno
+db_home
+platform$
+pyconfig.h$
+python$
+python.bat$
+python.exe$
+python-config$
+python-config.py$
+reflog.txt$
+tags$
+Misc/python.pc
+Misc/python-config.sh$
+Modules/Setup$
+Modules/Setup.config
+Modules/Setup.local
+Modules/config.c
+Modules/ld_so_aix$
+Parser/pgen$
+^lcov-report/
+^core
+^python-gdb.py
+^python.exe-gdb.py
+^pybuilddir.txt
+
+syntax: glob
+libpython*.a
+libpython*.so*
+libpython*.dylib
+*.swp
+*.o
+*.pyc
+*.pyo
+*.pyd
+*.cover
+*~
+*.gc??
+*.profclang?
+*.profraw
+*.dyn
+Include/pydtrace_probes.h
+Lib/distutils/command/*.pdb
+Lib/lib2to3/*.pickle
+Lib/test/data/*
+Misc/*.wpu
+PC/python_nt*.h
+PC/pythonnt_rc*.h
+PC/*/*.exe
+PC/*/*.exp
+PC/*/*.lib
+PC/*/*.bsc
+PC/*/*.dll
+PC/*/*.pdb
+PC/*/*.user
+PC/*/*.ncb
+PC/*/*.suo
+PC/*/Win32-temp-*
+PC/*/x64-temp-*
+PC/*/amd64
+PCbuild/*.user
+PCbuild/*.suo
+PCbuild/*.*sdf
+PCbuild/*-pgi
+PCbuild/*-pgo
+PCbuild/.vs
+PCbuild/amd64
+PCbuild/obj
+PCbuild/win32
+Tools/unicode/build/
+Tools/unicode/MAPPINGS/
+BuildLog.htm
+__pycache__
+Programs/_freeze_importlib
+Programs/_testembed
+.coverage
+coverage/
+externals/
+htmlcov/
+*.gcda
+*.gcno
+*.gcov
+ipch/
+coverage.info
+Tools/msi/obj
+Tools/ssl/amd64
+Tools/ssl/win32
+.vs/
+.vscode/

third_party/python/.travis.yml

@@ -0,0 +1,135 @@
+language: c
+dist: xenial
+
+# To cache doc-building dependencies and C compiler output.
+cache:
+  - pip
+  - ccache
+
+env:
+  global:
+    # Use -O3 because we don't use debugger on Travis-CI
+    - CFLAGS="-O3"
+
+branches:
+  only:
+    - master
+    - /^\d\.\d$/
+    - buildbot-custom
+
+matrix:
+  fast_finish: true
+  allow_failures:
+    - env: OPTIONAL=true
+  include:
+    - os: linux
+      language: c
+      compiler: clang
+      # gcc also works, but to keep the # of concurrent builds down, we use one C
+      # compiler here and the other to run the coverage build. Clang is preferred
+      # in this instance for its better error messages.
+      env: TESTING=cpython
+      addons:
+        apt:
+          packages:
+            - xvfb
+    - os: linux
+      language: python
+      python: 3.6
+      env: TESTING=docs
+      before_script:
+        - cd Doc
+        # Sphinx is pinned so that new versions that introduce new warnings won't suddenly cause build failures.
+        # (Updating the version is fine as long as no warnings are raised by doing so.)
+        - python -m pip install sphinx==1.8.2 blurb
+      script:
+        - make check suspicious html SPHINXOPTS="-q -W -j4"
+    - os: linux
+      language: c
+      compiler: gcc
+      env: OPTIONAL=true
+      addons:
+        apt:
+          packages:
+            - xvfb
+      before_script:
+        - ./configure PYTHON_FOR_REGEN=python3
+        - make -s -j4
+        # Need a venv that can parse covered code.
+        - ./python -m venv venv
+        - ./venv/bin/python -m pip install -U coverage
+        - ./venv/bin/python -m test.pythoninfo
+      script:
+        # Skip tests that re-run the entire test suite.
+        - xvfb-run ./venv/bin/python -m coverage run --pylib -m test -uall,-cpu -x test_multiprocessing_fork -x test_multiprocessing_forkserver -x test_multiprocessing_spawn
+      after_script:  # Probably should be after_success once test suite updated to run under coverage.py.
+        # Make the `coverage` command available to Codecov w/ a version of Python that can parse all source files.
+        - source ./venv/bin/activate
+        - bash <(curl -s https://codecov.io/bash)
+
+
+before_install:
+  - set -e
+  - |
+      # Check short-circuit conditions
+      if [ "${TESTING}" != "docs" ]
+      then
+        if [ "$TRAVIS_PULL_REQUEST" = "false" ]
+        then
+          echo "Not a PR, doing full build."
+        else
+          # Pull requests are slightly complicated because $TRAVIS_COMMIT_RANGE
+          # may include more changes than desired if the history is convoluted.
+          # Instead, explicitly fetch the base branch and compare against the
+          # merge-base commit.
+          git fetch -q origin +refs/heads/$TRAVIS_BRANCH
+          changes=$(git diff --name-only HEAD $(git merge-base HEAD FETCH_HEAD))
+          echo "Files changed:"
+          echo "$changes"
+          if ! echo "$changes" | grep -qvE '(\.rst$)|(^Doc)|(^Misc)'
+          then
+            echo "Only docs were updated, stopping build process."
+            exit
+          fi
+        fi
+      fi
+
+# Travis provides only 2 cores, so don't overdo the parallelism and waste memory.
+before_script:
+  - ./configure --with-pydebug PYTHON_FOR_REGEN=python3
+  - make -j4 regen-all
+  - changes=`git status --porcelain`
+  - |
+      # Check for changes in regenerated files
+      if ! test -z "$changes"
+      then
+        echo "Generated files not up to date"
+        echo "$changes"
+        exit 1
+      fi
+  - make -j4
+  - make pythoninfo
+
+script:
+  # Using the built Python as patchcheck.py is built around the idea of using
+  # a checkout-build of CPython to know things like what base branch the changes
+  # should be compared against.
+  # Only run on Linux as the check only needs to be run once.
+  - if [[ "$TRAVIS_OS_NAME" == "linux" ]]; then ./python Tools/scripts/patchcheck.py --travis $TRAVIS_PULL_REQUEST; fi
+  # Check that all symbols exported by libpython start with "Py" or "_Py"
+  - make smelly
+  # `-r -w` implicitly provided through `make buildbottest`.
+  - if [[ "$TRAVIS_OS_NAME" == "linux" ]]; then XVFB_RUN=xvfb-run; fi; $XVFB_RUN make buildbottest TESTOPTS="-j4 -uall,-cpu"
+
+notifications:
+  email: false
+  irc:
+    channels:
+      # This is set to a secure variable to prevent forks from notifying the
+      # IRC channel whenever they fail a build. This can be removed when travis
+      # implements https://github.com/travis-ci/travis-ci/issues/1094.
+      # The actual value here is: irc.freenode.net#python-dev
+      - secure: "s7kAkpcom2yUJ8XqyjFI0obJmhAGrn1xmoivdaPdgBIA++X47TBp1x4pgDsbEsoalef7bEwa4l07KdT4qa+DOd/c4QxaWom7fbN3BuLVsZuVfODnl79+gYq/TAbGfyH+yDs18DXrUfPgwD7C5aW32ugsqAOd4iWzfGJQ5OrOZzqzGjYdYQUEkJFXgxDEIb4aHvxNDWGO3Po9uKISrhb5saQ0l776yLo1Ur7M4oxl8RTbCdgX0vf5TzPg52BgvZpOgt3DHOUYPeiJLKNjAE6ibg0U95sEvMfHX77nz4aFY4/3UI6FFaRla34rZ+mYKrn0TdxOhera1QOgPmM6HzdO4K44FpfK1DS0Xxk9U9/uApq+cG0bU3W+cVUHDBe5+90lpRBAXHeHCgT7TI8gec614aiT8lEr3+yH8OBRYGzkjNK8E2LJZ/SxnVxDe7aLF6AWcoWLfS6/ziAIBFQ5Nc4U72CT8fGVSkl8ywPiRlvixKdvTODMSZo0jMqlfZSNaAPTsNRx4wu5Uis4qekwe32Fz4aB6KGpsuuVjBi+H6v0RKxNJNGY3JKDiEH2TK0UE2auJ5GvLW48aUVFcQMB7euCWYXlSWVRHh3WLU8QXF29Dw4JduRZqUpOdRgMHU79UHRq+mkE0jAS/nBcS6CvsmxCpTSrfVYuMOu32yt18QQoTyU="
+    on_success: change
+    on_failure: always
+    skip_join: true

third_party/python/Doc/README.rst

@@ -0,0 +1,138 @@
+Python Documentation README
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This directory contains the reStructuredText (reST) sources to the Python
+documentation.  You don't need to build them yourself, `prebuilt versions are
+available <https://docs.python.org/dev/download.html>`_.
+
+Documentation on authoring Python documentation, including information about
+both style and markup, is available in the "`Documenting Python
+<https://devguide.python.org/documenting/>`_" chapter of the
+developers guide.
+
+
+Building the docs
+=================
+
+The documentation is built with several tools which are not included in this
+tree but are maintained separately and are available from
+`PyPI <https://pypi.org/>`_.
+
+* `Sphinx <https://pypi.org/project/Sphinx/>`_
+* `blurb <https://pypi.org/project/blurb/>`_
+
+The easiest way to install these tools is to create a virtual environment and
+install the tools into there.
+
+
+Using make
+----------
+
+To get started on UNIX, you can create a virtual environment with the command ::
+
+  make venv
+
+That will install all the tools necessary to build the documentation. Assuming
+the virtual environment was created in the ``venv`` directory (the default;
+configurable with the VENVDIR variable), you can run the following command to
+build the HTML output files::
+
+  make html
+
+By default, if the virtual environment is not created, the Makefile will
+look for instances of sphinxbuild and blurb installed on your process PATH
+(configurable with the SPHINXBUILD and BLURB variables).
+
+On Windows, we try to emulate the Makefile as closely as possible with a
+``make.bat`` file. If you need to specify the Python interpreter to use,
+set the PYTHON environment variable instead.
+
+Available make targets are:
+
+* "clean", which removes all build files.
+
+* "venv", which creates a virtual environment with all necessary tools
+  installed.
+
+* "html", which builds standalone HTML files for offline viewing.
+
+* "htmlview", which re-uses the "html" builder, but then opens the main page
+  in your default web browser.
+
+* "htmlhelp", which builds HTML files and a HTML Help project file usable to
+  convert them into a single Compiled HTML (.chm) file -- these are popular
+  under Microsoft Windows, but very handy on every platform.
+
+  To create the CHM file, you need to run the Microsoft HTML Help Workshop
+  over the generated project (.hhp) file.  The make.bat script does this for
+  you on Windows.
+
+* "latex", which builds LaTeX source files as input to "pdflatex" to produce
+  PDF documents.
+
+* "text", which builds a plain text file for each source file.
+
+* "epub", which builds an EPUB document, suitable to be viewed on e-book
+  readers.
+
+* "linkcheck", which checks all external references to see whether they are
+  broken, redirected or malformed, and outputs this information to stdout as
+  well as a plain-text (.txt) file.
+
+* "changes", which builds an overview over all versionadded/versionchanged/
+  deprecated items in the current version. This is meant as a help for the
+  writer of the "What's New" document.
+
+* "coverage", which builds a coverage overview for standard library modules and
+  C API.
+
+* "pydoc-topics", which builds a Python module containing a dictionary with
+  plain text documentation for the labels defined in
+  `tools/pyspecific.py` -- pydoc needs these to show topic and keyword help.
+
+* "suspicious", which checks the parsed markup for text that looks like
+  malformed and thus unconverted reST.
+
+* "check", which checks for frequent markup errors.
+
+* "serve", which serves the build/html directory on port 8000.
+
+* "dist", (Unix only) which creates distributable archives of HTML, text,
+  PDF, and EPUB builds.
+
+
+Without make
+------------
+
+First, install the tool dependencies from PyPI.
+
+Then, from the ``Doc`` directory, run ::
+
+   sphinx-build -b<builder> . build/<builder>
+
+where ``<builder>`` is one of html, text, latex, or htmlhelp (for explanations
+see the make targets above).
+
+Deprecation header
+==================
+
+You can define the ``outdated`` variable in ``html_context`` to show a
+red banner on each page redirecting to the "latest" version.
+
+The link points to the same page on ``/3/``, sadly for the moment the
+language is lost during the process.
+
+
+Contributing
+============
+
+Bugs in the content should be reported to the
+`Python bug tracker <https://bugs.python.org>`_.
+
+Bugs in the toolset should be reported to the tools themselves.
+
+You can also send a mail to the Python Documentation Team at docs@python.org,
+and we will process your request as soon as possible.
+
+If you want to help the Documentation Team, you are always welcome.  Just send
+a mail to docs@python.org.

third_party/python/Doc/about.rst

@@ -0,0 +1,39 @@
+=====================
+About these documents
+=====================
+
+
+These documents are generated from `reStructuredText`_ sources by `Sphinx`_, a
+document processor specifically written for the Python documentation.
+
+.. _reStructuredText: http://docutils.sourceforge.net/rst.html
+.. _Sphinx: http://sphinx-doc.org/
+
+.. In the online version of these documents, you can submit comments and suggest
+   changes directly on the documentation pages.
+
+Development of the documentation and its toolchain is an entirely volunteer
+effort, just like Python itself.  If you want to contribute, please take a
+look at the :ref:`reporting-bugs` page for information on how to do so.  New
+volunteers are always welcome!
+
+Many thanks go to:
+
+* Fred L. Drake, Jr., the creator of the original Python documentation toolset
+  and writer of much of the content;
+* the `Docutils <http://docutils.sourceforge.net/>`_ project for creating
+  reStructuredText and the Docutils suite;
+* Fredrik Lundh for his `Alternative Python Reference
+  <http://effbot.org/zone/pyref.htm>`_ project from which Sphinx got many good
+  ideas.
+
+
+Contributors to the Python Documentation
+----------------------------------------
+
+Many people have contributed to the Python language, the Python standard
+library, and the Python documentation.  See :source:`Misc/ACKS` in the Python
+source distribution for a partial list of contributors.
+
+It is only with the input and contributions of the Python community
+that Python has such wonderful documentation -- Thank You!

third_party/python/Doc/bugs.rst

@@ -0,0 +1,92 @@
+.. _reporting-bugs:
+
+*****************
+Dealing with Bugs
+*****************
+
+Python is a mature programming language which has established a reputation for
+stability.  In order to maintain this reputation, the developers would like to
+know of any deficiencies you find in Python.
+
+It can be sometimes faster to fix bugs yourself and contribute patches to
+Python as it streamlines the process and involves less people. Learn how to
+:ref:`contribute <contributing-to-python>`.
+
+Documentation bugs
+==================
+
+If you find a bug in this documentation or would like to propose an improvement,
+please submit a bug report on the :ref:`tracker <using-the-tracker>`.  If you
+have a suggestion how to fix it, include that as well.
+
+If you're short on time, you can also email documentation bug reports to
+docs@python.org (behavioral bugs can be sent to python-list@python.org).
+'docs@' is a mailing list run by volunteers; your request will be noticed,
+though it may take a while to be processed.
+
+.. seealso::
+   `Documentation bugs`_ on the Python issue tracker
+
+.. _using-the-tracker:
+
+Using the Python issue tracker
+==============================
+
+Bug reports for Python itself should be submitted via the Python Bug Tracker
+(https://bugs.python.org/).  The bug tracker offers a Web form which allows
+pertinent information to be entered and submitted to the developers.
+
+The first step in filing a report is to determine whether the problem has
+already been reported.  The advantage in doing so, aside from saving the
+developers time, is that you learn what has been done to fix it; it may be that
+the problem has already been fixed for the next release, or additional
+information is needed (in which case you are welcome to provide it if you can!).
+To do this, search the bug database using the search box on the top of the page.
+
+If the problem you're reporting is not already in the bug tracker, go back to
+the Python Bug Tracker and log in.  If you don't already have a tracker account,
+select the "Register" link or, if you use OpenID, one of the OpenID provider
+logos in the sidebar.  It is not possible to submit a bug report anonymously.
+
+Being now logged in, you can submit a bug.  Select the "Create New" link in the
+sidebar to open the bug reporting form.
+
+The submission form has a number of fields.  For the "Title" field, enter a
+*very* short description of the problem; less than ten words is good.  In the
+"Type" field, select the type of your problem; also select the "Component" and
+"Versions" to which the bug relates.
+
+In the "Comment" field, describe the problem in detail, including what you
+expected to happen and what did happen.  Be sure to include whether any
+extension modules were involved, and what hardware and software platform you
+were using (including version information as appropriate).
+
+Each bug report will be assigned to a developer who will determine what needs to
+be done to correct the problem.  You will receive an update each time action is
+taken on the bug.
+
+
+.. seealso::
+
+   `How to Report Bugs Effectively <http://www.chiark.greenend.org.uk/~sgtatham/bugs.html>`_
+      Article which goes into some detail about how to create a useful bug report.
+      This describes what kind of information is useful and why it is useful.
+
+   `Bug Writing Guidelines <https://developer.mozilla.org/en-US/docs/Mozilla/QA/Bug_writing_guidelines>`_
+      Information about writing a good bug report.  Some of this is specific to the
+      Mozilla project, but describes general good practices.
+
+.. _contributing-to-python:
+
+Getting started contributing to Python yourself
+===============================================
+
+Beyond just reporting bugs that you find, you are also welcome to submit
+patches to fix them.  You can find more information on how to get started
+patching Python in the `Python Developer's Guide`_.  If you have questions,
+the `core-mentorship mailing list`_ is a friendly place to get answers to
+any and all questions pertaining to the process of fixing issues in Python.
+
+.. _Documentation bugs: https://bugs.python.org/issue?@filter=status&@filter=components&components=4&status=1&@columns=id,activity,title,status&@sort=-activity
+.. _Python Developer's Guide: https://devguide.python.org/
+.. _core-mentorship mailing list: https://mail.python.org/mailman/listinfo/core-mentorship/

third_party/python/Doc/c-api/abstract.rst

@@ -0,0 +1,26 @@
+.. highlightlang:: c
+
+.. _abstract:
+
+**********************
+Abstract Objects Layer
+**********************
+
+The functions in this chapter interact with Python objects regardless of their
+type, or with wide classes of object types (e.g. all numerical types, or all
+sequence types).  When used on object types for which they do not apply, they
+will raise a Python exception.
+
+It is not possible to use these functions on objects that are not properly
+initialized, such as a list object that has been created by :c:func:`PyList_New`,
+but whose items have not been set to some non-\ ``NULL`` value yet.
+
+.. toctree::
+
+   object.rst
+   number.rst
+   sequence.rst
+   mapping.rst
+   iter.rst
+   buffer.rst
+   objbuffer.rst

third_party/python/Doc/c-api/allocation.rst

@@ -0,0 +1,71 @@
+.. highlightlang:: c
+
+.. _allocating-objects:
+
+Allocating Objects on the Heap
+==============================
+
+
+.. c:function:: PyObject* _PyObject_New(PyTypeObject *type)
+
+
+.. c:function:: PyVarObject* _PyObject_NewVar(PyTypeObject *type, Py_ssize_t size)
+
+
+.. c:function:: PyObject* PyObject_Init(PyObject *op, PyTypeObject *type)
+
+   Initialize a newly-allocated object *op* with its type and initial
+   reference.  Returns the initialized object.  If *type* indicates that the
+   object participates in the cyclic garbage detector, it is added to the
+   detector's set of observed objects. Other fields of the object are not
+   affected.
+
+
+.. c:function:: PyVarObject* PyObject_InitVar(PyVarObject *op, PyTypeObject *type, Py_ssize_t size)
+
+   This does everything :c:func:`PyObject_Init` does, and also initializes the
+   length information for a variable-size object.
+
+
+.. c:function:: TYPE* PyObject_New(TYPE, PyTypeObject *type)
+
+   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.
+
+
+.. c:function:: TYPE* PyObject_NewVar(TYPE, PyTypeObject *type, Py_ssize_t 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
+   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
+   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.
+
+
+.. c:function:: void PyObject_Del(PyObject *op)
+
+   Releases memory allocated to an object using :c:func:`PyObject_New` or
+   :c:func:`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.
+
+
+.. c:var:: PyObject _Py_NoneStruct
+
+   Object which is visible in Python as ``None``.  This should only be accessed
+   using the :c:macro:`Py_None` macro, which evaluates to a pointer to this
+   object.
+
+
+.. seealso::
+
+   :c:func:`PyModule_Create`
+      To allocate and create extension modules.
+

third_party/python/Doc/c-api/apiabiversion.rst

@@ -0,0 +1,39 @@
+.. highlightlang:: c
+
+.. _apiabiversion:
+
+***********************
+API and ABI Versioning
+***********************
+
+``PY_VERSION_HEX`` is the Python version number encoded in a single integer.
+
+For example if the ``PY_VERSION_HEX`` is set to ``0x030401a2``, the underlying
+version information can be found by treating it as a 32 bit number in
+the following manner:
+
+   +-------+-------------------------+------------------------------------------------+
+   | Bytes | Bits (big endian order) | Meaning                                        |
+   +=======+=========================+================================================+
+   | ``1`` |       ``1-8``           |  ``PY_MAJOR_VERSION`` (the ``3`` in            |
+   |       |                         |  ``3.4.1a2``)                                  |
+   +-------+-------------------------+------------------------------------------------+
+   | ``2`` |       ``9-16``          |  ``PY_MINOR_VERSION`` (the ``4`` in            |
+   |       |                         |  ``3.4.1a2``)                                  |
+   +-------+-------------------------+------------------------------------------------+
+   | ``3`` |       ``17-24``         |  ``PY_MICRO_VERSION`` (the ``1`` in            |
+   |       |                         |  ``3.4.1a2``)                                  |
+   +-------+-------------------------+------------------------------------------------+
+   | ``4`` |       ``25-28``         |  ``PY_RELEASE_LEVEL`` (``0xA`` for alpha,      |
+   |       |                         |  ``0xB`` for beta, ``0xC`` for release         |
+   |       |                         |  candidate and ``0xF`` for final), in this     |
+   |       |                         |  case it is alpha.                             |
+   +-------+-------------------------+------------------------------------------------+
+   |       |       ``29-32``         |  ``PY_RELEASE_SERIAL`` (the ``2`` in           |
+   |       |                         |  ``3.4.1a2``, zero for final releases)         |
+   +-------+-------------------------+------------------------------------------------+
+
+Thus ``3.4.1a2`` is hexversion ``0x030401a2``.
+
+All the given macros are defined in :source:`Include/patchlevel.h`.
+

third_party/python/Doc/c-api/arg.rst

@@ -0,0 +1,676 @@
+.. highlightlang:: c
+
+.. _arg-parsing:
+
+Parsing arguments and building values
+=====================================
+
+These functions are useful when creating your own extensions functions and
+methods.  Additional information and examples are available in
+:ref:`extending-index`.
+
+The first three of these functions described, :c:func:`PyArg_ParseTuple`,
+:c:func:`PyArg_ParseTupleAndKeywords`, and :c:func:`PyArg_Parse`, all use *format
+strings* which are used to tell the function about the expected arguments.  The
+format strings use the same syntax for each of these functions.
+
+-----------------
+Parsing arguments
+-----------------
+
+A format string consists of zero or more "format units."  A format unit
+describes one Python object; it is usually a single character or a parenthesized
+sequence of format units.  With a few exceptions, a format unit that is not a
+parenthesized sequence normally corresponds to a single address argument to
+these functions.  In the following description, the quoted form is the format
+unit; the entry in (round) parentheses is the Python object type that matches
+the format unit; and the entry in [square] brackets is the type of the C
+variable(s) whose address should be passed.
+
+Strings and buffers
+-------------------
+
+These formats allow accessing an object as a contiguous chunk of memory.
+You don't have to provide raw storage for the returned unicode or bytes
+area.
+
+In general, when a format sets a pointer to a buffer, the buffer is
+managed by the corresponding Python object, and the buffer shares
+the lifetime of this object.  You won't have to release any memory yourself.
+The only exceptions are ``es``, ``es#``, ``et`` and ``et#``.
+
+However, when a :c:type:`Py_buffer` structure gets filled, the underlying
+buffer is locked so that the caller can subsequently use the buffer even
+inside a :c:type:`Py_BEGIN_ALLOW_THREADS` block without the risk of mutable data
+being resized or destroyed.  As a result, **you have to call**
+:c:func:`PyBuffer_Release` after you have finished processing the data (or
+in any early abort case).
+
+Unless otherwise stated, buffers are not NUL-terminated.
+
+Some formats require a read-only :term:`bytes-like object`, and set a
+pointer instead of a buffer structure.  They work by checking that
+the object's :c:member:`PyBufferProcs.bf_releasebuffer` field is *NULL*,
+which disallows mutable objects such as :class:`bytearray`.
+
+.. note::
+
+   For all ``#`` variants of formats (``s#``, ``y#``, etc.), the type of
+   the length argument (int or :c:type:`Py_ssize_t`) is controlled by
+   defining the macro :c:macro:`PY_SSIZE_T_CLEAN` before including
+   :file:`Python.h`.  If the macro was defined, length is a
+   :c:type:`Py_ssize_t` rather than an :c:type:`int`. This behavior will change
+   in a future Python version to only support :c:type:`Py_ssize_t` and
+   drop :c:type:`int` support. It is best to always define :c:macro:`PY_SSIZE_T_CLEAN`.
+
+
+``s`` (:class:`str`) [const char \*]
+   Convert a Unicode object to a C pointer to a character string.
+   A pointer to an existing string is stored in the character pointer
+   variable whose address you pass.  The C string is NUL-terminated.
+   The Python string must not contain embedded null code points; if it does,
+   a :exc:`ValueError` exception is raised. Unicode objects are converted
+   to C strings using ``'utf-8'`` encoding. If this conversion fails, a
+   :exc:`UnicodeError` is raised.
+
+   .. note::
+      This format does not accept :term:`bytes-like objects
+      <bytes-like object>`.  If you want to accept
+      filesystem paths and convert them to C character strings, it is
+      preferable to use the ``O&`` format with :c:func:`PyUnicode_FSConverter`
+      as *converter*.
+
+   .. versionchanged:: 3.5
+      Previously, :exc:`TypeError` was raised when embedded null code points
+      were encountered in the Python string.
+
+``s*`` (:class:`str` or :term:`bytes-like object`) [Py_buffer]
+   This format accepts Unicode objects as well as bytes-like objects.
+   It fills a :c:type:`Py_buffer` structure provided by the caller.
+   In this case the resulting C string may contain embedded NUL bytes.
+   Unicode objects are converted to C strings using ``'utf-8'`` encoding.
+
+``s#`` (:class:`str`, read-only :term:`bytes-like object`) [const char \*, int or :c:type:`Py_ssize_t`]
+   Like ``s*``, except that it doesn't accept mutable objects.
+   The result is stored into two C variables,
+   the first one a pointer to a C string, the second one its length.
+   The string may contain embedded null bytes. Unicode objects are converted
+   to C strings using ``'utf-8'`` encoding.
+
+``z`` (:class:`str` or ``None``) [const char \*]
+   Like ``s``, but the Python object may also be ``None``, in which case the C
+   pointer is set to *NULL*.
+
+``z*`` (:class:`str`, :term:`bytes-like object` or ``None``) [Py_buffer]
+   Like ``s*``, but the Python object may also be ``None``, in which case the
+   ``buf`` member of the :c:type:`Py_buffer` structure is set to *NULL*.
+
+``z#`` (:class:`str`, read-only :term:`bytes-like object` or ``None``) [const char \*, int]
+   Like ``s#``, but the Python object may also be ``None``, in which case the C
+   pointer is set to *NULL*.
+
+``y`` (read-only :term:`bytes-like object`) [const char \*]
+   This format converts a bytes-like object to a C pointer to a character
+   string; it does not accept Unicode objects.  The bytes buffer must not
+   contain embedded null bytes; if it does, a :exc:`ValueError`
+   exception is raised.
+
+   .. versionchanged:: 3.5
+      Previously, :exc:`TypeError` was raised when embedded null bytes were
+      encountered in the bytes buffer.
+
+``y*`` (:term:`bytes-like object`) [Py_buffer]
+   This variant on ``s*`` doesn't accept Unicode objects, only
+   bytes-like objects.  **This is the recommended way to accept
+   binary data.**
+
+``y#`` (read-only :term:`bytes-like object`) [const char \*, int]
+   This variant on ``s#`` doesn't accept Unicode objects, only bytes-like
+   objects.
+
+``S`` (:class:`bytes`) [PyBytesObject \*]
+   Requires that the Python object is a :class:`bytes` object, without
+   attempting any conversion.  Raises :exc:`TypeError` if the object is not
+   a bytes object.  The C variable may also be declared as :c:type:`PyObject\*`.
+
+``Y`` (:class:`bytearray`) [PyByteArrayObject \*]
+   Requires that the Python object is a :class:`bytearray` object, without
+   attempting any conversion.  Raises :exc:`TypeError` if the object is not
+   a :class:`bytearray` object. The C variable may also be declared as :c:type:`PyObject\*`.
+
+``u`` (:class:`str`) [Py_UNICODE \*]
+   Convert a Python Unicode object to a C pointer to a NUL-terminated buffer of
+   Unicode characters.  You must pass the address of a :c:type:`Py_UNICODE`
+   pointer variable, which will be filled with the pointer to an existing
+   Unicode buffer.  Please note that the width of a :c:type:`Py_UNICODE`
+   character depends on compilation options (it is either 16 or 32 bits).
+   The Python string must not contain embedded null code points; if it does,
+   a :exc:`ValueError` exception is raised.
+
+   .. versionchanged:: 3.5
+      Previously, :exc:`TypeError` was raised when embedded null code points
+      were encountered in the Python string.
+
+   .. deprecated-removed:: 3.3 4.0
+      Part of the old-style :c:type:`Py_UNICODE` API; please migrate to using
+      :c:func:`PyUnicode_AsWideCharString`.
+
+``u#`` (:class:`str`) [Py_UNICODE \*, int]
+   This variant on ``u`` stores into two C variables, the first one a pointer to a
+   Unicode data buffer, the second one its length.  This variant allows
+   null code points.
+
+   .. deprecated-removed:: 3.3 4.0
+      Part of the old-style :c:type:`Py_UNICODE` API; please migrate to using
+      :c:func:`PyUnicode_AsWideCharString`.
+
+``Z`` (:class:`str` or ``None``) [Py_UNICODE \*]
+   Like ``u``, but the Python object may also be ``None``, in which case the
+   :c:type:`Py_UNICODE` pointer is set to *NULL*.
+
+   .. deprecated-removed:: 3.3 4.0
+      Part of the old-style :c:type:`Py_UNICODE` API; please migrate to using
+      :c:func:`PyUnicode_AsWideCharString`.
+
+``Z#`` (:class:`str` or ``None``) [Py_UNICODE \*, int]
+   Like ``u#``, but the Python object may also be ``None``, in which case the
+   :c:type:`Py_UNICODE` pointer is set to *NULL*.
+
+   .. deprecated-removed:: 3.3 4.0
+      Part of the old-style :c:type:`Py_UNICODE` API; please migrate to using
+      :c:func:`PyUnicode_AsWideCharString`.
+
+``U`` (:class:`str`) [PyObject \*]
+   Requires that the Python object is a Unicode object, without attempting
+   any conversion.  Raises :exc:`TypeError` if the object is not a Unicode
+   object.  The C variable may also be declared as :c:type:`PyObject\*`.
+
+``w*`` (read-write :term:`bytes-like object`) [Py_buffer]
+   This format accepts any object which implements the read-write buffer
+   interface. It fills a :c:type:`Py_buffer` structure provided by the caller.
+   The buffer may contain embedded null bytes. The caller have to call
+   :c:func:`PyBuffer_Release` when it is done with the buffer.
+
+``es`` (:class:`str`) [const char \*encoding, char \*\*buffer]
+   This variant on ``s`` is used for encoding Unicode into a character buffer.
+   It only works for encoded data without embedded NUL bytes.
+
+   This format requires two arguments.  The first is only used as input, and
+   must be a :c:type:`const char\*` which points to the name of an encoding as a
+   NUL-terminated string, or *NULL*, in which case ``'utf-8'`` encoding is used.
+   An exception is raised if the named encoding is not known to Python.  The
+   second argument must be a :c:type:`char\*\*`; the value of the pointer it
+   references will be set to a buffer with the contents of the argument text.
+   The text will be encoded in the encoding specified by the first argument.
+
+   :c:func:`PyArg_ParseTuple` will allocate a buffer of the needed size, copy the
+   encoded data into this buffer and adjust *\*buffer* to reference the newly
+   allocated storage.  The caller is responsible for calling :c:func:`PyMem_Free` to
+   free the allocated buffer after use.
+
+``et`` (:class:`str`, :class:`bytes` or :class:`bytearray`) [const char \*encoding, char \*\*buffer]
+   Same as ``es`` except that byte string objects are passed through without
+   recoding them.  Instead, the implementation assumes that the byte string object uses
+   the encoding passed in as parameter.
+
+``es#`` (:class:`str`) [const char \*encoding, char \*\*buffer, int \*buffer_length]
+   This variant on ``s#`` is used for encoding Unicode into a character buffer.
+   Unlike the ``es`` format, this variant allows input data which contains NUL
+   characters.
+
+   It requires three arguments.  The first is only used as input, and must be a
+   :c:type:`const char\*` which points to the name of an encoding as a
+   NUL-terminated string, or *NULL*, in which case ``'utf-8'`` encoding is used.
+   An exception is raised if the named encoding is not known to Python.  The
+   second argument must be a :c:type:`char\*\*`; the value of the pointer it
+   references will be set to a buffer with the contents of the argument text.
+   The text will be encoded in the encoding specified by the first argument.
+   The third argument must be a pointer to an integer; the referenced integer
+   will be set to the number of bytes in the output buffer.
+
+   There are two modes of operation:
+
+   If *\*buffer* points a *NULL* pointer, the function will allocate a buffer of
+   the needed size, copy the encoded data into this buffer and set *\*buffer* to
+   reference the newly allocated storage.  The caller is responsible for calling
+   :c:func:`PyMem_Free` to free the allocated buffer after usage.
+
+   If *\*buffer* points to a non-*NULL* pointer (an already allocated buffer),
+   :c:func:`PyArg_ParseTuple` will use this location as the buffer and interpret the
+   initial value of *\*buffer_length* as the buffer size.  It will then copy the
+   encoded data into the buffer and NUL-terminate it.  If the buffer is not large
+   enough, a :exc:`ValueError` will be set.
+
+   In both cases, *\*buffer_length* is set to the length of the encoded data
+   without the trailing NUL byte.
+
+``et#`` (:class:`str`, :class:`bytes` or :class:`bytearray`) [const char \*encoding, char \*\*buffer, int \*buffer_length]
+   Same as ``es#`` except that byte string objects are passed through without recoding
+   them. Instead, the implementation assumes that the byte string object uses the
+   encoding passed in as parameter.
+
+Numbers
+-------
+
+``b`` (:class:`int`) [unsigned char]
+   Convert a nonnegative Python integer to an unsigned tiny int, stored in a C
+   :c:type:`unsigned char`.
+
+``B`` (:class:`int`) [unsigned char]
+   Convert a Python integer to a tiny int without overflow checking, stored in a C
+   :c:type:`unsigned char`.
+
+``h`` (:class:`int`) [short int]
+   Convert a Python integer to a C :c:type:`short int`.
+
+``H`` (:class:`int`) [unsigned short int]
+   Convert a Python integer to a C :c:type:`unsigned short int`, without overflow
+   checking.
+
+``i`` (:class:`int`) [int]
+   Convert a Python integer to a plain C :c:type:`int`.
+
+``I`` (:class:`int`) [unsigned int]
+   Convert a Python integer to a C :c:type:`unsigned int`, without overflow
+   checking.
+
+``l`` (:class:`int`) [long int]
+   Convert a Python integer to a C :c:type:`long int`.
+
+``k`` (:class:`int`) [unsigned long]
+   Convert a Python integer to a C :c:type:`unsigned long` without
+   overflow checking.
+
+``L`` (:class:`int`) [long long]
+   Convert a Python integer to a C :c:type:`long long`.
+
+``K`` (:class:`int`) [unsigned long long]
+   Convert a Python integer to a C :c:type:`unsigned long long`
+   without overflow checking.
+
+``n`` (:class:`int`) [Py_ssize_t]
+   Convert a Python integer to a C :c:type:`Py_ssize_t`.
+
+``c`` (:class:`bytes` or :class:`bytearray` of length 1) [char]
+   Convert a Python byte, represented as a :class:`bytes` or
+   :class:`bytearray` object of length 1, to a C :c:type:`char`.
+
+   .. versionchanged:: 3.3
+      Allow :class:`bytearray` objects.
+
+``C`` (:class:`str` of length 1) [int]
+   Convert a Python character, represented as a :class:`str` object of
+   length 1, to a C :c:type:`int`.
+
+``f`` (:class:`float`) [float]
+   Convert a Python floating point number to a C :c:type:`float`.
+
+``d`` (:class:`float`) [double]
+   Convert a Python floating point number to a C :c:type:`double`.
+
+``D`` (:class:`complex`) [Py_complex]
+   Convert a Python complex number to a C :c:type:`Py_complex` structure.
+
+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*.
+
+``O!`` (object) [*typeobject*, PyObject \*]
+   Store a Python object in a C object pointer.  This is similar to ``O``, but
+   takes two C arguments: the first is the address of a Python type object, the
+   second is the address of the C variable (of type :c:type:`PyObject\*`) into which
+   the object pointer is stored.  If the Python object does not have the required
+   type, :exc:`TypeError` is raised.
+
+.. _o_ampersand:
+
+``O&`` (object) [*converter*, *anything*]
+   Convert a Python object to a C variable through a *converter* function.  This
+   takes two arguments: the first is a function, the second is the address of a C
+   variable (of arbitrary type), converted to :c:type:`void \*`.  The *converter*
+   function in turn is called as follows::
+
+      status = converter(object, address);
+
+   where *object* is the Python object to be converted and *address* is the
+   :c:type:`void\*` argument that was passed to the :c:func:`PyArg_Parse\*` function.
+   The returned *status* should be ``1`` for a successful conversion and ``0`` if
+   the conversion has failed.  When the conversion fails, the *converter* function
+   should raise an exception and leave the content of *address* unmodified.
+
+   If the *converter* returns ``Py_CLEANUP_SUPPORTED``, it may get called a
+   second time if the argument parsing eventually fails, giving the converter a
+   chance to release any memory that it had already allocated. In this second
+   call, the *object* parameter will be NULL; *address* will have the same value
+   as in the original call.
+
+   .. versionchanged:: 3.1
+      ``Py_CLEANUP_SUPPORTED`` was added.
+
+``p`` (:class:`bool`) [int]
+   Tests the value passed in for truth (a boolean **p**\ redicate) and converts
+   the result to its equivalent C true/false integer value.
+   Sets the int to ``1`` if the expression was true and ``0`` if it was false.
+   This accepts any valid Python value.  See :ref:`truth` for more
+   information about how Python tests values for truth.
+
+   .. versionadded:: 3.3
+
+``(items)`` (:class:`tuple`) [*matching-items*]
+   The object must be a Python sequence whose length is the number of format units
+   in *items*.  The C arguments must correspond to the individual format units in
+   *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
+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).
+
+A few other characters have a meaning in a format string.  These may not occur
+inside nested parentheses.  They are:
+
+``|``
+   Indicates that the remaining arguments in the Python argument list are optional.
+   The C variables corresponding to optional arguments should be initialized to
+   their default value --- when an optional argument is not specified,
+   :c:func:`PyArg_ParseTuple` does not touch the contents of the corresponding C
+   variable(s).
+
+``$``
+   :c:func:`PyArg_ParseTupleAndKeywords` only:
+   Indicates that the remaining arguments in the Python argument list are
+   keyword-only.  Currently, all keyword-only arguments must also be optional
+   arguments, so ``|`` must always be specified before ``$`` in the format
+   string.
+
+   .. versionadded:: 3.3
+
+``:``
+   The list of format units ends here; the string after the colon is used as the
+   function name in error messages (the "associated value" of the exception that
+   :c:func:`PyArg_ParseTuple` raises).
+
+``;``
+   The list of format units ends here; the string after the semicolon is used as
+   the error message *instead* of the default error message.  ``:`` and ``;``
+   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!
+
+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
+from the input tuple.  There are a few cases, as described in the list of format
+units above, where these parameters are used as input values; they should match
+what is specified for the corresponding format unit in that case.
+
+For the conversion to succeed, the *arg* object must match the format
+and the format must be exhausted.  On success, the
+:c:func:`PyArg_Parse\*` functions return true, otherwise they return
+false and raise an appropriate exception. When the
+:c:func:`PyArg_Parse\*` functions fail due to conversion failure in one
+of the format units, the variables at the addresses corresponding to that
+and the following format units are left untouched.
+
+API Functions
+-------------
+
+.. c:function:: int PyArg_ParseTuple(PyObject *args, const char *format, ...)
+
+   Parse the parameters of a function that takes only positional parameters into
+   local variables.  Returns true on success; on failure, it returns false and
+   raises the appropriate exception.
+
+
+.. c:function:: int PyArg_VaParse(PyObject *args, const char *format, va_list vargs)
+
+   Identical to :c:func:`PyArg_ParseTuple`, except that it accepts a va_list rather
+   than a variable number of arguments.
+
+
+.. c:function:: int PyArg_ParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *keywords[], ...)
+
+   Parse the parameters of a function that takes both positional and keyword
+   parameters into local variables.  The *keywords* argument is a
+   *NULL*-terminated array of keyword parameter names.  Empty names denote
+   :ref:`positional-only parameters <positional-only_parameter>`.
+   Returns true on success; on failure, it returns false and raises the
+   appropriate exception.
+
+   .. versionchanged:: 3.6
+      Added support for :ref:`positional-only parameters
+      <positional-only_parameter>`.
+
+
+.. c:function:: int PyArg_VaParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *keywords[], va_list vargs)
+
+   Identical to :c:func:`PyArg_ParseTupleAndKeywords`, except that it accepts a
+   va_list rather than a variable number of arguments.
+
+
+.. c:function:: int PyArg_ValidateKeywordArguments(PyObject *)
+
+   Ensure that the keys in the keywords argument dictionary are strings.  This
+   is only needed if :c:func:`PyArg_ParseTupleAndKeywords` is not used, since the
+   latter already does this check.
+
+   .. versionadded:: 3.2
+
+
+.. XXX deprecated, will be removed
+.. c:function:: int PyArg_Parse(PyObject *args, const char *format, ...)
+
+   Function used to deconstruct the argument lists of "old-style" functions ---
+   these are functions which use the :const:`METH_OLDARGS` parameter parsing
+   method, which has been removed in Python 3.  This is not recommended for use
+   in parameter parsing in new code, and most code in the standard interpreter
+   has been modified to no longer use this for that purpose.  It does remain a
+   convenient way to decompose other tuples, however, and may continue to be
+   used for that purpose.
+
+
+.. c:function:: int PyArg_UnpackTuple(PyObject *args, const char *name, Py_ssize_t min, Py_ssize_t max, ...)
+
+   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
+   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
+   arguments must be passed to the function, each of which should be a pointer to a
+   :c:type:`PyObject\*` variable; these will be filled in with the values from
+   *args*; they will contain borrowed references.  The variables which correspond
+   to optional parameters not given by *args* will not be filled in; these should
+   be initialized by the caller. This function returns true on success and false if
+   *args* is not a tuple or contains the wrong number of elements; an exception
+   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::
+
+      static PyObject *
+      weakref_ref(PyObject *self, PyObject *args)
+      {
+          PyObject *object;
+          PyObject *callback = NULL;
+          PyObject *result = NULL;
+
+          if (PyArg_UnpackTuple(args, "ref", 1, 2, &object, &callback)) {
+              result = PyWeakref_NewRef(object, callback);
+          }
+          return result;
+      }
+
+   The call to :c:func:`PyArg_UnpackTuple` in this example is entirely equivalent to
+   this call to :c:func:`PyArg_ParseTuple`::
+
+      PyArg_ParseTuple(args, "O|O:ref", &object, &callback)
+
+
+---------------
+Building values
+---------------
+
+.. c:function:: PyObject* Py_BuildValue(const char *format, ...)
+
+   Create a new value based on a format string similar to those accepted by the
+   :c:func:`PyArg_Parse\*` family of functions and a sequence of values.  Returns
+   the value or *NULL* in the case of an error; an exception will be raised if
+   *NULL* is returned.
+
+   :c:func:`Py_BuildValue` does not always build a tuple.  It builds a tuple only if
+   its format string contains two or more format units.  If the format string is
+   empty, it returns ``None``; if it contains exactly one format unit, it returns
+   whatever object is described by that format unit.  To force it to return a tuple
+   of size 0 or one, parenthesize the format string.
+
+   When memory buffers are passed as parameters to supply data to build objects, as
+   for the ``s`` and ``s#`` formats, the required data is copied.  Buffers provided
+   by the caller are never referenced by the objects created by
+   :c:func:`Py_BuildValue`.  In other words, if your code invokes :c:func:`malloc`
+   and passes the allocated memory to :c:func:`Py_BuildValue`, your code is
+   responsible for calling :c:func:`free` for that memory once
+   :c:func:`Py_BuildValue` returns.
+
+   In the following description, the quoted form is the format unit; the entry in
+   (round) parentheses is the Python object type that the format unit will return;
+   and the entry in [square] brackets is the type of the C value(s) to be passed.
+
+   The characters space, tab, colon and comma are ignored in format strings (but
+   not within format units such as ``s#``).  This can be used to make long format
+   strings a tad more readable.
+
+   ``s`` (:class:`str` or ``None``) [char \*]
+      Convert a null-terminated C string to a Python :class:`str` object using ``'utf-8'``
+      encoding. If the C string pointer is *NULL*, ``None`` is used.
+
+   ``s#`` (:class:`str` or ``None``) [char \*, int]
+      Convert a C string and its length to a Python :class:`str` object using ``'utf-8'``
+      encoding. If the C string pointer is *NULL*, the length is ignored and
+      ``None`` is returned.
+
+   ``y`` (:class:`bytes`) [char \*]
+      This converts a C string to a Python :class:`bytes` object.  If the C
+      string pointer is *NULL*, ``None`` is returned.
+
+   ``y#`` (:class:`bytes`) [char \*, int]
+      This converts a C string and its lengths to a Python object.  If the C
+      string pointer is *NULL*, ``None`` is returned.
+
+   ``z`` (:class:`str` or ``None``) [char \*]
+      Same as ``s``.
+
+   ``z#`` (:class:`str` or ``None``) [char \*, int]
+      Same as ``s#``.
+
+   ``u`` (:class:`str`) [wchar_t \*]
+      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.
+
+   ``u#`` (:class:`str`) [wchar_t \*, int]
+      Convert a Unicode (UTF-16 or UCS-4) data buffer and its length to a Python
+      Unicode object.   If the Unicode buffer pointer is *NULL*, the length is ignored
+      and ``None`` is returned.
+
+   ``U`` (:class:`str` or ``None``) [char \*]
+      Same as ``s``.
+
+   ``U#`` (:class:`str` or ``None``) [char \*, int]
+      Same as ``s#``.
+
+   ``i`` (:class:`int`) [int]
+      Convert a plain C :c:type:`int` to a Python integer object.
+
+   ``b`` (:class:`int`) [char]
+      Convert a plain C :c:type:`char` to a Python integer object.
+
+   ``h`` (:class:`int`) [short int]
+      Convert a plain C :c:type:`short int` to a Python integer object.
+
+   ``l`` (:class:`int`) [long int]
+      Convert a C :c:type:`long int` to a Python integer object.
+
+   ``B`` (:class:`int`) [unsigned char]
+      Convert a C :c:type:`unsigned char` to a Python integer object.
+
+   ``H`` (:class:`int`) [unsigned short int]
+      Convert a C :c:type:`unsigned short int` to a Python integer object.
+
+   ``I`` (:class:`int`) [unsigned int]
+      Convert a C :c:type:`unsigned int` to a Python integer object.
+
+   ``k`` (:class:`int`) [unsigned long]
+      Convert a C :c:type:`unsigned long` to a Python integer object.
+
+   ``L`` (:class:`int`) [long long]
+      Convert a C :c:type:`long long` to a Python integer object.
+
+   ``K`` (:class:`int`) [unsigned long long]
+      Convert a C :c:type:`unsigned long long` to a Python integer object.
+
+   ``n`` (:class:`int`) [Py_ssize_t]
+      Convert a C :c:type:`Py_ssize_t` to a Python integer.
+
+   ``c`` (:class:`bytes` of length 1) [char]
+      Convert a C :c:type:`int` representing a byte to a Python :class:`bytes` object of
+      length 1.
+
+   ``C`` (:class:`str` of length 1) [int]
+      Convert a C :c:type:`int` representing a character to Python :class:`str`
+      object of length 1.
+
+   ``d`` (:class:`float`) [double]
+      Convert a C :c:type:`double` to a Python floating point number.
+
+   ``f`` (:class:`float`) [float]
+      Convert a C :c:type:`float` to a Python floating point number.
+
+   ``D`` (:class:`complex`) [Py_complex \*]
+      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
+      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
+      set.
+
+   ``S`` (object) [PyObject \*]
+      Same as ``O``.
+
+   ``N`` (object) [PyObject \*]
+      Same as ``O``, except it doesn't increment the reference count on the object.
+      Useful when the object is created by a call to an object constructor in the
+      argument list.
+
+   ``O&`` (object) [*converter*, *anything*]
+      Convert *anything* to a Python object through a *converter* function.  The
+      function is called with *anything* (which should be compatible with :c:type:`void
+      \*`) as its argument and should return a "new" Python object, or *NULL* if an
+      error occurred.
+
+   ``(items)`` (:class:`tuple`) [*matching-items*]
+      Convert a sequence of C values to a Python tuple with the same number of items.
+
+   ``[items]`` (:class:`list`) [*matching-items*]
+      Convert a sequence of C values to a Python list with the same number of items.
+
+   ``{items}`` (:class:`dict`) [*matching-items*]
+      Convert a sequence of C values to a Python dictionary.  Each pair of consecutive
+      C values adds one item to the dictionary, serving as key and value,
+      respectively.
+
+   If there is an error in the format string, the :exc:`SystemError` exception is
+   set and *NULL* returned.
+
+.. c:function:: PyObject* Py_VaBuildValue(const char *format, va_list vargs)
+
+   Identical to :c:func:`Py_BuildValue`, except that it accepts a va_list
+   rather than a variable number of arguments.

third_party/python/Doc/c-api/bool.rst

@@ -0,0 +1,46 @@
+.. highlightlang:: c
+
+.. _boolobjects:
+
+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
+creation and deletion functions don't apply to booleans.  The following macros
+are available, however.
+
+
+.. c:function:: int PyBool_Check(PyObject *o)
+
+   Return true if *o* is of type :c:data:`PyBool_Type`.
+
+
+.. 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.
+
+
+.. 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.
+
+
+.. c:macro:: Py_RETURN_FALSE
+
+   Return :const:`Py_False` from a function, properly incrementing its reference
+   count.
+
+
+.. c:macro:: Py_RETURN_TRUE
+
+   Return :const:`Py_True` from a function, properly incrementing its reference
+   count.
+
+
+.. 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*.

third_party/python/Doc/c-api/buffer.rst

@@ -0,0 +1,508 @@
+.. highlightlang:: c
+
+.. index::
+   single: buffer protocol
+   single: buffer interface; (see buffer protocol)
+   single: buffer object; (see buffer protocol)
+
+.. _bufferobjects:
+
+Buffer Protocol
+---------------
+
+.. sectionauthor:: Greg Stein <gstein@lyra.org>
+.. sectionauthor:: Benjamin Peterson
+.. sectionauthor:: Stefan Krah
+
+
+Certain objects available in Python wrap access to an underlying memory
+array or *buffer*.  Such objects include the built-in :class:`bytes` and
+:class:`bytearray`, and some extension types like :class:`array.array`.
+Third-party libraries may define their own types for special purposes, such
+as image processing or numeric analysis.
+
+While each of these types have their own semantics, they share the common
+characteristic of being backed by a possibly large memory buffer.  It is
+then desirable, in some situations, to access that buffer directly and
+without intermediate copying.
+
+Python provides such a facility at the C level in the form of the :ref:`buffer
+protocol <bufferobjects>`.  This protocol has two sides:
+
+.. index:: single: PyBufferProcs
+
+- on the producer side, a type can export a "buffer interface" which allows
+  objects of that type to expose information about their underlying buffer.
+  This interface is described in the section :ref:`buffer-structs`;
+
+- on the consumer side, several means are available to obtain a pointer to
+  the raw underlying data of an object (for example a method parameter).
+
+Simple objects such as :class:`bytes` and :class:`bytearray` expose their
+underlying buffer in byte-oriented form.  Other forms are possible; for example,
+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
+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
+selectively allow or reject exporting of read-write and read-only buffers.
+
+There are two ways for a consumer of the buffer interface to acquire a buffer
+over a target object:
+
+* call :c:func:`PyObject_GetBuffer` with the right parameters;
+
+* call :c:func:`PyArg_ParseTuple` (or one of its siblings) with one of the
+  ``y*``, ``w*`` or ``s*`` :ref:`format codes <arg-parsing>`.
+
+In both cases, :c:func:`PyBuffer_Release` must be called when the buffer
+isn't needed anymore.  Failure to do so could lead to various issues such as
+resource leaks.
+
+
+.. _buffer-structure:
+
+Buffer structure
+================
+
+Buffer structures (or simply "buffers") are useful as a way to expose the
+binary data from another object to the Python programmer.  They can also be
+used as a zero-copy slicing mechanism.  Using their ability to reference a
+block of memory, it is possible to expose any data to the Python programmer
+quite easily.  The memory could be a large, constant array in a C extension,
+it could be a raw block of memory for manipulation before passing to an
+operating system library, or it could be used to pass around structured data
+in its native, in-memory format.
+
+Contrary to most data types exposed by the Python interpreter, buffers
+are not :c:type:`PyObject` pointers but rather simple C structures.  This
+allows them to be created and copied very simply.  When a generic wrapper
+around a buffer is needed, a :ref:`memoryview <memoryview-objects>` object
+can be created.
+
+For short instructions how to write an exporting object, see
+:ref:`Buffer Object Structures <buffer-structs>`. For obtaining
+a buffer, see :c:func:`PyObject_GetBuffer`.
+
+.. c:type:: Py_buffer
+
+   .. c:member:: void \*buf
+
+      A pointer to the start of the logical structure described by the buffer
+      fields. This can be any location within the underlying physical memory
+      block of the exporter. For example, with negative :c:member:`~Py_buffer.strides`
+      the value may point to the end of the memory block.
+
+      For :term:`contiguous` arrays, the value points to the beginning of
+      the memory block.
+
+   .. c:member:: void \*obj
+
+      A new reference to the exporting object. The reference is owned by
+      the consumer and automatically decremented and set to *NULL* by
+      :c:func:`PyBuffer_Release`. The field is the equivalent of the return
+      value of any standard C-API function.
+
+      As a special case, for *temporary* buffers that are wrapped by
+      :c:func:`PyMemoryView_FromBuffer` or :c:func:`PyBuffer_FillInfo`
+      this field is *NULL*. In general, exporting objects MUST NOT
+      use this scheme.
+
+   .. c:member:: Py_ssize_t len
+
+      ``product(shape) * itemsize``. For contiguous arrays, this is the length
+      of the underlying memory block. For non-contiguous arrays, it is the length
+      that the logical structure would have if it were copied to a contiguous
+      representation.
+
+      Accessing ``((char *)buf)[0] up to ((char *)buf)[len-1]`` is only valid
+      if the buffer has been obtained by a request that guarantees contiguity. In
+      most cases such a request will be :c:macro:`PyBUF_SIMPLE` or :c:macro:`PyBUF_WRITABLE`.
+
+   .. c:member:: int readonly
+
+      An indicator of whether the buffer is read-only. This field is controlled
+      by the :c:macro:`PyBUF_WRITABLE` flag.
+
+   .. c:member:: Py_ssize_t itemsize
+
+      Item size in bytes of a single element. Same as the value of :func:`struct.calcsize`
+      called on non-NULL :c:member:`~Py_buffer.format` values.
+
+      Important exception: If a consumer requests a buffer without the
+      :c:macro:`PyBUF_FORMAT` flag, :c:member:`~Py_buffer.format` will
+      be set to  *NULL*,  but :c:member:`~Py_buffer.itemsize` still has
+      the value for the original format.
+
+      If :c:member:`~Py_buffer.shape` is present, the equality
+      ``product(shape) * itemsize == len`` still holds and the consumer
+      can use :c:member:`~Py_buffer.itemsize` to navigate the buffer.
+
+      If :c:member:`~Py_buffer.shape` is *NULL* as a result of a :c:macro:`PyBUF_SIMPLE`
+      or a :c:macro:`PyBUF_WRITABLE` request, the consumer must disregard
+      :c:member:`~Py_buffer.itemsize` and assume ``itemsize == 1``.
+
+   .. c:member:: const char \*format
+
+      A *NUL* terminated string in :mod:`struct` module style syntax describing
+      the contents of a single item. If this is *NULL*, ``"B"`` (unsigned bytes)
+      is assumed.
+
+      This field is controlled by the :c:macro:`PyBUF_FORMAT` flag.
+
+   .. c:member:: int ndim
+
+      The number of dimensions the memory represents as an n-dimensional array.
+      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.
+
+   .. c:member:: Py_ssize_t \*shape
+
+      An array of :c:type:`Py_ssize_t` of length :c:member:`~Py_buffer.ndim`
+      indicating the shape of the memory as an n-dimensional array. Note that
+      ``shape[0] * ... * shape[ndim-1] * itemsize`` MUST be equal to
+      :c:member:`~Py_buffer.len`.
+
+      Shape values are restricted to ``shape[n] >= 0``. The case
+      ``shape[n] == 0`` requires special attention. See `complex arrays`_
+      for further information.
+
+      The shape array is read-only for the consumer.
+
+   .. c:member:: Py_ssize_t \*strides
+
+      An array of :c:type:`Py_ssize_t` of length :c:member:`~Py_buffer.ndim`
+      giving the number of bytes to skip to get to a new element in each
+      dimension.
+
+      Stride values can be any integer. For regular arrays, strides are
+      usually positive, but a consumer MUST be able to handle the case
+      ``strides[n] <= 0``. See `complex arrays`_ for further information.
+
+      The strides array is read-only for the consumer.
+
+   .. c:member:: Py_ssize_t \*suboffsets
+
+      An array of :c:type:`Py_ssize_t` of length :c:member:`~Py_buffer.ndim`.
+      If ``suboffsets[n] >= 0``, the values stored along the nth dimension are
+      pointers and the suboffset value dictates how many bytes to add to each
+      pointer after de-referencing. A suboffset value that is negative
+      indicates that no de-referencing should occur (striding in a contiguous
+      memory block).
+
+      If all suboffsets are negative (i.e. no de-referencing is needed), then
+      this field must be NULL (the default value).
+
+      This type of array representation is used by the Python Imaging Library
+      (PIL). See `complex arrays`_ for further information how to access elements
+      of such an array.
+
+      The suboffsets array is read-only for the consumer.
+
+   .. c:member:: void \*internal
+
+      This is for use internally by the exporting object. For example, this
+      might be re-cast as an integer by the exporter and used to store flags
+      about whether or not the shape, strides, and suboffsets arrays must be
+      freed when the buffer is released. The consumer MUST NOT alter this
+      value.
+
+.. _buffer-request-types:
+
+Buffer request types
+====================
+
+Buffers are usually obtained by sending a buffer request to an exporting
+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
+type.
+
+request-independent fields
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+The following fields are not influenced by *flags* and must always be filled in
+with the correct values: :c:member:`~Py_buffer.obj`, :c:member:`~Py_buffer.buf`,
+:c:member:`~Py_buffer.len`, :c:member:`~Py_buffer.itemsize`, :c:member:`~Py_buffer.ndim`.
+
+
+readonly, format
+~~~~~~~~~~~~~~~~
+
+   .. c:macro:: PyBUF_WRITABLE
+
+      Controls the :c:member:`~Py_buffer.readonly` field. If set, the exporter
+      MUST provide a writable buffer or else report failure. Otherwise, the
+      exporter MAY provide either a read-only or writable buffer, but the choice
+      MUST be consistent for all consumers.
+
+   .. c:macro:: PyBUF_FORMAT
+
+      Controls the :c:member:`~Py_buffer.format` field. If set, this field MUST
+      be filled in correctly. Otherwise, this field MUST be *NULL*.
+
+
+:c:macro:`PyBUF_WRITABLE` can be \|'d to any of the flags in the next section.
+Since :c:macro:`PyBUF_SIMPLE` is defined as 0, :c:macro:`PyBUF_WRITABLE`
+can be used as a stand-alone flag to request a simple writable buffer.
+
+:c:macro:`PyBUF_FORMAT` can be \|'d to any of the flags except :c:macro:`PyBUF_SIMPLE`.
+The latter already implies format ``B`` (unsigned bytes).
+
+
+shape, strides, suboffsets
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The flags that control the logical structure of the memory are listed
+in decreasing order of complexity. Note that each flag contains all bits
+of the flags below it.
+
+.. tabularcolumns:: |p{0.35\linewidth}|l|l|l|
+
++-----------------------------+-------+---------+------------+
+|  Request                    | shape | strides | suboffsets |
++=============================+=======+=========+============+
+| .. c:macro:: PyBUF_INDIRECT |  yes  |   yes   | if needed  |
++-----------------------------+-------+---------+------------+
+| .. c:macro:: PyBUF_STRIDES  |  yes  |   yes   |    NULL    |
++-----------------------------+-------+---------+------------+
+| .. c:macro:: PyBUF_ND       |  yes  |   NULL  |    NULL    |
++-----------------------------+-------+---------+------------+
+| .. c:macro:: PyBUF_SIMPLE   |  NULL |   NULL  |    NULL    |
++-----------------------------+-------+---------+------------+
+
+
+.. index:: contiguous, C-contiguous, Fortran contiguous
+
+contiguity requests
+~~~~~~~~~~~~~~~~~~~
+
+C or Fortran :term:`contiguity <contiguous>` can be explicitly requested,
+with and without stride information. Without stride information, the buffer
+must be C-contiguous.
+
+.. tabularcolumns:: |p{0.35\linewidth}|l|l|l|l|
+
++-----------------------------------+-------+---------+------------+--------+
+|  Request                          | shape | strides | suboffsets | contig |
++===================================+=======+=========+============+========+
+| .. c:macro:: PyBUF_C_CONTIGUOUS   |  yes  |   yes   |    NULL    |   C    |
++-----------------------------------+-------+---------+------------+--------+
+| .. c:macro:: PyBUF_F_CONTIGUOUS   |  yes  |   yes   |    NULL    |   F    |
++-----------------------------------+-------+---------+------------+--------+
+| .. c:macro:: PyBUF_ANY_CONTIGUOUS |  yes  |   yes   |    NULL    | C or F |
++-----------------------------------+-------+---------+------------+--------+
+| .. c:macro:: PyBUF_ND             |  yes  |   NULL  |    NULL    |   C    |
++-----------------------------------+-------+---------+------------+--------+
+
+
+compound requests
+~~~~~~~~~~~~~~~~~
+
+All possible requests are fully defined by some combination of the flags in
+the previous section. For convenience, the buffer protocol provides frequently
+used combinations as single flags.
+
+In the following table *U* stands for undefined contiguity. The consumer would
+have to call :c:func:`PyBuffer_IsContiguous` to determine contiguity.
+
+.. tabularcolumns:: |p{0.35\linewidth}|l|l|l|l|l|l|
+
++-------------------------------+-------+---------+------------+--------+----------+--------+
+|  Request                      | shape | strides | suboffsets | contig | readonly | format |
++===============================+=======+=========+============+========+==========+========+
+| .. c:macro:: PyBUF_FULL       |  yes  |   yes   | if needed  |   U    |     0    |  yes   |
++-------------------------------+-------+---------+------------+--------+----------+--------+
+| .. c:macro:: PyBUF_FULL_RO    |  yes  |   yes   | if needed  |   U    |  1 or 0  |  yes   |
++-------------------------------+-------+---------+------------+--------+----------+--------+
+| .. c:macro:: PyBUF_RECORDS    |  yes  |   yes   |    NULL    |   U    |     0    |  yes   |
++-------------------------------+-------+---------+------------+--------+----------+--------+
+| .. c:macro:: PyBUF_RECORDS_RO |  yes  |   yes   |    NULL    |   U    |  1 or 0  |  yes   |
++-------------------------------+-------+---------+------------+--------+----------+--------+
+| .. c:macro:: PyBUF_STRIDED    |  yes  |   yes   |    NULL    |   U    |     0    |  NULL  |
++-------------------------------+-------+---------+------------+--------+----------+--------+
+| .. c:macro:: PyBUF_STRIDED_RO |  yes  |   yes   |    NULL    |   U    |  1 or 0  |  NULL  |
++-------------------------------+-------+---------+------------+--------+----------+--------+
+| .. c:macro:: PyBUF_CONTIG     |  yes  |   NULL  |    NULL    |   C    |     0    |  NULL  |
++-------------------------------+-------+---------+------------+--------+----------+--------+
+| .. c:macro:: PyBUF_CONTIG_RO  |  yes  |   NULL  |    NULL    |   C    |  1 or 0  |  NULL  |
++-------------------------------+-------+---------+------------+--------+----------+--------+
+
+
+Complex arrays
+==============
+
+NumPy-style: shape and strides
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The logical structure of NumPy-style arrays is defined by :c:member:`~Py_buffer.itemsize`,
+:c:member:`~Py_buffer.ndim`, :c:member:`~Py_buffer.shape` and :c:member:`~Py_buffer.strides`.
+
+If ``ndim == 0``, the memory location pointed to by :c:member:`~Py_buffer.buf` is
+interpreted as a scalar of size :c:member:`~Py_buffer.itemsize`. In that case,
+both :c:member:`~Py_buffer.shape` and :c:member:`~Py_buffer.strides` are *NULL*.
+
+If :c:member:`~Py_buffer.strides` is *NULL*, the array is interpreted as
+a standard n-dimensional C-array. Otherwise, the consumer must access an
+n-dimensional array as follows:
+
+   ``ptr = (char *)buf + indices[0] * strides[0] + ... + indices[n-1] * strides[n-1]``
+   ``item = *((typeof(item) *)ptr);``
+
+
+As noted above, :c:member:`~Py_buffer.buf` can point to any location within
+the actual memory block. An exporter can check the validity of a buffer with
+this function:
+
+.. code-block:: python
+
+   def verify_structure(memlen, itemsize, ndim, shape, strides, offset):
+       """Verify that the parameters represent a valid array within
+          the bounds of the allocated memory:
+              char *mem: start of the physical memory block
+              memlen: length of the physical memory block
+              offset: (char *)buf - mem
+       """
+       if offset % itemsize:
+           return False
+       if offset < 0 or offset+itemsize > memlen:
+           return False
+       if any(v % itemsize for v in strides):
+           return False
+
+       if ndim <= 0:
+           return ndim == 0 and not shape and not strides
+       if 0 in shape:
+           return True
+
+       imin = sum(strides[j]*(shape[j]-1) for j in range(ndim)
+                  if strides[j] <= 0)
+       imax = sum(strides[j]*(shape[j]-1) for j in range(ndim)
+                  if strides[j] > 0)
+
+       return 0 <= offset+imin and offset+imax+itemsize <= memlen
+
+
+PIL-style: shape, strides and suboffsets
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In addition to the regular items, PIL-style arrays can contain pointers
+that must be followed in order to get to the next element in a dimension.
+For example, the regular three-dimensional C-array ``char v[2][2][3]`` can
+also be viewed as an array of 2 pointers to 2 two-dimensional arrays:
+``char (*v[2])[2][3]``. In suboffsets representation, those two pointers
+can be embedded at the start of :c:member:`~Py_buffer.buf`, pointing
+to two ``char x[2][3]`` arrays that can be located anywhere in memory.
+
+
+Here is a function that returns a pointer to the element in an N-D array
+pointed to by an N-dimensional index when there are both non-NULL strides
+and suboffsets::
+
+   void *get_item_pointer(int ndim, void *buf, Py_ssize_t *strides,
+                          Py_ssize_t *suboffsets, Py_ssize_t *indices) {
+       char *pointer = (char*)buf;
+       int i;
+       for (i = 0; i < ndim; i++) {
+           pointer += strides[i] * indices[i];
+           if (suboffsets[i] >=0 ) {
+               pointer = *((char**)pointer) + suboffsets[i];
+           }
+       }
+       return (void*)pointer;
+   }
+
+
+Buffer-related functions
+========================
+
+.. c:function:: int PyObject_CheckBuffer(PyObject *obj)
+
+   Return ``1`` if *obj* supports the buffer interface otherwise ``0``.  When ``1`` is
+   returned, it doesn't guarantee that :c:func:`PyObject_GetBuffer` will
+   succeed.  This function always succeeds.
+
+
+.. c:function:: int PyObject_GetBuffer(PyObject *exporter, Py_buffer *view, int flags)
+
+   Send a request to *exporter* to fill in *view* as specified by  *flags*.
+   If the exporter cannot provide a buffer of the exact type, it MUST raise
+   :c:data:`PyExc_BufferError`, set :c:member:`view->obj` to *NULL* and
+   return ``-1``.
+
+   On success, fill in *view*, set :c:member:`view->obj` to a new reference
+   to *exporter* and return 0. In the case of chained buffer providers
+   that redirect requests to a single object, :c:member:`view->obj` MAY
+   refer to this object instead of *exporter* (See :ref:`Buffer Object Structures <buffer-structs>`).
+
+   Successful calls to :c:func:`PyObject_GetBuffer` must be paired with calls
+   to :c:func:`PyBuffer_Release`, similar to :c:func:`malloc` and :c:func:`free`.
+   Thus, after the consumer is done with the buffer, :c:func:`PyBuffer_Release`
+   must be called exactly once.
+
+
+.. c:function:: void PyBuffer_Release(Py_buffer *view)
+
+   Release the buffer *view* and decrement the reference count for
+   :c:member:`view->obj`. This function MUST be called when the buffer
+   is no longer being used, otherwise reference leaks may occur.
+
+   It is an error to call this function on a buffer that was not obtained via
+   :c:func:`PyObject_GetBuffer`.
+
+
+.. c:function:: Py_ssize_t PyBuffer_SizeFromFormat(const char *)
+
+   Return the implied :c:data:`~Py_buffer.itemsize` from :c:data:`~Py_buffer.format`.
+   This function is not yet implemented.
+
+
+.. c:function:: int PyBuffer_IsContiguous(Py_buffer *view, char order)
+
+   Return ``1`` if the memory defined by the *view* is C-style (*order* is
+   ``'C'``) or Fortran-style (*order* is ``'F'``) :term:`contiguous` or either one
+   (*order* is ``'A'``).  Return ``0`` otherwise.  This function always succeeds.
+
+
+.. c:function:: int PyBuffer_ToContiguous(void *buf, Py_buffer *src, Py_ssize_t len, char order)
+
+   Copy *len* bytes from *src* to its contiguous representation in *buf*.
+   *order* can be ``'C'`` or ``'F'`` (for C-style or Fortran-style ordering).
+   ``0`` is returned on success, ``-1`` on error.
+
+   This function fails if *len* != *src->len*.
+
+
+.. c:function:: void PyBuffer_FillContiguousStrides(int ndims, Py_ssize_t *shape, Py_ssize_t *strides, int itemsize, char order)
+
+   Fill the *strides* array with byte-strides of a :term:`contiguous` (C-style if
+   *order* is ``'C'`` or Fortran-style if *order* is ``'F'``) array of the
+   given shape with the given number of bytes per element.
+
+
+.. c:function:: int PyBuffer_FillInfo(Py_buffer *view, PyObject *exporter, void *buf, Py_ssize_t len, int readonly, int flags)
+
+   Handle buffer requests for an exporter that wants to expose *buf* of size *len*
+   with writability set according to *readonly*. *buf* is interpreted as a sequence
+   of unsigned bytes.
+
+   The *flags* argument indicates the request type. This function always fills in
+   *view* as specified by flags, unless *buf* has been designated as read-only
+   and :c:macro:`PyBUF_WRITABLE` is set in *flags*.
+
+   On success, set :c:member:`view->obj` to a new reference to *exporter* and
+   return 0. Otherwise, raise :c:data:`PyExc_BufferError`, set
+   :c:member:`view->obj` to *NULL* and return ``-1``;
+
+   If this function is used as part of a :ref:`getbufferproc <buffer-structs>`,
+   *exporter* MUST be set to the exporting object and *flags* must be passed
+   unmodified. Otherwise, *exporter* MUST be NULL.

third_party/python/Doc/c-api/bytearray.rst

@@ -0,0 +1,87 @@
+.. highlightlang:: c
+
+.. _bytearrayobjects:
+
+Byte Array Objects
+------------------
+
+.. index:: object: bytearray
+
+
+.. c:type:: PyByteArrayObject
+
+   This subtype of :c:type:`PyObject` represents a Python bytearray object.
+
+
+.. c:var:: PyTypeObject PyByteArray_Type
+
+   This instance of :c:type:`PyTypeObject` represents the Python bytearray type;
+   it is the same object as :class:`bytearray` in the Python layer.
+
+
+Type check macros
+^^^^^^^^^^^^^^^^^
+
+.. c:function:: int PyByteArray_Check(PyObject *o)
+
+   Return true if the object *o* is a bytearray object or an instance of a
+   subtype of the bytearray type.
+
+
+.. c:function:: int PyByteArray_CheckExact(PyObject *o)
+
+   Return true if the object *o* is a bytearray object, but not an instance of a
+   subtype of the bytearray type.
+
+
+Direct API functions
+^^^^^^^^^^^^^^^^^^^^
+
+.. c:function:: PyObject* PyByteArray_FromObject(PyObject *o)
+
+   Return a new bytearray object from any object, *o*, that implements the
+   :ref:`buffer protocol <bufferobjects>`.
+
+   .. XXX expand about the buffer protocol, at least somewhere
+
+
+.. c:function:: PyObject* PyByteArray_FromStringAndSize(const char *string, Py_ssize_t len)
+
+   Create a new bytearray object from *string* and its length, *len*.  On
+   failure, *NULL* is returned.
+
+
+.. c:function:: PyObject* PyByteArray_Concat(PyObject *a, PyObject *b)
+
+   Concat bytearrays *a* and *b* and return a new bytearray with the result.
+
+
+.. c:function:: Py_ssize_t PyByteArray_Size(PyObject *bytearray)
+
+   Return the size of *bytearray* after checking for a *NULL* pointer.
+
+
+.. c:function:: char* PyByteArray_AsString(PyObject *bytearray)
+
+   Return the contents of *bytearray* as a char array after checking for a
+   *NULL* pointer.  The returned array always has an extra
+   null byte appended.
+
+
+.. c:function:: int PyByteArray_Resize(PyObject *bytearray, Py_ssize_t len)
+
+   Resize the internal buffer of *bytearray* to *len*.
+
+Macros
+^^^^^^
+
+These macros trade safety for speed and they don't check pointers.
+
+.. c:function:: char* PyByteArray_AS_STRING(PyObject *bytearray)
+
+   Macro version of :c:func:`PyByteArray_AsString`.
+
+
+.. c:function:: Py_ssize_t PyByteArray_GET_SIZE(PyObject *bytearray)
+
+   Macro version of :c:func:`PyByteArray_Size`.

third_party/python/Doc/c-api/bytes.rst

@@ -0,0 +1,202 @@
+.. highlightlang:: c
+
+.. _bytesobjects:
+
+Bytes Objects
+-------------
+
+These functions raise :exc:`TypeError` when expecting a bytes parameter and are
+called with a non-bytes parameter.
+
+.. index:: object: bytes
+
+
+.. c:type:: PyBytesObject
+
+   This subtype of :c:type:`PyObject` represents a Python bytes object.
+
+
+.. c:var:: PyTypeObject PyBytes_Type
+
+   This instance of :c:type:`PyTypeObject` represents the Python bytes type; it
+   is the same object as :class:`bytes` in the Python layer.
+
+
+.. c:function:: int PyBytes_Check(PyObject *o)
+
+   Return true if the object *o* is a bytes object or an instance of a subtype
+   of the bytes type.
+
+
+.. c:function:: int PyBytes_CheckExact(PyObject *o)
+
+   Return true if the object *o* is a bytes object, but not an instance of a
+   subtype of the bytes type.
+
+
+.. c:function:: PyObject* PyBytes_FromString(const char *v)
+
+   Return a new bytes object with a copy of the string *v* as value on success,
+   and *NULL* on failure.  The parameter *v* must not be *NULL*; it will not be
+   checked.
+
+
+.. c:function:: PyObject* PyBytes_FromStringAndSize(const char *v, Py_ssize_t len)
+
+   Return a new bytes object with a copy of the string *v* as value and length
+   *len* on success, and *NULL* on failure.  If *v* is *NULL*, the contents of
+   the bytes object are uninitialized.
+
+
+.. c:function:: PyObject* PyBytes_FromFormat(const char *format, ...)
+
+   Take a C :c:func:`printf`\ -style *format* string and a variable number of
+   arguments, calculate the size of the resulting Python bytes object and return
+   a bytes object with the values formatted into it.  The variable arguments
+   must be C types and must correspond exactly to the format characters in the
+   *format* string.  The following format characters are allowed:
+
+   .. % XXX: This should be exactly the same as the table in PyErr_Format.
+   .. % One should just refer to the other.
+   .. % XXX: The descriptions for %zd and %zu are wrong, but the truth is complicated
+   .. % because not all compilers support the %z width modifier -- we fake it
+   .. % when necessary via interpolating PY_FORMAT_SIZE_T.
+
+   .. tabularcolumns:: |l|l|L|
+
+   +-------------------+---------------+--------------------------------+
+   | Format Characters | Type          | Comment                        |
+   +===================+===============+================================+
+   | :attr:`%%`        | *n/a*         | The literal % character.       |
+   +-------------------+---------------+--------------------------------+
+   | :attr:`%c`        | int           | A single byte,                 |
+   |                   |               | represented as a C int.        |
+   +-------------------+---------------+--------------------------------+
+   | :attr:`%d`        | int           | Exactly equivalent to          |
+   |                   |               | ``printf("%d")``.              |
+   +-------------------+---------------+--------------------------------+
+   | :attr:`%u`        | unsigned int  | Exactly equivalent to          |
+   |                   |               | ``printf("%u")``.              |
+   +-------------------+---------------+--------------------------------+
+   | :attr:`%ld`       | long          | Exactly equivalent to          |
+   |                   |               | ``printf("%ld")``.             |
+   +-------------------+---------------+--------------------------------+
+   | :attr:`%lu`       | unsigned long | Exactly equivalent to          |
+   |                   |               | ``printf("%lu")``.             |
+   +-------------------+---------------+--------------------------------+
+   | :attr:`%zd`       | Py_ssize_t    | Exactly equivalent to          |
+   |                   |               | ``printf("%zd")``.             |
+   +-------------------+---------------+--------------------------------+
+   | :attr:`%zu`       | size_t        | Exactly equivalent to          |
+   |                   |               | ``printf("%zu")``.             |
+   +-------------------+---------------+--------------------------------+
+   | :attr:`%i`        | int           | Exactly equivalent to          |
+   |                   |               | ``printf("%i")``.              |
+   +-------------------+---------------+--------------------------------+
+   | :attr:`%x`        | int           | Exactly equivalent to          |
+   |                   |               | ``printf("%x")``.              |
+   +-------------------+---------------+--------------------------------+
+   | :attr:`%s`        | char\*        | A null-terminated C character  |
+   |                   |               | array.                         |
+   +-------------------+---------------+--------------------------------+
+   | :attr:`%p`        | void\*        | The hex representation of a C  |
+   |                   |               | pointer. Mostly equivalent to  |
+   |                   |               | ``printf("%p")`` except that   |
+   |                   |               | it is guaranteed to start with |
+   |                   |               | the literal ``0x`` regardless  |
+   |                   |               | of what the platform's         |
+   |                   |               | ``printf`` yields.             |
+   +-------------------+---------------+--------------------------------+
+
+   An unrecognized format character causes all the rest of the format string to be
+   copied as-is to the result object, and any extra arguments discarded.
+
+
+.. c:function:: PyObject* PyBytes_FromFormatV(const char *format, va_list vargs)
+
+   Identical to :c:func:`PyBytes_FromFormat` except that it takes exactly two
+   arguments.
+
+
+.. c:function:: PyObject* PyBytes_FromObject(PyObject *o)
+
+   Return the bytes representation of object *o* that implements the buffer
+   protocol.
+
+
+.. c:function:: Py_ssize_t PyBytes_Size(PyObject *o)
+
+   Return the length of the bytes in bytes object *o*.
+
+
+.. c:function:: Py_ssize_t PyBytes_GET_SIZE(PyObject *o)
+
+   Macro form of :c:func:`PyBytes_Size` but without error checking.
+
+
+.. c:function:: char* PyBytes_AsString(PyObject *o)
+
+   Return a pointer to the contents of *o*.  The pointer
+   refers to the internal buffer of *o*, which consists of ``len(o) + 1``
+   bytes.  The last byte in the buffer is always null, regardless of
+   whether there are any other null bytes.  The data must not be
+   modified in any way, unless the object was just created using
+   ``PyBytes_FromStringAndSize(NULL, size)``. It must not be deallocated.  If
+   *o* is not a bytes object at all, :c:func:`PyBytes_AsString` returns *NULL*
+   and raises :exc:`TypeError`.
+
+
+.. c:function:: char* PyBytes_AS_STRING(PyObject *string)
+
+   Macro form of :c:func:`PyBytes_AsString` but without error checking.
+
+
+.. c:function:: int PyBytes_AsStringAndSize(PyObject *obj, char **buffer, Py_ssize_t *length)
+
+   Return the null-terminated contents of the object *obj*
+   through the output variables *buffer* and *length*.
+
+   If *length* is *NULL*, the bytes object
+   may not contain embedded null bytes;
+   if it does, the function returns ``-1`` and a :exc:`ValueError` is raised.
+
+   The buffer refers to an internal buffer of *obj*, which includes an
+   additional null byte at the end (not counted in *length*).  The data
+   must not be modified in any way, unless the object was just created using
+   ``PyBytes_FromStringAndSize(NULL, size)``.  It must not be deallocated.  If
+   *obj* is not a bytes object at all, :c:func:`PyBytes_AsStringAndSize`
+   returns ``-1`` and raises :exc:`TypeError`.
+
+   .. versionchanged:: 3.5
+      Previously, :exc:`TypeError` was raised when embedded null bytes were
+      encountered in the bytes object.
+
+
+.. c:function:: void PyBytes_Concat(PyObject **bytes, PyObject *newpart)
+
+   Create a new bytes object in *\*bytes* containing the contents of *newpart*
+   appended to *bytes*; the caller will own the new reference.  The reference to
+   the old value of *bytes* will be stolen.  If the new object cannot be
+   created, the old reference to *bytes* will still be discarded and the value
+   of *\*bytes* will be set to *NULL*; the appropriate exception will be set.
+
+
+.. 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*.
+
+
+.. c:function:: int _PyBytes_Resize(PyObject **bytes, Py_ssize_t newsize)
+
+   A way to resize a bytes object even though it is "immutable". Only use this
+   to build up a brand new bytes object; don't use this if the bytes may already
+   be known in other parts of the code.  It is an error to call this function if
+   the refcount on the input bytes object is not one. Pass the address of an
+   existing bytes object as an lvalue (it may be written into), and the new size
+   desired.  On success, *\*bytes* holds the resized bytes object and ``0`` is
+   returned; the address in *\*bytes* may differ from its input value.  If the
+   reallocation fails, the original bytes object at *\*bytes* is deallocated,
+   *\*bytes* is set to *NULL*, :exc:`MemoryError` is set, and ``-1`` is
+   returned.

third_party/python/Doc/c-api/capsule.rst

@@ -0,0 +1,157 @@
+.. highlightlang:: c
+
+.. _capsules:
+
+Capsules
+--------
+
+.. index:: object: Capsule
+
+Refer to :ref:`using-capsules` for more information on using these objects.
+
+.. versionadded:: 3.1
+
+
+.. c:type:: PyCapsule
+
+   This subtype of :c:type:`PyObject` represents an opaque value, useful for C
+   extension modules who need to pass an opaque value (as a :c:type:`void\*`
+   pointer) through Python code to other C code.  It is often used to make a C
+   function pointer defined in one module available to other modules, so the
+   regular import mechanism can be used to access C APIs defined in dynamically
+   loaded modules.
+
+
+.. c:type:: PyCapsule_Destructor
+
+   The type of a destructor callback for a capsule.  Defined as::
+
+      typedef void (*PyCapsule_Destructor)(PyObject *);
+
+   See :c:func:`PyCapsule_New` for the semantics of PyCapsule_Destructor
+   callbacks.
+
+
+.. c:function:: int PyCapsule_CheckExact(PyObject *p)
+
+   Return true if its argument is a :c:type:`PyCapsule`.
+
+
+.. c:function:: PyObject* PyCapsule_New(void *pointer, const char *name, PyCapsule_Destructor destructor)
+
+   Create a :c:type:`PyCapsule` encapsulating the *pointer*.  The *pointer*
+   argument may not be *NULL*.
+
+   On failure, set an exception and return *NULL*.
+
+   The *name* string may either be *NULL* or a pointer to a valid C string.  If
+   non-*NULL*, this string must outlive the capsule.  (Though it is permitted to
+   free it inside the *destructor*.)
+
+   If the *destructor* argument is not *NULL*, it will be called with the
+   capsule as its argument when it is destroyed.
+
+   If this capsule will be stored as an attribute of a module, the *name* should
+   be specified as ``modulename.attributename``.  This will enable other modules
+   to import the capsule using :c:func:`PyCapsule_Import`.
+
+
+.. c:function:: void* PyCapsule_GetPointer(PyObject *capsule, const char *name)
+
+   Retrieve the *pointer* stored in the capsule.  On failure, set an exception
+   and return *NULL*.
+
+   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
+   names.
+
+
+.. c:function:: PyCapsule_Destructor PyCapsule_GetDestructor(PyObject *capsule)
+
+   Return the current destructor stored in the capsule.  On failure, set an
+   exception and return *NULL*.
+
+   It is legal for a capsule to have a *NULL* destructor.  This makes a *NULL*
+   return code somewhat ambiguous; use :c:func:`PyCapsule_IsValid` or
+   :c:func:`PyErr_Occurred` to disambiguate.
+
+
+.. c:function:: void* PyCapsule_GetContext(PyObject *capsule)
+
+   Return the current context stored in the capsule.  On failure, set an
+   exception and return *NULL*.
+
+   It is legal for a capsule to have a *NULL* context.  This makes a *NULL*
+   return code somewhat ambiguous; use :c:func:`PyCapsule_IsValid` or
+   :c:func:`PyErr_Occurred` to disambiguate.
+
+
+.. c:function:: const char* PyCapsule_GetName(PyObject *capsule)
+
+   Return the current name stored in the capsule.  On failure, set an exception
+   and return *NULL*.
+
+   It is legal for a capsule to have a *NULL* name.  This makes a *NULL* return
+   code somewhat ambiguous; use :c:func:`PyCapsule_IsValid` or
+   :c:func:`PyErr_Occurred` to disambiguate.
+
+
+.. c:function:: void* PyCapsule_Import(const char *name, int no_block)
+
+   Import a pointer to a C object from a capsule attribute in a module.  The
+   *name* parameter should specify the full name to the attribute, as in
+   ``module.attribute``.  The *name* stored in the capsule must match this
+   string exactly.  If *no_block* is true, import the module without blocking
+   (using :c:func:`PyImport_ImportModuleNoBlock`).  If *no_block* is false,
+   import the module conventionally (using :c:func:`PyImport_ImportModule`).
+
+   Return the capsule's internal *pointer* on success.  On failure, set an
+   exception and return *NULL*.
+
+
+.. c:function:: int PyCapsule_IsValid(PyObject *capsule, const char *name)
+
+   Determines whether or not *capsule* is a valid capsule.  A valid capsule is
+   non-*NULL*, passes :c:func:`PyCapsule_CheckExact`, has a non-*NULL* pointer
+   stored in it, and its internal name matches the *name* parameter.  (See
+   :c:func:`PyCapsule_GetPointer` for information on how capsule names are
+   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
+   guaranteed to succeed.
+
+   Return a nonzero value if the object is valid and matches the name passed in.
+   Return ``0`` otherwise.  This function will not fail.
+
+
+.. c:function:: int PyCapsule_SetContext(PyObject *capsule, void *context)
+
+   Set the context pointer inside *capsule* to *context*.
+
+   Return ``0`` on success.  Return nonzero and set an exception on failure.
+
+
+.. c:function:: int PyCapsule_SetDestructor(PyObject *capsule, PyCapsule_Destructor destructor)
+
+   Set the destructor inside *capsule* to *destructor*.
+
+   Return ``0`` on success.  Return nonzero and set an exception on failure.
+
+
+.. c:function:: int PyCapsule_SetName(PyObject *capsule, const char *name)
+
+   Set the name inside *capsule* to *name*.  If non-*NULL*, the name must
+   outlive the capsule.  If the previous *name* stored in the capsule was not
+   *NULL*, no attempt is made to free it.
+
+   Return ``0`` on success.  Return nonzero and set an exception on failure.
+
+
+.. c:function:: int PyCapsule_SetPointer(PyObject *capsule, void *pointer)
+
+   Set the void pointer inside *capsule* to *pointer*.  The pointer may not be
+   *NULL*.
+
+   Return ``0`` on success.  Return nonzero and set an exception on failure.

third_party/python/Doc/c-api/cell.rst

@@ -0,0 +1,62 @@
+.. highlightlang:: c
+
+.. _cell-objects:
+
+Cell Objects
+------------
+
+"Cell" objects are used to implement variables referenced by multiple scopes.
+For each such variable, a cell object is created to store the value; the local
+variables of each stack frame that references the value contains a reference to
+the cells from outer scopes which also use that variable.  When the value is
+accessed, the value contained in the cell is used instead of the cell object
+itself.  This de-referencing of the cell object requires support from the
+generated byte-code; these are not automatically de-referenced when accessed.
+Cell objects are not likely to be useful elsewhere.
+
+
+.. c:type:: PyCellObject
+
+   The C structure used for cell objects.
+
+
+.. c:var:: PyTypeObject PyCell_Type
+
+   The type object corresponding to cell objects.
+
+
+.. c:function:: int PyCell_Check(ob)
+
+   Return true if *ob* is a cell object; *ob* must not be *NULL*.
+
+
+.. c:function:: PyObject* PyCell_New(PyObject *ob)
+
+   Create and return a new cell object containing the value *ob*. The parameter may
+   be *NULL*.
+
+
+.. c:function:: PyObject* PyCell_Get(PyObject *cell)
+
+   Return the contents of the cell *cell*.
+
+
+.. c:function:: PyObject* PyCell_GET(PyObject *cell)
+
+   Return the contents of the cell *cell*, but without checking that *cell* is
+   non-*NULL* and a cell object.
+
+
+.. c:function:: int PyCell_Set(PyObject *cell, PyObject *value)
+
+   Set the contents of the cell object *cell* to *value*.  This releases the
+   reference to any current content of the cell. *value* may be *NULL*.  *cell*
+   must be non-*NULL*; if it is not a cell object, ``-1`` will be returned.  On
+   success, ``0`` will be returned.
+
+
+.. c:function:: void PyCell_SET(PyObject *cell, PyObject *value)
+
+   Sets the value of the cell object *cell* to *value*.  No reference counts are
+   adjusted, and no checks are made for safety; *cell* must be non-*NULL* and must
+   be a cell object.

third_party/python/Doc/c-api/code.rst

@@ -0,0 +1,48 @@
+.. highlightlang:: c
+
+.. _codeobjects:
+
+.. index:: object; code, code object
+
+Code Objects
+------------
+
+.. sectionauthor:: Jeffrey Yasskin <jyasskin@gmail.com>
+
+Code objects are a low-level detail of the CPython implementation.
+Each one represents a chunk of executable code that hasn't yet been
+bound into a function.
+
+.. c:type:: PyCodeObject
+
+   The C structure of the objects used to describe code objects.  The
+   fields of this type are subject to change at any time.
+
+
+.. c:var:: PyTypeObject PyCode_Type
+
+   This is an instance of :c:type:`PyTypeObject` representing the Python
+   :class:`code` type.
+
+
+.. c:function:: int PyCode_Check(PyObject *co)
+
+   Return true if *co* is a :class:`code` object.
+
+.. c:function:: int PyCode_GetNumFree(PyCodeObject *co)
+
+   Return the number of free variables in *co*.
+
+.. c:function:: PyCodeObject* PyCode_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 *lnotab)
+
+   Return a new code object.  If you need a dummy code object to
+   create a frame, use :c:func:`PyCode_NewEmpty` instead.  Calling
+   :c:func:`PyCode_New` directly can bind you to a precise Python
+   version since the definition of the bytecode changes often.
+
+
+.. c:function:: PyCodeObject* PyCode_NewEmpty(const char *filename, const char *funcname, int firstlineno)
+
+   Return a new empty code object with the specified filename,
+   function name, and first line number.  It is illegal to
+   :func:`exec` or :func:`eval` the resulting code object.

third_party/python/Doc/c-api/codec.rst

@@ -0,0 +1,123 @@
+.. _codec-registry:
+
+Codec registry and support functions
+====================================
+
+.. c:function:: int PyCodec_Register(PyObject *search_function)
+
+   Register a new codec search function.
+
+   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_KnownEncoding(const char *encoding)
+
+   Return ``1`` or ``0`` depending on whether there is a registered codec for
+   the given *encoding*.  This function always succeeds.
+
+.. c:function:: PyObject* PyCodec_Encode(PyObject *object, const char *encoding, const char *errors)
+
+   Generic codec based encoding API.
+
+   *object* is passed through the encoder function found for the given
+   *encoding* using the error handling method defined by *errors*.  *errors* may
+   be *NULL* to use the default method defined for the codec.  Raises a
+   :exc:`LookupError` if no encoder can be found.
+
+.. c:function:: PyObject* PyCodec_Decode(PyObject *object, const char *encoding, const char *errors)
+
+   Generic codec based decoding API.
+
+   *object* is passed through the decoder function found for the given
+   *encoding* using the error handling method defined by *errors*.  *errors* may
+   be *NULL* to use the default method defined for the codec.  Raises a
+   :exc:`LookupError` if no encoder can be found.
+
+
+Codec lookup API
+----------------
+
+In the following functions, the *encoding* string is looked up converted to all
+lower-case characters, which makes encodings looked up through this mechanism
+effectively case-insensitive.  If no codec is found, a :exc:`KeyError` is set
+and *NULL* returned.
+
+.. c:function:: PyObject* PyCodec_Encoder(const char *encoding)
+
+   Get an encoder function for the given *encoding*.
+
+.. c:function:: PyObject* PyCodec_Decoder(const char *encoding)
+
+   Get a decoder function for the given *encoding*.
+
+.. c:function:: PyObject* PyCodec_IncrementalEncoder(const char *encoding, const char *errors)
+
+   Get an :class:`~codecs.IncrementalEncoder` object for the given *encoding*.
+
+.. c:function:: PyObject* PyCodec_IncrementalDecoder(const char *encoding, const char *errors)
+
+   Get an :class:`~codecs.IncrementalDecoder` object for the given *encoding*.
+
+.. c:function:: PyObject* PyCodec_StreamReader(const char *encoding, PyObject *stream, const char *errors)
+
+   Get a :class:`~codecs.StreamReader` factory function for the given *encoding*.
+
+.. c:function:: PyObject* PyCodec_StreamWriter(const char *encoding, PyObject *stream, const char *errors)
+
+   Get a :class:`~codecs.StreamWriter` factory function for the given *encoding*.
+
+
+Registry API for Unicode encoding error handlers
+------------------------------------------------
+
+.. c:function:: int PyCodec_RegisterError(const char *name, PyObject *error)
+
+   Register the error handling callback function *error* under the given *name*.
+   This callback function will be called by a codec when it encounters
+   unencodable characters/undecodable bytes and *name* is specified as the error
+   parameter in the call to the encode/decode function.
+
+   The callback gets a single argument, an instance of
+   :exc:`UnicodeEncodeError`, :exc:`UnicodeDecodeError` or
+   :exc:`UnicodeTranslateError` that holds information about the problematic
+   sequence of characters or bytes and their offset in the original string (see
+   :ref:`unicodeexceptions` for functions to extract this information).  The
+   callback must either raise the given exception, or return a two-item tuple
+   containing the replacement for the problematic sequence, and an integer
+   giving the offset in the original string at which encoding/decoding should be
+   resumed.
+
+   Return ``0`` on success, ``-1`` on error.
+
+.. c:function:: PyObject* PyCodec_LookupError(const char *name)
+
+   Lookup the error handling callback function registered under *name*.  As a
+   special case *NULL* can be passed, in which case the error handling callback
+   for "strict" will be returned.
+
+.. c:function:: PyObject* PyCodec_StrictErrors(PyObject *exc)
+
+   Raise *exc* as an exception.
+
+.. c:function:: PyObject* PyCodec_IgnoreErrors(PyObject *exc)
+
+   Ignore the unicode error, skipping the faulty input.
+
+.. c:function:: PyObject* PyCodec_ReplaceErrors(PyObject *exc)
+
+   Replace the unicode encode error with ``?`` or ``U+FFFD``.
+
+.. c:function:: PyObject* PyCodec_XMLCharRefReplaceErrors(PyObject *exc)
+
+   Replace the unicode encode error with XML character references.
+
+.. c:function:: PyObject* PyCodec_BackslashReplaceErrors(PyObject *exc)
+
+   Replace the unicode encode error with backslash escapes (``\x``, ``\u`` and
+   ``\U``).
+
+.. c:function:: PyObject* PyCodec_NameReplaceErrors(PyObject *exc)
+
+   Replace the unicode encode error with ``\N{...}`` escapes.
+
+   .. versionadded:: 3.5

third_party/python/Doc/c-api/complex.rst

@@ -0,0 +1,132 @@
+.. highlightlang:: c
+
+.. _complexobjects:
+
+Complex Number Objects
+----------------------
+
+.. index:: object: complex number
+
+Python's complex number objects are implemented as two distinct types when
+viewed from the C API:  one is the Python object exposed to Python programs, and
+the other is a C structure which represents the actual complex number value.
+The API provides functions for working with both.
+
+
+Complex Numbers as C Structures
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Note that the functions which accept these structures as parameters and return
+them as results do so *by value* rather than dereferencing them through
+pointers.  This is consistent throughout the API.
+
+
+.. c:type:: Py_complex
+
+   The C structure which corresponds to the value portion of a Python complex
+   number object.  Most of the functions for dealing with complex number objects
+   use structures of this type as input or output values, as appropriate.  It is
+   defined as::
+
+      typedef struct {
+         double real;
+         double imag;
+      } Py_complex;
+
+
+.. c:function:: Py_complex _Py_c_sum(Py_complex left, Py_complex right)
+
+   Return the sum of two complex numbers, using the C :c:type:`Py_complex`
+   representation.
+
+
+.. c:function:: Py_complex _Py_c_diff(Py_complex left, Py_complex right)
+
+   Return the difference between two complex numbers, using the C
+   :c:type:`Py_complex` representation.
+
+
+.. c:function:: Py_complex _Py_c_neg(Py_complex complex)
+
+   Return the negation of the complex number *complex*, using the C
+   :c:type:`Py_complex` representation.
+
+
+.. c:function:: Py_complex _Py_c_prod(Py_complex left, Py_complex right)
+
+   Return the product of two complex numbers, using the C :c:type:`Py_complex`
+   representation.
+
+
+.. c:function:: Py_complex _Py_c_quot(Py_complex dividend, Py_complex divisor)
+
+   Return the quotient of two complex numbers, using the C :c:type:`Py_complex`
+   representation.
+
+   If *divisor* is null, this method returns zero and sets
+   :c:data:`errno` to :c:data:`EDOM`.
+
+
+.. c:function:: Py_complex _Py_c_pow(Py_complex num, Py_complex exp)
+
+   Return the exponentiation of *num* by *exp*, using the C :c:type:`Py_complex`
+   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`.
+
+
+Complex Numbers as Python Objects
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+
+.. c:type:: PyComplexObject
+
+   This subtype of :c:type:`PyObject` represents a Python complex number object.
+
+
+.. c:var:: PyTypeObject PyComplex_Type
+
+   This instance of :c:type:`PyTypeObject` represents the Python complex number
+   type. It is the same object as :class:`complex` in the Python layer.
+
+
+.. c:function:: int PyComplex_Check(PyObject *p)
+
+   Return true if its argument is a :c:type:`PyComplexObject` or a subtype of
+   :c:type:`PyComplexObject`.
+
+
+.. c:function:: int PyComplex_CheckExact(PyObject *p)
+
+   Return true if its argument is a :c:type:`PyComplexObject`, but not a subtype of
+   :c:type:`PyComplexObject`.
+
+
+.. c:function:: PyObject* PyComplex_FromCComplex(Py_complex v)
+
+   Create a new Python complex number object from a C :c:type:`Py_complex` value.
+
+
+.. c:function:: PyObject* PyComplex_FromDoubles(double real, double imag)
+
+   Return a new :c:type:`PyComplexObject` object from *real* and *imag*.
+
+
+.. c:function:: double PyComplex_RealAsDouble(PyObject *op)
+
+   Return the real part of *op* as a C :c:type:`double`.
+
+
+.. c:function:: double PyComplex_ImagAsDouble(PyObject *op)
+
+   Return the imaginary part of *op* as a C :c:type:`double`.
+
+
+.. c:function:: Py_complex PyComplex_AsCComplex(PyObject *op)
+
+   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__`
+   method, this method will first be called to convert *op* to a Python complex
+   number object. Upon failure, this method returns ``-1.0`` as a real value.

third_party/python/Doc/c-api/concrete.rst

@@ -0,0 +1,117 @@
+.. highlightlang:: c
+
+
+.. _concrete:
+
+**********************
+Concrete Objects Layer
+**********************
+
+The functions in this chapter are specific to certain Python object types.
+Passing them an object of the wrong type is not a good idea; if you receive an
+object from a Python program and you are not sure that it has the right type,
+you must perform a type check first; for example, to check that an object is a
+dictionary, use :c:func:`PyDict_Check`.  The chapter is structured like the
+"family tree" of Python object types.
+
+.. warning::
+
+   While the functions described in this chapter carefully check the type of the
+   objects which are passed in, many of them do not check for *NULL* being passed
+   instead of a valid object.  Allowing *NULL* to be passed in can cause memory
+   access violations and immediate termination of the interpreter.
+
+
+.. _fundamental:
+
+Fundamental Objects
+===================
+
+This section describes Python type objects and the singleton object ``None``.
+
+.. toctree::
+
+   type.rst
+   none.rst
+
+
+.. _numericobjects:
+
+Numeric Objects
+===============
+
+.. index:: object: numeric
+
+.. toctree::
+
+   long.rst
+   bool.rst
+   float.rst
+   complex.rst
+
+
+.. _sequenceobjects:
+
+Sequence Objects
+================
+
+.. index:: object: sequence
+
+Generic operations on sequence objects were discussed in the previous chapter;
+this section deals with the specific kinds of sequence objects that are
+intrinsic to the Python language.
+
+.. XXX sort out unicode, str, bytes and bytearray
+
+.. toctree::
+
+   bytes.rst
+   bytearray.rst
+   unicode.rst
+   tuple.rst
+   list.rst
+
+
+.. _mapobjects:
+
+Container Objects
+=================
+
+.. index:: object: mapping
+
+.. toctree::
+
+   dict.rst
+   set.rst
+
+
+.. _otherobjects:
+
+Function Objects
+================
+
+.. toctree::
+
+   function.rst
+   method.rst
+   cell.rst
+   code.rst
+
+
+Other Objects
+=============
+
+.. toctree::
+
+   file.rst
+   module.rst
+   iterator.rst
+   descriptor.rst
+   slice.rst
+   memoryview.rst
+   weakref.rst
+   capsule.rst
+   gen.rst
+   coro.rst
+   datetime.rst
+

third_party/python/Doc/c-api/conversion.rst

@@ -0,0 +1,131 @@
+.. highlightlang:: c
+
+.. _string-conversion:
+
+String conversion and formatting
+================================
+
+Functions for number conversion and formatted string output.
+
+
+.. c:function:: int PyOS_snprintf(char *str, size_t size,  const char *format, ...)
+
+   Output not more than *size* bytes to *str* according to the format string
+   *format* and the extra arguments. See the Unix man page :manpage:`snprintf(2)`.
+
+
+.. c:function:: int PyOS_vsnprintf(char *str, size_t size, const char *format, va_list va)
+
+   Output not more than *size* bytes to *str* according to the format string
+   *format* and the variable argument list *va*. Unix man page
+   :manpage:`vsnprintf(2)`.
+
+:c:func:`PyOS_snprintf` and :c:func:`PyOS_vsnprintf` wrap the Standard C library
+functions :c:func:`snprintf` and :c:func:`vsnprintf`. Their purpose is to
+guarantee consistent behavior in corner cases, which the Standard C functions do
+not.
+
+The wrappers ensure that *str*[*size*-1] is always ``'\0'`` upon return. They
+never write more than *size* bytes (including the trailing ``'\0'``) into str.
+Both functions require that ``str != NULL``, ``size > 0`` and ``format !=
+NULL``.
+
+If the platform doesn't have :c:func:`vsnprintf` and the buffer size needed to
+avoid truncation exceeds *size* by more than 512 bytes, Python aborts with a
+*Py_FatalError*.
+
+The return value (*rv*) for these functions should be interpreted as follows:
+
+* When ``0 <= rv < size``, the output conversion was successful and *rv*
+  characters were written to *str* (excluding the trailing ``'\0'`` byte at
+  *str*[*rv*]).
+
+* When ``rv >= size``, the output conversion was truncated and a buffer with
+  ``rv + 1`` bytes would have been needed to succeed. *str*[*size*-1] is ``'\0'``
+  in this case.
+
+* When ``rv < 0``, "something bad happened." *str*[*size*-1] is ``'\0'`` in
+  this case too, but the rest of *str* is undefined. The exact cause of the error
+  depends on the underlying platform.
+
+The following functions provide locale-independent string to number conversions.
+
+
+.. c:function:: double PyOS_string_to_double(const char *s, char **endptr, PyObject *overflow_exception)
+
+   Convert a string ``s`` to a :c:type:`double`, raising a Python
+   exception on failure.  The set of accepted strings corresponds to
+   the set of strings accepted by Python's :func:`float` constructor,
+   except that ``s`` must not have leading or trailing whitespace.
+   The conversion is independent of the current locale.
+
+   If ``endptr`` is ``NULL``, convert the whole string.  Raise
+   ValueError and return ``-1.0`` if the string is not a valid
+   representation of a floating-point number.
+
+   If endptr is not ``NULL``, convert as much of the string as
+   possible and set ``*endptr`` to point to the first unconverted
+   character.  If no initial segment of the string is the valid
+   representation of a floating-point number, set ``*endptr`` to point
+   to the beginning of the string, raise ValueError, and return
+   ``-1.0``.
+
+   If ``s`` represents a value that is too large to store in a float
+   (for example, ``"1e500"`` is such a string on many platforms) then
+   if ``overflow_exception`` is ``NULL`` return ``Py_HUGE_VAL`` (with
+   an appropriate sign) and don't set any exception.  Otherwise,
+   ``overflow_exception`` must point to a Python exception object;
+   raise that exception and return ``-1.0``.  In both cases, set
+   ``*endptr`` to point to the first character after the converted value.
+
+   If any other error occurs during the conversion (for example an
+   out-of-memory error), set the appropriate Python exception and
+   return ``-1.0``.
+
+   .. versionadded:: 3.1
+
+
+.. c:function:: char* PyOS_double_to_string(double val, char format_code, int precision, int flags, int *ptype)
+
+   Convert a :c:type:`double` *val* to a string using supplied
+   *format_code*, *precision*, and *flags*.
+
+   *format_code* must be one of ``'e'``, ``'E'``, ``'f'``, ``'F'``,
+   ``'g'``, ``'G'`` or ``'r'``.  For ``'r'``, the supplied *precision*
+   must be 0 and is ignored.  The ``'r'`` format code specifies the
+   standard :func:`repr` format.
+
+   *flags* can be zero or more of the values *Py_DTSF_SIGN*,
+   *Py_DTSF_ADD_DOT_0*, or *Py_DTSF_ALT*, or-ed together:
+
+   * *Py_DTSF_SIGN* means to always precede the returned string with a sign
+     character, even if *val* is non-negative.
+
+   * *Py_DTSF_ADD_DOT_0* means to ensure that the returned string will not look
+     like an integer.
+
+   * *Py_DTSF_ALT* means to apply "alternate" formatting rules.  See the
+     documentation for the :c:func:`PyOS_snprintf` ``'#'`` specifier for
+     details.
+
+   If *ptype* is non-NULL, then the value it points to will be set to one of
+   *Py_DTST_FINITE*, *Py_DTST_INFINITE*, or *Py_DTST_NAN*, signifying that
+   *val* is a finite number, an infinite number, or not a number, respectively.
+
+   The return value is a pointer to *buffer* with the converted string or
+   *NULL* if the conversion failed. The caller is responsible for freeing the
+   returned string by calling :c:func:`PyMem_Free`.
+
+   .. versionadded:: 3.1
+
+
+.. 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.
+
+
+.. 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.

third_party/python/Doc/c-api/coro.rst

@@ -0,0 +1,34 @@
+.. highlightlang:: c
+
+.. _coro-objects:
+
+Coroutine Objects
+-----------------
+
+.. versionadded:: 3.5
+
+Coroutine objects are what functions declared with an ``async`` keyword
+return.
+
+
+.. c:type:: PyCoroObject
+
+   The C structure used for coroutine objects.
+
+
+.. c:var:: PyTypeObject PyCoro_Type
+
+   The type object corresponding to coroutine objects.
+
+
+.. c:function:: int PyCoro_CheckExact(PyObject *ob)
+
+   Return true if *ob*'s type is *PyCoro_Type*; *ob* must not be *NULL*.
+
+
+.. c:function:: PyObject* PyCoro_New(PyFrameObject *frame, PyObject *name, PyObject *qualname)
+
+   Create and return a new coroutine object based on the *frame* object,
+   with ``__name__`` and ``__qualname__`` set to *name* and *qualname*.
+   A reference to *frame* is stolen by this function.  The *frame* argument
+   must not be *NULL*.

third_party/python/Doc/c-api/datetime.rst

@@ -0,0 +1,209 @@
+.. highlightlang:: c
+
+.. _datetimeobjects:
+
+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
+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
+macros.
+
+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*.
+
+
+.. c:function:: int PyDate_CheckExact(PyObject *ob)
+
+   Return true if *ob* is of type :c:data:`PyDateTime_DateType`. *ob* must not be
+   *NULL*.
+
+
+.. 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*.
+
+
+.. c:function:: int PyDateTime_CheckExact(PyObject *ob)
+
+   Return true if *ob* is of type :c:data:`PyDateTime_DateTimeType`. *ob* must not
+   be *NULL*.
+
+
+.. 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*.
+
+
+.. c:function:: int PyTime_CheckExact(PyObject *ob)
+
+   Return true if *ob* is of type :c:data:`PyDateTime_TimeType`. *ob* must not be
+   *NULL*.
+
+
+.. 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*.
+
+
+.. c:function:: int PyDelta_CheckExact(PyObject *ob)
+
+   Return true if *ob* is of type :c:data:`PyDateTime_DeltaType`. *ob* must not be
+   *NULL*.
+
+
+.. 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*.
+
+
+.. c:function:: int PyTZInfo_CheckExact(PyObject *ob)
+
+   Return true if *ob* is of type :c:data:`PyDateTime_TZInfoType`. *ob* must not be
+   *NULL*.
+
+
+Macros to create objects:
+
+.. c:function:: PyObject* PyDate_FromDate(int year, int month, int day)
+
+   Return a ``datetime.date`` object with the specified year, month and day.
+
+
+.. c:function:: PyObject* PyDateTime_FromDateAndTime(int year, int month, int day, int hour, int minute, int second, int usecond)
+
+   Return a ``datetime.datetime`` object with the specified year, month, day, hour,
+   minute, second and microsecond.
+
+
+.. c:function:: PyObject* PyTime_FromTime(int hour, int minute, int second, int usecond)
+
+   Return a ``datetime.time`` object with the specified hour, minute, second and
+   microsecond.
+
+
+.. c:function:: PyObject* PyDelta_FromDSU(int days, int seconds, int useconds)
+
+   Return a ``datetime.timedelta`` object representing the given number of days,
+   seconds and microseconds.  Normalization is performed so that the resulting
+   number of microseconds and seconds lie in the ranges documented for
+   ``datetime.timedelta`` 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
+not checked:
+
+.. c:function:: int PyDateTime_GET_YEAR(PyDateTime_Date *o)
+
+   Return the year, as a positive int.
+
+
+.. c:function:: int PyDateTime_GET_MONTH(PyDateTime_Date *o)
+
+   Return the month, as an int from 1 through 12.
+
+
+.. c:function:: int PyDateTime_GET_DAY(PyDateTime_Date *o)
+
+   Return the day, as an int from 1 through 31.
+
+
+Macros to extract fields from datetime objects.  The argument must be an
+instance of :c:data:`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)
+
+   Return the hour, as an int from 0 through 23.
+
+
+.. c:function:: int PyDateTime_DATE_GET_MINUTE(PyDateTime_DateTime *o)
+
+   Return the minute, as an int from 0 through 59.
+
+
+.. c:function:: int PyDateTime_DATE_GET_SECOND(PyDateTime_DateTime *o)
+
+   Return the second, as an int from 0 through 59.
+
+
+.. c:function:: int PyDateTime_DATE_GET_MICROSECOND(PyDateTime_DateTime *o)
+
+   Return the microsecond, as an int from 0 through 999999.
+
+
+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*,
+and the type is not checked:
+
+.. c:function:: int PyDateTime_TIME_GET_HOUR(PyDateTime_Time *o)
+
+   Return the hour, as an int from 0 through 23.
+
+
+.. c:function:: int PyDateTime_TIME_GET_MINUTE(PyDateTime_Time *o)
+
+   Return the minute, as an int from 0 through 59.
+
+
+.. c:function:: int PyDateTime_TIME_GET_SECOND(PyDateTime_Time *o)
+
+   Return the second, as an int from 0 through 59.
+
+
+.. c:function:: int PyDateTime_TIME_GET_MICROSECOND(PyDateTime_Time *o)
+
+   Return the microsecond, as an int from 0 through 999999.
+
+
+Macros to extract fields from time delta objects.  The argument must be an
+instance of :c:data:`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)
+
+   Return the number of days, as an int from -999999999 to 999999999.
+
+   .. versionadded:: 3.3
+
+
+.. c:function:: int PyDateTime_DELTA_GET_SECONDS(PyDateTime_Delta *o)
+
+   Return the number of seconds, as an int from 0 through 86399.
+
+   .. versionadded:: 3.3
+
+
+.. c:function:: int PyDateTime_DELTA_GET_MICROSECONDS(PyDateTime_Delta *o)
+
+   Return the number of microseconds, as an int from 0 through 999999.
+
+   .. versionadded:: 3.3
+
+
+Macros for the convenience of modules implementing the DB API:
+
+.. c:function:: PyObject* PyDateTime_FromTimestamp(PyObject *args)
+
+   Create and return a new ``datetime.datetime`` object given an argument tuple
+   suitable for passing to ``datetime.datetime.fromtimestamp()``.
+
+
+.. c:function:: PyObject* PyDate_FromTimestamp(PyObject *args)
+
+   Create and return a new ``datetime.date`` object given an argument tuple
+   suitable for passing to ``datetime.date.fromtimestamp()``.

third_party/python/Doc/c-api/descriptor.rst

@@ -0,0 +1,40 @@
+.. highlightlang:: c
+
+.. _descriptor-objects:
+
+Descriptor Objects
+------------------
+
+"Descriptors" are objects that describe some attribute of an object. They are
+found in the dictionary of type objects.
+
+.. XXX document these!
+
+.. c:var:: PyTypeObject PyProperty_Type
+
+   The type object for the built-in descriptor types.
+
+
+.. c:function:: PyObject* PyDescr_NewGetSet(PyTypeObject *type, struct PyGetSetDef *getset)
+
+
+.. c:function:: PyObject* PyDescr_NewMember(PyTypeObject *type, struct PyMemberDef *meth)
+
+
+.. c:function:: PyObject* PyDescr_NewMethod(PyTypeObject *type, struct PyMethodDef *meth)
+
+
+.. c:function:: PyObject* PyDescr_NewWrapper(PyTypeObject *type, struct wrapperbase *wrapper, void *wrapped)
+
+
+.. c:function:: PyObject* PyDescr_NewClassMethod(PyTypeObject *type, PyMethodDef *method)
+
+
+.. c:function:: int PyDescr_IsData(PyObject *descr)
+
+   Return true if the descriptor objects *descr* describes a data attribute, or
+   false if it describes a method.  *descr* must be a descriptor object; there is
+   no error checking.
+
+
+.. c:function:: PyObject* PyWrapper_New(PyObject *, PyObject *)

third_party/python/Doc/c-api/dict.rst

@@ -0,0 +1,240 @@
+.. highlightlang:: c
+
+.. _dictobjects:
+
+Dictionary Objects
+------------------
+
+.. index:: object: dictionary
+
+
+.. c:type:: PyDictObject
+
+   This subtype of :c:type:`PyObject` represents a Python dictionary object.
+
+
+.. c:var:: PyTypeObject PyDict_Type
+
+   This instance of :c:type:`PyTypeObject` represents the Python dictionary
+   type.  This is the same object as :class:`dict` in the Python layer.
+
+
+.. c:function:: int PyDict_Check(PyObject *p)
+
+   Return true if *p* is a dict object or an instance of a subtype of the dict
+   type.
+
+
+.. c:function:: int PyDict_CheckExact(PyObject *p)
+
+   Return true if *p* is a dict object, but not an instance of a subtype of
+   the dict type.
+
+
+.. c:function:: PyObject* PyDict_New()
+
+   Return a new empty dictionary, or *NULL* on failure.
+
+
+.. c:function:: PyObject* PyDictProxy_New(PyObject *mapping)
+
+   Return a :class:`types.MappingProxyType` object for a mapping which
+   enforces read-only behavior.  This is normally used to create a view to
+   prevent modification of the dictionary for non-dynamic class types.
+
+
+.. c:function:: void PyDict_Clear(PyObject *p)
+
+   Empty an existing dictionary of all key-value pairs.
+
+
+.. c:function:: int PyDict_Contains(PyObject *p, PyObject *key)
+
+   Determine if dictionary *p* contains *key*.  If an item in *p* is matches
+   *key*, return ``1``, otherwise return ``0``.  On error, return ``-1``.
+   This is equivalent to the Python expression ``key in p``.
+
+
+.. c:function:: PyObject* PyDict_Copy(PyObject *p)
+
+   Return a new dictionary that contains the same key-value pairs as *p*.
+
+
+.. c:function:: int PyDict_SetItem(PyObject *p, PyObject *key, PyObject *val)
+
+   Insert *value* into the dictionary *p* with a key of *key*.  *key* must be
+   :term:`hashable`; if it isn't, :exc:`TypeError` will be raised. Return
+   ``0`` on success or ``-1`` on failure.
+
+
+.. c:function:: int PyDict_SetItemString(PyObject *p, const char *key, PyObject *val)
+
+   .. index:: single: PyUnicode_FromString()
+
+   Insert *value* into the dictionary *p* using *key* as a key. *key* should
+   be a :c:type:`char\*`.  The key object is created using
+   ``PyUnicode_FromString(key)``.  Return ``0`` on success or ``-1`` on
+   failure.
+
+
+.. c:function:: int PyDict_DelItem(PyObject *p, PyObject *key)
+
+   Remove the entry in dictionary *p* with key *key*. *key* must be hashable;
+   if it isn't, :exc:`TypeError` is raised.  Return ``0`` on success or ``-1``
+   on failure.
+
+
+.. c:function:: int PyDict_DelItemString(PyObject *p, const char *key)
+
+   Remove the entry in dictionary *p* which has a key specified by the string
+   *key*.  Return ``0`` on success or ``-1`` on failure.
+
+
+.. c:function:: PyObject* PyDict_GetItem(PyObject *p, PyObject *key)
+
+   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.
+
+
+.. c:function:: PyObject* PyDict_GetItemWithError(PyObject *p, PyObject *key)
+
+   Variant of :c:func:`PyDict_GetItem` that does not suppress
+   exceptions. Return *NULL* **with** an exception set if an exception
+   occurred.  Return *NULL* **without** an exception set if the key
+   wasn't present.
+
+
+.. c:function:: PyObject* PyDict_GetItemString(PyObject *p, const char *key)
+
+   This is the same as :c:func:`PyDict_GetItem`, but *key* is specified as a
+   :c:type:`char\*`, rather than a :c:type:`PyObject\*`.
+
+   Note that exceptions which occur while calling :meth:`__hash__` and
+   :meth:`__eq__` methods and creating a temporary string object
+   will get suppressed.
+   To get error reporting use :c:func:`PyDict_GetItemWithError()` instead.
+
+
+.. c:function:: PyObject* PyDict_SetDefault(PyObject *p, PyObject *key, PyObject *default)
+
+   This is the same as the Python-level :meth:`dict.setdefault`.  If present, it
+   returns the value corresponding to *key* from the dictionary *p*.  If the key
+   is not in the dict, it is inserted with value *defaultobj* and *defaultobj*
+   is returned.  This function evaluates the hash function of *key* only once,
+   instead of evaluating it independently for the lookup and the insertion.
+
+   .. versionadded:: 3.4
+
+.. c:function:: PyObject* PyDict_Items(PyObject *p)
+
+   Return a :c:type:`PyListObject` containing all the items from the dictionary.
+
+
+.. c:function:: PyObject* PyDict_Keys(PyObject *p)
+
+   Return a :c:type:`PyListObject` containing all the keys from the dictionary.
+
+
+.. c:function:: PyObject* PyDict_Values(PyObject *p)
+
+   Return a :c:type:`PyListObject` containing all the values from the dictionary
+   *p*.
+
+
+.. c:function:: Py_ssize_t PyDict_Size(PyObject *p)
+
+   .. index:: builtin: len
+
+   Return the number of items in the dictionary.  This is equivalent to
+   ``len(p)`` on a dictionary.
+
+
+.. c:function:: int PyDict_Next(PyObject *p, Py_ssize_t *ppos, PyObject **pkey, PyObject **pvalue)
+
+   Iterate over all key-value pairs in the dictionary *p*.  The
+   :c:type:`Py_ssize_t` referred to by *ppos* must be initialized to ``0``
+   prior to the first call to this function to start the iteration; the
+   function returns true for each pair in the dictionary, and false once all
+   pairs have been reported.  The parameters *pkey* and *pvalue* should either
+   point to :c:type:`PyObject\*` variables that will be filled in with each key
+   and value, respectively, or may be *NULL*.  Any references returned through
+   them are borrowed.  *ppos* should not be altered during iteration. Its
+   value represents offsets within the internal dictionary structure, and
+   since the structure is sparse, the offsets are not consecutive.
+
+   For example::
+
+      PyObject *key, *value;
+      Py_ssize_t pos = 0;
+
+      while (PyDict_Next(self->dict, &pos, &key, &value)) {
+          /* do something interesting with the values... */
+          ...
+      }
+
+   The dictionary *p* should not be mutated during iteration.  It is safe to
+   modify the values of the keys as you iterate over the dictionary, but only
+   so long as the set of keys does not change.  For example::
+
+      PyObject *key, *value;
+      Py_ssize_t pos = 0;
+
+      while (PyDict_Next(self->dict, &pos, &key, &value)) {
+          long i = PyLong_AsLong(value);
+          if (i == -1 && PyErr_Occurred()) {
+              return -1;
+          }
+          PyObject *o = PyLong_FromLong(i + 1);
+          if (o == NULL)
+              return -1;
+          if (PyDict_SetItem(self->dict, key, o) < 0) {
+              Py_DECREF(o);
+              return -1;
+          }
+          Py_DECREF(o);
+      }
+
+
+.. c:function:: int PyDict_Merge(PyObject *a, PyObject *b, int override)
+
+   Iterate over mapping object *b* adding key-value pairs to dictionary *a*.
+   *b* may be a dictionary, or any object supporting :c:func:`PyMapping_Keys`
+   and :c:func:`PyObject_GetItem`. If *override* is true, existing pairs in *a*
+   will be replaced if a matching key is found in *b*, otherwise pairs will
+   only be added if there is not a matching key in *a*. Return ``0`` on
+   success or ``-1`` if an exception was raised.
+
+
+.. c:function:: int PyDict_Update(PyObject *a, PyObject *b)
+
+   This is the same as ``PyDict_Merge(a, b, 1)`` in C, and is similar to
+   ``a.update(b)`` in Python except that :c:func:`PyDict_Update` doesn't fall
+   back to the iterating over a sequence of key value pairs if the second
+   argument has no "keys" attribute.  Return ``0`` on success or ``-1`` if an
+   exception was raised.
+
+
+.. c:function:: int PyDict_MergeFromSeq2(PyObject *a, PyObject *seq2, int override)
+
+   Update or merge into dictionary *a*, from the key-value pairs in *seq2*.
+   *seq2* must be an iterable object producing iterable objects of length 2,
+   viewed as key-value pairs.  In case of duplicate keys, the last wins if
+   *override* is true, else the first wins. Return ``0`` on success or ``-1``
+   if an exception was raised. Equivalent Python (except for the return
+   value)::
+
+      def PyDict_MergeFromSeq2(a, seq2, override):
+          for key, value in seq2:
+              if override or key not in a:
+                  a[key] = value
+
+
+.. c:function:: int PyDict_ClearFreeList()
+
+   Clear the free list. Return the total number of freed items.
+
+   .. versionadded:: 3.3

third_party/python/Doc/c-api/file.rst

@@ -0,0 +1,76 @@
+.. highlightlang:: c
+
+.. _fileobjects:
+
+File Objects
+------------
+
+.. index:: object: file
+
+These APIs are a minimal emulation of the Python 2 C API for built-in file
+objects, which used to rely on the buffered I/O (:c:type:`FILE\*`) support
+from the C standard library.  In Python 3, files and streams use the new
+:mod:`io` module, which defines several layers over the low-level unbuffered
+I/O of the operating system.  The functions described below are
+convenience C wrappers over these new APIs, and meant mostly for internal
+error reporting in the interpreter; third-party code is advised to access
+the :mod:`io` APIs instead.
+
+
+.. c:function:: PyFile_FromFd(int fd, const char *name, const char *mode, int buffering, const char *encoding, const char *errors, const char *newline, int closefd)
+
+   Create a Python file object from the file descriptor of an already
+   opened file *fd*.  The arguments *name*, *encoding*, *errors* and *newline*
+   can be *NULL* to use the defaults; *buffering* can be *-1* to use the
+   default. *name* is ignored and kept for backward compatibility. Return
+   *NULL* on failure. For a more comprehensive description of the arguments,
+   please refer to the :func:`io.open` function documentation.
+
+   .. warning::
+
+     Since Python streams have their own buffering layer, mixing them with
+     OS-level file descriptors can produce various issues (such as unexpected
+     ordering of data).
+
+   .. versionchanged:: 3.2
+      Ignore *name* attribute.
+
+
+.. c:function:: int PyObject_AsFileDescriptor(PyObject *p)
+
+   Return the file descriptor associated with *p* as an :c:type:`int`.  If the
+   object is an integer, its value is returned.  If not, the
+   object's :meth:`~io.IOBase.fileno` method is called if it exists; the
+   method must return an integer, which is returned as the file descriptor
+   value.  Sets an exception and returns ``-1`` on failure.
+
+
+.. c:function:: PyObject* PyFile_GetLine(PyObject *p, int n)
+
+   .. index:: single: EOFError (built-in exception)
+
+   Equivalent to ``p.readline([n])``, this function reads one line from the
+   object *p*.  *p* may be a file object or any object with a
+   :meth:`~io.IOBase.readline`
+   method.  If *n* is ``0``, exactly one line is read, regardless of the length of
+   the line.  If *n* is greater than ``0``, no more than *n* bytes will be read
+   from the file; a partial line can be returned.  In both cases, an empty string
+   is returned if the end of the file is reached immediately.  If *n* is less than
+   ``0``, however, one line is read regardless of length, but :exc:`EOFError` is
+   raised if the end of the file is reached immediately.
+
+
+.. c:function:: int PyFile_WriteObject(PyObject *obj, PyObject *p, int flags)
+
+   .. 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
+   instead of the :func:`repr`.  Return ``0`` on success or ``-1`` on failure; the
+   appropriate exception will be set.
+
+
+.. c:function:: int PyFile_WriteString(const char *s, PyObject *p)
+
+   Write string *s* to file object *p*.  Return ``0`` on success or ``-1`` on
+   failure; the appropriate exception will be set.

third_party/python/Doc/c-api/float.rst

@@ -0,0 +1,79 @@
+.. highlightlang:: c
+
+.. _floatobjects:
+
+Floating Point Objects
+----------------------
+
+.. index:: object: floating point
+
+
+.. c:type:: PyFloatObject
+
+   This subtype of :c:type:`PyObject` represents a Python floating point object.
+
+
+.. c:var:: PyTypeObject PyFloat_Type
+
+   This instance of :c:type:`PyTypeObject` represents the Python floating point
+   type.  This is the same object as :class:`float` in the Python layer.
+
+
+.. c:function:: int PyFloat_Check(PyObject *p)
+
+   Return true if its argument is a :c:type:`PyFloatObject` or a subtype of
+   :c:type:`PyFloatObject`.
+
+
+.. c:function:: int PyFloat_CheckExact(PyObject *p)
+
+   Return true if its argument is a :c:type:`PyFloatObject`, but not a subtype of
+   :c:type:`PyFloatObject`.
+
+
+.. c:function:: PyObject* PyFloat_FromString(PyObject *str)
+
+   Create a :c:type:`PyFloatObject` object based on the string value in *str*, or
+   *NULL* on failure.
+
+
+.. c:function:: PyObject* PyFloat_FromDouble(double v)
+
+   Create a :c:type:`PyFloatObject` object from *v*, or *NULL* on failure.
+
+
+.. c:function:: double PyFloat_AsDouble(PyObject *pyfloat)
+
+   Return a C :c:type:`double` representation of the contents of *pyfloat*.  If
+   *pyfloat* is not a Python floating point object but has a :meth:`__float__`
+   method, this method will first be called to convert *pyfloat* into a float.
+   This method returns ``-1.0`` upon failure, so one should call
+   :c:func:`PyErr_Occurred` to check for errors.
+
+
+.. c:function:: double PyFloat_AS_DOUBLE(PyObject *pyfloat)
+
+   Return a C :c:type:`double` representation of the contents of *pyfloat*, but
+   without error checking.
+
+
+.. c:function:: PyObject* PyFloat_GetInfo(void)
+
+   Return a structseq instance which contains information about the
+   precision, minimum and maximum values of a float. It's a thin wrapper
+   around the header file :file:`float.h`.
+
+
+.. c:function:: double PyFloat_GetMax()
+
+   Return the maximum representable finite float *DBL_MAX* as C :c:type:`double`.
+
+
+.. c:function:: double PyFloat_GetMin()
+
+   Return the minimum normalized positive float *DBL_MIN* as C :c:type:`double`.
+
+.. c:function:: int PyFloat_ClearFreeList()
+
+   Clear the float free list. Return the number of items that could not
+   be freed.

third_party/python/Doc/c-api/function.rst

@@ -0,0 +1,108 @@
+.. highlightlang:: c
+
+.. _function-objects:
+
+Function Objects
+----------------
+
+.. index:: object: function
+
+There are a few functions specific to Python functions.
+
+
+.. c:type:: PyFunctionObject
+
+   The C structure used for functions.
+
+
+.. c:var:: PyTypeObject PyFunction_Type
+
+   .. index:: single: MethodType (in module types)
+
+   This is an instance of :c:type:`PyTypeObject` and represents the Python function
+   type.  It is exposed to Python programmers as ``types.FunctionType``.
+
+
+.. c:function:: int PyFunction_Check(PyObject *o)
+
+   Return true if *o* is a function object (has type :c:data:`PyFunction_Type`).
+   The parameter must not be *NULL*.
+
+
+.. c:function:: PyObject* PyFunction_New(PyObject *code, PyObject *globals)
+
+   Return a new function object associated with the code object *code*. *globals*
+   must be a dictionary with the global variables accessible to the function.
+
+   The function's docstring and name are retrieved from the code object. *__module__*
+   is retrieved from *globals*. The argument defaults, annotations and closure are
+   set to *NULL*. *__qualname__* is set to the same value as the function's name.
+
+
+.. c:function:: PyObject* PyFunction_NewWithQualName(PyObject *code, PyObject *globals, PyObject *qualname)
+
+   As :c:func:`PyFunction_New`, but also allows setting the function object's
+   ``__qualname__`` attribute.  *qualname* should be a unicode object or NULL;
+   if NULL, the ``__qualname__`` attribute is set to the same value as its
+   ``__name__`` attribute.
+
+   .. versionadded:: 3.3
+
+
+.. c:function:: PyObject* PyFunction_GetCode(PyObject *op)
+
+   Return the code object associated with the function object *op*.
+
+
+.. c:function:: PyObject* PyFunction_GetGlobals(PyObject *op)
+
+   Return the globals dictionary associated with the function object *op*.
+
+
+.. c:function:: PyObject* PyFunction_GetModule(PyObject *op)
+
+   Return the *__module__* attribute of the function object *op*. This is normally
+   a string containing the module name, but can be set to any other object by
+   Python code.
+
+
+.. c:function:: PyObject* PyFunction_GetDefaults(PyObject *op)
+
+   Return the argument default values of the function object *op*. This can be a
+   tuple of arguments or *NULL*.
+
+
+.. c:function:: int PyFunction_SetDefaults(PyObject *op, PyObject *defaults)
+
+   Set the argument default values for the function object *op*. *defaults* must be
+   *Py_None* or a tuple.
+
+   Raises :exc:`SystemError` and returns ``-1`` on failure.
+
+
+.. c:function:: PyObject* PyFunction_GetClosure(PyObject *op)
+
+   Return the closure associated with the function object *op*. This can be *NULL*
+   or a tuple of cell objects.
+
+
+.. c:function:: int PyFunction_SetClosure(PyObject *op, PyObject *closure)
+
+   Set the closure associated with the function object *op*. *closure* must be
+   *Py_None* or a tuple of cell objects.
+
+   Raises :exc:`SystemError` and returns ``-1`` on failure.
+
+
+.. c:function:: PyObject *PyFunction_GetAnnotations(PyObject *op)
+
+   Return the annotations of the function object *op*. This can be a
+   mutable dictionary or *NULL*.
+
+
+.. c:function:: int PyFunction_SetAnnotations(PyObject *op, PyObject *annotations)
+
+   Set the annotations for the function object *op*. *annotations*
+   must be a dictionary or *Py_None*.
+
+   Raises :exc:`SystemError` and returns ``-1`` on failure.

third_party/python/Doc/c-api/gcsupport.rst

@@ -0,0 +1,159 @@
+.. highlightlang:: c
+
+.. _supporting-cycle-detection:
+
+Supporting Cyclic Garbage Collection
+====================================
+
+Python's support for detecting and collecting garbage which involves circular
+references requires support from object types which are "containers" for other
+objects which may also be containers.  Types which do not store references to
+other objects, or which only store references to atomic types (such as numbers
+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
+: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:
+
+   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`.
+
+#. Once all the fields which may contain references to other containers are
+   initialized, it must call :c:func:`PyObject_GC_Track`.
+
+
+.. c:function:: TYPE* PyObject_GC_New(TYPE, PyTypeObject *type)
+
+   Analogous to :c:func:`PyObject_New` but for container objects with the
+   :const:`Py_TPFLAGS_HAVE_GC` flag set.
+
+
+.. c:function:: TYPE* PyObject_GC_NewVar(TYPE, PyTypeObject *type, Py_ssize_t size)
+
+   Analogous to :c:func:`PyObject_NewVar` but for container objects with the
+   :const:`Py_TPFLAGS_HAVE_GC` flag set.
+
+
+.. c:function:: TYPE* PyObject_GC_Resize(TYPE, PyVarObject *op, Py_ssize_t newsize)
+
+   Resize an object allocated by :c:func:`PyObject_NewVar`.  Returns the
+   resized object or *NULL* on failure.  *op* must not be tracked by the collector yet.
+
+
+.. c:function:: void PyObject_GC_Track(PyObject *op)
+
+   Adds the object *op* to the set of container objects tracked by the
+   collector.  The collector can run at unexpected times so objects must be
+   valid while being tracked.  This should be called once all the fields
+   followed by the :c:member:`~PyTypeObject.tp_traverse` handler become valid, usually near the
+   end of the constructor.
+
+
+.. c:function:: void _PyObject_GC_TRACK(PyObject *op)
+
+   A macro version of :c:func:`PyObject_GC_Track`.  It should not be used for
+   extension modules.
+
+   .. deprecated:: 3.6
+      This macro is removed from Python 3.8.
+
+Similarly, the deallocator for the object must conform to a similar pair of
+rules:
+
+#. Before fields which refer to other containers are invalidated,
+   :c:func:`PyObject_GC_UnTrack` must be called.
+
+#. The object's memory must be deallocated using :c:func:`PyObject_GC_Del`.
+
+
+.. c:function:: void PyObject_GC_Del(void *op)
+
+   Releases memory allocated to an object using :c:func:`PyObject_GC_New` or
+   :c:func:`PyObject_GC_NewVar`.
+
+
+.. c:function:: void PyObject_GC_UnTrack(void *op)
+
+   Remove the object *op* from the set of container objects tracked by the
+   collector.  Note that :c:func:`PyObject_GC_Track` can be called again on
+   this object to add it back to the set of tracked objects.  The deallocator
+   (:c:member:`~PyTypeObject.tp_dealloc` handler) should call this for the object before any of
+   the fields used by the :c:member:`~PyTypeObject.tp_traverse` handler become invalid.
+
+
+.. c:function:: void _PyObject_GC_UNTRACK(PyObject *op)
+
+   A macro version of :c:func:`PyObject_GC_UnTrack`.  It should not be used for
+   extension modules.
+
+   .. deprecated:: 3.6
+      This macro is removed from Python 3.8.
+
+The :c:member:`~PyTypeObject.tp_traverse` handler accepts a function parameter of this type:
+
+
+.. c:type:: int (*visitproc)(PyObject *object, void *arg)
+
+   Type of the visitor function passed to the :c:member:`~PyTypeObject.tp_traverse` handler.
+   The function should be called with an object to traverse as *object* and
+   the third parameter to the :c:member:`~PyTypeObject.tp_traverse` handler as *arg*.  The
+   Python core uses several visitor functions to implement cyclic garbage
+   detection; it's not expected that users will need to write their own
+   visitor functions.
+
+The :c:member:`~PyTypeObject.tp_traverse` handler must have the following type:
+
+
+.. c:type:: int (*traverseproc)(PyObject *self, visitproc visit, void *arg)
+
+   Traversal function for a container object.  Implementations must call the
+   *visit* function for each object directly contained by *self*, with the
+   parameters to *visit* being the contained object and the *arg* value passed
+   to the handler.  The *visit* function must not be called with a *NULL*
+   object argument.  If *visit* returns a non-zero value that value should be
+   returned immediately.
+
+To simplify writing :c:member:`~PyTypeObject.tp_traverse` handlers, a :c:func:`Py_VISIT` macro is
+provided.  In order to use this macro, the :c:member:`~PyTypeObject.tp_traverse` implementation
+must name its arguments exactly *visit* and *arg*:
+
+
+.. c:function:: void Py_VISIT(PyObject *o)
+
+   If *o* is not *NULL*, call the *visit* callback, with arguments *o*
+   and *arg*.  If *visit* returns a non-zero value, then return it.
+   Using this macro, :c:member:`~PyTypeObject.tp_traverse` handlers
+   look like::
+
+      static int
+      my_traverse(Noddy *self, visitproc visit, void *arg)
+      {
+          Py_VISIT(self->foo);
+          Py_VISIT(self->bar);
+          return 0;
+      }
+
+The :c:member:`~PyTypeObject.tp_clear` handler must be of the :c:type:`inquiry` type, or *NULL*
+if the object is immutable.
+
+
+.. c:type:: int (*inquiry)(PyObject *self)
+
+   Drop references that may have created reference cycles.  Immutable objects
+   do not have to define this method since they can never directly create
+   reference cycles.  Note that the object must still be valid after calling
+   this method (don't just call :c:func:`Py_DECREF` on a reference).  The
+   collector will call this method if it detects that this object is involved
+   in a reference cycle.

third_party/python/Doc/c-api/gen.rst

@@ -0,0 +1,44 @@
+.. highlightlang:: c
+
+.. _gen-objects:
+
+Generator Objects
+-----------------
+
+Generator objects are what Python uses to implement generator iterators. They
+are normally created by iterating over a function that yields values, rather
+than explicitly calling :c:func:`PyGen_New` or :c:func:`PyGen_NewWithQualName`.
+
+
+.. c:type:: PyGenObject
+
+   The C structure used for generator objects.
+
+
+.. c:var:: PyTypeObject PyGen_Type
+
+   The type object corresponding to generator objects.
+
+
+.. c:function:: int PyGen_Check(PyObject *ob)
+
+   Return true if *ob* is a generator object; *ob* must not be *NULL*.
+
+
+.. c:function:: int PyGen_CheckExact(PyObject *ob)
+
+   Return true if *ob*'s type is *PyGen_Type*; *ob* must not be *NULL*.
+
+
+.. c:function:: PyObject* PyGen_New(PyFrameObject *frame)
+
+   Create and return a new generator object based on the *frame* object.
+   A reference to *frame* is stolen by this function. The argument must not be
+   *NULL*.
+
+.. c:function:: PyObject* PyGen_NewWithQualName(PyFrameObject *frame, PyObject *name, PyObject *qualname)
+
+   Create and return a new generator object based on the *frame* object,
+   with ``__name__`` and ``__qualname__`` set to *name* and *qualname*.
+   A reference to *frame* is stolen by this function.  The *frame* argument
+   must not be *NULL*.

third_party/python/Doc/c-api/import.rst

@@ -0,0 +1,315 @@
+.. highlightlang:: c
+
+.. _importing:
+
+Importing Modules
+=================
+
+
+.. c:function:: PyObject* PyImport_ImportModule(const char *name)
+
+   .. index::
+      single: package variable; __all__
+      single: __all__ (package variable)
+      single: modules (in module sys)
+
+   This is a simplified interface to :c:func:`PyImport_ImportModuleEx` below,
+   leaving the *globals* and *locals* arguments set to *NULL* and *level* set
+   to 0.  When the *name*
+   argument contains a dot (when it specifies a submodule of a package), the
+   *fromlist* argument is set to the list ``['*']`` so that the return value is the
+   named module rather than the top-level package containing it as would otherwise
+   be the case.  (Unfortunately, this has an additional side effect when *name* in
+   fact specifies a subpackage instead of a submodule: the submodules specified in
+   the package's ``__all__`` variable are  loaded.)  Return a new reference to the
+   imported module, or *NULL* with an exception set on failure.  A failing
+   import of a module doesn't leave the module in :data:`sys.modules`.
+
+   This function always uses absolute imports.
+
+
+.. c:function:: PyObject* PyImport_ImportModuleNoBlock(const char *name)
+
+   This function is a deprecated alias of :c:func:`PyImport_ImportModule`.
+
+   .. versionchanged:: 3.3
+      This function used to fail immediately when the import lock was held
+      by another thread.  In Python 3.3 though, the locking scheme switched
+      to per-module locks for most purposes, so this function's special
+      behaviour isn't needed anymore.
+
+
+.. c:function:: PyObject* PyImport_ImportModuleEx(const char *name, PyObject *globals, PyObject *locals, PyObject *fromlist)
+
+   .. index:: builtin: __import__
+
+   Import a module.  This is best described by referring to the built-in Python
+   function :func:`__import__`.
+
+   The return value is a new reference to the imported module or top-level
+   package, or *NULL* with an exception set on failure.  Like for
+   :func:`__import__`, the return value when a submodule of a package was
+   requested is normally the top-level package, unless a non-empty *fromlist*
+   was given.
+
+   Failing imports remove incomplete module objects, like with
+   :c:func:`PyImport_ImportModule`.
+
+
+.. c:function:: PyObject* PyImport_ImportModuleLevelObject(PyObject *name, PyObject *globals, PyObject *locals, PyObject *fromlist, int level)
+
+   Import a module.  This is best described by referring to the built-in Python
+   function :func:`__import__`, as the standard :func:`__import__` function calls
+   this function directly.
+
+   The return value is a new reference to the imported module or top-level package,
+   or *NULL* with an exception set on failure.  Like for :func:`__import__`,
+   the return value when a submodule of a package was requested is normally the
+   top-level package, unless a non-empty *fromlist* was given.
+
+   .. versionadded:: 3.3
+
+
+.. c:function:: PyObject* PyImport_ImportModuleLevel(const char *name, PyObject *globals, PyObject *locals, PyObject *fromlist, int level)
+
+   Similar to :c:func:`PyImport_ImportModuleLevelObject`, but the name is a
+   UTF-8 encoded string instead of a Unicode object.
+
+   .. versionchanged:: 3.3
+         Negative values for *level* are no longer accepted.
+
+.. c:function:: PyObject* PyImport_Import(PyObject *name)
+
+   This is a higher-level interface that calls the current "import hook
+   function" (with an explicit *level* of 0, meaning absolute import).  It
+   invokes the :func:`__import__` function from the ``__builtins__`` of the
+   current globals.  This means that the import is done using whatever import
+   hooks are installed in the current environment.
+
+   This function always uses absolute imports.
+
+
+.. c:function:: PyObject* PyImport_ReloadModule(PyObject *m)
+
+   Reload a module.  Return a new reference to the reloaded module, or *NULL* with
+   an exception set on failure (the module still exists in this case).
+
+
+.. c:function:: PyObject* PyImport_AddModuleObject(PyObject *name)
+
+   Return the module object corresponding to a module name.  The *name* argument
+   may be of the form ``package.module``. First check the modules dictionary if
+   there's one there, and if not, create a new one and insert it in the modules
+   dictionary. Return *NULL* with an exception set on failure.
+
+   .. note::
+
+      This function does not load or import the module; if the module wasn't already
+      loaded, you will get an empty module object. Use :c:func:`PyImport_ImportModule`
+      or one of its variants to import a module.  Package structures implied by a
+      dotted name for *name* are not created if not already present.
+
+   .. versionadded:: 3.3
+
+
+.. c:function:: PyObject* PyImport_AddModule(const char *name)
+
+   Similar to :c:func:`PyImport_AddModuleObject`, but the name is a UTF-8
+   encoded string instead of a Unicode object.
+
+
+.. c:function:: PyObject* PyImport_ExecCodeModule(const char *name, PyObject *co)
+
+   .. index:: builtin: compile
+
+   Given a module name (possibly of the form ``package.module``) and a code object
+   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
+   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.
+
+   The module's :attr:`__file__` attribute will be set to the code object's
+   :c:member:`co_filename`.  If applicable, :attr:`__cached__` will also
+   be set.
+
+   This function will reload the module if it was already imported.  See
+   :c:func:`PyImport_ReloadModule` for the intended way to reload a module.
+
+   If *name* points to a dotted name of the form ``package.module``, any package
+   structures not already created will still not be created.
+
+   See also :c:func:`PyImport_ExecCodeModuleEx` and
+   :c:func:`PyImport_ExecCodeModuleWithPathnames`.
+
+
+.. c:function:: PyObject* PyImport_ExecCodeModuleEx(const char *name, PyObject *co, const char *pathname)
+
+   Like :c:func:`PyImport_ExecCodeModule`, but the :attr:`__file__` attribute of
+   the module object is set to *pathname* if it is non-``NULL``.
+
+   See also :c:func:`PyImport_ExecCodeModuleWithPathnames`.
+
+
+.. c:function:: PyObject* PyImport_ExecCodeModuleObject(PyObject *name, PyObject *co, PyObject *pathname, PyObject *cpathname)
+
+   Like :c:func:`PyImport_ExecCodeModuleEx`, but the :attr:`__cached__`
+   attribute of the module object is set to *cpathname* if it is
+   non-``NULL``.  Of the three functions, this is the preferred one to use.
+
+   .. versionadded:: 3.3
+
+
+.. c:function:: PyObject* PyImport_ExecCodeModuleWithPathnames(const char *name, PyObject *co, const char *pathname, const char *cpathname)
+
+   Like :c:func:`PyImport_ExecCodeModuleObject`, but *name*, *pathname* and
+   *cpathname* are UTF-8 encoded strings. Attempts are also made to figure out
+   what the value for *pathname* should be from *cpathname* if the former is
+   set to ``NULL``.
+
+   .. versionadded:: 3.2
+   .. versionchanged:: 3.3
+      Uses :func:`imp.source_from_cache()` in calculating the source path if
+      only the bytecode path is provided.
+
+
+.. c:function:: long PyImport_GetMagicNumber()
+
+   Return the magic number for Python bytecode files (a.k.a. :file:`.pyc` file).
+   The magic number should be present in the first four bytes of the bytecode
+   file, in little-endian byte order. Returns ``-1`` on error.
+
+   .. versionchanged:: 3.3
+      Return value of ``-1`` upon failure.
+
+
+.. c:function:: const char * PyImport_GetMagicTag()
+
+   Return the magic tag string for :pep:`3147` format Python bytecode file
+   names.  Keep in mind that the value at ``sys.implementation.cache_tag`` is
+   authoritative and should be used instead of this function.
+
+   .. versionadded:: 3.2
+
+.. c:function:: PyObject* PyImport_GetModuleDict()
+
+   Return the dictionary used for the module administration (a.k.a.
+   ``sys.modules``).  Note that this is a per-interpreter variable.
+
+
+.. c:function:: PyObject* PyImport_GetImporter(PyObject *path)
+
+   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;
+   this tells our caller that the :term:`path based finder` could not find a
+   finder for this path item. Cache the result in :data:`sys.path_importer_cache`.
+   Return a new reference to the finder object.
+
+
+.. c:function:: void _PyImport_Init()
+
+   Initialize the import mechanism.  For internal use only.
+
+
+.. c:function:: void PyImport_Cleanup()
+
+   Empty the module table.  For internal use only.
+
+
+.. c:function:: void _PyImport_Fini()
+
+   Finalize the import mechanism.  For internal use only.
+
+
+.. c:function:: PyObject* _PyImport_FindExtension(char *, char *)
+
+   For internal use only.
+
+
+.. c:function:: int PyImport_ImportFrozenModuleObject(PyObject *name)
+
+   Load a frozen module named *name*.  Return ``1`` for success, ``0`` if the
+   module is not found, and ``-1`` with an exception set if the initialization
+   failed.  To access the imported module on a successful load, use
+   :c:func:`PyImport_ImportModule`.  (Note the misnomer --- this function would
+   reload the module if it was already imported.)
+
+   .. versionadded:: 3.3
+
+   .. versionchanged:: 3.4
+      The ``__file__`` attribute is no longer set on the module.
+
+
+.. c:function:: int PyImport_ImportFrozenModule(const char *name)
+
+   Similar to :c:func:`PyImport_ImportFrozenModuleObject`, but the name is a
+   UTF-8 encoded string instead of a Unicode object.
+
+
+.. c:type:: struct _frozen
+
+   .. index:: single: freeze utility
+
+   This is the structure type definition for frozen module descriptors, as
+   generated by the :program:`freeze` utility (see :file:`Tools/freeze/` in the
+   Python source distribution).  Its definition, found in :file:`Include/import.h`,
+   is::
+
+      struct _frozen {
+          char *name;
+          unsigned char *code;
+          int size;
+      };
+
+
+.. c:var:: const struct _frozen* PyImport_FrozenModules
+
+   This pointer is initialized to point to an array of :c:type:`struct _frozen`
+   records, terminated by one whose members are all *NULL* or zero.  When a frozen
+   module is imported, it is searched in this table.  Third-party code could play
+   tricks with this to provide a dynamically created collection of frozen modules.
+
+
+.. c:function:: int PyImport_AppendInittab(const char *name, PyObject* (*initfunc)(void))
+
+   Add a single module to the existing table of built-in modules.  This is a
+   convenience wrapper around :c:func:`PyImport_ExtendInittab`, returning ``-1`` if
+   the table could not be extended.  The new module can be imported by the name
+   *name*, and uses the function *initfunc* as the initialization function called
+   on the first attempted import.  This should be called before
+   :c:func:`Py_Initialize`.
+
+
+.. c:type:: 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
+   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::
+
+      struct _inittab {
+          char *name;                 /* ASCII encoded string */
+          PyObject* (*initfunc)(void);
+      };
+
+
+.. 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`
+   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
+   internal table.  This should be called before :c:func:`Py_Initialize`.

third_party/python/Doc/c-api/index.rst

@@ -0,0 +1,26 @@
+.. _c-api-index:
+
+##################################
+  Python/C API Reference Manual
+##################################
+
+This manual documents the API used by C and C++ programmers who want to write
+extension modules or embed Python.  It is a companion to :ref:`extending-index`,
+which describes the general principles of extension writing but does not
+document the API functions in detail.
+
+.. toctree::
+   :maxdepth: 2
+
+   intro.rst
+   stable.rst
+   veryhigh.rst
+   refcounting.rst
+   exceptions.rst
+   utilities.rst
+   abstract.rst
+   concrete.rst
+   init.rst
+   memory.rst
+   objimpl.rst
+   apiabiversion.rst

third_party/python/Doc/c-api/intro.rst

@@ -0,0 +1,645 @@
+.. highlightlang:: c
+
+
+.. _api-intro:
+
+************
+Introduction
+************
+
+The Application Programmer's Interface to Python gives C and C++ programmers
+access to the Python interpreter at a variety of levels.  The API is equally
+usable from C++, but for brevity it is generally referred to as the Python/C
+API.  There are two fundamentally different reasons for using the Python/C API.
+The first reason is to write *extension modules* for specific purposes; these
+are C modules that extend the Python interpreter.  This is probably the most
+common use.  The second reason is to use Python as a component in a larger
+application; this technique is generally referred to as :dfn:`embedding` Python
+in an application.
+
+Writing an extension module is a relatively well-understood process,  where a
+"cookbook" approach works well.  There are several tools  that automate the
+process to some extent.  While people have embedded  Python in other
+applications since its early existence, the process of  embedding Python is less
+straightforward than writing an extension.
+
+Many API functions are useful independent of whether you're embedding  or
+extending Python; moreover, most applications that embed Python  will need to
+provide a custom extension as well, so it's probably a  good idea to become
+familiar with writing an extension before  attempting to embed Python in a real
+application.
+
+
+.. _api-includes:
+
+Include Files
+=============
+
+All function, type and macro definitions needed to use the Python/C API are
+included in your code by the following line::
+
+   #include "Python.h"
+
+This implies inclusion of the following standard headers: ``<stdio.h>``,
+``<string.h>``, ``<errno.h>``, ``<limits.h>``, ``<assert.h>`` and ``<stdlib.h>``
+(if available).
+
+.. note::
+
+   Since Python may define some pre-processor definitions which affect the standard
+   headers on some systems, you *must* include :file:`Python.h` before any standard
+   headers are included.
+
+All user visible names defined by Python.h (except those defined by the included
+standard headers) have one of the prefixes ``Py`` or ``_Py``.  Names beginning
+with ``_Py`` are for internal use by the Python implementation and should not be
+used by extension writers. Structure member names do not have a reserved prefix.
+
+**Important:** user code should never define names that begin with ``Py`` or
+``_Py``.  This confuses the reader, and jeopardizes the portability of the user
+code to future Python versions, which may define additional names beginning with
+one of these prefixes.
+
+The header files are typically installed with Python.  On Unix, these  are
+located in the directories :file:`{prefix}/include/pythonversion/` and
+:file:`{exec_prefix}/include/pythonversion/`, where :envvar:`prefix` and
+:envvar:`exec_prefix` are defined by the corresponding parameters to Python's
+:program:`configure` script and *version* is
+``'%d.%d' % sys.version_info[:2]``.  On Windows, the headers are installed
+in :file:`{prefix}/include`, where :envvar:`prefix` is the installation
+directory specified to the installer.
+
+To include the headers, place both directories (if different) on your compiler's
+search path for includes.  Do *not* place the parent directories on the search
+path and then use ``#include <pythonX.Y/Python.h>``; this will break on
+multi-platform builds since the platform independent headers under
+:envvar:`prefix` include the platform specific headers from
+:envvar:`exec_prefix`.
+
+C++ users should note that though the API is defined entirely using C, the
+header files do properly declare the entry points to be ``extern "C"``, so there
+is no need to do anything special to use the API from C++.
+
+
+.. _api-objects:
+
+Objects, Types and Reference Counts
+===================================
+
+.. index:: object: type
+
+Most Python/C API functions have one or more arguments as well as a return value
+of type :c:type:`PyObject\*`.  This type is a pointer to an opaque data type
+representing an arbitrary Python object.  Since all Python object types are
+treated the same way by the Python language in most situations (e.g.,
+assignments, scope rules, and argument passing), it is only fitting that they
+should be represented by a single C type.  Almost all Python objects live on the
+heap: you never declare an automatic or static variable of type
+:c:type:`PyObject`, only pointer variables of type :c:type:`PyObject\*` can  be
+declared.  The sole exception are the type objects; since these must never be
+deallocated, they are typically static :c:type:`PyTypeObject` objects.
+
+All Python objects (even Python integers) have a :dfn:`type` and a
+:dfn:`reference count`.  An object's type determines what kind of object it is
+(e.g., an integer, a list, or a user-defined function; there are many more as
+explained in :ref:`types`).  For each of the well-known types there is a macro
+to check whether an object is of that type; for instance, ``PyList_Check(a)`` is
+true if (and only if) the object pointed to by *a* is a Python list.
+
+
+.. _api-refcounts:
+
+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.")
+
+.. 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
+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
+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
+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.
+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
+and possible 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
+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.
+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.
+
+
+.. _api-refcountdetails:
+
+Reference Count Details
+^^^^^^^^^^^^^^^^^^^^^^^
+
+The reference count behavior of functions in the Python/C API is best  explained
+in terms of *ownership of references*.  Ownership pertains to references, never
+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`
+when it's no longer needed---or passing on this responsibility (usually to its
+caller). When a function passes ownership of a reference on to its caller, the
+caller is said to receive a *new* reference.  When no ownership is transferred,
+the caller is said to *borrow* the reference. Nothing needs to be done for a
+borrowed reference.
+
+Conversely, when a calling function passes in a reference to an  object, there
+are two possibilities: the function *steals* a  reference to the object, or it
+does not.  *Stealing a reference* means that when you pass a reference to a
+function, that function assumes that it now owns that reference, and you are not
+responsible for it any longer.
+
+.. index::
+   single: PyList_SetItem()
+   single: PyTuple_SetItem()
+
+Few functions steal references; the two notable exceptions are
+:c:func:`PyList_SetItem` and :c:func:`PyTuple_SetItem`, which  steal a reference
+to the item (but not to the tuple or list into which the item is put!).  These
+functions were designed to steal a reference because of a common idiom for
+populating a tuple or list with newly created objects; for example, the code to
+create the tuple ``(1, 2, "three")`` could look like this (forgetting about
+error handling for the moment; a better way to code this is shown below)::
+
+   PyObject *t;
+
+   t = PyTuple_New(3);
+   PyTuple_SetItem(t, 0, PyLong_FromLong(1L));
+   PyTuple_SetItem(t, 1, PyLong_FromLong(2L));
+   PyTuple_SetItem(t, 2, PyUnicode_FromString("three"));
+
+Here, :c:func:`PyLong_FromLong` returns a new reference which is immediately
+stolen by :c:func:`PyTuple_SetItem`.  When you want to keep using an object
+although the reference to it will be stolen, use :c:func:`Py_INCREF` to grab
+another reference before calling the reference-stealing function.
+
+Incidentally, :c:func:`PyTuple_SetItem` is the *only* way to set tuple items;
+:c:func:`PySequence_SetItem` and :c:func:`PyObject_SetItem` refuse to do this
+since tuples are an immutable data type.  You should only use
+:c:func:`PyTuple_SetItem` for tuples that you are creating yourself.
+
+Equivalent code for populating a list can be written using :c:func:`PyList_New`
+and :c:func:`PyList_SetItem`.
+
+However, in practice, you will rarely use these ways of creating and populating
+a tuple or list.  There's a generic function, :c:func:`Py_BuildValue`, that can
+create most common objects from C values, directed by a :dfn:`format string`.
+For example, the above two blocks of code could be replaced by the following
+(which also takes care of the error checking)::
+
+   PyObject *tuple, *list;
+
+   tuple = Py_BuildValue("(iis)", 1, 2, "three");
+   list = Py_BuildValue("[iis]", 1, 2, "three");
+
+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
+sets all items of a list (actually, any mutable sequence) to a given item::
+
+   int
+   set_all(PyObject *target, PyObject *item)
+   {
+       Py_ssize_t i, n;
+
+       n = PyObject_Length(target);
+       if (n < 0)
+           return -1;
+       for (i = 0; i < n; i++) {
+           PyObject *index = PyLong_FromSsize_t(i);
+           if (!index)
+               return -1;
+           if (PyObject_SetItem(target, index, item) < 0) {
+               Py_DECREF(index);
+               return -1;
+           }
+           Py_DECREF(index);
+       }
+       return 0;
+   }
+
+.. index:: single: set_all()
+
+The situation is slightly different for function return values.   While passing
+a reference to most functions does not change your  ownership responsibilities
+for that reference, many functions that  return a reference to an object give
+you ownership of the reference. The reason is simple: in many cases, the
+returned object is created  on the fly, and the reference you get is the only
+reference to the  object.  Therefore, the generic functions that return object
+references, like :c:func:`PyObject_GetItem` and  :c:func:`PySequence_GetItem`,
+always return a new reference (the caller becomes the owner of the reference).
+
+It is important to realize that whether you own a reference returned  by a
+function depends on which function you call only --- *the plumage* (the type of
+the object passed as an argument to the function) *doesn't enter into it!*
+Thus, if you  extract an item from a list using :c:func:`PyList_GetItem`, you
+don't own the reference --- but if you obtain the same item from the same list
+using :c:func:`PySequence_GetItem` (which happens to take exactly the same
+arguments), you do own a reference to the returned object.
+
+.. index::
+   single: PyList_GetItem()
+   single: PySequence_GetItem()
+
+Here is an example of how you could write a function that computes the sum of
+the items in a list of integers; once using  :c:func:`PyList_GetItem`, and once
+using :c:func:`PySequence_GetItem`. ::
+
+   long
+   sum_list(PyObject *list)
+   {
+       Py_ssize_t i, n;
+       long total = 0, value;
+       PyObject *item;
+
+       n = PyList_Size(list);
+       if (n < 0)
+           return -1; /* Not a list */
+       for (i = 0; i < n; i++) {
+           item = PyList_GetItem(list, i); /* Can't fail */
+           if (!PyLong_Check(item)) continue; /* Skip non-integers */
+           value = PyLong_AsLong(item);
+           if (value == -1 && PyErr_Occurred())
+               /* Integer too big to fit in a C long, bail out */
+               return -1;
+           total += value;
+       }
+       return total;
+   }
+
+.. index:: single: sum_list()
+
+::
+
+   long
+   sum_sequence(PyObject *sequence)
+   {
+       Py_ssize_t i, n;
+       long total = 0, value;
+       PyObject *item;
+       n = PySequence_Length(sequence);
+       if (n < 0)
+           return -1; /* Has no length */
+       for (i = 0; i < n; i++) {
+           item = PySequence_GetItem(sequence, i);
+           if (item == NULL)
+               return -1; /* Not a sequence, or other failure */
+           if (PyLong_Check(item)) {
+               value = PyLong_AsLong(item);
+               Py_DECREF(item);
+               if (value == -1 && PyErr_Occurred())
+                   /* Integer too big to fit in a C long, bail out */
+                   return -1;
+               total += value;
+           }
+           else {
+               Py_DECREF(item); /* Discard reference ownership */
+           }
+       }
+       return total;
+   }
+
+.. index:: single: sum_sequence()
+
+
+.. _api-types:
+
+Types
+-----
+
+There are few other data types that play a significant role in  the Python/C
+API; most are simple C types such as :c:type:`int`,  :c:type:`long`,
+:c:type:`double` and :c:type:`char\*`.  A few structure types  are used to
+describe static tables used to list the functions exported  by a module or the
+data attributes of a new object type, and another is used to describe the value
+of a complex number.  These will  be discussed together with the functions that
+use them.
+
+
+.. _api-exceptions:
+
+Exceptions
+==========
+
+The Python programmer only needs to deal with exceptions if specific  error
+handling is required; unhandled exceptions are automatically  propagated to the
+caller, then to the caller's caller, and so on, until they reach the top-level
+interpreter, where they are reported to the  user accompanied by a stack
+traceback.
+
+.. index:: single: PyErr_Occurred()
+
+For C programmers, however, error checking always has to be explicit.  All
+functions in the Python/C API can raise exceptions, unless an explicit claim is
+made otherwise in a function's documentation.  In general, when a function
+encounters an error, it sets an exception, discards any object references that
+it owns, and returns an error indicator.  If not documented otherwise, this
+indicator is either *NULL* or ``-1``, depending on the function's return type.
+A few functions return a Boolean true/false result, with false indicating an
+error.  Very few functions return no explicit error indicator or have an
+ambiguous return value, and require explicit testing for errors with
+:c:func:`PyErr_Occurred`.  These exceptions are always explicitly documented.
+
+.. index::
+   single: PyErr_SetString()
+   single: PyErr_Clear()
+
+Exception state is maintained in per-thread storage (this is  equivalent to
+using global storage in an unthreaded application).  A  thread can be in one of
+two states: an exception has occurred, or not. The function
+:c:func:`PyErr_Occurred` can be used to check for this: it returns a borrowed
+reference to the exception type object when an exception has occurred, and
+*NULL* otherwise.  There are a number of functions to set the exception state:
+:c:func:`PyErr_SetString` is the most common (though not the most general)
+function to set the exception state, and :c:func:`PyErr_Clear` clears the
+exception state.
+
+The full exception state consists of three objects (all of which can  be
+*NULL*): the exception type, the corresponding exception  value, and the
+traceback.  These have the same meanings as the Python result of
+``sys.exc_info()``; however, they are not the same: the Python objects represent
+the last exception being handled by a Python  :keyword:`try` ...
+:keyword:`except` statement, while the C level exception state only exists while
+an exception is being passed on between C functions until it reaches the Python
+bytecode interpreter's  main loop, which takes care of transferring it to
+``sys.exc_info()`` and friends.
+
+.. index:: single: exc_info() (in module sys)
+
+Note that starting with Python 1.5, the preferred, thread-safe way to access the
+exception state from Python code is to call the function :func:`sys.exc_info`,
+which returns the per-thread exception state for Python code.  Also, the
+semantics of both ways to access the exception state have changed so that a
+function which catches an exception will save and restore its thread's exception
+state so as to preserve the exception state of its caller.  This prevents common
+bugs in exception handling code caused by an innocent-looking function
+overwriting the exception being handled; it also reduces the often unwanted
+lifetime extension for objects that are referenced by the stack frames in the
+traceback.
+
+As a general principle, a function that calls another function to  perform some
+task should check whether the called function raised an  exception, and if so,
+pass the exception state on to its caller.  It  should discard any object
+references that it owns, and return an  error indicator, but it should *not* set
+another exception --- that would overwrite the exception that was just raised,
+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
+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::
+
+   def incr_item(dict, key):
+       try:
+           item = dict[key]
+       except KeyError:
+           item = 0
+       dict[key] = item + 1
+
+.. index:: single: incr_item()
+
+Here is the corresponding C code, in all its glory::
+
+   int
+   incr_item(PyObject *dict, PyObject *key)
+   {
+       /* Objects all initialized to NULL for Py_XDECREF */
+       PyObject *item = NULL, *const_one = NULL, *incremented_item = NULL;
+       int rv = -1; /* Return value initialized to -1 (failure) */
+
+       item = PyObject_GetItem(dict, key);
+       if (item == NULL) {
+           /* Handle KeyError only: */
+           if (!PyErr_ExceptionMatches(PyExc_KeyError))
+               goto error;
+
+           /* Clear the error and use zero: */
+           PyErr_Clear();
+           item = PyLong_FromLong(0L);
+           if (item == NULL)
+               goto error;
+       }
+       const_one = PyLong_FromLong(1L);
+       if (const_one == NULL)
+           goto error;
+
+       incremented_item = PyNumber_Add(item, const_one);
+       if (incremented_item == NULL)
+           goto error;
+
+       if (PyObject_SetItem(dict, key, incremented_item) < 0)
+           goto error;
+       rv = 0; /* Success */
+       /* Continue with cleanup code */
+
+    error:
+       /* Cleanup code, shared by success and failure path */
+
+       /* Use Py_XDECREF() to ignore NULL references */
+       Py_XDECREF(item);
+       Py_XDECREF(const_one);
+       Py_XDECREF(incremented_item);
+
+       return rv; /* -1 for error, 0 for success */
+   }
+
+.. index:: single: incr_item()
+
+.. index::
+   single: PyErr_ExceptionMatches()
+   single: PyErr_Clear()
+   single: Py_XDECREF()
+
+This example represents an endorsed use of the ``goto`` statement  in C!
+It illustrates the use of :c:func:`PyErr_ExceptionMatches` and
+:c:func:`PyErr_Clear` to handle specific exceptions, and the use of
+:c:func:`Py_XDECREF` to dispose of owned references that may be *NULL* (note the
+``'X'`` in the name; :c:func:`Py_DECREF` would crash when confronted with a
+*NULL* reference).  It is important that the variables used to hold owned
+references are initialized to *NULL* for this to work; likewise, the proposed
+return value is initialized to ``-1`` (failure) and only set to success after
+the final call made is successful.
+
+
+.. _api-embedding:
+
+Embedding Python
+================
+
+The one important task that only embedders (as opposed to extension writers) of
+the Python interpreter have to worry about is the initialization, and possibly
+the finalization, of the Python interpreter.  Most functionality of the
+interpreter can only be used after the interpreter has been initialized.
+
+.. index::
+   single: Py_Initialize()
+   module: builtins
+   module: __main__
+   module: sys
+   triple: module; search; path
+   single: path (in module sys)
+
+The basic initialization function is :c:func:`Py_Initialize`. This initializes
+the table of loaded modules, and creates the fundamental modules
+:mod:`builtins`, :mod:`__main__`, and :mod:`sys`.  It also
+initializes the module search path (``sys.path``).
+
+.. index:: single: PySys_SetArgvEx()
+
+:c:func:`Py_Initialize` does not set the "script argument list"  (``sys.argv``).
+If this variable is needed by Python code that will be executed later, it must
+be set explicitly with a call to  ``PySys_SetArgvEx(argc, argv, updatepath)``
+after the call to :c:func:`Py_Initialize`.
+
+On most systems (in particular, on Unix and Windows, although the details are
+slightly different), :c:func:`Py_Initialize` calculates the module search path
+based upon its best guess for the location of the standard Python interpreter
+executable, assuming that the Python library is found in a fixed location
+relative to the Python interpreter executable.  In particular, it looks for a
+directory named :file:`lib/python{X.Y}` relative to the parent directory
+where the executable named :file:`python` is found on the shell command search
+path (the environment variable :envvar:`PATH`).
+
+For instance, if the Python executable is found in
+:file:`/usr/local/bin/python`, it will assume that the libraries are in
+:file:`/usr/local/lib/python{X.Y}`.  (In fact, this particular path is also
+the "fallback" location, used when no executable file named :file:`python` is
+found along :envvar:`PATH`.)  The user can override this behavior by setting the
+environment variable :envvar:`PYTHONHOME`, or insert additional directories in
+front of the standard path by setting :envvar:`PYTHONPATH`.
+
+.. index::
+   single: Py_SetProgramName()
+   single: Py_GetPath()
+   single: Py_GetPrefix()
+   single: Py_GetExecPrefix()
+   single: Py_GetProgramFullPath()
+
+The embedding application can steer the search by calling
+``Py_SetProgramName(file)`` *before* calling  :c:func:`Py_Initialize`.  Note that
+:envvar:`PYTHONHOME` still overrides this and :envvar:`PYTHONPATH` is still
+inserted in front of the standard path.  An application that requires total
+control has to provide its own implementation of :c:func:`Py_GetPath`,
+:c:func:`Py_GetPrefix`, :c:func:`Py_GetExecPrefix`, and
+:c:func:`Py_GetProgramFullPath` (all defined in :file:`Modules/getpath.c`).
+
+.. index:: single: Py_IsInitialized()
+
+Sometimes, it is desirable to "uninitialize" Python.  For instance,  the
+application may want to start over (make another call to
+:c:func:`Py_Initialize`) or the application is simply done with its  use of
+Python and wants to free memory allocated by Python.  This can be accomplished
+by calling :c:func:`Py_FinalizeEx`.  The function :c:func:`Py_IsInitialized` returns
+true if Python is currently in the initialized state.  More information about
+these functions is given in a later chapter. Notice that :c:func:`Py_FinalizeEx`
+does *not* free all memory allocated by the Python interpreter, e.g. memory
+allocated by extension modules currently cannot be released.
+
+
+.. _api-debugging:
+
+Debugging Builds
+================
+
+Python can be built with several macros to enable extra checks of the
+interpreter and extension modules.  These checks tend to add a large amount of
+overhead to the runtime so they are not enabled by default.
+
+A full list of the various types of debugging builds is in the file
+:file:`Misc/SpecialBuilds.txt` in the Python source distribution. Builds are
+available that support tracing of reference counts, debugging the memory
+allocator, or low-level profiling of the main interpreter loop.  Only the most
+frequently-used builds will be described in the remainder of this section.
+
+Compiling the interpreter with the :c:macro:`Py_DEBUG` macro defined produces
+what is generally meant by "a debug build" of Python. :c:macro:`Py_DEBUG` is
+enabled in the Unix build by adding ``--with-pydebug`` to the
+:file:`./configure` command.  It is also implied by the presence of the
+not-Python-specific :c:macro:`_DEBUG` macro.  When :c:macro:`Py_DEBUG` is enabled
+in the Unix build, compiler optimization is disabled.
+
+In addition to the reference count debugging described below, the following
+extra checks are performed:
+
+* Extra checks are added to the object allocator.
+
+* Extra checks are added to the parser and compiler.
+
+* Downcasts from wide types to narrow types are checked for loss of information.
+
+* A number of assertions are added to the dictionary and set implementations.
+  In addition, the set object acquires a :meth:`test_c_api` method.
+
+* Sanity checks of the input arguments are added to frame creation.
+
+* The storage for ints is initialized with a known invalid pattern to catch
+  reference to uninitialized digits.
+
+* Low-level tracing and extra exception checking are added to the runtime
+  virtual machine.
+
+* Extra checks are added to the memory arena implementation.
+
+* Extra debugging is added to the thread module.
+
+There may be additional checks not mentioned here.
+
+Defining :c:macro:`Py_TRACE_REFS` enables reference tracing.  When defined, a
+circular doubly linked list of active objects is maintained by adding two extra
+fields to every :c:type:`PyObject`.  Total allocations are tracked as well.  Upon
+exit, all existing references are printed.  (In interactive mode this happens
+after every statement run by the interpreter.)  Implied by :c:macro:`Py_DEBUG`.
+
+Please refer to :file:`Misc/SpecialBuilds.txt` in the Python source distribution
+for more detailed information.
+

third_party/python/Doc/c-api/iter.rst

@@ -0,0 +1,46 @@
+.. highlightlang:: c
+
+.. _iterator:
+
+Iterator Protocol
+=================
+
+There are two functions specifically for working with iterators.
+
+.. c:function:: int PyIter_Check(PyObject *o)
+
+   Return true if the object *o* supports the iterator protocol.
+
+
+.. c:function:: PyObject* PyIter_Next(PyObject *o)
+
+   Return the next value from the iteration *o*.  The object must be an iterator
+   (it is up to the caller to check this).  If there are no remaining values,
+   returns *NULL* with no exception set.  If an error occurs while retrieving
+   the item, returns *NULL* and passes along the exception.
+
+To write a loop which iterates over an iterator, the C code should look
+something like this::
+
+   PyObject *iterator = PyObject_GetIter(obj);
+   PyObject *item;
+
+   if (iterator == NULL) {
+       /* propagate error */
+   }
+
+   while (item = PyIter_Next(iterator)) {
+       /* do something with item */
+       ...
+       /* release reference when done */
+       Py_DECREF(item);
+   }
+
+   Py_DECREF(iterator);
+
+   if (PyErr_Occurred()) {
+       /* propagate error */
+   }
+   else {
+       /* continue doing useful work */
+   }

third_party/python/Doc/c-api/iterator.rst

@@ -0,0 +1,50 @@
+.. highlightlang:: c
+
+.. _iterator-objects:
+
+Iterator Objects
+----------------
+
+Python provides two general-purpose iterator objects.  The first, a sequence
+iterator, works with an arbitrary sequence supporting the :meth:`__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.
+
+
+.. c:var:: PyTypeObject PySeqIter_Type
+
+   Type object for iterator objects returned by :c:func:`PySeqIter_New` and the
+   one-argument form of the :func:`iter` built-in function for built-in sequence
+   types.
+
+
+.. c:function:: int PySeqIter_Check(op)
+
+   Return true if the type of *op* is :c:data:`PySeqIter_Type`.
+
+
+.. c:function:: PyObject* PySeqIter_New(PyObject *seq)
+
+   Return an iterator that works with a general sequence object, *seq*.  The
+   iteration ends when the sequence raises :exc:`IndexError` for the subscripting
+   operation.
+
+
+.. c:var:: PyTypeObject PyCallIter_Type
+
+   Type object for iterator objects returned by :c:func:`PyCallIter_New` and the
+   two-argument form of the :func:`iter` built-in function.
+
+
+.. c:function:: int PyCallIter_Check(op)
+
+   Return true if the type of *op* is :c:data:`PyCallIter_Type`.
+
+
+.. c:function:: PyObject* PyCallIter_New(PyObject *callable, PyObject *sentinel)
+
+   Return a new iterator.  The first parameter, *callable*, can be any Python
+   callable object that can be called with no parameters; each call to it should
+   return the next item in the iteration.  When *callable* returns a value equal to
+   *sentinel*, the iteration will be terminated.

third_party/python/Doc/c-api/list.rst

@@ -0,0 +1,151 @@
+.. highlightlang:: c
+
+.. _listobjects:
+
+List Objects
+------------
+
+.. index:: object: list
+
+
+.. c:type:: PyListObject
+
+   This subtype of :c:type:`PyObject` represents a Python list object.
+
+
+.. c:var:: PyTypeObject PyList_Type
+
+   This instance of :c:type:`PyTypeObject` represents the Python list type.
+   This is the same object as :class:`list` in the Python layer.
+
+
+.. c:function:: int PyList_Check(PyObject *p)
+
+   Return true if *p* is a list object or an instance of a subtype of the list
+   type.
+
+
+.. c:function:: int PyList_CheckExact(PyObject *p)
+
+   Return true if *p* is a list object, but not an instance of a subtype of
+   the list type.
+
+
+.. c:function:: PyObject* PyList_New(Py_ssize_t len)
+
+   Return a new list of length *len* on success, or *NULL* on failure.
+
+   .. note::
+
+      If *len* is greater than zero, the returned list object's items are
+      set to ``NULL``.  Thus you cannot use abstract API functions such as
+      :c:func:`PySequence_SetItem`  or expose the object to Python code before
+      setting all items to a real object with :c:func:`PyList_SetItem`.
+
+
+.. c:function:: Py_ssize_t PyList_Size(PyObject *list)
+
+   .. index:: builtin: len
+
+   Return the length of the list object in *list*; this is equivalent to
+   ``len(list)`` on a list object.
+
+
+.. c:function:: Py_ssize_t PyList_GET_SIZE(PyObject *list)
+
+   Macro form of :c:func:`PyList_Size` without error checking.
+
+
+.. c:function:: PyObject* PyList_GetItem(PyObject *list, Py_ssize_t index)
+
+   Return the object at position *index* in the list pointed to by *list*.  The
+   position must be positive, indexing from the end of the list is not
+   supported.  If *index* is out of bounds, return *NULL* and set an
+   :exc:`IndexError` exception.
+
+
+.. c:function:: PyObject* PyList_GET_ITEM(PyObject *list, Py_ssize_t i)
+
+   Macro form of :c:func:`PyList_GetItem` without error checking.
+
+
+.. c:function:: int PyList_SetItem(PyObject *list, Py_ssize_t index, PyObject *item)
+
+   Set the item at index *index* in list to *item*.  Return ``0`` on success
+   or ``-1`` on failure.
+
+   .. note::
+
+      This function "steals" a reference to *item* and discards a reference to
+      an item already in the list at the affected position.
+
+
+.. c:function:: void PyList_SET_ITEM(PyObject *list, Py_ssize_t i, PyObject *o)
+
+   Macro form of :c:func:`PyList_SetItem` without error checking. This is
+   normally only used to fill in new lists where there is no previous content.
+
+   .. note::
+
+      This macro "steals" a reference to *item*, and, unlike
+      :c:func:`PyList_SetItem`, does *not* discard a reference to any item that
+      is being replaced; any reference in *list* at position *i* will be
+      leaked.
+
+
+.. c:function:: int PyList_Insert(PyObject *list, Py_ssize_t index, PyObject *item)
+
+   Insert the item *item* into list *list* in front of index *index*.  Return
+   ``0`` if successful; return ``-1`` and set an exception if unsuccessful.
+   Analogous to ``list.insert(index, item)``.
+
+
+.. c:function:: int PyList_Append(PyObject *list, PyObject *item)
+
+   Append the object *item* at the end of list *list*. Return ``0`` if
+   successful; return ``-1`` and set an exception if unsuccessful.  Analogous
+   to ``list.append(item)``.
+
+
+.. c:function:: PyObject* PyList_GetSlice(PyObject *list, Py_ssize_t low, Py_ssize_t high)
+
+   Return a list of the objects in *list* containing the objects *between* *low*
+   and *high*.  Return *NULL* and set an exception if unsuccessful.  Analogous
+   to ``list[low:high]``.  Negative indices, as when slicing from Python, are not
+   supported.
+
+
+.. c:function:: int PyList_SetSlice(PyObject *list, Py_ssize_t low, Py_ssize_t high, PyObject *itemlist)
+
+   Set the slice of *list* between *low* and *high* to the contents of
+   *itemlist*.  Analogous to ``list[low:high] = itemlist``. The *itemlist* may
+   be *NULL*, indicating the assignment of an empty list (slice deletion).
+   Return ``0`` on success, ``-1`` on failure.  Negative indices, as when
+   slicing from Python, are not supported.
+
+
+.. c:function:: int PyList_Sort(PyObject *list)
+
+   Sort the items of *list* in place.  Return ``0`` on success, ``-1`` on
+   failure.  This is equivalent to ``list.sort()``.
+
+
+.. c:function:: int PyList_Reverse(PyObject *list)
+
+   Reverse the items of *list* in place.  Return ``0`` on success, ``-1`` on
+   failure.  This is the equivalent of ``list.reverse()``.
+
+
+.. c:function:: PyObject* PyList_AsTuple(PyObject *list)
+
+   .. index:: builtin: tuple
+
+   Return a new tuple object containing the contents of *list*; equivalent to
+   ``tuple(list)``.
+
+
+.. c:function:: int PyList_ClearFreeList()
+
+   Clear the free list. Return the total number of freed items.
+
+   .. versionadded:: 3.3

third_party/python/Doc/c-api/long.rst

@@ -0,0 +1,295 @@
+.. highlightlang:: c
+
+.. _longobjects:
+
+Integer Objects
+---------------
+
+.. index:: object: long integer
+           object: integer
+
+All integers are implemented as "long" integer objects of arbitrary size.
+
+On error, most ``PyLong_As*`` APIs return ``(return type)-1`` which cannot be
+distinguished from a number.  Use :c:func:`PyErr_Occurred` to disambiguate.
+
+.. c:type:: PyLongObject
+
+   This subtype of :c:type:`PyObject` represents a Python integer object.
+
+
+.. c:var:: PyTypeObject PyLong_Type
+
+   This instance of :c:type:`PyTypeObject` represents the Python integer type.
+   This is the same object as :class:`int` in the Python layer.
+
+
+.. c:function:: int PyLong_Check(PyObject *p)
+
+   Return true if its argument is a :c:type:`PyLongObject` or a subtype of
+   :c:type:`PyLongObject`.
+
+
+.. c:function:: int PyLong_CheckExact(PyObject *p)
+
+   Return true if its argument is a :c:type:`PyLongObject`, but not a subtype of
+   :c:type:`PyLongObject`.
+
+
+.. c:function:: PyObject* PyLong_FromLong(long v)
+
+   Return a new :c:type:`PyLongObject` object from *v*, or *NULL* on failure.
+
+   The current implementation keeps an array of integer objects for all integers
+   between ``-5`` and ``256``, when you create an int in that range you actually
+   just get back a reference to the existing object. So it should be possible to
+   change the value of ``1``.  I suspect the behaviour of Python in this case is
+   undefined. :-)
+
+
+.. c:function:: PyObject* PyLong_FromUnsignedLong(unsigned long v)
+
+   Return a new :c:type:`PyLongObject` object from a C :c:type:`unsigned long`, or
+   *NULL* on failure.
+
+
+.. c:function:: PyObject* PyLong_FromSsize_t(Py_ssize_t v)
+
+   Return a new :c:type:`PyLongObject` object from a C :c:type:`Py_ssize_t`, or
+   *NULL* on failure.
+
+
+.. c:function:: PyObject* PyLong_FromSize_t(size_t v)
+
+   Return a new :c:type:`PyLongObject` object from a C :c:type:`size_t`, or
+   *NULL* on failure.
+
+
+.. c:function:: PyObject* PyLong_FromLongLong(long long v)
+
+   Return a new :c:type:`PyLongObject` object from a C :c:type:`long long`, or *NULL*
+   on failure.
+
+
+.. c:function:: PyObject* PyLong_FromUnsignedLongLong(unsigned long long v)
+
+   Return a new :c:type:`PyLongObject` object from a C :c:type:`unsigned long long`,
+   or *NULL* on failure.
+
+
+.. c:function:: PyObject* PyLong_FromDouble(double v)
+
+   Return a new :c:type:`PyLongObject` object from the integer part of *v*, or
+   *NULL* on failure.
+
+
+.. c:function:: PyObject* PyLong_FromString(const char *str, char **pend, int base)
+
+   Return a new :c:type:`PyLongObject` based on the string value in *str*, which
+   is interpreted according to the radix in *base*.  If *pend* is non-*NULL*,
+   *\*pend* will point to the first character in *str* which follows the
+   representation of the number.  If *base* is ``0``, *str* is interpreted using
+   the :ref:`integers` definition; in this case, leading zeros in a
+   non-zero decimal number raises a :exc:`ValueError`. If *base* is not ``0``,
+   it must be between ``2`` and ``36``, inclusive.  Leading spaces and single
+   underscores after a base specifier and between digits are ignored.  If there
+   are no digits, :exc:`ValueError` will be raised.
+
+
+.. c:function:: PyObject* PyLong_FromUnicode(Py_UNICODE *u, Py_ssize_t length, int base)
+
+   Convert a sequence of Unicode digits to a Python integer value.  The Unicode
+   string is first encoded to a byte string using :c:func:`PyUnicode_EncodeDecimal`
+   and then converted using :c:func:`PyLong_FromString`.
+
+   .. deprecated-removed:: 3.3 4.0
+      Part of the old-style :c:type:`Py_UNICODE` API; please migrate to using
+      :c:func:`PyLong_FromUnicodeObject`.
+
+
+.. c:function:: PyObject* PyLong_FromUnicodeObject(PyObject *u, int base)
+
+   Convert a sequence of Unicode digits in the string *u* to a Python integer
+   value.  The Unicode string is first encoded to a byte string using
+   :c:func:`PyUnicode_EncodeDecimal` and then converted using
+   :c:func:`PyLong_FromString`.
+
+   .. versionadded:: 3.3
+
+
+.. c:function:: PyObject* PyLong_FromVoidPtr(void *p)
+
+   Create a Python integer from the pointer *p*. The pointer value can be
+   retrieved from the resulting value using :c:func:`PyLong_AsVoidPtr`.
+
+
+.. XXX alias PyLong_AS_LONG (for now)
+.. c:function:: long PyLong_AsLong(PyObject *obj)
+
+   .. index::
+      single: LONG_MAX
+      single: OverflowError (built-in exception)
+
+   Return a C :c:type:`long` representation of *obj*.  If *obj* is not an
+   instance of :c:type:`PyLongObject`, first call its :meth:`__int__` method
+   (if present) to convert it to a :c:type:`PyLongObject`.
+
+   Raise :exc:`OverflowError` if the value of *obj* is out of range for a
+   :c:type:`long`.
+
+   Returns ``-1`` on error.  Use :c:func:`PyErr_Occurred` to disambiguate.
+
+
+.. c:function:: long PyLong_AsLongAndOverflow(PyObject *obj, int *overflow)
+
+   Return a C :c:type:`long` representation of *obj*.  If *obj* is not an
+   instance of :c:type:`PyLongObject`, first call its :meth:`__int__` 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
+   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.
+
+
+.. c:function:: long long PyLong_AsLongLong(PyObject *obj)
+
+   .. index::
+      single: OverflowError (built-in exception)
+
+   Return a C :c:type:`long long` representation of *obj*.  If *obj* is not an
+   instance of :c:type:`PyLongObject`, first call its :meth:`__int__` method
+   (if present) to convert it to a :c:type:`PyLongObject`.
+
+   Raise :exc:`OverflowError` if the value of *obj* is out of range for a
+   :c:type:`long`.
+
+   Returns ``-1`` on error.  Use :c:func:`PyErr_Occurred` to disambiguate.
+
+
+.. c:function:: long long PyLong_AsLongLongAndOverflow(PyObject *obj, int *overflow)
+
+   Return a C :c:type:`long long` representation of *obj*.  If *obj* is not an
+   instance of :c:type:`PyLongObject`, first call its :meth:`__int__` method
+   (if present) to convert it to a :c:type:`PyLongObject`.
+
+   If the value of *obj* is greater than :const:`PY_LLONG_MAX` or less than
+   :const:`PY_LLONG_MIN`, set *\*overflow* to ``1`` or ``-1``, respectively,
+   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.
+
+   .. versionadded:: 3.2
+
+
+.. c:function:: Py_ssize_t PyLong_AsSsize_t(PyObject *pylong)
+
+   .. index::
+      single: PY_SSIZE_T_MAX
+      single: OverflowError (built-in exception)
+
+   Return a C :c:type:`Py_ssize_t` representation of *pylong*.  *pylong* must
+   be an instance of :c:type:`PyLongObject`.
+
+   Raise :exc:`OverflowError` if the value of *pylong* is out of range for a
+   :c:type:`Py_ssize_t`.
+
+   Returns ``-1`` on error.  Use :c:func:`PyErr_Occurred` to disambiguate.
+
+
+.. c:function:: unsigned long PyLong_AsUnsignedLong(PyObject *pylong)
+
+   .. index::
+      single: ULONG_MAX
+      single: OverflowError (built-in exception)
+
+   Return a C :c:type:`unsigned long` representation of *pylong*.  *pylong*
+   must be an instance of :c:type:`PyLongObject`.
+
+   Raise :exc:`OverflowError` if the value of *pylong* is out of range for a
+   :c:type:`unsigned long`.
+
+   Returns ``(unsigned long)-1`` on error.
+   Use :c:func:`PyErr_Occurred` to disambiguate.
+
+
+.. c:function:: size_t PyLong_AsSize_t(PyObject *pylong)
+
+   .. index::
+      single: SIZE_MAX
+      single: OverflowError (built-in exception)
+
+   Return a C :c:type:`size_t` representation of *pylong*.  *pylong* must be
+   an instance of :c:type:`PyLongObject`.
+
+   Raise :exc:`OverflowError` if the value of *pylong* is out of range for a
+   :c:type:`size_t`.
+
+   Returns ``(size_t)-1`` on error.
+   Use :c:func:`PyErr_Occurred` to disambiguate.
+
+
+.. c:function:: unsigned long long PyLong_AsUnsignedLongLong(PyObject *pylong)
+
+   .. index::
+      single: OverflowError (built-in exception)
+
+   Return a C :c:type:`unsigned long long` representation of *pylong*.  *pylong*
+   must be an instance of :c:type:`PyLongObject`.
+
+   Raise :exc:`OverflowError` if the value of *pylong* is out of range for an
+   :c:type:`unsigned long long`.
+
+   Returns ``(unsigned long long)-1`` on error.
+   Use :c:func:`PyErr_Occurred` to disambiguate.
+
+   .. versionchanged:: 3.1
+      A negative *pylong* now raises :exc:`OverflowError`, not :exc:`TypeError`.
+
+
+.. c:function:: unsigned long PyLong_AsUnsignedLongMask(PyObject *obj)
+
+   Return a C :c:type:`unsigned long` representation of *obj*.  If *obj*
+   is not an instance of :c:type:`PyLongObject`, first call its :meth:`__int__`
+   method (if present) to convert it to a :c:type:`PyLongObject`.
+
+   If the value of *obj* is out of range for an :c:type:`unsigned long`,
+   return the reduction of that value modulo ``ULONG_MAX + 1``.
+
+   Returns ``-1`` on error.  Use :c:func:`PyErr_Occurred` to disambiguate.
+
+
+.. c:function:: unsigned long long PyLong_AsUnsignedLongLongMask(PyObject *obj)
+
+   Return a C :c:type:`unsigned long long` representation of *obj*.  If *obj*
+   is not an instance of :c:type:`PyLongObject`, first call its :meth:`__int__`
+   method (if present) to convert it to a :c:type:`PyLongObject`.
+
+   If the value of *obj* is out of range for an :c:type:`unsigned long long`,
+   return the reduction of that value modulo ``PY_ULLONG_MAX + 1``.
+
+   Returns ``-1`` on error.  Use :c:func:`PyErr_Occurred` to disambiguate.
+
+
+.. c:function:: double PyLong_AsDouble(PyObject *pylong)
+
+   Return a C :c:type:`double` representation of *pylong*.  *pylong* must be
+   an instance of :c:type:`PyLongObject`.
+
+   Raise :exc:`OverflowError` if the value of *pylong* is out of range for a
+   :c:type:`double`.
+
+   Returns ``-1.0`` on error.  Use :c:func:`PyErr_Occurred` to disambiguate.
+
+
+.. c:function:: void* PyLong_AsVoidPtr(PyObject *pylong)
+
+   Convert a Python integer *pylong* to a C :c:type:`void` pointer.
+   If *pylong* cannot be converted, an :exc:`OverflowError` will be raised.  This
+   is only assured to produce a usable :c:type:`void` pointer for values created
+   with :c:func:`PyLong_FromVoidPtr`.
+
+   Returns *NULL* on error.  Use :c:func:`PyErr_Occurred` to disambiguate.

third_party/python/Doc/c-api/mapping.rst

@@ -0,0 +1,94 @@
+.. highlightlang:: c
+
+.. _mapping:
+
+Mapping Protocol
+================
+
+See also :c:func:`PyObject_GetItem`, :c:func:`PyObject_SetItem` and
+:c:func:`PyObject_DelItem`.
+
+
+.. c:function:: int PyMapping_Check(PyObject *o)
+
+   Return ``1`` if the object provides mapping protocol or supports slicing,
+   and ``0`` otherwise.  Note that it returns ``1`` for Python classes with
+   a :meth:`__getitem__` method since in general case it is impossible to
+   determine what the type of keys it supports.  This function always
+   succeeds.
+
+
+.. c:function:: Py_ssize_t PyMapping_Size(PyObject *o)
+               Py_ssize_t PyMapping_Length(PyObject *o)
+
+   .. index:: builtin: len
+
+   Returns the number of keys in object *o* on success, and ``-1`` on failure.
+   This is equivalent to the Python expression ``len(o)``.
+
+
+.. c:function:: PyObject* PyMapping_GetItemString(PyObject *o, const char *key)
+
+   Return element of *o* corresponding to the string *key* or *NULL* on failure.
+   This is the equivalent of the Python expression ``o[key]``.
+   See also :c:func:`PyObject_GetItem`.
+
+
+.. c:function:: int PyMapping_SetItemString(PyObject *o, const char *key, PyObject *v)
+
+   Map the string *key* to the value *v* in object *o*.  Returns ``-1`` on
+   failure.  This is the equivalent of the Python statement ``o[key] = v``.
+   See also :c:func:`PyObject_SetItem`.
+
+
+.. c:function:: int PyMapping_DelItem(PyObject *o, PyObject *key)
+
+   Remove the mapping for the object *key* from the object *o*.  Return ``-1``
+   on failure.  This is equivalent to the Python statement ``del o[key]``.
+   This is an alias of :c:func:`PyObject_DelItem`.
+
+
+.. c:function:: int PyMapping_DelItemString(PyObject *o, const char *key)
+
+   Remove the mapping for the string *key* from the object *o*.  Return ``-1``
+   on failure.  This is equivalent to the Python statement ``del o[key]``.
+
+
+.. c:function:: int PyMapping_HasKey(PyObject *o, PyObject *key)
+
+   Return ``1`` if the mapping object has the key *key* and ``0`` otherwise.
+   This is equivalent to the Python expression ``key in o``.
+   This function always succeeds.
+
+   Note that exceptions which occur while calling the :meth:`__getitem__`
+   method will get suppressed.
+   To get error reporting use :c:func:`PyObject_GetItem()` instead.
+
+
+.. c:function:: int PyMapping_HasKeyString(PyObject *o, const char *key)
+
+   Return ``1`` if the mapping object has the key *key* and ``0`` otherwise.
+   This is equivalent to the Python expression ``key in o``.
+   This function always succeeds.
+
+   Note that exceptions which occur while calling the :meth:`__getitem__`
+   method and creating a temporary string object will get suppressed.
+   To get error reporting use :c:func:`PyMapping_GetItemString()` instead.
+
+
+.. c:function:: PyObject* PyMapping_Keys(PyObject *o)
+
+   On success, return a list or tuple of the keys in object *o*.  On failure,
+   return *NULL*.
+
+
+.. c:function:: PyObject* PyMapping_Values(PyObject *o)
+
+   On success, return a list or tuple of the values in object *o*.  On failure,
+   return *NULL*.
+
+
+.. c:function:: PyObject* PyMapping_Items(PyObject *o)
+
+   On success, return a list or tuple of the items in object *o*, where each item
+   is a tuple containing a key-value pair.  On failure, return *NULL*.

third_party/python/Doc/c-api/marshal.rst

@@ -0,0 +1,94 @@
+.. highlightlang:: c
+
+.. _marshalling-utils:
+
+Data marshalling support
+========================
+
+These routines allow C code to work with serialized objects using the same
+data format as the :mod:`marshal` module.  There are functions to write data
+into the serialization format, and additional functions that can be used to
+read the data back.  Files used to store marshalled data must be opened in
+binary mode.
+
+Numeric values are stored with the least significant byte first.
+
+The module supports two versions of the data format: version 0 is the
+historical version, version 1 shares interned strings in the file, and upon
+unmarshalling.  Version 2 uses a binary format for floating point numbers.
+*Py_MARSHAL_VERSION* indicates the current file format (currently 2).
+
+
+.. c:function:: void PyMarshal_WriteLongToFile(long value, FILE *file, int version)
+
+   Marshal a :c:type:`long` integer, *value*, to *file*.  This will only write
+   the least-significant 32 bits of *value*; regardless of the size of the
+   native :c:type:`long` type.  *version* indicates the file format.
+
+
+.. c:function:: void PyMarshal_WriteObjectToFile(PyObject *value, FILE *file, int version)
+
+   Marshal a Python object, *value*, to *file*.
+   *version* indicates the file format.
+
+
+.. c:function:: PyObject* PyMarshal_WriteObjectToString(PyObject *value, int version)
+
+   Return a bytes object containing the marshalled representation of *value*.
+   *version* indicates the file format.
+
+
+The following functions allow marshalled values to be read back in.
+
+
+.. c:function:: long PyMarshal_ReadLongFromFile(FILE *file)
+
+   Return a C :c:type:`long` from the data stream in a :c:type:`FILE\*` opened
+   for reading.  Only a 32-bit value can be read in using this function,
+   regardless of the native size of :c:type:`long`.
+
+   On error, sets the appropriate exception (:exc:`EOFError`) and returns
+   ``-1``.
+
+
+.. c:function:: int PyMarshal_ReadShortFromFile(FILE *file)
+
+   Return a C :c:type:`short` from the data stream in a :c:type:`FILE\*` opened
+   for reading.  Only a 16-bit value can be read in using this function,
+   regardless of the native size of :c:type:`short`.
+
+   On error, sets the appropriate exception (:exc:`EOFError`) and returns
+   ``-1``.
+
+
+.. c:function:: PyObject* PyMarshal_ReadObjectFromFile(FILE *file)
+
+   Return a Python object from the data stream in a :c:type:`FILE\*` opened for
+   reading.
+
+   On error, sets the appropriate exception (:exc:`EOFError`, :exc:`ValueError`
+   or :exc:`TypeError`) and returns *NULL*.
+
+
+.. c:function:: PyObject* PyMarshal_ReadLastObjectFromFile(FILE *file)
+
+   Return a Python object from the data stream in a :c:type:`FILE\*` opened for
+   reading.  Unlike :c:func:`PyMarshal_ReadObjectFromFile`, this function
+   assumes that no further objects will be read from the file, allowing it to
+   aggressively load file data into memory so that the de-serialization can
+   operate from data in memory rather than reading a byte at a time from the
+   file.  Only use these variant if you are certain that you won't be reading
+   anything else from the file.
+
+   On error, sets the appropriate exception (:exc:`EOFError`, :exc:`ValueError`
+   or :exc:`TypeError`) and returns *NULL*.
+
+
+.. c:function:: PyObject* PyMarshal_ReadObjectFromString(const char *data, Py_ssize_t len)
+
+   Return a Python object from the data stream in a byte buffer
+   containing *len* bytes pointed to by *data*.
+
+   On error, sets the appropriate exception (:exc:`EOFError`, :exc:`ValueError`
+   or :exc:`TypeError`) and returns *NULL*.
+

third_party/python/Doc/c-api/memory.rst

@@ -0,0 +1,546 @@
+.. highlightlang:: c
+
+
+.. _memory:
+
+*****************
+Memory Management
+*****************
+
+.. sectionauthor:: Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>
+
+
+
+.. _memoryoverview:
+
+Overview
+========
+
+Memory management in Python involves a private heap containing all Python
+objects and data structures. The management of this private heap is ensured
+internally by the *Python memory manager*.  The Python memory manager has
+different components which deal with various dynamic storage management aspects,
+like sharing, segmentation, preallocation or caching.
+
+At the lowest level, a raw memory allocator ensures that there is enough room in
+the private heap for storing all Python-related data by interacting with the
+memory manager of the operating system. On top of the raw memory allocator,
+several object-specific allocators operate on the same heap and implement
+distinct memory management policies adapted to the peculiarities of every object
+type. For example, integer objects are managed differently within the heap than
+strings, tuples or dictionaries because integers imply different storage
+requirements and speed/space tradeoffs. The Python memory manager thus delegates
+some of the work to the object-specific allocators, but ensures that the latter
+operate within the bounds of the private heap.
+
+It is important to understand that the management of the Python heap is
+performed by the interpreter itself and that the user has no control over it,
+even if they regularly manipulate object pointers to memory blocks inside that
+heap.  The allocation of heap space for Python objects and other internal
+buffers is performed on demand by the Python memory manager through the Python/C
+API functions listed in this document.
+
+.. index::
+   single: malloc()
+   single: calloc()
+   single: realloc()
+   single: free()
+
+To avoid memory corruption, extension writers should never try to operate on
+Python objects with the functions exported by the C library: :c:func:`malloc`,
+:c:func:`calloc`, :c:func:`realloc` and :c:func:`free`.  This will result in  mixed
+calls between the C allocator and the Python memory manager with fatal
+consequences, because they implement different algorithms and operate on
+different heaps.  However, one may safely allocate and release memory blocks
+with the C library allocator for individual purposes, as shown in the following
+example::
+
+   PyObject *res;
+   char *buf = (char *) malloc(BUFSIZ); /* for I/O */
+
+   if (buf == NULL)
+       return PyErr_NoMemory();
+   ...Do some I/O operation involving buf...
+   res = PyBytes_FromString(buf);
+   free(buf); /* malloc'ed */
+   return res;
+
+In this example, the memory request for the I/O buffer is handled by the C
+library allocator. The Python memory manager is involved only in the allocation
+of the string object returned as a result.
+
+In most situations, however, it is recommended to allocate memory from the
+Python heap specifically because the latter is under control of the Python
+memory manager. For example, this is required when the interpreter is extended
+with new object types written in C. Another reason for using the Python heap is
+the desire to *inform* the Python memory manager about the memory needs of the
+extension module. Even when the requested memory is used exclusively for
+internal, highly-specific purposes, delegating all memory requests to the Python
+memory manager causes the interpreter to have a more accurate image of its
+memory footprint as a whole. Consequently, under certain circumstances, the
+Python memory manager may or may not trigger appropriate actions, like garbage
+collection, memory compaction or other preventive procedures. Note that by using
+the C library allocator as shown in the previous example, the allocated memory
+for the I/O buffer escapes completely the Python memory manager.
+
+.. seealso::
+
+   The :envvar:`PYTHONMALLOC` environment variable can be used to configure
+   the memory allocators used by Python.
+
+   The :envvar:`PYTHONMALLOCSTATS` environment variable can be used to print
+   statistics of the :ref:`pymalloc memory allocator <pymalloc>` every time a
+   new pymalloc object arena is created, and on shutdown.
+
+
+Raw Memory Interface
+====================
+
+The following function sets are wrappers to the system allocator. These
+functions are thread-safe, the :term:`GIL <global interpreter lock>` does not
+need to be held.
+
+The default raw memory block 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 zero bytes.
+
+.. versionadded:: 3.4
+
+.. c:function:: void* PyMem_RawMalloc(size_t n)
+
+   Allocates *n* bytes and returns a pointer of type :c:type:`void\*` to the
+   allocated memory, or *NULL* if the request fails.
+
+   Requesting zero bytes returns a distinct non-*NULL* pointer if possible, as
+   if ``PyMem_RawMalloc(1)`` had been called instead. The memory will not have
+   been initialized in any way.
+
+
+.. c:function:: void* PyMem_RawCalloc(size_t nelem, size_t elsize)
+
+   Allocates *nelem* elements each whose size in bytes is *elsize* and returns
+   a pointer of type :c:type:`void\*` to the allocated memory, or *NULL* if the
+   request fails. The memory is initialized to zeros.
+
+   Requesting zero elements or elements of size zero bytes returns a distinct
+   non-*NULL* pointer if possible, as if ``PyMem_RawCalloc(1, 1)`` had been
+   called instead.
+
+   .. versionadded:: 3.5
+
+
+.. c:function:: void* PyMem_RawRealloc(void *p, size_t n)
+
+   Resizes the memory block pointed to by *p* to *n* bytes. The contents will
+   be unchanged to the minimum of the old and the new sizes.
+
+   If *p* is *NULL*, the call is equivalent to ``PyMem_RawMalloc(n)``; else if
+   *n* is equal to zero, the memory block is resized but is not freed, and the
+   returned pointer is non-*NULL*.
+
+   Unless *p* is *NULL*, it must have been returned by a previous call to
+   :c:func:`PyMem_RawMalloc`, :c:func:`PyMem_RawRealloc` or
+   :c:func:`PyMem_RawCalloc`.
+
+   If the request fails, :c:func:`PyMem_RawRealloc` returns *NULL* and *p*
+   remains a valid pointer to the previous memory area.
+
+
+.. c:function:: void PyMem_RawFree(void *p)
+
+   Frees the memory block pointed to by *p*, which must have been returned by a
+   previous call to :c:func:`PyMem_RawMalloc`, :c:func:`PyMem_RawRealloc` or
+   :c:func:`PyMem_RawCalloc`.  Otherwise, or if ``PyMem_RawFree(p)`` has been
+   called before, undefined behavior occurs.
+
+   If *p* is *NULL*, no operation is performed.
+
+
+.. _memoryinterface:
+
+Memory Interface
+================
+
+The following function sets, modeled after the ANSI C standard, but specifying
+behavior when requesting zero bytes, are available for allocating and releasing
+memory from the Python heap.
+
+By default, these functions use :ref:`pymalloc memory allocator <pymalloc>`.
+
+.. warning::
+
+   The :term:`GIL <global interpreter lock>` must be held when using these
+   functions.
+
+.. versionchanged:: 3.6
+
+   The default allocator is now pymalloc instead of system :c:func:`malloc`.
+
+.. c:function:: void* PyMem_Malloc(size_t n)
+
+   Allocates *n* bytes and returns a pointer of type :c:type:`void\*` to the
+   allocated memory, or *NULL* if the request fails.
+
+   Requesting zero bytes returns a distinct non-*NULL* pointer if possible, as
+   if ``PyMem_Malloc(1)`` had been called instead. The memory will not have
+   been initialized in any way.
+
+
+.. c:function:: void* PyMem_Calloc(size_t nelem, size_t elsize)
+
+   Allocates *nelem* elements each whose size in bytes is *elsize* and returns
+   a pointer of type :c:type:`void\*` to the allocated memory, or *NULL* if the
+   request fails. The memory is initialized to zeros.
+
+   Requesting zero elements or elements of size zero bytes returns a distinct
+   non-*NULL* pointer if possible, as if ``PyMem_Calloc(1, 1)`` had been called
+   instead.
+
+   .. versionadded:: 3.5
+
+
+.. c:function:: void* PyMem_Realloc(void *p, size_t n)
+
+   Resizes the memory block pointed to by *p* to *n* bytes. The contents will be
+   unchanged to the minimum of the old and the new sizes.
+
+   If *p* is *NULL*, the call is equivalent to ``PyMem_Malloc(n)``; else if *n*
+   is equal to zero, the memory block is resized but is not freed, and the
+   returned pointer is non-*NULL*.
+
+   Unless *p* is *NULL*, it must have been returned by a previous call to
+   :c:func:`PyMem_Malloc`, :c:func:`PyMem_Realloc` or :c:func:`PyMem_Calloc`.
+
+   If the request fails, :c:func:`PyMem_Realloc` returns *NULL* and *p* remains
+   a valid pointer to the previous memory area.
+
+
+.. c:function:: void PyMem_Free(void *p)
+
+   Frees the memory block pointed to by *p*, which must have been returned by a
+   previous call to :c:func:`PyMem_Malloc`, :c:func:`PyMem_Realloc` or
+   :c:func:`PyMem_Calloc`.  Otherwise, or if ``PyMem_Free(p)`` has been called
+   before, undefined behavior occurs.
+
+   If *p* is *NULL*, no operation is performed.
+
+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)
+
+   Same as :c:func:`PyMem_Malloc`, but allocates ``(n * sizeof(TYPE))`` bytes of
+   memory.  Returns a pointer cast to :c:type:`TYPE\*`.  The memory will not have
+   been initialized in any way.
+
+
+.. c:function:: TYPE* PyMem_Resize(void *p, TYPE, size_t n)
+
+   Same as :c:func:`PyMem_Realloc`, but the memory block is resized to ``(n *
+   sizeof(TYPE))`` bytes.  Returns a pointer cast to :c:type:`TYPE\*`. On return,
+   *p* will be a pointer to the new memory area, or *NULL* in the event of
+   failure.
+
+   This is a C preprocessor macro; *p* is always reassigned.  Save the original
+   value of *p* to avoid losing memory when handling errors.
+
+
+.. c:function:: void PyMem_Del(void *p)
+
+   Same as :c:func:`PyMem_Free`.
+
+In addition, the following macro sets are provided for calling the Python memory
+allocator directly, without involving the C API functions listed above. However,
+note that their use does not preserve binary compatibility across Python
+versions and is therefore deprecated in extension modules.
+
+* ``PyMem_MALLOC(size)``
+* ``PyMem_NEW(type, size)``
+* ``PyMem_REALLOC(ptr, size)``
+* ``PyMem_RESIZE(ptr, type, size)``
+* ``PyMem_FREE(ptr)``
+* ``PyMem_DEL(ptr)``
+
+
+Object allocators
+=================
+
+The following function sets, modeled after the ANSI C standard, but specifying
+behavior when requesting zero bytes, are available for allocating and releasing
+memory from the Python heap.
+
+By default, these functions use :ref:`pymalloc memory allocator <pymalloc>`.
+
+.. warning::
+
+   The :term:`GIL <global interpreter lock>` must be held when using these
+   functions.
+
+.. c:function:: void* PyObject_Malloc(size_t n)
+
+   Allocates *n* bytes and returns a pointer of type :c:type:`void\*` to the
+   allocated memory, or *NULL* if the request fails.
+
+   Requesting zero bytes returns a distinct non-*NULL* pointer if possible, as
+   if ``PyObject_Malloc(1)`` had been called instead. The memory will not have
+   been initialized in any way.
+
+
+.. c:function:: void* PyObject_Calloc(size_t nelem, size_t elsize)
+
+   Allocates *nelem* elements each whose size in bytes is *elsize* and returns
+   a pointer of type :c:type:`void\*` to the allocated memory, or *NULL* if the
+   request fails. The memory is initialized to zeros.
+
+   Requesting zero elements or elements of size zero bytes returns a distinct
+   non-*NULL* pointer if possible, as if ``PyObject_Calloc(1, 1)`` had been called
+   instead.
+
+   .. versionadded:: 3.5
+
+
+.. c:function:: void* PyObject_Realloc(void *p, size_t n)
+
+   Resizes the memory block pointed to by *p* to *n* bytes. The contents will be
+   unchanged to the minimum of the old and the new sizes.
+
+   If *p* is *NULL*, the call is equivalent to ``PyObject_Malloc(n)``; else if *n*
+   is equal to zero, the memory block is resized but is not freed, and the
+   returned pointer is non-*NULL*.
+
+   Unless *p* is *NULL*, it must have been returned by a previous call to
+   :c:func:`PyObject_Malloc`, :c:func:`PyObject_Realloc` or :c:func:`PyObject_Calloc`.
+
+   If the request fails, :c:func:`PyObject_Realloc` returns *NULL* and *p* remains
+   a valid pointer to the previous memory area.
+
+
+.. c:function:: void PyObject_Free(void *p)
+
+   Frees the memory block pointed to by *p*, which must have been returned by a
+   previous call to :c:func:`PyObject_Malloc`, :c:func:`PyObject_Realloc` or
+   :c:func:`PyObject_Calloc`.  Otherwise, or if ``PyObject_Free(p)`` has been called
+   before, undefined behavior occurs.
+
+   If *p* is *NULL*, no operation is performed.
+
+
+Customize Memory Allocators
+===========================
+
+.. versionadded:: 3.4
+
+.. c:type:: PyMemAllocatorEx
+
+   Structure used to describe a memory block allocator. The structure has
+   four fields:
+
+   +----------------------------------------------------------+---------------------------------------+
+   | Field                                                    | Meaning                               |
+   +==========================================================+=======================================+
+   | ``void *ctx``                                            | user context passed as first argument |
+   +----------------------------------------------------------+---------------------------------------+
+   | ``void* malloc(void *ctx, size_t size)``                 | allocate a memory block               |
+   +----------------------------------------------------------+---------------------------------------+
+   | ``void* calloc(void *ctx, size_t nelem, size_t elsize)`` | allocate a memory block initialized   |
+   |                                                          | with zeros                            |
+   +----------------------------------------------------------+---------------------------------------+
+   | ``void* realloc(void *ctx, void *ptr, size_t new_size)`` | allocate or resize a memory block     |
+   +----------------------------------------------------------+---------------------------------------+
+   | ``void free(void *ctx, void *ptr)``                      | free a memory block                   |
+   +----------------------------------------------------------+---------------------------------------+
+
+   .. versionchanged:: 3.5
+      The :c:type:`PyMemAllocator` structure was renamed to
+      :c:type:`PyMemAllocatorEx` and a new ``calloc`` field was added.
+
+
+.. c:type:: PyMemAllocatorDomain
+
+   Enum used to identify an allocator domain. Domains:
+
+   .. c:var:: PYMEM_DOMAIN_RAW
+
+      Functions:
+
+      * :c:func:`PyMem_RawMalloc`
+      * :c:func:`PyMem_RawRealloc`
+      * :c:func:`PyMem_RawCalloc`
+      * :c:func:`PyMem_RawFree`
+
+   .. c:var:: PYMEM_DOMAIN_MEM
+
+      Functions:
+
+      * :c:func:`PyMem_Malloc`,
+      * :c:func:`PyMem_Realloc`
+      * :c:func:`PyMem_Calloc`
+      * :c:func:`PyMem_Free`
+
+   .. c:var:: PYMEM_DOMAIN_OBJ
+
+      Functions:
+
+      * :c:func:`PyObject_Malloc`
+      * :c:func:`PyObject_Realloc`
+      * :c:func:`PyObject_Calloc`
+      * :c:func:`PyObject_Free`
+
+.. c:function:: void PyMem_GetAllocator(PyMemAllocatorDomain domain, PyMemAllocatorEx *allocator)
+
+   Get the memory block allocator of the specified domain.
+
+
+.. c:function:: void PyMem_SetAllocator(PyMemAllocatorDomain domain, PyMemAllocatorEx *allocator)
+
+   Set the memory block allocator of the specified domain.
+
+   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
+   thread-safe: the :term:`GIL <global interpreter lock>` is not held when the
+   allocator is called.
+
+   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.
+
+
+.. c:function:: void PyMem_SetupDebugHooks(void)
+
+   Setup hooks to detect bugs in the Python memory allocator functions.
+
+   Newly allocated memory is filled with the byte ``0xCB``, freed memory is
+   filled with the byte ``0xDB``.
+
+   Runtime checks:
+
+   - Detect API violations, ex: :c:func:`PyObject_Free` called on a buffer
+     allocated by :c:func:`PyMem_Malloc`
+   - 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 <global interpreter lock>` is held when
+     allocator functions of :c:data:`PYMEM_DOMAIN_OBJ` (ex:
+     :c:func:`PyObject_Malloc`) and :c:data:`PYMEM_DOMAIN_MEM` (ex:
+     :c:func:`PyMem_Malloc`) domains are called
+
+   On error, the debug hooks use the :mod:`tracemalloc` module to get the
+   traceback where a memory block was allocated. The traceback is only
+   displayed if :mod:`tracemalloc` is tracing Python memory allocations and the
+   memory block was traced.
+
+   These hooks are installed by default if Python is compiled in debug
+   mode. The :envvar:`PYTHONMALLOC` environment variable can be used to install
+   debug hooks on a Python compiled in release mode.
+
+   .. versionchanged:: 3.6
+      This function now also works on Python 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 called.
+
+
+.. _pymalloc:
+
+The pymalloc allocator
+======================
+
+Python has a *pymalloc* allocator optimized for small objects (smaller or equal
+to 512 bytes) with a short lifetime. It uses memory mappings called "arenas"
+with a fixed size of 256 KB. It falls back to :c:func:`PyMem_RawMalloc` and
+:c:func:`PyMem_RawRealloc` for allocations larger than 512 bytes.
+
+*pymalloc* is the 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.
+
+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:`malloc` and :c:func:`free` otherwise.
+
+Customize pymalloc Arena Allocator
+----------------------------------
+
+.. versionadded:: 3.4
+
+.. c:type:: PyObjectArenaAllocator
+
+   Structure used to describe an arena allocator. The structure has
+   three fields:
+
+   +--------------------------------------------------+---------------------------------------+
+   | Field                                            | Meaning                               |
+   +==================================================+=======================================+
+   | ``void *ctx``                                    | user context passed as first argument |
+   +--------------------------------------------------+---------------------------------------+
+   | ``void* alloc(void *ctx, size_t size)``          | allocate an arena of size bytes       |
+   +--------------------------------------------------+---------------------------------------+
+   | ``void free(void *ctx, size_t size, void *ptr)`` | free an arena                         |
+   +--------------------------------------------------+---------------------------------------+
+
+.. c:function:: PyObject_GetArenaAllocator(PyObjectArenaAllocator *allocator)
+
+   Get the arena allocator.
+
+.. c:function:: PyObject_SetArenaAllocator(PyObjectArenaAllocator *allocator)
+
+   Set the arena allocator.
+
+
+.. _memoryexamples:
+
+Examples
+========
+
+Here is the example from section :ref:`memoryoverview`, rewritten so that the
+I/O buffer is allocated from the Python heap by using the first function set::
+
+   PyObject *res;
+   char *buf = (char *) PyMem_Malloc(BUFSIZ); /* for I/O */
+
+   if (buf == NULL)
+       return PyErr_NoMemory();
+   /* ...Do some I/O operation involving buf... */
+   res = PyBytes_FromString(buf);
+   PyMem_Free(buf); /* allocated with PyMem_Malloc */
+   return res;
+
+The same code using the type-oriented function set::
+
+   PyObject *res;
+   char *buf = PyMem_New(char, BUFSIZ); /* for I/O */
+
+   if (buf == NULL)
+       return PyErr_NoMemory();
+   /* ...Do some I/O operation involving buf... */
+   res = PyBytes_FromString(buf);
+   PyMem_Del(buf); /* allocated with PyMem_New */
+   return res;
+
+Note that in the two examples above, the buffer is always manipulated via
+functions belonging to the same set. Indeed, it is required to use the same
+memory API family for a given memory block, so that the risk of mixing different
+allocators is reduced to a minimum. The following code sequence contains two
+errors, one of which is labeled as *fatal* because it mixes two different
+allocators operating on different heaps. ::
+
+   char *buf1 = PyMem_New(char, BUFSIZ);
+   char *buf2 = (char *) malloc(BUFSIZ);
+   char *buf3 = (char *) PyMem_Malloc(BUFSIZ);
+   ...
+   PyMem_Del(buf3);  /* Wrong -- should be PyMem_Free() */
+   free(buf2);       /* Right -- allocated via malloc() */
+   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`.
+
+These will be explained in the next chapter on defining and implementing new
+object types in C.
+

third_party/python/Doc/c-api/memoryview.rst

@@ -0,0 +1,63 @@
+.. highlightlang:: c
+
+.. _memoryview-objects:
+
+.. index::
+   object: memoryview
+
+MemoryView objects
+------------------
+
+A :class:`memoryview` object exposes the C level :ref:`buffer interface
+<bufferobjects>` as a Python object which can then be passed around like
+any other object.
+
+
+.. c:function:: PyObject *PyMemoryView_FromObject(PyObject *obj)
+
+   Create a memoryview object from an object that provides the buffer interface.
+   If *obj* supports writable buffer exports, the memoryview object will be
+   read/write, otherwise it may be either read-only or read/write at the
+   discretion of the exporter.
+
+.. c:function:: PyObject *PyMemoryView_FromMemory(char *mem, Py_ssize_t size, int flags)
+
+   Create a memoryview object using *mem* as the underlying buffer.
+   *flags* can be one of :c:macro:`PyBUF_READ` or :c:macro:`PyBUF_WRITE`.
+
+   .. versionadded:: 3.3
+
+.. c:function:: PyObject *PyMemoryView_FromBuffer(Py_buffer *view)
+
+   Create a memoryview object wrapping the given buffer structure *view*.
+   For simple byte buffers, :c:func:`PyMemoryView_FromMemory` is the preferred
+   function.
+
+.. c:function:: PyObject *PyMemoryView_GetContiguous(PyObject *obj, int buffertype, char order)
+
+   Create a memoryview object to a :term:`contiguous` chunk of memory (in either
+   'C' or 'F'ortran *order*) from an object that defines the buffer
+   interface. If memory is contiguous, the memoryview object points to the
+   original memory. Otherwise, a copy is made and the memoryview points to a
+   new bytes object.
+
+
+.. c:function:: int PyMemoryView_Check(PyObject *obj)
+
+   Return true if the object *obj* is a memoryview object.  It is not
+   currently allowed to create subclasses of :class:`memoryview`.
+
+
+.. c:function:: Py_buffer *PyMemoryView_GET_BUFFER(PyObject *mview)
+
+   Return a pointer to the memoryview's private copy of the exporter's buffer.
+   *mview* **must** be a memoryview instance; this macro doesn't check its type,
+   you must do it yourself or you will risk crashes.
+
+.. c:function:: Py_buffer *PyMemoryView_GET_BASE(PyObject *mview)
+
+   Return either a pointer to the exporting object that the memoryview is based
+   on or *NULL* if the memoryview has been created by one of the functions
+   :c:func:`PyMemoryView_FromMemory` or :c:func:`PyMemoryView_FromBuffer`.
+   *mview* **must** be a memoryview instance.
+

third_party/python/Doc/c-api/method.rst

@@ -0,0 +1,100 @@
+.. highlightlang:: c
+
+.. _instancemethod-objects:
+
+Instance Method Objects
+-----------------------
+
+.. index:: 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
+``PyMethod_New(func, NULL, class)``.
+
+
+.. c:var:: PyTypeObject PyInstanceMethod_Type
+
+   This instance of :c:type:`PyTypeObject` represents the Python instance
+   method type. It is not exposed to Python programs.
+
+
+.. c:function:: int PyInstanceMethod_Check(PyObject *o)
+
+   Return true if *o* is an instance method object (has type
+   :c:data:`PyInstanceMethod_Type`).  The parameter must not be *NULL*.
+
+
+.. c:function:: PyObject* PyInstanceMethod_New(PyObject *func)
+
+   Return a new instance method object, with *func* being any callable object
+   *func* is the function that will be called when the instance method is
+   called.
+
+
+.. c:function:: PyObject* PyInstanceMethod_Function(PyObject *im)
+
+   Return the function object associated with the instance method *im*.
+
+
+.. c:function:: PyObject* PyInstanceMethod_GET_FUNCTION(PyObject *im)
+
+   Macro version of :c:func:`PyInstanceMethod_Function` which avoids error checking.
+
+
+.. _method-objects:
+
+Method Objects
+--------------
+
+.. index:: object: method
+
+Methods are bound function objects. Methods are always bound to an instance of
+a user-defined class. Unbound methods (methods bound to a class object) are
+no longer available.
+
+
+.. c:var:: PyTypeObject PyMethod_Type
+
+   .. index:: single: MethodType (in module types)
+
+   This instance of :c:type:`PyTypeObject` represents the Python method type.  This
+   is exposed to Python programs as ``types.MethodType``.
+
+
+.. c:function:: int PyMethod_Check(PyObject *o)
+
+   Return true if *o* is a method object (has type :c:data:`PyMethod_Type`).  The
+   parameter must not be *NULL*.
+
+
+.. c:function:: PyObject* PyMethod_New(PyObject *func, PyObject *self)
+
+   Return a new method object, with *func* being any callable object and *self*
+   the instance the method should be bound. *func* is the function that will
+   be called when the method is called. *self* must not be *NULL*.
+
+
+.. c:function:: PyObject* PyMethod_Function(PyObject *meth)
+
+   Return the function object associated with the method *meth*.
+
+
+.. c:function:: PyObject* PyMethod_GET_FUNCTION(PyObject *meth)
+
+   Macro version of :c:func:`PyMethod_Function` which avoids error checking.
+
+
+.. c:function:: PyObject* PyMethod_Self(PyObject *meth)
+
+   Return the instance associated with the method *meth*.
+
+
+.. c:function:: PyObject* PyMethod_GET_SELF(PyObject *meth)
+
+   Macro version of :c:func:`PyMethod_Self` which avoids error checking.
+
+
+.. c:function:: int PyMethod_ClearFreeList()
+
+   Clear the free list. Return the total number of freed items.
+

third_party/python/Doc/c-api/module.rst

@@ -0,0 +1,479 @@
+.. highlightlang:: c
+
+.. _moduleobjects:
+
+Module Objects
+--------------
+
+.. index:: object: module
+
+
+.. c:var:: PyTypeObject PyModule_Type
+
+   .. index:: single: ModuleType (in module types)
+
+   This instance of :c:type:`PyTypeObject` represents the Python module type.  This
+   is exposed to Python programs as ``types.ModuleType``.
+
+
+.. c:function:: int PyModule_Check(PyObject *p)
+
+   Return true if *p* is a module object, or a subtype of a module object.
+
+
+.. c:function:: int PyModule_CheckExact(PyObject *p)
+
+   Return true if *p* is a module object, but not a subtype of
+   :c:data:`PyModule_Type`.
+
+
+.. c:function:: PyObject* PyModule_NewObject(PyObject *name)
+
+   .. index::
+      single: __name__ (module attribute)
+      single: __doc__ (module attribute)
+      single: __file__ (module attribute)
+      single: __package__ (module attribute)
+      single: __loader__ (module attribute)
+
+   Return a new module object with the :attr:`__name__` attribute set to *name*.
+   The module's :attr:`__name__`, :attr:`__doc__`, :attr:`__package__`, and
+   :attr:`__loader__` attributes are filled in (all but :attr:`__name__` are set
+   to ``None``); the caller is responsible for providing a :attr:`__file__`
+   attribute.
+
+   .. versionadded:: 3.3
+
+   .. versionchanged:: 3.4
+      :attr:`__package__` and :attr:`__loader__` are set to ``None``.
+
+
+.. c:function:: PyObject* PyModule_New(const char *name)
+
+   Similar to :c:func:`PyModule_NewObject`, but the name is a UTF-8 encoded
+   string instead of a Unicode object.
+
+
+.. c:function:: PyObject* PyModule_GetDict(PyObject *module)
+
+   .. index:: single: __dict__ (module attribute)
+
+   Return the dictionary object that implements *module*'s namespace; this object
+   is the same as the :attr:`~object.__dict__` attribute of the module object.
+   If *module* is not a module object (or a subtype of a module object),
+   :exc:`SystemError` is raised and *NULL* is returned.
+
+   It is recommended extensions use other :c:func:`PyModule_\*` and
+   :c:func:`PyObject_\*` functions rather than directly manipulate a module's
+   :attr:`~object.__dict__`.
+
+
+.. c:function:: PyObject* PyModule_GetNameObject(PyObject *module)
+
+   .. index::
+      single: __name__ (module attribute)
+      single: SystemError (built-in exception)
+
+   Return *module*'s :attr:`__name__` value.  If the module does not provide one,
+   or if it is not a string, :exc:`SystemError` is raised and *NULL* is returned.
+
+   .. versionadded:: 3.3
+
+
+.. c:function:: char* PyModule_GetName(PyObject *module)
+
+   Similar to :c:func:`PyModule_GetNameObject` but return the name encoded to
+   ``'utf-8'``.
+
+.. c:function:: void* PyModule_GetState(PyObject *module)
+
+   Return the "state" of the module, that is, a pointer to the block of memory
+   allocated at module creation time, or *NULL*.  See
+   :c:member:`PyModuleDef.m_size`.
+
+
+.. c:function:: PyModuleDef* PyModule_GetDef(PyObject *module)
+
+   Return a pointer to the :c:type:`PyModuleDef` struct from which the module was
+   created, or *NULL* if the module wasn't created from a definition.
+
+
+.. c:function:: PyObject* PyModule_GetFilenameObject(PyObject *module)
+
+   .. index::
+      single: __file__ (module attribute)
+      single: SystemError (built-in exception)
+
+   Return the name of the file from which *module* was loaded using *module*'s
+   :attr:`__file__` attribute.  If this is not defined, or if it is not a
+   unicode string, raise :exc:`SystemError` and return *NULL*; otherwise return
+   a reference to a Unicode object.
+
+   .. versionadded:: 3.2
+
+
+.. c:function:: char* PyModule_GetFilename(PyObject *module)
+
+   Similar to :c:func:`PyModule_GetFilenameObject` but return the filename
+   encoded to 'utf-8'.
+
+   .. deprecated:: 3.2
+      :c:func:`PyModule_GetFilename` raises :c:type:`UnicodeEncodeError` on
+      unencodable filenames, use :c:func:`PyModule_GetFilenameObject` instead.
+
+
+.. _initializing-modules:
+
+Initializing C modules
+^^^^^^^^^^^^^^^^^^^^^^
+
+Modules objects are usually created from extension modules (shared libraries
+which export an initialization function), or compiled-in modules
+(where the initialization function is added using :c:func:`PyImport_AppendInittab`).
+See :ref:`building` or :ref:`extending-with-embedding` for details.
+
+The initialization function can either pass a module definition instance
+to :c:func:`PyModule_Create`, and return the resulting module object,
+or request "multi-phase initialization" by returning the definition struct itself.
+
+.. c:type:: PyModuleDef
+
+   The module definition struct, which holds all information needed to create
+   a module object. There is usually only one statically initialized variable
+   of this type for each module.
+
+   .. c:member:: PyModuleDef_Base m_base
+
+      Always initialize this member to :const:`PyModuleDef_HEAD_INIT`.
+
+   .. c:member:: char* m_name
+
+      Name for the new module.
+
+   .. c:member:: char* m_doc
+
+      Docstring for the module; usually a docstring variable created with
+      :c:func:`PyDoc_STRVAR` is used.
+
+   .. c:member:: Py_ssize_t m_size
+
+      Module state may be kept in a per-module memory area that can be
+      retrieved with :c:func:`PyModule_GetState`, rather than in static globals.
+      This makes modules safe for use in multiple sub-interpreters.
+
+      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.
+
+      Setting ``m_size`` to ``-1`` means that the module does not support
+      sub-interpreters, because it has global state.
+
+      Setting it to a non-negative value means that the module can be
+      re-initialized and specifies the additional amount of memory it requires
+      for its state. Non-negative ``m_size`` is required for multi-phase
+      initialization.
+
+      See :PEP:`3121` for more details.
+
+   .. c:member:: PyMethodDef* m_methods
+
+      A pointer to a table of module-level functions, described by
+      :c:type:`PyMethodDef` values.  Can be *NULL* if no functions are present.
+
+   .. c:member:: PyModuleDef_Slot* m_slots
+
+      An array of slot definitions for multi-phase initialization, terminated by
+      a ``{0, NULL}`` entry.
+      When using single-phase initialization, *m_slots* must be *NULL*.
+
+      .. versionchanged:: 3.5
+
+         Prior to version 3.5, this member was always set to *NULL*,
+         and was defined as:
+
+           .. c:member:: inquiry m_reload
+
+   .. c:member:: traverseproc m_traverse
+
+      A traversal function to call during GC traversal of the module object, or
+      *NULL* if not needed. This function may be called before module state
+      is allocated (:c:func:`PyModule_GetState()` may return `NULL`),
+      and before the :c:member:`Py_mod_exec` function is executed.
+
+   .. c:member:: inquiry m_clear
+
+      A clear function to call during GC clearing of the module object, or
+      *NULL* if not needed. This function may be called before module state
+      is allocated (:c:func:`PyModule_GetState()` may return `NULL`),
+      and before the :c:member:`Py_mod_exec` function is executed.
+
+   .. c:member:: freefunc m_free
+
+      A function to call during deallocation of the module object, or *NULL* if
+      not needed. This function may be called before module state
+      is allocated (:c:func:`PyModule_GetState()` may return `NULL`),
+      and before the :c:member:`Py_mod_exec` function is executed.
+
+Single-phase initialization
+...........................
+
+The module initialization function may create and return the module object
+directly. This is referred to as "single-phase initialization", and uses one
+of the following two module creation functions:
+
+.. c:function:: PyObject* PyModule_Create(PyModuleDef *def)
+
+   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:function:: PyObject* PyModule_Create2(PyModuleDef *def, int module_api_version)
+
+   Create a new module object, given the definition in *def*, assuming the
+   API version *module_api_version*.  If that version does not match the version
+   of the running interpreter, a :exc:`RuntimeWarning` is emitted.
+
+   .. note::
+
+      Most uses of this function should be using :c:func:`PyModule_Create`
+      instead; only use this if you are sure you need it.
+
+Before it is returned from in the initialization function, the resulting module
+object is typically populated using functions like :c:func:`PyModule_AddObject`.
+
+.. _multi-phase-initialization:
+
+Multi-phase initialization
+..........................
+
+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
+of classes.
+
+Unlike modules created using single-phase initialization, these modules are not
+singletons: if the *sys.modules* entry is removed and the module is re-imported,
+a new module object is created, and the old module is subject to normal garbage
+collection -- as with Python modules.
+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`).
+
+All modules created using multi-phase initialization are expected to support
+:ref:`sub-interpreters <sub-interpreter-support>`. Making sure multiple modules
+are independent is typically enough to achieve this.
+
+To request multi-phase initialization, the initialization function
+(PyInit_modulename) returns a :c:type:`PyModuleDef` instance with non-empty
+:c:member:`~PyModuleDef.m_slots`. Before it is returned, the ``PyModuleDef``
+instance must be initialized with the following function:
+
+.. c:function:: PyObject* PyModuleDef_Init(PyModuleDef *def)
+
+   Ensures a module definition is a properly initialized Python object that
+   correctly reports its type and reference count.
+
+   Returns *def* cast to ``PyObject*``, or *NULL* if an error occurred.
+
+   .. versionadded:: 3.5
+
+The *m_slots* member of the module definition must point to an array of
+``PyModuleDef_Slot`` structures:
+
+.. c:type:: PyModuleDef_Slot
+
+   .. c:member:: int slot
+
+      A slot ID, chosen from the available values explained below.
+
+   .. c:member:: void* value
+
+      Value of the slot, whose meaning depends on the slot ID.
+
+   .. versionadded:: 3.5
+
+The *m_slots* array must be terminated by a slot with id 0.
+
+The available slot types are:
+
+.. c:var:: Py_mod_create
+
+   Specifies a function that is called to create the module object itself.
+   The *value* pointer of this slot must point to a function of the signature:
+
+   .. c:function:: PyObject* create_module(PyObject *spec, PyModuleDef *def)
+
+   The function receives a :py:class:`~importlib.machinery.ModuleSpec`
+   instance, as defined in :PEP:`451`, and the module definition.
+   It should return a new module object, or set an error
+   and return *NULL*.
+
+   This function should be kept minimal. In particular, it should not
+   call arbitrary Python code, as trying to import the same module again may
+   result in an infinite loop.
+
+   Multiple ``Py_mod_create`` slots may not be specified in one module
+   definition.
+
+   If ``Py_mod_create`` is not specified, the import machinery will create
+   a normal module object using :c:func:`PyModule_New`. The name is taken from
+   *spec*, not the definition, to allow extension modules to dynamically adjust
+   to their place in the module hierarchy and be imported under different
+   names through symlinks, all while sharing a single module definition.
+
+   There is no requirement for the returned object to be an instance of
+   :c:type:`PyModule_Type`. Any type can be used, as long as it supports
+   setting and getting import-related attributes.
+   However, only ``PyModule_Type`` instances may be returned if the
+   ``PyModuleDef`` has non-*NULL* ``m_traverse``, ``m_clear``,
+   ``m_free``; non-zero ``m_size``; or slots other than ``Py_mod_create``.
+
+.. c:var:: Py_mod_exec
+
+   Specifies a function that is called to *execute* the module.
+   This is equivalent to executing the code of a Python module: typically,
+   this function adds classes and constants to the module.
+   The signature of the function is:
+
+   .. c:function:: int exec_module(PyObject* module)
+
+   If multiple ``Py_mod_exec`` slots are specified, they are processed in the
+   order they appear in the *m_slots* array.
+
+See :PEP:`489` for more details on multi-phase initialization.
+
+Low-level module creation functions
+...................................
+
+The following functions are called under the hood when using multi-phase
+initialization. They can be used directly, for example when creating module
+objects dynamically. Note that both ``PyModule_FromDefAndSpec`` and
+``PyModule_ExecDef`` must be called to fully initialize a module.
+
+.. c:function:: PyObject * PyModule_FromDefAndSpec(PyModuleDef *def, PyObject *spec)
+
+   Create a new module object, given the definition in *module* and the
+   ModuleSpec *spec*.  This behaves like :c:func:`PyModule_FromDefAndSpec2`
+   with *module_api_version* set to :const:`PYTHON_API_VERSION`.
+
+   .. versionadded:: 3.5
+
+.. c:function:: PyObject * PyModule_FromDefAndSpec2(PyModuleDef *def, PyObject *spec, int module_api_version)
+
+   Create a new module object, given the definition in *module* and the
+   ModuleSpec *spec*, assuming the API version *module_api_version*.
+   If that version does not match the version of the running interpreter,
+   a :exc:`RuntimeWarning` is emitted.
+
+   .. note::
+
+      Most uses of this function should be using :c:func:`PyModule_FromDefAndSpec`
+      instead; only use this if you are sure you need it.
+
+   .. versionadded:: 3.5
+
+.. c:function:: int PyModule_ExecDef(PyObject *module, PyModuleDef *def)
+
+   Process any execution slots (:c:data:`Py_mod_exec`) given in *def*.
+
+   .. versionadded:: 3.5
+
+.. c:function:: int PyModule_SetDocString(PyObject *module, const char *docstring)
+
+   Set the docstring for *module* to *docstring*.
+   This function is called automatically when creating a module from
+   ``PyModuleDef``, using either ``PyModule_Create`` or
+   ``PyModule_FromDefAndSpec``.
+
+   .. versionadded:: 3.5
+
+.. c:function:: int PyModule_AddFunctions(PyObject *module, PyMethodDef *functions)
+
+   Add the functions from the *NULL* terminated *functions* array to *module*.
+   Refer to the :c:type:`PyMethodDef` documentation for details on individual
+   entries (due to the lack of a shared module namespace, module level
+   "functions" implemented in C typically receive the module as their first
+   parameter, making them similar to instance methods on Python classes).
+   This function is called automatically when creating a module from
+   ``PyModuleDef``, using either ``PyModule_Create`` or
+   ``PyModule_FromDefAndSpec``.
+
+   .. versionadded:: 3.5
+
+Support functions
+.................
+
+The module initialization function (if using single phase initialization) or
+a function called from a module execution slot (if using multi-phase
+initialization), can use the following functions to help initialize the module
+state:
+
+.. c:function:: int PyModule_AddObject(PyObject *module, const char *name, PyObject *value)
+
+   Add an object to *module* as *name*.  This is a convenience function which can
+   be used from the module's initialization function.  This steals a reference to
+   *value*.  Return ``-1`` on error, ``0`` on success.
+
+.. c:function:: int PyModule_AddIntConstant(PyObject *module, const char *name, long value)
+
+   Add an integer constant to *module* as *name*.  This convenience function can be
+   used from the module's initialization function. Return ``-1`` on error, ``0`` on
+   success.
+
+
+.. c:function:: int PyModule_AddStringConstant(PyObject *module, const char *name, const char *value)
+
+   Add a string constant to *module* as *name*.  This convenience function can be
+   used from the module's initialization function.  The string *value* must be
+   *NULL*-terminated.  Return ``-1`` on error, ``0`` on success.
+
+
+.. c:function:: int PyModule_AddIntMacro(PyObject *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
+   constant *AF_INET* with the value of *AF_INET* to *module*.
+   Return ``-1`` on error, ``0`` on success.
+
+
+.. c:function:: int PyModule_AddStringMacro(PyObject *module, macro)
+
+   Add a string constant to *module*.
+
+
+Module lookup
+^^^^^^^^^^^^^
+
+Single-phase initialization creates singleton modules that can be looked up
+in the context of the current interpreter. This allows the module object to be
+retrieved later with only a reference to the module definition.
+
+These functions will not work on modules created using multi-phase initialization,
+since multiple such modules can be created from a single definition.
+
+.. c:function:: PyObject* PyState_FindModule(PyModuleDef *def)
+
+   Returns the module object that was created from *def* for the current interpreter.
+   This method requires that the module object has been attached to the interpreter state with
+   :c:func:`PyState_AddModule` beforehand. In case the corresponding module object is not
+   found or has not been attached to the interpreter state yet, it returns *NULL*.
+
+.. c:function:: int PyState_AddModule(PyObject *module, PyModuleDef *def)
+
+   Attaches the module object passed to the function to the interpreter state. This allows
+   the module object to be accessible via :c:func:`PyState_FindModule`.
+
+   Only effective on modules created using single-phase initialization.
+
+   .. versionadded:: 3.3
+
+.. c:function:: int PyState_RemoveModule(PyModuleDef *def)
+
+   Removes the module object created from *def* from the interpreter state.
+
+   .. versionadded:: 3.3

third_party/python/Doc/c-api/none.rst

@@ -0,0 +1,26 @@
+.. highlightlang:: c
+
+.. _noneobject:
+
+The ``None`` Object
+-------------------
+
+.. index:: object: None
+
+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
+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.
+
+
+.. 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.)

third_party/python/Doc/c-api/number.rst

@@ -0,0 +1,283 @@
+.. highlightlang:: c
+
+.. _number:
+
+Number Protocol
+===============
+
+
+.. c:function:: int PyNumber_Check(PyObject *o)
+
+   Returns ``1`` if the object *o* provides numeric protocols, and false otherwise.
+   This function always succeeds.
+
+
+.. c:function:: PyObject* PyNumber_Add(PyObject *o1, PyObject *o2)
+
+   Returns the result of adding *o1* and *o2*, or *NULL* on failure.  This is the
+   equivalent of the Python expression ``o1 + o2``.
+
+
+.. c:function:: PyObject* PyNumber_Subtract(PyObject *o1, PyObject *o2)
+
+   Returns the result of subtracting *o2* from *o1*, or *NULL* on failure.  This is
+   the equivalent of the Python expression ``o1 - o2``.
+
+
+.. c:function:: PyObject* PyNumber_Multiply(PyObject *o1, PyObject *o2)
+
+   Returns the result of multiplying *o1* and *o2*, or *NULL* on failure.  This is
+   the equivalent of the Python expression ``o1 * o2``.
+
+
+.. c:function:: PyObject* PyNumber_MatrixMultiply(PyObject *o1, PyObject *o2)
+
+   Returns the result of matrix multiplication on *o1* and *o2*, or *NULL* on
+   failure.  This is the equivalent of the Python expression ``o1 @ o2``.
+
+   .. versionadded:: 3.5
+
+
+.. c:function:: PyObject* PyNumber_FloorDivide(PyObject *o1, PyObject *o2)
+
+   Return the floor of *o1* divided by *o2*, or *NULL* on failure.  This is
+   equivalent to the "classic" division of integers.
+
+
+.. c:function:: PyObject* PyNumber_TrueDivide(PyObject *o1, PyObject *o2)
+
+   Return a reasonable approximation for the mathematical value of *o1* divided by
+   *o2*, or *NULL* on failure.  The return value is "approximate" because binary
+   floating point numbers are approximate; it is not possible to represent all real
+   numbers in base two.  This function can return a floating point value when
+   passed two integers.
+
+
+.. c:function:: PyObject* PyNumber_Remainder(PyObject *o1, PyObject *o2)
+
+   Returns the remainder of dividing *o1* by *o2*, or *NULL* on failure.  This is
+   the equivalent of the Python expression ``o1 % o2``.
+
+
+.. c:function:: PyObject* PyNumber_Divmod(PyObject *o1, PyObject *o2)
+
+   .. index:: builtin: divmod
+
+   See the built-in function :func:`divmod`. Returns *NULL* on failure.  This is
+   the equivalent of the Python expression ``divmod(o1, o2)``.
+
+
+.. c:function:: PyObject* PyNumber_Power(PyObject *o1, PyObject *o2, PyObject *o3)
+
+   .. index:: builtin: pow
+
+   See the built-in function :func:`pow`. Returns *NULL* on failure.  This is the
+   equivalent of the Python expression ``pow(o1, o2, o3)``, where *o3* is optional.
+   If *o3* is to be ignored, pass :c:data:`Py_None` in its place (passing *NULL* for
+   *o3* would cause an illegal memory access).
+
+
+.. c:function:: PyObject* PyNumber_Negative(PyObject *o)
+
+   Returns the negation of *o* on success, or *NULL* on failure. This is the
+   equivalent of the Python expression ``-o``.
+
+
+.. c:function:: PyObject* PyNumber_Positive(PyObject *o)
+
+   Returns *o* on success, or *NULL* on failure.  This is the equivalent of the
+   Python expression ``+o``.
+
+
+.. c:function:: PyObject* PyNumber_Absolute(PyObject *o)
+
+   .. index:: builtin: abs
+
+   Returns the absolute value of *o*, or *NULL* on failure.  This is the equivalent
+   of the Python expression ``abs(o)``.
+
+
+.. c:function:: PyObject* PyNumber_Invert(PyObject *o)
+
+   Returns the bitwise negation of *o* on success, or *NULL* on failure.  This is
+   the equivalent of the Python expression ``~o``.
+
+
+.. c:function:: PyObject* PyNumber_Lshift(PyObject *o1, PyObject *o2)
+
+   Returns the result of left shifting *o1* by *o2* on success, or *NULL* on
+   failure.  This is the equivalent of the Python expression ``o1 << o2``.
+
+
+.. c:function:: PyObject* PyNumber_Rshift(PyObject *o1, PyObject *o2)
+
+   Returns the result of right shifting *o1* by *o2* on success, or *NULL* on
+   failure.  This is the equivalent of the Python expression ``o1 >> o2``.
+
+
+.. c:function:: PyObject* PyNumber_And(PyObject *o1, PyObject *o2)
+
+   Returns the "bitwise and" of *o1* and *o2* on success and *NULL* on failure.
+   This is the equivalent of the Python expression ``o1 & o2``.
+
+
+.. c:function:: PyObject* PyNumber_Xor(PyObject *o1, PyObject *o2)
+
+   Returns the "bitwise exclusive or" of *o1* by *o2* on success, or *NULL* on
+   failure.  This is the equivalent of the Python expression ``o1 ^ o2``.
+
+
+.. c:function:: PyObject* PyNumber_Or(PyObject *o1, PyObject *o2)
+
+   Returns the "bitwise or" of *o1* and *o2* on success, or *NULL* on failure.
+   This is the equivalent of the Python expression ``o1 | o2``.
+
+
+.. c:function:: PyObject* PyNumber_InPlaceAdd(PyObject *o1, PyObject *o2)
+
+   Returns the result of adding *o1* and *o2*, or *NULL* on failure.  The operation
+   is done *in-place* when *o1* supports it.  This is the equivalent of the Python
+   statement ``o1 += o2``.
+
+
+.. c:function:: PyObject* PyNumber_InPlaceSubtract(PyObject *o1, PyObject *o2)
+
+   Returns the result of subtracting *o2* from *o1*, or *NULL* on failure.  The
+   operation is done *in-place* when *o1* supports it.  This is the equivalent of
+   the Python statement ``o1 -= o2``.
+
+
+.. c:function:: PyObject* PyNumber_InPlaceMultiply(PyObject *o1, PyObject *o2)
+
+   Returns the result of multiplying *o1* and *o2*, or *NULL* on failure.  The
+   operation is done *in-place* when *o1* supports it.  This is the equivalent of
+   the Python statement ``o1 *= o2``.
+
+
+.. c:function:: PyObject* PyNumber_InPlaceMatrixMultiply(PyObject *o1, PyObject *o2)
+
+   Returns the result of matrix multiplication on *o1* and *o2*, or *NULL* on
+   failure.  The operation is done *in-place* when *o1* supports it.  This is
+   the equivalent of the Python statement ``o1 @= o2``.
+
+   .. versionadded:: 3.5
+
+
+.. c:function:: PyObject* PyNumber_InPlaceFloorDivide(PyObject *o1, PyObject *o2)
+
+   Returns the mathematical floor of dividing *o1* by *o2*, or *NULL* on failure.
+   The operation is done *in-place* when *o1* supports it.  This is the equivalent
+   of the Python statement ``o1 //= o2``.
+
+
+.. c:function:: PyObject* PyNumber_InPlaceTrueDivide(PyObject *o1, PyObject *o2)
+
+   Return a reasonable approximation for the mathematical value of *o1* divided by
+   *o2*, or *NULL* on failure.  The return value is "approximate" because binary
+   floating point numbers are approximate; it is not possible to represent all real
+   numbers in base two.  This function can return a floating point value when
+   passed two integers.  The operation is done *in-place* when *o1* supports it.
+
+
+.. c:function:: PyObject* PyNumber_InPlaceRemainder(PyObject *o1, PyObject *o2)
+
+   Returns the remainder of dividing *o1* by *o2*, or *NULL* on failure.  The
+   operation is done *in-place* when *o1* supports it.  This is the equivalent of
+   the Python statement ``o1 %= o2``.
+
+
+.. c:function:: PyObject* PyNumber_InPlacePower(PyObject *o1, PyObject *o2, PyObject *o3)
+
+   .. index:: builtin: pow
+
+   See the built-in function :func:`pow`. Returns *NULL* on failure.  The operation
+   is done *in-place* when *o1* supports it.  This is the equivalent of the Python
+   statement ``o1 **= o2`` when o3 is :c:data:`Py_None`, or an in-place variant of
+   ``pow(o1, o2, o3)`` otherwise. If *o3* is to be ignored, pass :c:data:`Py_None`
+   in its place (passing *NULL* for *o3* would cause an illegal memory access).
+
+
+.. c:function:: PyObject* PyNumber_InPlaceLshift(PyObject *o1, PyObject *o2)
+
+   Returns the result of left shifting *o1* by *o2* on success, or *NULL* on
+   failure.  The operation is done *in-place* when *o1* supports it.  This is the
+   equivalent of the Python statement ``o1 <<= o2``.
+
+
+.. c:function:: PyObject* PyNumber_InPlaceRshift(PyObject *o1, PyObject *o2)
+
+   Returns the result of right shifting *o1* by *o2* on success, or *NULL* on
+   failure.  The operation is done *in-place* when *o1* supports it.  This is the
+   equivalent of the Python statement ``o1 >>= o2``.
+
+
+.. c:function:: PyObject* PyNumber_InPlaceAnd(PyObject *o1, PyObject *o2)
+
+   Returns the "bitwise and" of *o1* and *o2* on success and *NULL* on failure. The
+   operation is done *in-place* when *o1* supports it.  This is the equivalent of
+   the Python statement ``o1 &= o2``.
+
+
+.. c:function:: PyObject* PyNumber_InPlaceXor(PyObject *o1, PyObject *o2)
+
+   Returns the "bitwise exclusive or" of *o1* by *o2* on success, or *NULL* on
+   failure.  The operation is done *in-place* when *o1* supports it.  This is the
+   equivalent of the Python statement ``o1 ^= o2``.
+
+
+.. c:function:: PyObject* PyNumber_InPlaceOr(PyObject *o1, PyObject *o2)
+
+   Returns the "bitwise or" of *o1* and *o2* on success, or *NULL* on failure.  The
+   operation is done *in-place* when *o1* supports it.  This is the equivalent of
+   the Python statement ``o1 |= o2``.
+
+
+.. c:function:: PyObject* PyNumber_Long(PyObject *o)
+
+   .. index:: builtin: int
+
+   Returns the *o* converted to an integer object on success, or *NULL* on
+   failure.  This is the equivalent of the Python expression ``int(o)``.
+
+
+.. c:function:: PyObject* PyNumber_Float(PyObject *o)
+
+   .. index:: builtin: float
+
+   Returns the *o* converted to a float object on success, or *NULL* on failure.
+   This is the equivalent of the Python expression ``float(o)``.
+
+
+.. c:function:: PyObject* PyNumber_Index(PyObject *o)
+
+   Returns the *o* converted to a Python int on success or *NULL* with a
+   :exc:`TypeError` exception raised on failure.
+
+
+.. c:function:: PyObject* PyNumber_ToBase(PyObject *n, int base)
+
+   Returns the integer *n* converted to base *base* as a string.  The *base*
+   argument must be one of 2, 8, 10, or 16.  For base 2, 8, or 16, the
+   returned string is prefixed with a base marker of ``'0b'``, ``'0o'``, or
+   ``'0x'``, respectively.  If *n* is not a Python int, it is converted with
+   :c:func:`PyNumber_Index` first.
+
+
+.. c:function:: Py_ssize_t PyNumber_AsSsize_t(PyObject *o, PyObject *exc)
+
+   Returns *o* converted to a Py_ssize_t value if *o* can be interpreted as an
+   integer.  If the call fails, an exception is raised and ``-1`` is returned.
+
+   If *o* can be converted to a Python int but the attempt to
+   convert to a Py_ssize_t value would raise an :exc:`OverflowError`, then the
+   *exc* argument is the type of exception that will be raised (usually
+   :exc:`IndexError` or :exc:`OverflowError`).  If *exc* is *NULL*, then the
+   exception is cleared and the value is clipped to *PY_SSIZE_T_MIN* for a negative
+   integer or *PY_SSIZE_T_MAX* for a positive integer.
+
+
+.. c:function:: int PyIndex_Check(PyObject *o)
+
+   Returns ``1`` if *o* is an index integer (has the nb_index slot of  the
+   tp_as_number structure filled in), and ``0`` otherwise.
+   This function always succeeds.

third_party/python/Doc/c-api/objbuffer.rst

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

third_party/python/Doc/c-api/object.rst

@@ -0,0 +1,425 @@
+.. highlightlang:: c
+
+.. _object:
+
+Object Protocol
+===============
+
+
+.. c:var:: PyObject* Py_NotImplemented
+
+   The ``NotImplemented`` singleton, used to signal that an operation is
+   not implemented for the given type combination.
+
+
+.. 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).
+
+
+.. 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
+   instead of the :func:`repr`.
+
+
+.. c:function:: int PyObject_HasAttr(PyObject *o, PyObject *attr_name)
+
+   Returns ``1`` if *o* has the attribute *attr_name*, and ``0`` otherwise.  This
+   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.
+
+
+.. c:function:: int PyObject_HasAttrString(PyObject *o, const char *attr_name)
+
+   Returns ``1`` if *o* has the attribute *attr_name*, and ``0`` otherwise.  This
+   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.
+
+
+.. c:function:: PyObject* PyObject_GetAttr(PyObject *o, PyObject *attr_name)
+
+   Retrieve an attribute named *attr_name* from object *o*. Returns the attribute
+   value on success, or *NULL* on failure.  This is the equivalent of the Python
+   expression ``o.attr_name``.
+
+
+.. c:function:: PyObject* PyObject_GetAttrString(PyObject *o, const char *attr_name)
+
+   Retrieve an attribute named *attr_name* from object *o*. Returns the attribute
+   value on success, or *NULL* on failure. This is the equivalent of the Python
+   expression ``o.attr_name``.
+
+
+.. c:function:: PyObject* PyObject_GenericGetAttr(PyObject *o, PyObject *name)
+
+   Generic attribute getter function that is meant to be put into a type
+   object's ``tp_getattro`` slot.  It looks for a descriptor in the dictionary
+   of classes in the object's MRO as well as an attribute in the object's
+   :attr:`~object.__dict__` (if present).  As outlined in :ref:`descriptors`,
+   data descriptors take preference over instance attributes, while non-data
+   descriptors don't.  Otherwise, an :exc:`AttributeError` is raised.
+
+
+.. c:function:: int PyObject_SetAttr(PyObject *o, PyObject *attr_name, PyObject *v)
+
+   Set the value of the attribute named *attr_name*, for object *o*, to the value
+   *v*. Raise an exception and return ``-1`` on failure;
+   return ``0`` on success.  This is the equivalent of the Python statement
+   ``o.attr_name = v``.
+
+   If *v* is *NULL*, the attribute is deleted, however this feature is
+   deprecated in favour of using :c:func:`PyObject_DelAttr`.
+
+
+.. c:function:: int PyObject_SetAttrString(PyObject *o, const char *attr_name, PyObject *v)
+
+   Set the value of the attribute named *attr_name*, for object *o*, to the value
+   *v*. Raise an exception and return ``-1`` on failure;
+   return ``0`` on success.  This is the equivalent of the Python statement
+   ``o.attr_name = v``.
+
+   If *v* is *NULL*, the attribute is deleted, however this feature is
+   deprecated in favour of using :c:func:`PyObject_DelAttrString`.
+
+
+.. c:function:: int PyObject_GenericSetAttr(PyObject *o, PyObject *name, PyObject *value)
+
+   Generic attribute setter and deleter function that is meant
+   to be put into a type object's :c:member:`~PyTypeObject.tp_setattro`
+   slot.  It looks for a data descriptor in the
+   dictionary of classes in the object's MRO, and if found it takes preference
+   over setting or deleting the attribute in the instance dictionary. Otherwise, the
+   attribute is set or deleted in the object's :attr:`~object.__dict__` (if present).
+   On success, ``0`` is returned, otherwise an :exc:`AttributeError`
+   is raised and ``-1`` is returned.
+
+
+.. c:function:: int PyObject_DelAttr(PyObject *o, PyObject *attr_name)
+
+   Delete attribute named *attr_name*, for object *o*. Returns ``-1`` on failure.
+   This is the equivalent of the Python statement ``del o.attr_name``.
+
+
+.. c:function:: int PyObject_DelAttrString(PyObject *o, const char *attr_name)
+
+   Delete attribute named *attr_name*, for object *o*. Returns ``-1`` on failure.
+   This is the equivalent of the Python statement ``del o.attr_name``.
+
+
+.. c:function:: PyObject* PyObject_GenericGetDict(PyObject *o, void *context)
+
+   A generic implementation for the getter of a ``__dict__`` descriptor. It
+   creates the dictionary if necessary.
+
+   .. versionadded:: 3.3
+
+
+.. c:function:: int PyObject_GenericSetDict(PyObject *o, void *context)
+
+   A generic implementation for the setter of a ``__dict__`` descriptor. This
+   implementation does not allow the dictionary to be deleted.
+
+   .. versionadded:: 3.3
+
+
+.. 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 ``<``,
+   ``<=``, ``==``, ``!=``, ``>``, 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.
+
+
+.. 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 ``<``,
+   ``<=``, ``==``, ``!=``, ``>``, 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
+   *opid*.
+
+.. 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`.
+
+.. c:function:: PyObject* PyObject_Repr(PyObject *o)
+
+   .. index:: builtin: repr
+
+   Compute a string representation of object *o*.  Returns the string
+   representation on success, *NULL* on failure.  This is the equivalent of the
+   Python expression ``repr(o)``.  Called by the :func:`repr` built-in function.
+
+   .. versionchanged:: 3.4
+      This function now includes a debug assertion to help ensure that it
+      does not silently discard an active exception.
+
+.. c:function:: PyObject* PyObject_ASCII(PyObject *o)
+
+   .. index:: builtin: ascii
+
+   As :c:func:`PyObject_Repr`, compute a string representation of object *o*, but
+   escape the non-ASCII characters in the string returned by
+   :c:func:`PyObject_Repr` with ``\x``, ``\u`` or ``\U`` escapes.  This generates
+   a string similar to that returned by :c:func:`PyObject_Repr` in Python 2.
+   Called by the :func:`ascii` built-in function.
+
+   .. index:: string; PyObject_Str (C function)
+
+
+.. c:function:: PyObject* PyObject_Str(PyObject *o)
+
+   Compute a string representation of object *o*.  Returns the string
+   representation on success, *NULL* on failure.  This is the equivalent of the
+   Python expression ``str(o)``.  Called by the :func:`str` built-in function
+   and, therefore, by the :func:`print` function.
+
+   .. versionchanged:: 3.4
+      This function now includes a debug assertion to help ensure that it
+      does not silently discard an active exception.
+
+.. c:function:: PyObject* PyObject_Bytes(PyObject *o)
+
+   .. index:: builtin: bytes
+
+   Compute a bytes representation of object *o*.  *NULL* is returned on
+   failure and a bytes object on success.  This is equivalent to the Python
+   expression ``bytes(o)``, when *o* is not an integer.  Unlike ``bytes(o)``,
+   a TypeError is raised when *o* is an integer instead of a zero-initialized
+   bytes object.
+
+
+.. c:function:: int PyObject_IsSubclass(PyObject *derived, PyObject *cls)
+
+   Return ``1`` if the class *derived* is identical to or derived from the class
+   *cls*, otherwise return ``0``.  In case of an error, return ``-1``.
+
+   If *cls* is a tuple, the check will be done against every entry in *cls*.
+   The result will be ``1`` when at least one of the checks returns ``1``,
+   otherwise it will be ``0``.
+
+   If *cls* has a :meth:`~class.__subclasscheck__` method, it will be called to
+   determine the subclass status as described in :pep:`3119`.  Otherwise,
+   *derived* is a subclass of *cls* if it is a direct or indirect subclass,
+   i.e. contained in ``cls.__mro__``.
+
+   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).
+
+
+.. c:function:: int PyObject_IsInstance(PyObject *inst, PyObject *cls)
+
+   Return ``1`` if *inst* is an instance of the class *cls* or a subclass of
+   *cls*, or ``0`` if not.  On error, returns ``-1`` and sets an exception.
+
+   If *cls* is a tuple, the check will be done against every entry in *cls*.
+   The result will be ``1`` when at least one of the checks returns ``1``,
+   otherwise it will be ``0``.
+
+   If *cls* has a :meth:`~class.__instancecheck__` method, it will be called to
+   determine the subclass status as described in :pep:`3119`.  Otherwise, *inst*
+   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.
+
+   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
+   of base classes).
+
+
+.. c:function:: int PyCallable_Check(PyObject *o)
+
+   Determine if the object *o* is callable.  Return ``1`` if the object is callable
+   and ``0`` otherwise.  This function always succeeds.
+
+
+.. c:function:: PyObject* PyObject_Call(PyObject *callable_object, PyObject *args, PyObject *kw)
+
+   Call a callable Python object *callable_object*, with arguments given by the
+   tuple *args*, and named arguments given by the dictionary *kw*. If no named
+   arguments are needed, *kw* may be *NULL*. *args* must not be *NULL*, use an
+   empty tuple if no arguments are needed. Returns the result of the call on
+   success, or *NULL* on failure.  This is the equivalent of the Python expression
+   ``callable_object(*args, **kw)``.
+
+
+.. c:function:: PyObject* PyObject_CallObject(PyObject *callable_object, PyObject *args)
+
+   Call a callable Python object *callable_object*, with arguments given by the
+   tuple *args*.  If no arguments are needed, then *args* may be *NULL*.  Returns
+   the result of the call on success, or *NULL* on failure.  This is the equivalent
+   of the Python expression ``callable_object(*args)``.
+
+
+.. c:function:: PyObject* PyObject_CallFunction(PyObject *callable, const char *format, ...)
+
+   Call a callable Python object *callable*, with a variable number of C arguments.
+   The C arguments are described using a :c:func:`Py_BuildValue` style format
+   string.  The format may be *NULL*, indicating that no arguments are provided.
+   Returns the result of the call on success, or *NULL* on failure.  This is the
+   equivalent of the Python expression ``callable(*args)``. Note that if you only
+   pass :c:type:`PyObject \*` args, :c:func:`PyObject_CallFunctionObjArgs` is a
+   faster alternative.
+
+   .. versionchanged:: 3.4
+      The type of *format* was changed from ``char *``.
+
+
+.. c:function:: PyObject* PyObject_CallMethod(PyObject *o, const char *method, const char *format, ...)
+
+   Call the method named *method* of object *o* with a variable number of C
+   arguments.  The C arguments are described by a :c:func:`Py_BuildValue` format
+   string that should  produce a tuple.  The format may be *NULL*, indicating that
+   no arguments are provided. Returns the result of the call on success, or *NULL*
+   on failure.  This is the equivalent of the Python expression ``o.method(args)``.
+   Note that if you only pass :c:type:`PyObject \*` args,
+   :c:func:`PyObject_CallMethodObjArgs` is a faster alternative.
+
+   .. versionchanged:: 3.4
+      The types of *method* and *format* were changed from ``char *``.
+
+
+.. c:function:: PyObject* PyObject_CallFunctionObjArgs(PyObject *callable, ..., NULL)
+
+   Call a callable Python object *callable*, with a variable number of
+   :c:type:`PyObject\*` arguments.  The arguments are provided as a variable number
+   of parameters followed by *NULL*. Returns the result of the call on success, or
+   *NULL* on failure.
+
+
+.. c:function:: PyObject* PyObject_CallMethodObjArgs(PyObject *o, PyObject *name, ..., NULL)
+
+   Calls a method of the object *o*, where the name of the method is given as a
+   Python string object in *name*.  It is called with a variable number of
+   :c:type:`PyObject\*` arguments.  The arguments are provided as a variable number
+   of parameters followed by *NULL*. Returns the result of the call on success, or
+   *NULL* on failure.
+
+
+.. c:function:: Py_hash_t PyObject_Hash(PyObject *o)
+
+   .. index:: builtin: hash
+
+   Compute and return the hash value of an object *o*.  On failure, return ``-1``.
+   This is the equivalent of the Python expression ``hash(o)``.
+
+   .. versionchanged:: 3.2
+      The return type is now Py_hash_t.  This is a signed integer the same size
+      as Py_ssize_t.
+
+
+.. c:function:: Py_hash_t PyObject_HashNotImplemented(PyObject *o)
+
+   Set a :exc:`TypeError` indicating that ``type(o)`` is not hashable and return ``-1``.
+   This function receives special treatment when stored in a ``tp_hash`` slot,
+   allowing a type to explicitly indicate to the interpreter that it is not
+   hashable.
+
+
+.. c:function:: int PyObject_IsTrue(PyObject *o)
+
+   Returns ``1`` if the object *o* is considered to be true, and ``0`` otherwise.
+   This is equivalent to the Python expression ``not not o``.  On failure, return
+   ``-1``.
+
+
+.. c:function:: int PyObject_Not(PyObject *o)
+
+   Returns ``0`` if the object *o* is considered to be true, and ``1`` otherwise.
+   This is equivalent to the Python expression ``not o``.  On failure, return
+   ``-1``.
+
+
+.. c:function:: PyObject* PyObject_Type(PyObject *o)
+
+   .. index:: builtin: type
+
+   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
+   function instead of the common expression ``o->ob_type``, which returns a
+   pointer of type :c:type:`PyTypeObject\*`, except when the incremented reference
+   count is needed.
+
+
+.. c:function:: int PyObject_TypeCheck(PyObject *o, PyTypeObject *type)
+
+   Return true if the object *o* is of type *type* or a subtype of *type*.  Both
+   parameters must be non-*NULL*.
+
+
+.. c:function:: Py_ssize_t PyObject_Size(PyObject *o)
+               Py_ssize_t PyObject_Length(PyObject *o)
+
+   .. index:: builtin: len
+
+   Return the length of object *o*.  If the object *o* provides either the sequence
+   and mapping protocols, the sequence length is returned.  On error, ``-1`` is
+   returned.  This is the equivalent to the Python expression ``len(o)``.
+
+
+.. c:function:: Py_ssize_t PyObject_LengthHint(PyObject *o, Py_ssize_t default)
+
+   Return an estimated length for the object *o*. First try to return its
+   actual length, then an estimate using :meth:`~object.__length_hint__`, and
+   finally return the default value. On error return ``-1``. This is the
+   equivalent to the Python expression ``operator.length_hint(o, default)``.
+
+   .. versionadded:: 3.4
+
+
+.. c:function:: PyObject* PyObject_GetItem(PyObject *o, PyObject *key)
+
+   Return element of *o* corresponding to the object *key* or *NULL* on failure.
+   This is the equivalent of the Python expression ``o[key]``.
+
+
+.. c:function:: int PyObject_SetItem(PyObject *o, PyObject *key, PyObject *v)
+
+   Map the object *key* to the value *v*.  Raise an exception and
+   return ``-1`` on failure; return ``0`` on success.  This is the
+   equivalent of the Python statement ``o[key] = v``.
+
+
+.. c:function:: int PyObject_DelItem(PyObject *o, PyObject *key)
+
+   Remove the mapping for the object *key* from the object *o*.  Return ``-1``
+   on failure.  This is equivalent to the Python statement ``del o[key]``.
+
+
+.. c:function:: PyObject* PyObject_Dir(PyObject *o)
+
+   This is equivalent to the Python expression ``dir(o)``, returning a (possibly
+   empty) list of strings appropriate for the object argument, or *NULL* if there
+   was an error.  If the argument is *NULL*, this is like the Python ``dir()``,
+   returning the names of the current locals; in this case, if no execution frame
+   is active then *NULL* is returned but :c:func:`PyErr_Occurred` will return false.
+
+
+.. c:function:: PyObject* PyObject_GetIter(PyObject *o)
+
+   This is equivalent to the Python expression ``iter(o)``. It returns a new
+   iterator for the object argument, or the object  itself if the object is already
+   an iterator.  Raises :exc:`TypeError` and returns *NULL* if the object cannot be
+   iterated.

third_party/python/Doc/c-api/objimpl.rst

@@ -0,0 +1,17 @@
+.. highlightlang:: c
+
+.. _newtypes:
+
+*****************************
+Object Implementation Support
+*****************************
+
+This chapter describes the functions, types, and macros used when defining new
+object types.
+
+.. toctree::
+
+   allocation.rst
+   structures.rst
+   typeobj.rst
+   gcsupport.rst

third_party/python/Doc/c-api/refcounting.rst

@@ -0,0 +1,73 @@
+.. highlightlang:: c
+
+
+.. _countingrefs:
+
+******************
+Reference Counting
+******************
+
+The macros in this section are used for managing reference counts of Python
+objects.
+
+
+.. c:function:: void Py_INCREF(PyObject *o)
+
+   Increment the reference count for object *o*.  The object must not be *NULL*; if
+   you aren't sure that it isn't *NULL*, use :c:func:`Py_XINCREF`.
+
+
+.. 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.
+
+
+.. c:function:: void Py_DECREF(PyObject *o)
+
+   Decrement the reference count for object *o*.  The object must not be *NULL*; if
+   you aren't sure that it isn't *NULL*, use :c:func:`Py_XDECREF`.  If the reference
+   count reaches zero, the object's type's deallocation function (which must not be
+   *NULL*) is invoked.
+
+   .. 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
+      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
+      invoked.  For example, code to delete an object from a list should copy a
+      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.
+
+
+.. 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.
+
+
+.. c:function:: void Py_CLEAR(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`, 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.
+
+   It is a good idea to use this macro whenever decrementing the value of a
+   variable that might be traversed during garbage collection.
+
+
+The following functions are for runtime dynamic embedding of Python:
+``Py_IncRef(PyObject *o)``, ``Py_DecRef(PyObject *o)``. They are
+simply exported function versions of :c:func:`Py_XINCREF` and
+:c:func:`Py_XDECREF`, respectively.
+
+The following functions or macros are only for use within the interpreter core:
+:c:func:`_Py_Dealloc`, :c:func:`_Py_ForgetReference`, :c:func:`_Py_NewReference`,
+as well as the global variable :c:data:`_Py_RefTotal`.
+

third_party/python/Doc/c-api/reflection.rst

@@ -0,0 +1,49 @@
+.. highlightlang:: c
+
+.. _reflection:
+
+Reflection
+==========
+
+.. c:function:: PyObject* PyEval_GetBuiltins()
+
+   Return a dictionary of the builtins in the current execution frame,
+   or the interpreter of the thread state if no frame is currently executing.
+
+
+.. c:function:: PyObject* PyEval_GetLocals()
+
+   Return a dictionary of the local variables in the current execution frame,
+   or *NULL* if no frame is currently executing.
+
+
+.. c:function:: PyObject* PyEval_GetGlobals()
+
+   Return a dictionary of the global variables in the current execution frame,
+   or *NULL* if no frame is currently executing.
+
+
+.. c:function:: PyFrameObject* PyEval_GetFrame()
+
+   Return the current thread state's frame, which is *NULL* if no frame is
+   currently executing.
+
+
+.. c:function:: int PyFrame_GetLineNumber(PyFrameObject *frame)
+
+   Return the line number that *frame* is currently executing.
+
+
+.. c:function:: const char* PyEval_GetFuncName(PyObject *func)
+
+   Return the name of *func* if it is a function, class or instance object, else the
+   name of *func*\s type.
+
+
+.. c:function:: const char* PyEval_GetFuncDesc(PyObject *func)
+
+   Return a description string, depending on the type of *func*.
+   Return values include "()" for functions and methods, " constructor",
+   " instance", and " object".  Concatenated with the result of
+   :c:func:`PyEval_GetFuncName`, the result will be a description of
+   *func*.

third_party/python/Doc/c-api/sequence.rst

@@ -0,0 +1,169 @@
+.. highlightlang:: c
+
+.. _sequence:
+
+Sequence Protocol
+=================
+
+
+.. c:function:: int PySequence_Check(PyObject *o)
+
+   Return ``1`` if the object provides sequence protocol, and ``0`` otherwise.
+   Note that it returns ``1`` for Python classes with a :meth:`__getitem__`
+   method unless they are :class:`dict` subclasses since in general case it
+   is impossible to determine what the type of keys it supports.  This
+   function always succeeds.
+
+
+.. c:function:: Py_ssize_t PySequence_Size(PyObject *o)
+               Py_ssize_t PySequence_Length(PyObject *o)
+
+   .. index:: builtin: len
+
+   Returns the number of objects in sequence *o* on success, and ``-1`` on
+   failure.  This is equivalent to the Python expression ``len(o)``.
+
+
+.. c:function:: PyObject* PySequence_Concat(PyObject *o1, PyObject *o2)
+
+   Return the concatenation of *o1* and *o2* on success, and *NULL* on failure.
+   This is the equivalent of the Python expression ``o1 + o2``.
+
+
+.. c:function:: PyObject* PySequence_Repeat(PyObject *o, Py_ssize_t count)
+
+   Return the result of repeating sequence object *o* *count* times, or *NULL* on
+   failure.  This is the equivalent of the Python expression ``o * count``.
+
+
+.. c:function:: PyObject* PySequence_InPlaceConcat(PyObject *o1, PyObject *o2)
+
+   Return the concatenation of *o1* and *o2* on success, and *NULL* on failure.
+   The operation is done *in-place* when *o1* supports it.  This is the equivalent
+   of the Python expression ``o1 += o2``.
+
+
+.. c:function:: PyObject* PySequence_InPlaceRepeat(PyObject *o, Py_ssize_t count)
+
+   Return the result of repeating sequence object *o* *count* times, or *NULL* on
+   failure.  The operation is done *in-place* when *o* supports it.  This is the
+   equivalent of the Python expression ``o *= count``.
+
+
+.. c:function:: PyObject* PySequence_GetItem(PyObject *o, Py_ssize_t i)
+
+   Return the *i*\ th element of *o*, or *NULL* on failure. This is the equivalent of
+   the Python expression ``o[i]``.
+
+
+.. c:function:: PyObject* PySequence_GetSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2)
+
+   Return the slice of sequence object *o* between *i1* and *i2*, or *NULL* on
+   failure. This is the equivalent of the Python expression ``o[i1:i2]``.
+
+
+.. c:function:: int PySequence_SetItem(PyObject *o, Py_ssize_t i, PyObject *v)
+
+   Assign object *v* to the *i*\ th element of *o*.  Raise an exception
+   and return ``-1`` on failure; return ``0`` on success.  This
+   is the equivalent of the Python statement ``o[i] = v``.  This function *does
+   not* steal a reference to *v*.
+
+   If *v* is *NULL*, the element is deleted, however this feature is
+   deprecated in favour of using :c:func:`PySequence_DelItem`.
+
+
+.. c:function:: int PySequence_DelItem(PyObject *o, Py_ssize_t i)
+
+   Delete the *i*\ th element of object *o*.  Returns ``-1`` on failure.  This is the
+   equivalent of the Python statement ``del o[i]``.
+
+
+.. c:function:: int PySequence_SetSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2, PyObject *v)
+
+   Assign the sequence object *v* to the slice in sequence object *o* from *i1* to
+   *i2*.  This is the equivalent of the Python statement ``o[i1:i2] = v``.
+
+
+.. c:function:: int PySequence_DelSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2)
+
+   Delete the slice in sequence object *o* from *i1* to *i2*.  Returns ``-1`` on
+   failure.  This is the equivalent of the Python statement ``del o[i1:i2]``.
+
+
+.. c:function:: Py_ssize_t PySequence_Count(PyObject *o, PyObject *value)
+
+   Return the number of occurrences of *value* in *o*, that is, return the number
+   of keys for which ``o[key] == value``.  On failure, return ``-1``.  This is
+   equivalent to the Python expression ``o.count(value)``.
+
+
+.. c:function:: int PySequence_Contains(PyObject *o, PyObject *value)
+
+   Determine if *o* contains *value*.  If an item in *o* is equal to *value*,
+   return ``1``, otherwise return ``0``. On error, return ``-1``.  This is
+   equivalent to the Python expression ``value in o``.
+
+
+.. c:function:: Py_ssize_t PySequence_Index(PyObject *o, PyObject *value)
+
+   Return the first index *i* for which ``o[i] == value``.  On error, return
+   ``-1``.    This is equivalent to the Python expression ``o.index(value)``.
+
+
+.. c:function:: PyObject* PySequence_List(PyObject *o)
+
+   Return a list object with the same contents as the sequence or iterable *o*,
+   or *NULL* on failure.  The returned list is guaranteed to be new.  This is
+   equivalent to the Python expression ``list(o)``.
+
+
+.. c:function:: PyObject* PySequence_Tuple(PyObject *o)
+
+   .. index:: builtin: tuple
+
+   Return a tuple object with the same contents as the sequence or iterable *o*,
+   or *NULL* on failure.  If *o* is a tuple, a new reference will be returned,
+   otherwise a tuple will be constructed with the appropriate contents.  This is
+   equivalent to the Python expression ``tuple(o)``.
+
+
+.. c:function:: PyObject* PySequence_Fast(PyObject *o, const char *m)
+
+   Return the sequence or iterable *o* as a list, unless it is already a tuple or list, in
+   which case *o* is returned.  Use :c:func:`PySequence_Fast_GET_ITEM` to access
+   the members of the result.  Returns *NULL* on failure.  If the object is not
+   a sequence or iterable, raises :exc:`TypeError` with *m* as the message text.
+
+
+.. c:function:: Py_ssize_t PySequence_Fast_GET_SIZE(PyObject *o)
+
+   Returns the length of *o*, assuming that *o* was returned by
+   :c:func:`PySequence_Fast` and that *o* is not *NULL*.  The size can also be
+   gotten by calling :c:func:`PySequence_Size` on *o*, but
+   :c:func:`PySequence_Fast_GET_SIZE` is faster because it can assume *o* is a list
+   or tuple.
+
+
+.. c:function:: PyObject* PySequence_Fast_GET_ITEM(PyObject *o, Py_ssize_t i)
+
+   Return the *i*\ th element of *o*, assuming that *o* was returned by
+   :c:func:`PySequence_Fast`, *o* is not *NULL*, and that *i* is within bounds.
+
+
+.. c:function:: PyObject** PySequence_Fast_ITEMS(PyObject *o)
+
+   Return the underlying array of PyObject pointers.  Assumes that *o* was returned
+   by :c:func:`PySequence_Fast` and *o* is not *NULL*.
+
+   Note, if a list gets resized, the reallocation may relocate the items array.
+   So, only use the underlying array pointer in contexts where the sequence
+   cannot change.
+
+
+.. c:function:: PyObject* PySequence_ITEM(PyObject *o, Py_ssize_t i)
+
+   Return the *i*\ th element of *o* or *NULL* on failure. Macro form of
+   :c:func:`PySequence_GetItem` but without checking that
+   :c:func:`PySequence_Check` on *o* is true and without adjustment for negative
+   indices.

third_party/python/Doc/c-api/set.rst

@@ -0,0 +1,166 @@
+.. highlightlang:: c
+
+.. _setobjects:
+
+Set Objects
+-----------
+
+.. sectionauthor:: Raymond D. Hettinger <python@rcn.com>
+
+
+.. index::
+   object: set
+   object: frozenset
+
+This section details the public API for :class:`set` and :class:`frozenset`
+objects.  Any functionality not listed below is best accessed using the either
+the abstract object protocol (including :c:func:`PyObject_CallMethod`,
+:c:func:`PyObject_RichCompareBool`, :c:func:`PyObject_Hash`,
+:c:func:`PyObject_Repr`, :c:func:`PyObject_IsTrue`, :c:func:`PyObject_Print`, and
+:c:func:`PyObject_GetIter`) or the abstract number protocol (including
+:c:func:`PyNumber_And`, :c:func:`PyNumber_Subtract`, :c:func:`PyNumber_Or`,
+:c:func:`PyNumber_Xor`, :c:func:`PyNumber_InPlaceAnd`,
+:c:func:`PyNumber_InPlaceSubtract`, :c:func:`PyNumber_InPlaceOr`, and
+:c:func:`PyNumber_InPlaceXor`).
+
+
+.. c:type:: PySetObject
+
+   This subtype of :c:type:`PyObject` is used to hold the internal data for both
+   :class:`set` and :class:`frozenset` objects.  It is like a :c:type:`PyDictObject`
+   in that it is a fixed size for small sets (much like tuple storage) and will
+   point to a separate, variable sized block of memory for medium and large sized
+   sets (much like list storage). None of the fields of this structure should be
+   considered public and are subject to change.  All access should be done through
+   the documented API rather than by manipulating the values in the structure.
+
+
+.. c:var:: PyTypeObject PySet_Type
+
+   This is an instance of :c:type:`PyTypeObject` representing the Python
+   :class:`set` type.
+
+
+.. c:var:: PyTypeObject PyFrozenSet_Type
+
+   This is an instance of :c:type:`PyTypeObject` representing the Python
+   :class:`frozenset` type.
+
+The following type check macros work on pointers to any Python object. Likewise,
+the constructor functions work with any iterable Python object.
+
+
+.. c:function:: int PySet_Check(PyObject *p)
+
+   Return true if *p* is a :class:`set` object or an instance of a subtype.
+
+.. c:function:: int PyFrozenSet_Check(PyObject *p)
+
+   Return true if *p* is a :class:`frozenset` object or an instance of a
+   subtype.
+
+.. c:function:: int PyAnySet_Check(PyObject *p)
+
+   Return true if *p* is a :class:`set` object, a :class:`frozenset` object, or an
+   instance of a subtype.
+
+
+.. c:function:: int PyAnySet_CheckExact(PyObject *p)
+
+   Return true if *p* is a :class:`set` object or a :class:`frozenset` object but
+   not an instance of a subtype.
+
+
+.. c:function:: int PyFrozenSet_CheckExact(PyObject *p)
+
+   Return true if *p* is a :class:`frozenset` object but not an instance of a
+   subtype.
+
+
+.. c:function:: PyObject* PySet_New(PyObject *iterable)
+
+   Return a new :class:`set` containing objects returned by the *iterable*.  The
+   *iterable* may be *NULL* to create a new empty set.  Return the new set on
+   success or *NULL* on failure.  Raise :exc:`TypeError` if *iterable* is not
+   actually iterable.  The constructor is also useful for copying a set
+   (``c=set(s)``).
+
+
+.. c:function:: PyObject* PyFrozenSet_New(PyObject *iterable)
+
+   Return a new :class:`frozenset` containing objects returned by the *iterable*.
+   The *iterable* may be *NULL* to create a new empty frozenset.  Return the new
+   set on success or *NULL* on failure.  Raise :exc:`TypeError` if *iterable* is
+   not actually iterable.
+
+
+The following functions and macros are available for instances of :class:`set`
+or :class:`frozenset` or instances of their subtypes.
+
+
+.. c:function:: Py_ssize_t PySet_Size(PyObject *anyset)
+
+   .. index:: builtin: 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
+   :class:`set`, :class:`frozenset`, or an instance of a subtype.
+
+
+.. c:function:: Py_ssize_t PySet_GET_SIZE(PyObject *anyset)
+
+   Macro form of :c:func:`PySet_Size` without error checking.
+
+
+.. 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
+   convert unhashable sets into temporary frozensets.  Raise a :exc:`TypeError` if
+   the *key* is unhashable. Raise :exc:`PyExc_SystemError` if *anyset* is not a
+   :class:`set`, :class:`frozenset`, or an instance of a subtype.
+
+
+.. c:function:: int PySet_Add(PyObject *set, PyObject *key)
+
+   Add *key* to a :class:`set` instance.  Also works with :class:`frozenset`
+   instances (like :c:func:`PyTuple_SetItem` it can be used to fill-in the values
+   of brand new frozensets before they are exposed to other code).  Return ``0`` on
+   success or ``-1`` on failure. Raise a :exc:`TypeError` if the *key* is
+   unhashable. Raise a :exc:`MemoryError` if there is no room to grow.  Raise a
+   :exc:`SystemError` if *set* is not an instance of :class:`set` or its
+   subtype.
+
+
+The following functions are available for instances of :class:`set` or its
+subtypes but not for instances of :class:`frozenset` or its subtypes.
+
+
+.. c:function:: int PySet_Discard(PyObject *set, PyObject *key)
+
+   Return ``1`` if found and removed, ``0`` if not found (no action taken), and ``-1`` if an
+   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
+   instance of :class:`set` or its subtype.
+
+
+.. c:function:: PyObject* PySet_Pop(PyObject *set)
+
+   Return a new reference to an arbitrary object in the *set*, and removes the
+   object from the *set*.  Return *NULL* on failure.  Raise :exc:`KeyError` if the
+   set is empty. Raise a :exc:`SystemError` if *set* is not an instance of
+   :class:`set` or its subtype.
+
+
+.. c:function:: int PySet_Clear(PyObject *set)
+
+   Empty an existing set of all elements.
+
+
+.. c:function:: int PySet_ClearFreeList()
+
+   Clear the free list. Return the total number of freed items.
+
+   .. versionadded:: 3.3

third_party/python/Doc/c-api/slice.rst

@@ -0,0 +1,69 @@
+.. highlightlang:: c
+
+.. _slice-objects:
+
+Slice Objects
+-------------
+
+
+.. c:var:: PyTypeObject PySlice_Type
+
+   The type object for slice objects.  This is the same as :class:`slice` in the
+   Python layer.
+
+
+.. c:function:: int PySlice_Check(PyObject *ob)
+
+   Return true if *ob* is a slice object; *ob* must not be *NULL*.
+
+
+.. c:function:: PyObject* PySlice_New(PyObject *start, PyObject *stop, PyObject *step)
+
+   Return a new slice object with the given values.  The *start*, *stop*, and
+   *step* parameters are used as the values of the slice object attributes of
+   the same names.  Any of the values may be *NULL*, in which case the
+   ``None`` will be used for the corresponding attribute.  Return *NULL* if
+   the new object could not be allocated.
+
+
+.. c:function:: int PySlice_GetIndices(PyObject *slice, Py_ssize_t length, Py_ssize_t *start, Py_ssize_t *stop, Py_ssize_t *step)
+
+   Retrieve the start, stop and step indices from the slice object *slice*,
+   assuming a sequence of length *length*. Treats indices greater than
+   *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,
+   in which case ``-1`` is returned with an exception set).
+
+   You probably do not want to use this function.
+
+   .. versionchanged:: 3.2
+      The parameter type for the *slice* parameter was ``PySliceObject*``
+      before.
+
+
+.. c:function:: int PySlice_GetIndicesEx(PyObject *slice, Py_ssize_t length, Py_ssize_t *start, Py_ssize_t *stop, Py_ssize_t *step, Py_ssize_t *slicelength)
+
+   Usable replacement for :c:func:`PySlice_GetIndices`.  Retrieve the start,
+   stop, and step indices from the slice object *slice* assuming a sequence of
+   length *length*, and store the length of the slice in *slicelength*.  Out
+   of bounds indices are clipped in a manner consistent with the handling of
+   normal slices.
+
+   Returns ``0`` on success and ``-1`` on error with exception set.
+
+   .. versionchanged:: 3.2
+      The parameter type for the *slice* parameter was ``PySliceObject*``
+      before.
+
+
+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.

third_party/python/Doc/c-api/stable.rst

@@ -0,0 +1,38 @@
+.. highlightlang:: c
+
+.. _stable:
+
+***********************************
+Stable Application Binary Interface
+***********************************
+
+Traditionally, the C API of Python will change with every release.  Most changes
+will be source-compatible, typically by only adding API, rather than changing
+existing API or removing API (although some interfaces do get removed after
+being deprecated first).
+
+Unfortunately, the API compatibility does not extend to binary compatibility
+(the ABI). The reason is primarily the evolution of struct definitions, where
+addition of a new field, or changing the type of a field, might not break the
+API, but can break the ABI.  As a consequence, extension modules need to be
+recompiled for every Python release (although an exception is possible on Unix
+when none of the affected interfaces are used). In addition, on Windows,
+extension modules link with a specific pythonXY.dll and need to be recompiled to
+link with a newer one.
+
+Since Python 3.2, a subset of the API has been declared to guarantee a stable
+ABI. Extension modules wishing to use this API (called "limited API") need to
+define ``Py_LIMITED_API``. A number of interpreter details then become hidden
+from the extension module; in return, a module is built that works on any 3.x
+version (x>=2) without recompilation.
+
+In some cases, the stable ABI needs to be extended with new functions.
+Extension modules wishing to use these new APIs need to set ``Py_LIMITED_API``
+to the ``PY_VERSION_HEX`` value (see :ref:`apiabiversion`) of the minimum Python
+version they want to support (e.g. ``0x03030000`` for Python 3.3). Such modules
+will work on all subsequent Python releases, but fail to load (because of
+missing symbols) on the older releases.
+
+As of Python 3.2, the set of functions available to the limited API is
+documented in :pep:`384`.  In the C API documentation, API elements that are not
+part of the limited API are marked as "Not part of the limited API."

third_party/python/Doc/c-api/structures.rst

@@ -0,0 +1,337 @@
+.. highlightlang:: c
+
+.. _common-structs:
+
+Common Object Structures
+========================
+
+There are a large number of structures which are used in the definition of
+object types for Python.  This section describes these structures and how they
+are used.
+
+All Python objects ultimately share a small number of fields at the beginning
+of the object's representation in memory.  These are represented by the
+:c:type:`PyObject` and :c:type:`PyVarObject` types, which are defined, in turn,
+by the expansions of some macros also used, whether directly or indirectly, in
+the definition of all other Python objects.
+
+
+.. c:type:: PyObject
+
+   All object types are extensions of this type.  This is a type which
+   contains the information Python needs to treat a pointer to an object as an
+   object.  In a normal "release" build, it contains only the object's
+   reference count and a pointer to the corresponding type object.
+   Nothing is actually declared to be a :c:type:`PyObject`, but every pointer
+   to a Python object can be cast to a :c:type:`PyObject*`.  Access to the
+   members must be done by using the macros :c:macro:`Py_REFCNT` and
+   :c:macro:`Py_TYPE`.
+
+
+.. c:type:: PyVarObject
+
+   This is an extension of :c:type:`PyObject` that adds the :attr:`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
+   :c:macro:`Py_REFCNT`, :c:macro:`Py_TYPE`, and :c:macro:`Py_SIZE`.
+
+
+.. c:macro:: PyObject_HEAD
+
+   This is a macro used when declaring new types which represent objects
+   without a varying length.  The PyObject_HEAD macro expands to::
+
+      PyObject ob_base;
+
+   See documentation of :c:type:`PyObject` above.
+
+
+.. c:macro:: PyObject_VAR_HEAD
+
+   This is a macro used when declaring new types which represent objects
+   with a length that varies from instance to instance.
+   The PyObject_VAR_HEAD macro expands to::
+
+      PyVarObject ob_base;
+
+   See documentation of :c:type:`PyVarObject` above.
+
+
+.. c:macro:: Py_TYPE(o)
+
+   This macro is used to access the :attr:`ob_type` member of a Python object.
+   It expands to::
+
+      (((PyObject*)(o))->ob_type)
+
+
+.. c:macro:: Py_REFCNT(o)
+
+   This macro is used to access the :attr:`ob_refcnt` member of a Python
+   object.
+   It expands to::
+
+      (((PyObject*)(o))->ob_refcnt)
+
+
+.. c:macro:: Py_SIZE(o)
+
+   This macro is used to access the :attr:`ob_size` member of a Python object.
+   It expands to::
+
+      (((PyVarObject*)(o))->ob_size)
+
+
+.. c:macro:: PyObject_HEAD_INIT(type)
+
+   This is a macro which expands to initialization values for a new
+   :c:type:`PyObject` type.  This macro expands to::
+
+      _PyObject_EXTRA_INIT
+      1, type,
+
+
+.. 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.
+   This macro expands to::
+
+      _PyObject_EXTRA_INIT
+      1, type, size,
+
+
+.. c:type:: PyCFunction
+
+   Type of the functions used to implement most Python callables in C.
+   Functions of this type take two :c:type:`PyObject\*` parameters and return
+   one such value.  If the return value is *NULL*, an exception shall have
+   been set.  If not *NULL*, the return value is interpreted as the return
+   value of the function as exposed in Python.  The function must return a new
+   reference.
+
+
+.. c:type:: PyCFunctionWithKeywords
+
+   Type of the functions used to implement Python callables in C that take
+   keyword arguments: they take three :c:type:`PyObject\*` parameters and return
+   one such value.  See :c:type:`PyCFunction` above for the meaning of the return
+   value.
+
+
+.. c:type:: PyMethodDef
+
+   Structure used to describe a method of an extension type.  This structure has
+   four fields:
+
+   +------------------+-------------+-------------------------------+
+   | Field            | C Type      | Meaning                       |
+   +==================+=============+===============================+
+   | :attr:`ml_name`  | char \*     | name of the method            |
+   +------------------+-------------+-------------------------------+
+   | :attr:`ml_meth`  | PyCFunction | pointer to the C              |
+   |                  |             | implementation                |
+   +------------------+-------------+-------------------------------+
+   | :attr:`ml_flags` | int         | flag bits indicating how the  |
+   |                  |             | call should be constructed    |
+   +------------------+-------------+-------------------------------+
+   | :attr:`ml_doc`   | char \*     | points to the contents of the |
+   |                  |             | docstring                     |
+   +------------------+-------------+-------------------------------+
+
+The :attr:`ml_meth` is a C function pointer.  The functions may be of different
+types, but they always return :c:type:`PyObject\*`.  If the function is not of
+the :c:type:`PyCFunction`, the compiler will require a cast in the method table.
+Even though :c:type:`PyCFunction` defines the first parameter as
+:c:type:`PyObject\*`, it is common that the method implementation uses the
+specific C type of the *self* object.
+
+The :attr:`ml_flags` field is a bitfield which can include the following flags.
+The individual flags indicate either a calling convention or a binding
+convention.  Of the calling convention flags, only :const:`METH_VARARGS` and
+:const:`METH_KEYWORDS` can be combined. Any of the calling convention flags
+can be combined with a binding flag.
+
+
+.. data:: METH_VARARGS
+
+   This is the typical calling convention, where the methods have the type
+   :c:type:`PyCFunction`. The function expects two :c:type:`PyObject\*` values.
+   The first one is the *self* object for methods; for module functions, it is
+   the module object.  The second parameter (often called *args*) is a tuple
+   object representing all arguments. This parameter is typically processed
+   using :c:func:`PyArg_ParseTuple` or :c:func:`PyArg_UnpackTuple`.
+
+
+.. data:: METH_KEYWORDS
+
+   Methods with these flags must be of type :c:type:`PyCFunctionWithKeywords`.
+   The function expects three parameters: *self*, *args*, and a dictionary of
+   all the keyword arguments.  The flag must be combined with
+   :const:`METH_VARARGS`, and the parameters are typically processed using
+   :c:func:`PyArg_ParseTupleAndKeywords`.
+
+
+.. data:: 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
+   :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*.
+
+
+.. data:: METH_O
+
+   Methods with a single object argument can be listed with the :const:`METH_O`
+   flag, instead of invoking :c:func:`PyArg_ParseTuple` with a ``"O"`` argument.
+   They have the type :c:type:`PyCFunction`, with the *self* parameter, and a
+   :c:type:`PyObject\*` parameter representing the single argument.
+
+
+These two constants are not used to indicate the calling convention but the
+binding when use with methods of classes.  These may not be used for functions
+defined for modules.  At most one of these flags may be set for any given
+method.
+
+
+.. data:: METH_CLASS
+
+   .. index:: builtin: classmethod
+
+   The method will be passed the type object as the first parameter rather
+   than an instance of the type.  This is used to create *class methods*,
+   similar to what is created when using the :func:`classmethod` built-in
+   function.
+
+
+.. data:: METH_STATIC
+
+   .. index:: builtin: staticmethod
+
+   The method will be passed *NULL* as the first parameter rather than an
+   instance of the type.  This is used to create *static methods*, similar to
+   what is created when using the :func:`staticmethod` built-in function.
+
+One other constant controls whether a method is loaded in place of another
+definition with the same method name.
+
+
+.. data:: 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
+   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
+   than wrapper object calls.
+
+
+.. c:type:: PyMemberDef
+
+   Structure which describes an attribute of a type which corresponds to a C
+   struct member.  Its fields are:
+
+   +------------------+-------------+-------------------------------+
+   | Field            | C Type      | Meaning                       |
+   +==================+=============+===============================+
+   | :attr:`name`     | char \*     | name of the member            |
+   +------------------+-------------+-------------------------------+
+   | :attr:`!type`    | int         | the type of the member in the |
+   |                  |             | C struct                      |
+   +------------------+-------------+-------------------------------+
+   | :attr:`offset`   | Py_ssize_t  | the offset in bytes that the  |
+   |                  |             | member is located on the      |
+   |                  |             | type's object struct          |
+   +------------------+-------------+-------------------------------+
+   | :attr:`flags`    | int         | flag bits indicating if the   |
+   |                  |             | field should be read-only or  |
+   |                  |             | writable                      |
+   +------------------+-------------+-------------------------------+
+   | :attr:`doc`      | char \*     | points to the contents of the |
+   |                  |             | docstring                     |
+   +------------------+-------------+-------------------------------+
+
+   :attr:`!type` can be one of many ``T_`` macros corresponding to various C
+   types.  When the member is accessed in Python, it will be converted to the
+   equivalent Python type.
+
+   =============== ==================
+   Macro name      C type
+   =============== ==================
+   T_SHORT         short
+   T_INT           int
+   T_LONG          long
+   T_FLOAT         float
+   T_DOUBLE        double
+   T_STRING        char \*
+   T_OBJECT        PyObject \*
+   T_OBJECT_EX     PyObject \*
+   T_CHAR          char
+   T_BYTE          char
+   T_UBYTE         unsigned char
+   T_UINT          unsigned int
+   T_USHORT        unsigned short
+   T_ULONG         unsigned long
+   T_BOOL          char
+   T_LONGLONG      long long
+   T_ULONGLONG     unsigned long long
+   T_PYSSIZET      Py_ssize_t
+   =============== ==================
+
+   :c:macro:`T_OBJECT` and :c:macro:`T_OBJECT_EX` differ in that
+   :c:macro:`T_OBJECT` returns ``None`` if the member is *NULL* and
+   :c:macro:`T_OBJECT_EX` raises an :exc:`AttributeError`.  Try to use
+   :c:macro:`T_OBJECT_EX` over :c:macro:`T_OBJECT` because :c:macro:`T_OBJECT_EX`
+   handles use of the :keyword:`del` statement on that attribute more correctly
+   than :c:macro:`T_OBJECT`.
+
+   :attr:`flags` can be ``0`` for write and read access or :c:macro:`READONLY` for
+   read-only access.  Using :c:macro:`T_STRING` for :attr:`type` implies
+   :c:macro:`READONLY`.  :c:macro:`T_STRING` data is interpreted as UTF-8.
+   Only :c:macro:`T_OBJECT` and :c:macro:`T_OBJECT_EX`
+   members can be deleted.  (They are set to *NULL*).
+
+
+.. c:type:: PyGetSetDef
+
+   Structure to define property-like access for a type. See also description of
+   the :c:member:`PyTypeObject.tp_getset` slot.
+
+   +-------------+------------------+-----------------------------------+
+   | Field       | C Type           | Meaning                           |
+   +=============+==================+===================================+
+   | name        | char \*          | attribute name                    |
+   +-------------+------------------+-----------------------------------+
+   | get         | getter           | C Function to get the attribute   |
+   +-------------+------------------+-----------------------------------+
+   | set         | setter           | optional C function to set or     |
+   |             |                  | delete the attribute, if omitted  |
+   |             |                  | the attribute is readonly         |
+   +-------------+------------------+-----------------------------------+
+   | doc         | char \*          | optional docstring                |
+   +-------------+------------------+-----------------------------------+
+   | closure     | void \*          | optional function pointer,        |
+   |             |                  | providing additional data for     |
+   |             |                  | getter and setter                 |
+   +-------------+------------------+-----------------------------------+
+
+   The ``get`` function takes one :c:type:`PyObject\*` parameter (the
+   instance) and a function pointer (the associated ``closure``)::
+
+      typedef PyObject *(*getter)(PyObject *, void *);
+
+   It should return a new reference on success or *NULL* with a set exception
+   on failure.
+
+   ``set`` functions take two :c:type:`PyObject\*` parameters (the instance and
+   the value to be set) and a function pointer (the associated ``closure``)::
+
+      typedef int (*setter)(PyObject *, PyObject *, void *);
+
+   In case the attribute should be deleted the second parameter is *NULL*.
+   Should return ``0`` on success or ``-1`` with a set exception on failure.

third_party/python/Doc/c-api/sys.rst

@@ -0,0 +1,267 @@
+.. highlightlang:: c
+
+.. _os:
+
+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,
+   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.
+
+   .. versionadded:: 3.6
+
+
+.. c:function:: int Py_FdIsInteractive(FILE *fp, const char *filename)
+
+   Return true (nonzero) if the standard I/O file *fp* with name *filename* is
+   deemed interactive.  This is the case for files for which ``isatty(fileno(fp))``
+   is true.  If the global flag :c:data:`Py_InteractiveFlag` is true, this function
+   also returns true if the *filename* pointer is *NULL* or if the name is equal to
+   one of the strings ``'<stdin>'`` or ``'???'``.
+
+
+.. c:function:: void PyOS_AfterFork()
+
+   Function to update some internal state after a process fork; this should be
+   called in the new process if the Python interpreter will continue to be used.
+   If a new executable is loaded into the new process, this function does not need
+   to be called.
+
+
+.. 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
+   on Windows using the Microsoft Visual C++ compiler).  :const:`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
+   directly! :c:type:`PyOS_sighandler_t` is a typedef alias for :c:type:`void
+   (\*)(int)`.
+
+
+.. 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
+   not call those functions directly!  :c:type:`PyOS_sighandler_t` is a typedef
+   alias for :c:type:`void (\*)(int)`.
+
+.. c:function:: wchar_t* Py_DecodeLocale(const char* arg, size_t *size)
+
+   Decode a byte string from the locale encoding with the :ref:`surrogateescape
+   error handler <surrogateescape>`: undecodable bytes are decoded as
+   characters in range U+DC80..U+DCFF. If a byte sequence can be decoded as a
+   surrogate character, escape the bytes using the surrogateescape error
+   handler instead of decoding them.
+
+   Encoding, highest priority to lowest priority:
+
+   * ``UTF-8`` on macOS and Android;
+   * ``ASCII`` if the ``LC_CTYPE`` locale is ``"C"``,
+     ``nl_langinfo(CODESET)`` returns the ``ASCII`` encoding (or an alias),
+     and :c:func:`mbstowcs` and :c:func:`wcstombs` functions use the
+     ``ISO-8859-1`` encoding.
+   * the current locale encoding (``LC_CTYPE`` locale).
+
+   Return a pointer to a newly allocated wide character string, use
+   :c:func:`PyMem_RawFree` to free the memory. If size is not ``NULL``, write
+   the number of wide characters excluding the null character into ``*size``.
+
+   Return ``NULL`` on decoding error or memory allocation error. If *size* is
+   not ``NULL``, ``*size`` is set to ``(size_t)-1`` on memory error or set to
+   ``(size_t)-2`` on decoding error.
+
+   Decoding errors should never happen, unless there is a bug in the C
+   library.
+
+   Use the :c:func:`Py_EncodeLocale` function to encode the character string
+   back to a byte string.
+
+   .. seealso::
+
+      The :c:func:`PyUnicode_DecodeFSDefaultAndSize` and
+      :c:func:`PyUnicode_DecodeLocaleAndSize` functions.
+
+   .. versionadded:: 3.5
+
+
+.. c:function:: char* Py_EncodeLocale(const wchar_t *text, size_t *error_pos)
+
+   Encode a wide character string to the locale encoding with the
+   :ref:`surrogateescape error handler <surrogateescape>`: surrogate characters
+   in the range U+DC80..U+DCFF are converted to bytes 0x80..0xFF.
+
+   Encoding, highest priority to lowest priority:
+
+   * ``UTF-8`` on macOS and Android;
+   * ``ASCII`` if the ``LC_CTYPE`` locale is ``"C"``,
+     ``nl_langinfo(CODESET)`` returns the ``ASCII`` encoding (or an alias),
+     and :c:func:`mbstowcs` and :c:func:`wcstombs` functions uses the
+     ``ISO-8859-1`` encoding.
+   * the current locale encoding.
+
+   Return a pointer to a newly allocated byte string, use :c:func:`PyMem_Free`
+   to free the memory. Return ``NULL`` on encoding error or memory allocation
+   error
+
+   If error_pos is not ``NULL``, ``*error_pos`` is set to the index of the
+   invalid character on encoding error, or set to ``(size_t)-1`` otherwise.
+
+   Use the :c:func:`Py_DecodeLocale` function to decode the bytes string back
+   to a wide character string.
+
+   .. seealso::
+
+      The :c:func:`PyUnicode_EncodeFSDefault` and
+      :c:func:`PyUnicode_EncodeLocale` functions.
+
+   .. versionadded:: 3.5
+
+
+.. _systemfunctions:
+
+System Functions
+================
+
+These are utility functions that make functionality from the :mod:`sys` module
+accessible to C code.  They all work with the current interpreter thread's
+:mod:`sys` module's dict, which is contained in the internal thread state structure.
+
+.. c:function:: PyObject *PySys_GetObject(const char *name)
+
+   Return the object *name* from the :mod:`sys` module or *NULL* if it does
+   not exist, without setting an exception.
+
+.. c:function:: int PySys_SetObject(const char *name, PyObject *v)
+
+   Set *name* in the :mod:`sys` module to *v* unless *v* is *NULL*, in which
+   case *name* is deleted from the sys module. Returns ``0`` on success, ``-1``
+   on error.
+
+.. c:function:: void PySys_ResetWarnOptions()
+
+   Reset :data:`sys.warnoptions` to an empty list.
+
+.. c:function:: void PySys_AddWarnOption(wchar_t *s)
+
+   Append *s* to :data:`sys.warnoptions`.
+
+.. c:function:: void PySys_AddWarnOptionUnicode(PyObject *unicode)
+
+   Append *unicode* to :data:`sys.warnoptions`.
+
+.. c:function:: void PySys_SetPath(wchar_t *path)
+
+   Set :data:`sys.path` to a list object of paths found in *path* which should
+   be a list of paths separated with the platform's search path delimiter
+   (``:`` on Unix, ``;`` on Windows).
+
+.. c:function:: void PySys_WriteStdout(const char *format, ...)
+
+   Write the output string described by *format* to :data:`sys.stdout`.  No
+   exceptions are raised, even if truncation occurs (see below).
+
+   *format* should limit the total size of the formatted output string to
+   1000 bytes or less -- after 1000 bytes, the output string is truncated.
+   In particular, this means that no unrestricted "%s" formats should occur;
+   these should be limited using "%.<N>s" where <N> is a decimal number
+   calculated so that <N> plus the maximum size of other formatted text does not
+   exceed 1000 bytes.  Also watch out for "%f", which can print hundreds of
+   digits for very large numbers.
+
+   If a problem occurs, or :data:`sys.stdout` is unset, the formatted message
+   is written to the real (C level) *stdout*.
+
+.. c:function:: void PySys_WriteStderr(const char *format, ...)
+
+   As :c:func:`PySys_WriteStdout`, but write to :data:`sys.stderr` or *stderr*
+   instead.
+
+.. c:function:: void PySys_FormatStdout(const char *format, ...)
+
+   Function similar to PySys_WriteStdout() but format the message using
+   :c:func:`PyUnicode_FromFormatV` and don't truncate the message to an
+   arbitrary length.
+
+   .. versionadded:: 3.2
+
+.. c:function:: void PySys_FormatStderr(const char *format, ...)
+
+   As :c:func:`PySys_FormatStdout`, but write to :data:`sys.stderr` or *stderr*
+   instead.
+
+   .. versionadded:: 3.2
+
+.. c:function:: void PySys_AddXOption(const wchar_t *s)
+
+   Parse *s* as a set of :option:`-X` options and add them to the current
+   options mapping as returned by :c:func:`PySys_GetXOptions`.
+
+   .. versionadded:: 3.2
+
+.. c:function:: PyObject *PySys_GetXOptions()
+
+   Return the current dictionary of :option:`-X` options, similarly to
+   :data:`sys._xoptions`.  On error, *NULL* is returned and an exception is
+   set.
+
+   .. versionadded:: 3.2
+
+
+.. _processcontrol:
+
+Process Control
+===============
+
+
+.. c:function:: void Py_FatalError(const char *message)
+
+   .. index:: single: abort()
+
+   Print a fatal error message and kill the process.  No cleanup is performed.
+   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`
+   file.
+
+
+.. c:function:: void Py_Exit(int status)
+
+   .. index::
+      single: Py_FinalizeEx()
+      single: exit()
+
+   Exit the current process.  This calls :c:func:`Py_FinalizeEx` and then calls the
+   standard C library function ``exit(status)``.  If :c:func:`Py_FinalizeEx`
+   indicates an error, the exit status is set to 120.
+
+   .. versionchanged:: 3.6
+      Errors from finalization no longer ignored.
+
+
+.. c:function:: int Py_AtExit(void (*func) ())
+
+   .. index::
+      single: Py_FinalizeEx()
+      single: cleanup functions
+
+   Register a cleanup function to be called by :c:func:`Py_FinalizeEx`.  The cleanup
+   function will be called with no arguments and should return no value.  At most
+   32 cleanup functions can be registered.  When the registration is successful,
+   :c:func:`Py_AtExit` returns ``0``; on failure, it returns ``-1``.  The cleanup
+   function registered last is called first. Each cleanup function will be called
+   at most once.  Since Python's internal finalization will have completed before
+   the cleanup function, no Python APIs should be called by *func*.

third_party/python/Doc/c-api/tuple.rst

@@ -0,0 +1,218 @@
+.. highlightlang:: c
+
+.. _tupleobjects:
+
+Tuple Objects
+-------------
+
+.. index:: object: tuple
+
+
+.. c:type:: PyTupleObject
+
+   This subtype of :c:type:`PyObject` represents a Python tuple object.
+
+
+.. c:var:: PyTypeObject PyTuple_Type
+
+   This instance of :c:type:`PyTypeObject` represents the Python tuple type; it
+   is the same object as :class:`tuple` in the Python layer.
+
+
+.. c:function:: int PyTuple_Check(PyObject *p)
+
+   Return true if *p* is a tuple object or an instance of a subtype of the tuple
+   type.
+
+
+.. c:function:: int PyTuple_CheckExact(PyObject *p)
+
+   Return true if *p* is a tuple object, but not an instance of a subtype of the
+   tuple type.
+
+
+.. c:function:: PyObject* PyTuple_New(Py_ssize_t len)
+
+   Return a new tuple object of size *len*, or *NULL* on failure.
+
+
+.. c:function:: PyObject* PyTuple_Pack(Py_ssize_t n, ...)
+
+   Return a new tuple object of size *n*, or *NULL* on failure. The tuple values
+   are initialized to the subsequent *n* C arguments pointing to Python objects.
+   ``PyTuple_Pack(2, a, b)`` is equivalent to ``Py_BuildValue("(OO)", a, b)``.
+
+
+.. c:function:: Py_ssize_t PyTuple_Size(PyObject *p)
+
+   Take a pointer to a tuple object, and return the size of that tuple.
+
+
+.. c:function:: Py_ssize_t PyTuple_GET_SIZE(PyObject *p)
+
+   Return the size of the tuple *p*, which must be non-*NULL* and point to a tuple;
+   no error checking is performed.
+
+
+.. c:function:: PyObject* PyTuple_GetItem(PyObject *p, Py_ssize_t pos)
+
+   Return the object at position *pos* in the tuple pointed to by *p*.  If *pos* is
+   out of bounds, return *NULL* and sets an :exc:`IndexError` exception.
+
+
+.. c:function:: PyObject* PyTuple_GET_ITEM(PyObject *p, Py_ssize_t pos)
+
+   Like :c:func:`PyTuple_GetItem`, but does no checking of its arguments.
+
+
+.. c:function:: PyObject* PyTuple_GetSlice(PyObject *p, Py_ssize_t low, Py_ssize_t high)
+
+   Take a slice of the tuple pointed to by *p* from *low* to *high* and return it
+   as a new tuple.
+
+
+.. c:function:: int PyTuple_SetItem(PyObject *p, Py_ssize_t pos, PyObject *o)
+
+   Insert a reference to object *o* at position *pos* of the tuple pointed to by
+   *p*. Return ``0`` on success.
+
+   .. note::
+
+      This function "steals" a reference to *o*.
+
+
+.. c:function:: void PyTuple_SET_ITEM(PyObject *p, Py_ssize_t pos, PyObject *o)
+
+   Like :c:func:`PyTuple_SetItem`, but does no error checking, and should *only* be
+   used to fill in brand new tuples.
+
+   .. note::
+
+      This function "steals" a reference to *o*.
+
+
+.. c:function:: int _PyTuple_Resize(PyObject **p, Py_ssize_t newsize)
+
+   Can be used to resize a tuple.  *newsize* will be the new length of the tuple.
+   Because tuples are *supposed* to be immutable, this should only be used if there
+   is only one reference to the object.  Do *not* use this if the tuple may already
+   be known to some other part of the code.  The tuple will always grow or shrink
+   at the end.  Think of this as destroying the old tuple and creating a new one,
+   only more efficiently.  Returns ``0`` on success. Client code should never
+   assume that the resulting value of ``*p`` will be the same as before calling
+   this function. If the object referenced by ``*p`` is replaced, the original
+   ``*p`` is destroyed.  On failure, returns ``-1`` and sets ``*p`` to *NULL*, and
+   raises :exc:`MemoryError` or :exc:`SystemError`.
+
+
+.. c:function:: int PyTuple_ClearFreeList()
+
+   Clear the free list. Return the total number of freed items.
+
+
+Struct Sequence Objects
+-----------------------
+
+Struct sequence objects are the C equivalent of :func:`~collections.namedtuple`
+objects, i.e. a sequence whose items can also be accessed through attributes.
+To create a struct sequence, you first have to create a specific struct sequence
+type.
+
+.. c:function:: PyTypeObject* PyStructSequence_NewType(PyStructSequence_Desc *desc)
+
+   Create a new struct sequence type from the data in *desc*, described below. Instances
+   of the resulting type can be created with :c:func:`PyStructSequence_New`.
+
+
+.. c:function:: void PyStructSequence_InitType(PyTypeObject *type, PyStructSequence_Desc *desc)
+
+   Initializes a struct sequence type *type* from *desc* in place.
+
+
+.. c:function:: int PyStructSequence_InitType2(PyTypeObject *type, PyStructSequence_Desc *desc)
+
+   The same as ``PyStructSequence_InitType``, but returns ``0`` on success and ``-1`` on
+   failure.
+
+   .. versionadded:: 3.4
+
+
+.. c:type:: PyStructSequence_Desc
+
+   Contains the meta information of a struct sequence type to create.
+
+   +-------------------+------------------------------+------------------------------------+
+   | Field             | C Type                       | Meaning                            |
+   +===================+==============================+====================================+
+   | ``name``          | ``char *``                   | name of the struct sequence type   |
+   +-------------------+------------------------------+------------------------------------+
+   | ``doc``           | ``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:type:: PyStructSequence_Field
+
+   Describes a field of a struct sequence. As a struct sequence is modeled as a
+   tuple, all fields are typed as :c:type:`PyObject\*`.  The index in the
+   :attr:`fields` array of the :c:type:`PyStructSequence_Desc` determines which
+   field of the struct sequence is described.
+
+   +-----------+---------------+--------------------------------------+
+   | Field     | C Type        | Meaning                              |
+   +===========+===============+======================================+
+   | ``name``  | ``char *``    | name for the field or *NULL* to end  |
+   |           |               | the list of named fields, set to     |
+   |           |               | PyStructSequence_UnnamedField to     |
+   |           |               | leave unnamed                        |
+   +-----------+---------------+--------------------------------------+
+   | ``doc``   | ``char *``    | field docstring or *NULL* to omit    |
+   +-----------+---------------+--------------------------------------+
+
+
+.. c:var:: char* PyStructSequence_UnnamedField
+
+   Special value for a field name to leave it unnamed.
+
+
+.. c:function:: PyObject* PyStructSequence_New(PyTypeObject *type)
+
+   Creates an instance of *type*, which must have been created with
+   :c:func:`PyStructSequence_NewType`.
+
+
+.. c:function:: PyObject* PyStructSequence_GetItem(PyObject *p, Py_ssize_t pos)
+
+   Return the object at position *pos* in the struct sequence pointed to by *p*.
+   No bounds checking is performed.
+
+
+.. c:function:: PyObject* PyStructSequence_GET_ITEM(PyObject *p, Py_ssize_t pos)
+
+   Macro equivalent of :c:func:`PyStructSequence_GetItem`.
+
+
+.. c:function:: void PyStructSequence_SetItem(PyObject *p, Py_ssize_t pos, PyObject *o)
+
+   Sets the field at index *pos* of the struct sequence *p* to value *o*.  Like
+   :c:func:`PyTuple_SET_ITEM`, this should only be used to fill in brand new
+   instances.
+
+   .. note::
+
+      This function "steals" a reference to *o*.
+
+
+.. c:function:: void PyStructSequence_SET_ITEM(PyObject *p, Py_ssize_t *pos, PyObject *o)
+
+   Macro equivalent of :c:func:`PyStructSequence_SetItem`.
+
+   .. note::
+
+      This function "steals" a reference to *o*.

third_party/python/Doc/c-api/type.rst

@@ -0,0 +1,118 @@
+.. highlightlang:: c
+
+.. _typeobjects:
+
+Type Objects
+------------
+
+.. index:: object: type
+
+
+.. c:type:: PyTypeObject
+
+   The C structure of the objects used to describe built-in types.
+
+
+.. c:var:: PyObject* PyType_Type
+
+   This is the type object for type objects; it is the same object as
+   :class:`type` in the Python layer.
+
+
+.. c:function:: int PyType_Check(PyObject *o)
+
+   Return true if the object *o* is a type object, including instances of types
+   derived from the standard type object.  Return false in all other cases.
+
+
+.. c:function:: int PyType_CheckExact(PyObject *o)
+
+   Return true if the object *o* is a type object, but not a subtype of the
+   standard type object.  Return false in all other cases.
+
+
+.. c:function:: unsigned int PyType_ClearCache()
+
+   Clear the internal lookup cache. Return the current version tag.
+
+.. c:function:: unsigned long PyType_GetFlags(PyTypeObject* type)
+
+   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.
+
+   .. versionadded:: 3.2
+
+   .. versionchanged:: 3.4
+      The return type is now ``unsigned long`` rather than ``long``.
+
+
+.. c:function:: void PyType_Modified(PyTypeObject *type)
+
+   Invalidate the internal lookup cache for the type and all of its
+   subtypes.  This function must be called after any manual
+   modification of the attributes or base classes of the type.
+
+
+.. c:function:: int PyType_HasFeature(PyTypeObject *o, int feature)
+
+   Return true if the type object *o* sets the feature *feature*.  Type features
+   are denoted by single bit flags.
+
+
+.. 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`.
+
+
+.. c:function:: int PyType_IsSubtype(PyTypeObject *a, PyTypeObject *b)
+
+   Return true if *a* is a subtype of *b*.
+
+   This function only checks for actual subtypes, which means that
+   :meth:`~class.__subclasscheck__` is not called on *b*.  Call
+   :c:func:`PyObject_IsSubclass` to do the same check that :func:`issubclass`
+   would do.
+
+
+.. c:function:: PyObject* PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)
+
+   Generic handler for the :c:member:`~PyTypeObject.tp_alloc` slot of a type object.  Use
+   Python's default memory allocation mechanism to allocate a new instance and
+   initialize all its contents to *NULL*.
+
+.. c:function:: PyObject* PyType_GenericNew(PyTypeObject *type, PyObject *args, PyObject *kwds)
+
+   Generic handler for the :c:member:`~PyTypeObject.tp_new` slot of a type object.  Create a
+   new instance using the type's :c:member:`~PyTypeObject.tp_alloc` slot.
+
+.. c:function:: int PyType_Ready(PyTypeObject *type)
+
+   Finalize a type object.  This should be called on all type objects to finish
+   their initialization.  This function is responsible for adding inherited slots
+   from a type's base class.  Return ``0`` on success, or return ``-1`` and sets an
+   exception on error.
+
+.. c:function:: PyObject* PyType_FromSpec(PyType_Spec *spec)
+
+   Creates and returns a heap type object from the *spec* passed to the function.
+
+.. c:function:: PyObject* PyType_FromSpecWithBases(PyType_Spec *spec, PyObject *bases)
+
+   Creates and returns a heap type object from the *spec*. In addition to that,
+   the created heap type contains all types contained by the *bases* tuple as base
+   types. This allows the caller to reference other heap types as base types.
+
+   .. versionadded:: 3.3
+
+.. c:function:: void* PyType_GetSlot(PyTypeObject *type, int slot)
+
+   Return the function pointer stored in the given slot. If the
+   result is *NULL*, this indicates that either the slot is *NULL*,
+   or that the function was called with invalid parameters.
+   Callers will typically cast the result pointer into the appropriate
+   function type.
+
+   .. versionadded:: 3.4

third_party/python/Doc/c-api/utilities.rst

@@ -0,0 +1,21 @@
+.. highlightlang:: c
+
+.. _utilities:
+
+*********
+Utilities
+*********
+
+The functions in this chapter perform various utility tasks, ranging from
+helping C code be more portable across platforms, using Python modules from C,
+and parsing function arguments and constructing Python values from C values.
+
+.. toctree::
+
+   sys.rst
+   import.rst
+   marshal.rst
+   arg.rst
+   conversion.rst
+   reflection.rst
+   codec.rst

third_party/python/Doc/c-api/veryhigh.rst

@@ -0,0 +1,390 @@
+.. highlightlang:: c
+
+
+.. _veryhigh:
+
+*************************
+The Very High Level Layer
+*************************
+
+The functions in this chapter will let you execute Python source code given in a
+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
+following the functions which accept them as parameters.
+
+Note also that several of these functions take :c:type:`FILE\*` parameters.  One
+particular issue which needs to be handled carefully is that the :c:type:`FILE`
+structure for different C libraries can be different and incompatible.  Under
+Windows (at least), it is possible for dynamically linked extensions to actually
+use different libraries, so care should be taken that :c:type:`FILE\*` parameters
+are only passed to these functions if it is certain that they were created by
+the same library that the Python runtime is using.
+
+
+.. c:function:: int Py_Main(int argc, wchar_t **argv)
+
+   The main program for the standard interpreter.  This is made available for
+   programs which embed Python.  The *argc* and *argv* parameters should be
+   prepared exactly as those which are passed to a C program's :c:func:`main`
+   function (converted to wchar_t according to the user's locale).  It is
+   important to note that the argument list may be modified (but the contents of
+   the strings pointed to by the argument list are not). The return value will
+   be ``0`` if the interpreter exits normally (i.e., without an exception),
+   ``1`` if the interpreter exits due to an exception, or ``2`` if the parameter
+   list does not represent a valid Python command line.
+
+   Note that if an otherwise unhandled :exc:`SystemExit` is raised, this
+   function will not return ``1``, but exit the process, as long as
+   ``Py_InspectFlag`` is not set.
+
+
+.. c:function:: int PyRun_AnyFile(FILE *fp, const char *filename)
+
+   This is a simplified interface to :c:func:`PyRun_AnyFileExFlags` below, leaving
+   *closeit* set to ``0`` and *flags* set to *NULL*.
+
+
+.. c:function:: int PyRun_AnyFileFlags(FILE *fp, const char *filename, PyCompilerFlags *flags)
+
+   This is a simplified interface to :c:func:`PyRun_AnyFileExFlags` below, leaving
+   the *closeit* argument set to ``0``.
+
+
+.. c:function:: int PyRun_AnyFileEx(FILE *fp, const char *filename, int closeit)
+
+   This is a simplified interface to :c:func:`PyRun_AnyFileExFlags` below, leaving
+   the *flags* argument set to *NULL*.
+
+
+.. c:function:: int PyRun_AnyFileExFlags(FILE *fp, const char *filename, int closeit, PyCompilerFlags *flags)
+
+   If *fp* refers to a file associated with an interactive device (console or
+   terminal input or Unix pseudo-terminal), return the value of
+   :c:func:`PyRun_InteractiveLoop`, otherwise return the result of
+   :c:func:`PyRun_SimpleFile`.  *filename* is decoded from the filesystem
+   encoding (:func:`sys.getfilesystemencoding`).  If *filename* is *NULL*, this
+   function uses ``"???"`` as the filename.
+
+
+.. c:function:: int PyRun_SimpleString(const char *command)
+
+   This is a simplified interface to :c:func:`PyRun_SimpleStringFlags` below,
+   leaving the *PyCompilerFlags\** argument set to NULL.
+
+
+.. c:function:: int PyRun_SimpleStringFlags(const char *command, PyCompilerFlags *flags)
+
+   Executes the Python source code from *command* in the :mod:`__main__` module
+   according to the *flags* argument. If :mod:`__main__` does not already exist, it
+   is created.  Returns ``0`` on success or ``-1`` if an exception was raised.  If
+   there was an error, there is no way to get the exception information. For the
+   meaning of *flags*, see below.
+
+   Note that if an otherwise unhandled :exc:`SystemExit` is raised, this
+   function will not return ``-1``, but exit the process, as long as
+   ``Py_InspectFlag`` is not set.
+
+
+.. c:function:: int PyRun_SimpleFile(FILE *fp, const char *filename)
+
+   This is a simplified interface to :c:func:`PyRun_SimpleFileExFlags` below,
+   leaving *closeit* set to ``0`` and *flags* set to *NULL*.
+
+
+.. c:function:: int PyRun_SimpleFileEx(FILE *fp, const char *filename, int closeit)
+
+   This is a simplified interface to :c:func:`PyRun_SimpleFileExFlags` below,
+   leaving *flags* set to *NULL*.
+
+
+.. c:function:: int PyRun_SimpleFileExFlags(FILE *fp, const char *filename, int closeit, PyCompilerFlags *flags)
+
+   Similar to :c:func:`PyRun_SimpleStringFlags`, but the Python source code is read
+   from *fp* instead of an in-memory string. *filename* should be the name of
+   the file, it is decoded from the filesystem encoding
+   (:func:`sys.getfilesystemencoding`).  If *closeit* is true, the file is
+   closed before PyRun_SimpleFileExFlags returns.
+
+
+.. c:function:: int PyRun_InteractiveOne(FILE *fp, const char *filename)
+
+   This is a simplified interface to :c:func:`PyRun_InteractiveOneFlags` below,
+   leaving *flags* set to *NULL*.
+
+
+.. c:function:: int PyRun_InteractiveOneFlags(FILE *fp, const char *filename, PyCompilerFlags *flags)
+
+   Read and execute a single statement from a file associated with an
+   interactive device according to the *flags* argument.  The user will be
+   prompted using ``sys.ps1`` and ``sys.ps2``.  *filename* is decoded from the
+   filesystem encoding (:func:`sys.getfilesystemencoding`).
+
+   Returns ``0`` when the input was
+   executed successfully, ``-1`` if there was an exception, or an error code
+   from the :file:`errcode.h` include file distributed as part of Python if
+   there was a parse error.  (Note that :file:`errcode.h` is not included by
+   :file:`Python.h`, so must be included specifically if needed.)
+
+
+.. c:function:: int PyRun_InteractiveLoop(FILE *fp, const char *filename)
+
+   This is a simplified interface to :c:func:`PyRun_InteractiveLoopFlags` below,
+   leaving *flags* set to *NULL*.
+
+
+.. c:function:: int PyRun_InteractiveLoopFlags(FILE *fp, const char *filename, PyCompilerFlags *flags)
+
+   Read and execute statements from a file associated with an interactive device
+   until EOF is reached.  The user will be prompted using ``sys.ps1`` and
+   ``sys.ps2``.  *filename* is decoded from the filesystem encoding
+   (:func:`sys.getfilesystemencoding`).  Returns ``0`` at EOF or a negative
+   number upon failure.
+
+
+.. c:var:: int (*PyOS_InputHook)(void)
+
+   Can be set to point to a function with the prototype
+   ``int func(void)``.  The function will be called when Python's
+   interpreter prompt is about to become idle and wait for user input
+   from the terminal.  The return value is ignored.  Overriding this
+   hook can be used to integrate the interpreter's prompt with other
+   event loops, as done in the :file:`Modules/_tkinter.c` in the
+   Python source code.
+
+
+.. c:var:: char* (*PyOS_ReadlineFunctionPointer)(FILE *, FILE *, const char *)
+
+   Can be set to point to a function with the prototype
+   ``char *func(FILE *stdin, FILE *stdout, char *prompt)``,
+   overriding the default function used to read a single line of input
+   at the interpreter's prompt.  The function is expected to output
+   the string *prompt* if it's not *NULL*, and then read a line of
+   input from the provided standard input file, returning the
+   resulting string.  For example, The :mod:`readline` module sets
+   this hook to provide line-editing and tab-completion features.
+
+   The result must be a string allocated by :c:func:`PyMem_RawMalloc` or
+   :c:func:`PyMem_RawRealloc`, or *NULL* if an error occurred.
+
+   .. versionchanged:: 3.4
+      The result must be allocated by :c:func:`PyMem_RawMalloc` or
+      :c:func:`PyMem_RawRealloc`, instead of being allocated by
+      :c:func:`PyMem_Malloc` or :c:func:`PyMem_Realloc`.
+
+
+.. c:function:: struct _node* PyParser_SimpleParseString(const char *str, int start)
+
+   This is a simplified interface to
+   :c:func:`PyParser_SimpleParseStringFlagsFilename` below, leaving  *filename* set
+   to *NULL* and *flags* set to ``0``.
+
+
+.. c:function:: struct _node* PyParser_SimpleParseStringFlags( const char *str, int start, int flags)
+
+   This is a simplified interface to
+   :c:func:`PyParser_SimpleParseStringFlagsFilename` below, leaving  *filename* set
+   to *NULL*.
+
+
+.. c:function:: struct _node* PyParser_SimpleParseStringFlagsFilename( const char *str, const char *filename, int start, int flags)
+
+   Parse Python source code from *str* using the start token *start* according to
+   the *flags* argument.  The result can be used to create a code object which can
+   be evaluated efficiently. This is useful if a code fragment must be evaluated
+   many times. *filename* is decoded from the filesystem encoding
+   (:func:`sys.getfilesystemencoding`).
+
+
+.. c:function:: struct _node* PyParser_SimpleParseFile(FILE *fp, const char *filename, int start)
+
+   This is a simplified interface to :c:func:`PyParser_SimpleParseFileFlags` below,
+   leaving *flags* set to ``0``.
+
+
+.. c:function:: struct _node* PyParser_SimpleParseFileFlags(FILE *fp, const char *filename, int start, int flags)
+
+   Similar to :c:func:`PyParser_SimpleParseStringFlagsFilename`, but the Python
+   source code is read from *fp* instead of an in-memory string.
+
+
+.. 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
+   *flags* set to *NULL*.
+
+
+.. c:function:: PyObject* PyRun_StringFlags(const char *str, int start, PyObject *globals, PyObject *locals, PyCompilerFlags *flags)
+
+   Execute Python source code from *str* in the context specified by the
+   objects *globals* and *locals* with the compiler flags specified by
+   *flags*.  *globals* must be a dictionary; *locals* can be any object
+   that implements the mapping protocol.  The parameter *start* specifies
+   the start token that should be used to parse the source code.
+
+   Returns the result of executing the code as a Python object, or *NULL* if an
+   exception was raised.
+
+
+.. c:function:: PyObject* PyRun_File(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals)
+
+   This is a simplified interface to :c:func:`PyRun_FileExFlags` below, leaving
+   *closeit* set to ``0`` and *flags* set to *NULL*.
+
+
+.. c:function:: PyObject* PyRun_FileEx(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, int closeit)
+
+   This is a simplified interface to :c:func:`PyRun_FileExFlags` below, leaving
+   *flags* set to *NULL*.
+
+
+.. c:function:: PyObject* PyRun_FileFlags(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, PyCompilerFlags *flags)
+
+   This is a simplified interface to :c:func:`PyRun_FileExFlags` below, leaving
+   *closeit* set to ``0``.
+
+
+.. c:function:: PyObject* PyRun_FileExFlags(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, int closeit, PyCompilerFlags *flags)
+
+   Similar to :c:func:`PyRun_StringFlags`, but the Python source code is read from
+   *fp* instead of an in-memory string. *filename* should be the name of the file,
+   it is decoded from the filesystem encoding (:func:`sys.getfilesystemencoding`).
+   If *closeit* is true, the file is closed before :c:func:`PyRun_FileExFlags`
+   returns.
+
+
+.. c:function:: PyObject* Py_CompileString(const char *str, const char *filename, int start)
+
+   This is a simplified interface to :c:func:`Py_CompileStringFlags` below, leaving
+   *flags* set to *NULL*.
+
+
+.. c:function:: PyObject* Py_CompileStringFlags(const char *str, const char *filename, int start, PyCompilerFlags *flags)
+
+   This is a simplified interface to :c:func:`Py_CompileStringExFlags` below, with
+   *optimize* set to ``-1``.
+
+
+.. c:function:: PyObject* Py_CompileStringObject(const char *str, PyObject *filename, int start, PyCompilerFlags *flags, int optimize)
+
+   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
+   *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.
+
+   The integer *optimize* specifies the optimization level of the compiler; a
+   value of ``-1`` selects the optimization level of the interpreter as given by
+   :option:`-O` options.  Explicit levels are ``0`` (no optimization;
+   ``__debug__`` is true), ``1`` (asserts are removed, ``__debug__`` is false)
+   or ``2`` (docstrings are removed too).
+
+   .. versionadded:: 3.4
+
+
+.. c:function:: PyObject* Py_CompileStringExFlags(const char *str, const char *filename, int start, PyCompilerFlags *flags, int optimize)
+
+   Like :c:func:`Py_CompileStringObject`, but *filename* is a byte string
+   decoded from the filesystem encoding (:func:`os.fsdecode`).
+
+   .. versionadded:: 3.2
+
+.. c:function:: PyObject* PyEval_EvalCode(PyObject *co, PyObject *globals, PyObject *locals)
+
+   This is a simplified interface to :c:func:`PyEval_EvalCodeEx`, with just
+   the code object, and global and local variables.  The other arguments are
+   set to *NULL*.
+
+
+.. c:function:: PyObject* PyEval_EvalCodeEx(PyObject *co, PyObject *globals, PyObject *locals, PyObject **args, int argcount, PyObject **kws, int kwcount, PyObject **defs, int defcount, PyObject *kwdefs, PyObject *closure)
+
+   Evaluate a precompiled code object, given a particular environment for its
+   evaluation.  This environment consists of a dictionary of global variables,
+   a mapping object of local variables, arrays of arguments, keywords and
+   defaults, a dictionary of default values for :ref:`keyword-only
+   <keyword-only_parameter>` arguments and a closure tuple of cells.
+
+
+.. c:type:: PyFrameObject
+
+   The C structure of the objects used to describe frame objects. The
+   fields of this type are subject to change at any time.
+
+
+.. c:function:: PyObject* PyEval_EvalFrame(PyFrameObject *f)
+
+   Evaluate an execution frame.  This is a simplified interface to
+   :c:func:`PyEval_EvalFrameEx`, for backward compatibility.
+
+
+.. c:function:: PyObject* PyEval_EvalFrameEx(PyFrameObject *f, int throwflag)
+
+   This is the main, unvarnished function of Python interpretation.  It is
+   literally 2000 lines long.  The code object associated with the execution
+   frame *f* is executed, interpreting bytecode and executing calls as needed.
+   The additional *throwflag* parameter can mostly be ignored - if true, then
+   it causes an exception to immediately be thrown; this is used for the
+   :meth:`~generator.throw` methods of generator objects.
+
+   .. versionchanged:: 3.4
+      This function now includes a debug assertion to help ensure that it
+      does not silently discard an active exception.
+
+
+.. c:function:: int PyEval_MergeCompilerFlags(PyCompilerFlags *cf)
+
+   This function changes the flags of the current evaluation frame, and returns
+   true on success, false on failure.
+
+
+.. c:var:: int Py_eval_input
+
+   .. index:: single: Py_CompileString()
+
+   The start symbol from the Python grammar for isolated expressions; for use with
+   :c:func:`Py_CompileString`.
+
+
+.. c:var:: int Py_file_input
+
+   .. index:: single: Py_CompileString()
+
+   The start symbol from the Python grammar for sequences of statements as read
+   from a file or other source; for use with :c:func:`Py_CompileString`.  This is
+   the symbol to use when compiling arbitrarily long Python source code.
+
+
+.. c:var:: int Py_single_input
+
+   .. index:: single: Py_CompileString()
+
+   The start symbol from the Python grammar for a single statement; for use with
+   :c:func:`Py_CompileString`. This is the symbol used for the interactive
+   interpreter loop.
+
+
+.. c:type:: struct PyCompilerFlags
+
+   This is the structure used to hold compiler flags.  In cases where code is only
+   being compiled, it is passed as ``int flags``, and in cases where code is being
+   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
+   equal to ``0``, and any modification due to ``from __future__ import`` is
+   discarded.  ::
+
+      struct PyCompilerFlags {
+          int cf_flags;
+      }
+
+
+.. c:var:: int CO_FUTURE_DIVISION
+
+   This bit can be set in *flags* to cause division operator ``/`` to be
+   interpreted as "true division" according to :pep:`238`.

third_party/python/Doc/c-api/weakref.rst

@@ -0,0 +1,69 @@
+.. highlightlang:: c
+
+.. _weakrefobjects:
+
+Weak Reference Objects
+----------------------
+
+Python supports *weak references* as first-class objects.  There are two
+specific object types which directly implement weak references.  The first is a
+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)
+
+   Return true if *ob* is either a reference or proxy object.
+
+
+.. c:function:: int PyWeakref_CheckRef(ob)
+
+   Return true if *ob* is a reference object.
+
+
+.. c:function:: int PyWeakref_CheckProxy(ob)
+
+   Return true if *ob* is a proxy object.
+
+
+.. c:function:: PyObject* PyWeakref_NewRef(PyObject *ob, PyObject *callback)
+
+   Return a weak reference object for the object *ob*.  This will always return
+   a new reference, but is not guaranteed to create a new object; an existing
+   reference object may be returned.  The second parameter, *callback*, can be a
+   callable object that receives notification when *ob* is garbage collected; it
+   should accept a single parameter, which will be the weak reference object
+   itself. *callback* may also be ``None`` or *NULL*.  If *ob* is not a
+   weakly-referencable object, or if *callback* is not callable, ``None``, or
+   *NULL*, this will return *NULL* and raise :exc:`TypeError`.
+
+
+.. c:function:: PyObject* PyWeakref_NewProxy(PyObject *ob, PyObject *callback)
+
+   Return a weak reference proxy object for the object *ob*.  This will always
+   return a new reference, but is not guaranteed to create a new object; an
+   existing proxy object may be returned.  The second parameter, *callback*, can
+   be a callable object that receives notification when *ob* is garbage
+   collected; it should accept a single parameter, which will be the weak
+   reference object itself. *callback* may also be ``None`` or *NULL*.  If *ob*
+   is not a weakly-referencable object, or if *callback* is not callable,
+   ``None``, or *NULL*, this will return *NULL* and raise :exc:`TypeError`.
+
+
+.. 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`.
+
+   .. note::
+
+      This function returns a **borrowed reference** to the referenced object.
+      This means that you should always call :c:func:`Py_INCREF` on the object
+      except if you know that it cannot be destroyed while you are still
+      using it.
+
+
+.. c:function:: PyObject* PyWeakref_GET_OBJECT(PyObject *ref)
+
+   Similar to :c:func:`PyWeakref_GetObject`, but implemented as a macro that does no
+   error checking.

third_party/python/Doc/conf.py

@@ -0,0 +1,206 @@
+#
+# Python documentation build configuration file
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# The contents of this file are pickled, so don't put values in the namespace
+# that aren't pickleable (module imports are okay, they're removed automatically).
+
+import sys, os, time
+sys.path.append(os.path.abspath('tools/extensions'))
+
+# General configuration
+# ---------------------
+
+extensions = ['sphinx.ext.coverage', 'sphinx.ext.doctest',
+              'pyspecific', 'c_annotations', 'escape4chm']
+
+# General substitutions.
+project = 'Python'
+copyright = '2001-%s, Python Software Foundation' % time.strftime('%Y')
+
+# We look for the Include/patchlevel.h file in the current Python source tree
+# and replace the values accordingly.
+import patchlevel
+version, release = patchlevel.get_version_info()
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+today = ''
+# Else, today_fmt is used as the format for a strftime call.
+today_fmt = '%B %d, %Y'
+
+# By default, highlight as Python 3.
+highlight_language = 'python3'
+
+# Require Sphinx 1.2 for build.
+needs_sphinx = '1.2'
+
+# Ignore any .rst files in the venv/ directory.
+venvdir = os.getenv('VENVDIR', 'venv')
+exclude_patterns = [venvdir+'/*', 'README.rst']
+
+# Avoid a warning with Sphinx >= 2.0
+master_doc = 'contents'
+
+# Options for HTML output
+# -----------------------
+
+# Use our custom theme.
+html_theme = 'pydoctheme'
+html_theme_path = ['tools']
+html_theme_options = {'collapsiblesidebar': True}
+
+# Short title used e.g. for <title> HTML tags.
+html_short_title = '%s Documentation' % release
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+html_last_updated_fmt = '%b %d, %Y'
+
+# Path to find HTML templates.
+templates_path = ['tools/templates']
+
+# Custom sidebar templates, filenames relative to this file.
+html_sidebars = {
+    # Defaults taken from http://www.sphinx-doc.org/en/stable/config.html#confval-html_sidebars
+    # Removes the quick search block
+    '**': ['localtoc.html', 'relations.html', 'customsourcelink.html'],
+    'index': ['indexsidebar.html'],
+}
+
+# Additional templates that should be rendered to pages.
+html_additional_pages = {
+    'download': 'download.html',
+    'index': 'indexcontent.html',
+}
+
+# Output an OpenSearch description file.
+html_use_opensearch = 'https://docs.python.org/' + version
+
+# Additional static files.
+html_static_path = ['tools/static']
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'python' + release.replace('.', '')
+
+# Split the index
+html_split_index = True
+
+
+# Options for LaTeX output
+# ------------------------
+
+latex_engine = 'xelatex'
+
+# Get LaTeX to handle Unicode correctly
+latex_elements = {
+}
+
+# Additional stuff for the LaTeX preamble.
+latex_elements['preamble'] = r'''
+\authoraddress{
+  \sphinxstrong{Python Software Foundation}\\
+  Email: \sphinxemail{docs@python.org}
+}
+\let\Verbatim=\OriginalVerbatim
+\let\endVerbatim=\endOriginalVerbatim
+'''
+
+# The paper size ('letter' or 'a4').
+latex_elements['papersize'] = 'a4'
+
+# The font size ('10pt', '11pt' or '12pt').
+latex_elements['pointsize'] = '10pt'
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, document class [howto/manual]).
+_stdauthor = r'Guido van Rossum\\and the Python development team'
+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',
+     'Installing Python Modules', _stdauthor, 'manual'),
+    ('library/index', 'library.tex',
+     'The Python Library Reference', _stdauthor, 'manual'),
+    ('reference/index', 'reference.tex',
+     'The Python Language Reference', _stdauthor, 'manual'),
+    ('tutorial/index', 'tutorial.tex',
+     'Python Tutorial', _stdauthor, 'manual'),
+    ('using/index', 'using.tex',
+     'Python Setup and Usage', _stdauthor, 'manual'),
+    ('faq/index', 'faq.tex',
+     'Python Frequently Asked Questions', _stdauthor, 'manual'),
+    ('whatsnew/' + version, 'whatsnew.tex',
+     'What\'s New in Python', 'A. M. Kuchling', 'howto'),
+]
+# Collect all HOWTOs individually
+latex_documents.extend(('howto/' + fn[:-4], 'howto-' + fn[:-4] + '.tex',
+                        '', _stdauthor, 'howto')
+                       for fn in os.listdir('howto')
+                       if fn.endswith('.rst') and fn != 'index.rst')
+
+# Documents to append as an appendix to all manuals.
+latex_appendices = ['glossary', 'about', 'license', 'copyright']
+
+# Options for Epub output
+# -----------------------
+
+epub_author = 'Python Documentation Authors'
+epub_publisher = 'Python Software Foundation'
+
+# Options for the coverage checker
+# --------------------------------
+
+# The coverage checker will ignore all modules/functions/classes whose names
+# match any of the following regexes (using re.match).
+coverage_ignore_modules = [
+    r'[T|t][k|K]',
+    r'Tix',
+    r'distutils.*',
+]
+
+coverage_ignore_functions = [
+    'test($|_)',
+]
+
+coverage_ignore_classes = [
+]
+
+# Glob patterns for C source files for C API coverage, relative to this directory.
+coverage_c_path = [
+    '../Include/*.h',
+]
+
+# Regexes to find C items in the source files.
+coverage_c_regexes = {
+    'cfunction': (r'^PyAPI_FUNC\(.*\)\s+([^_][\w_]+)'),
+    'data': (r'^PyAPI_DATA\(.*\)\s+([^_][\w_]+)'),
+    'macro': (r'^#define ([^_][\w_]+)\(.*\)[\s|\\]'),
+}
+
+# The coverage checker will ignore all C items whose names match these regexes
+# (using re.match) -- the keys must be the same as in coverage_c_regexes.
+coverage_ignore_c_items = {
+#    'cfunction': [...]
+}
+
+
+# Options for the link checker
+# ----------------------------
+
+# Ignore certain URLs.
+linkcheck_ignore = [r'https://bugs.python.org/(issue)?\d+',
+                    # Ignore PEPs for now, they all have permanent redirects.
+                    r'http://www.python.org/dev/peps/pep-\d+']
+
+
+# Options for extensions
+# ----------------------
+
+# Relative filename of the reference count data file.
+refcount_file = 'data/refcounts.dat'

third_party/python/Doc/contents.rst

@@ -0,0 +1,31 @@
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+ Python Documentation contents
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+.. toctree::
+
+   whatsnew/index.rst
+   tutorial/index.rst
+   using/index.rst
+   reference/index.rst
+   library/index.rst
+   extending/index.rst
+   c-api/index.rst
+   distributing/index.rst
+   installing/index.rst
+   howto/index.rst
+   faq/index.rst
+   glossary.rst
+
+   about.rst
+   bugs.rst
+   copyright.rst
+   license.rst
+
+.. to include legacy packaging docs in build
+
+.. toctree::
+   :hidden:
+
+   distutils/index.rst
+   install/index.rst

third_party/python/Doc/copyright.rst

@@ -0,0 +1,19 @@
+*********
+Copyright
+*********
+
+Python and this documentation is:
+
+Copyright © 2001-2021 Python Software Foundation. All rights reserved.
+
+Copyright © 2000 BeOpen.com. All rights reserved.
+
+Copyright © 1995-2000 Corporation for National Research Initiatives. All rights
+reserved.
+
+Copyright © 1991-1995 Stichting Mathematisch Centrum. All rights reserved.
+
+-------
+
+See :ref:`history-and-license` for complete license and permissions information.
+

third_party/python/Doc/distributing/index.rst

@@ -0,0 +1,170 @@
+.. _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 <installing-index>`.
+
+.. 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 Packaging Index <https://pypi.org>`__ is a public
+  repository of open source licensed packages made available for use by
+  other Python users
+* the `Python Packaging Authority
+  <https://www.pypa.io/>`__ 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 both `GitHub <https://github.com/pypa>`__ and
+  `BitBucket <https://bitbucket.org/pypa/>`__.
+* :mod:`distutils` is the original build and distribution system first added
+  to the Python standard library in 1998. While direct use of :mod:`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 :mod:`distutils` first
+  published in 2004. Its most notable addition over the unmodified
+  :mod:`distutils` tools was the ability to declare dependencies on other
+  packages. It is currently recommended as a more regularly updated
+  alternative to :mod:`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 :mod:`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.org
+
+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 Mac OS X 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/en/latest/current/#packaging-tool-recommendations
+
+Reading the guide
+=================
+
+The Python Packaging User Guide covers the various key steps and elements
+involved in creating a project:
+
+* `Project structure`_
+* `Building and packaging the project`_
+* `Uploading the project to the Python Packaging Index`_
+
+.. _Project structure: \
+   https://packaging.python.org/en/latest/distributing/
+.. _Building and packaging the project: \
+   https://packaging.python.org/en/latest/distributing/#packaging-your-project
+.. _Uploading the project to the Python Packaging Index: \
+   https://packaging.python.org/en/latest/distributing/#uploading-your-project-to-pypi
+
+
+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 Packaging 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
+   <https://packaging.python.org/en/latest/extensions>`__
+
+.. other topics:
+
+   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/)

third_party/python/Doc/distutils/builtdist.rst

@@ -0,0 +1,459 @@
+.. _built-dist:
+
+****************************
+Creating Built Distributions
+****************************
+
+A "built distribution" is what you're probably used to thinking of either as a
+"binary package" or an "installer" (depending on your background).  It's not
+necessarily binary, though, because it might contain only Python source code
+and/or byte-code; and we don't call it a package, because that word is already
+spoken for in Python.  (And "installer" is a term specific to the world of
+mainstream desktop systems.)
+
+A built distribution is how you make life as easy as possible for installers of
+your module distribution: for users of RPM-based Linux systems, it's a binary
+RPM; for Windows users, it's an executable installer; for Debian-based Linux
+users, it's a Debian package; and so forth.  Obviously, no one person will be
+able to create built distributions for every platform under the sun, so the
+Distutils are designed to enable module developers to concentrate on their
+specialty---writing code and creating source distributions---while an
+intermediary species called *packagers* springs up to turn source distributions
+into built distributions for as many platforms as there are packagers.
+
+Of course, the module developer could be their own packager; or the packager could
+be a volunteer "out there" somewhere who has access to a platform which the
+original developer does not; or it could be software periodically grabbing new
+source distributions and turning them into built distributions for as many
+platforms as the software has access to.  Regardless of who they are, a packager
+uses the setup script and the :command:`bdist` command family to generate built
+distributions.
+
+As a simple example, if I run the following command in the Distutils source
+tree::
+
+   python setup.py bdist
+
+then the Distutils builds my module distribution (the Distutils itself in this
+case), does a "fake" installation (also in the :file:`build` directory), and
+creates the default type of built distribution for my platform.  The default
+format for built distributions is a "dumb" tar file on Unix, and a simple
+executable installer on Windows.  (That tar file is considered "dumb" because it
+has to be unpacked in a specific location to work.)
+
+Thus, the above command on a Unix system creates
+:file:`Distutils-1.0.{plat}.tar.gz`; unpacking this tarball from the right place
+installs the Distutils just as though you had downloaded the source distribution
+and run ``python setup.py install``.  (The "right place" is either the root of
+the filesystem or  Python's :file:`{prefix}` directory, depending on the options
+given to the :command:`bdist_dumb` command; the default is to make dumb
+distributions relative to :file:`{prefix}`.)
+
+Obviously, for pure Python distributions, this isn't any simpler than just
+running ``python setup.py install``\ ---but for non-pure distributions, which
+include extensions that would need to be compiled, it can mean the difference
+between someone being able to use your extensions or not.  And creating "smart"
+built distributions, such as an RPM package or an executable installer for
+Windows, is far more convenient for users even if your distribution doesn't
+include any extensions.
+
+The :command:`bdist` command has a :option:`!--formats` option, similar to the
+:command:`sdist` command, which you can use to select the types of built
+distribution to generate: for example, ::
+
+   python setup.py bdist --format=zip
+
+would, when run on a Unix system, create
+:file:`Distutils-1.0.{plat}.zip`\ ---again, this archive would be unpacked
+from the root directory to install the Distutils.
+
+The available formats for built distributions are:
+
++-------------+------------------------------+---------+
+| Format      | Description                  | Notes   |
++=============+==============================+=========+
+| ``gztar``   | gzipped tar file             | \(1)    |
+|             | (:file:`.tar.gz`)            |         |
++-------------+------------------------------+---------+
+| ``bztar``   | bzipped tar file             |         |
+|             | (:file:`.tar.bz2`)           |         |
++-------------+------------------------------+---------+
+| ``xztar``   | xzipped tar file             |         |
+|             | (:file:`.tar.xz`)            |         |
++-------------+------------------------------+---------+
+| ``ztar``    | compressed tar file          | \(3)    |
+|             | (:file:`.tar.Z`)             |         |
++-------------+------------------------------+---------+
+| ``tar``     | tar file (:file:`.tar`)      |         |
++-------------+------------------------------+---------+
+| ``zip``     | zip file (:file:`.zip`)      | (2),(4) |
++-------------+------------------------------+---------+
+| ``rpm``     | RPM                          | \(5)    |
++-------------+------------------------------+---------+
+| ``pkgtool`` | Solaris :program:`pkgtool`   |         |
++-------------+------------------------------+---------+
+| ``sdux``    | HP-UX :program:`swinstall`   |         |
++-------------+------------------------------+---------+
+| ``wininst`` | self-extracting ZIP file for | \(4)    |
+|             | Windows                      |         |
++-------------+------------------------------+---------+
+| ``msi``     | Microsoft Installer.         |         |
++-------------+------------------------------+---------+
+
+.. versionchanged:: 3.5
+   Added support for the ``xztar`` format.
+
+
+Notes:
+
+(1)
+   default on Unix
+
+(2)
+   default on Windows
+
+(3)
+   requires external :program:`compress` utility.
+
+(4)
+   requires either external :program:`zip` utility or :mod:`zipfile` module (part
+   of the standard Python library since Python 1.6)
+
+(5)
+   requires external :program:`rpm` utility, version 3.0.4 or better (use ``rpm
+   --version`` to find out which version you have)
+
+You don't have to use the :command:`bdist` command with the :option:`!--formats`
+option; you can also use the command that directly implements the format you're
+interested in.  Some of these :command:`bdist` "sub-commands" actually generate
+several similar formats; for instance, the :command:`bdist_dumb` command
+generates all the "dumb" archive formats (``tar``, ``gztar``, ``bztar``,
+``xztar``, ``ztar``, and ``zip``), and :command:`bdist_rpm` generates both
+binary and source RPMs.  The :command:`bdist` sub-commands, and the formats
+generated by each, are:
+
++--------------------------+-------------------------------------+
+| Command                  | Formats                             |
++==========================+=====================================+
+| :command:`bdist_dumb`    | tar, gztar, bztar, xztar, ztar, zip |
++--------------------------+-------------------------------------+
+| :command:`bdist_rpm`     | rpm, srpm                           |
++--------------------------+-------------------------------------+
+| :command:`bdist_wininst` | wininst                             |
++--------------------------+-------------------------------------+
+| :command:`bdist_msi`     | msi                                 |
++--------------------------+-------------------------------------+
+
+The following sections give details on the individual :command:`bdist_\*`
+commands.
+
+
+.. .. _creating-dumb:
+
+.. Creating dumb built distributions
+.. =================================
+
+.. XXX Need to document absolute vs. prefix-relative packages here, but first
+   I have to implement it!
+
+
+.. _creating-rpms:
+
+Creating RPM packages
+=====================
+
+The RPM format is used by many popular Linux distributions, including Red Hat,
+SuSE, and Mandrake.  If one of these (or any of the other RPM-based Linux
+distributions) is your usual environment, creating RPM packages for other users
+of that same distribution is trivial. Depending on the complexity of your module
+distribution and differences between Linux distributions, you may also be able
+to create RPMs that work on different RPM-based distributions.
+
+The usual way to create an RPM of your module distribution is to run the
+:command:`bdist_rpm` command::
+
+   python setup.py bdist_rpm
+
+or the :command:`bdist` command with the :option:`!--format` option::
+
+   python setup.py bdist --formats=rpm
+
+The former allows you to specify RPM-specific options; the latter allows  you to
+easily specify multiple formats in one run.  If you need to do both, you can
+explicitly specify multiple :command:`bdist_\*` commands and their options::
+
+   python setup.py bdist_rpm --packager="John Doe <jdoe@example.org>" \
+                   bdist_wininst --target-version="2.0"
+
+Creating RPM packages is driven by a :file:`.spec` file, much as using the
+Distutils is driven by the setup script.  To make your life easier, the
+:command:`bdist_rpm` command normally creates a :file:`.spec` file based on the
+information you supply in the setup script, on the command line, and in any
+Distutils configuration files.  Various options and sections in the
+:file:`.spec` file are derived from options in the setup script as follows:
+
++------------------------------------------+----------------------------------------------+
+| RPM :file:`.spec` file option or section | Distutils setup script option                |
++==========================================+==============================================+
+| Name                                     | ``name``                                     |
++------------------------------------------+----------------------------------------------+
+| Summary (in preamble)                    | ``description``                              |
++------------------------------------------+----------------------------------------------+
+| Version                                  | ``version``                                  |
++------------------------------------------+----------------------------------------------+
+| Vendor                                   | ``author`` and ``author_email``,             |
+|                                          | or  --- & ``maintainer`` and                 |
+|                                          | ``maintainer_email``                         |
++------------------------------------------+----------------------------------------------+
+| Copyright                                | ``license``                                  |
++------------------------------------------+----------------------------------------------+
+| Url                                      | ``url``                                      |
++------------------------------------------+----------------------------------------------+
+| %description (section)                   | ``long_description``                         |
++------------------------------------------+----------------------------------------------+
+
+Additionally, there are many options in :file:`.spec` files that don't have
+corresponding options in the setup script.  Most of these are handled through
+options to the :command:`bdist_rpm` command as follows:
+
++-------------------------------+-----------------------------+-------------------------+
+| RPM :file:`.spec` file option | :command:`bdist_rpm` option | default value           |
+| or section                    |                             |                         |
++===============================+=============================+=========================+
+| Release                       | ``release``                 | "1"                     |
++-------------------------------+-----------------------------+-------------------------+
+| Group                         | ``group``                   | "Development/Libraries" |
++-------------------------------+-----------------------------+-------------------------+
+| Vendor                        | ``vendor``                  | (see above)             |
++-------------------------------+-----------------------------+-------------------------+
+| Packager                      | ``packager``                | (none)                  |
++-------------------------------+-----------------------------+-------------------------+
+| Provides                      | ``provides``                | (none)                  |
++-------------------------------+-----------------------------+-------------------------+
+| Requires                      | ``requires``                | (none)                  |
++-------------------------------+-----------------------------+-------------------------+
+| Conflicts                     | ``conflicts``               | (none)                  |
++-------------------------------+-----------------------------+-------------------------+
+| Obsoletes                     | ``obsoletes``               | (none)                  |
++-------------------------------+-----------------------------+-------------------------+
+| Distribution                  | ``distribution_name``       | (none)                  |
++-------------------------------+-----------------------------+-------------------------+
+| BuildRequires                 | ``build_requires``          | (none)                  |
++-------------------------------+-----------------------------+-------------------------+
+| Icon                          | ``icon``                    | (none)                  |
++-------------------------------+-----------------------------+-------------------------+
+
+Obviously, supplying even a few of these options on the command-line would be
+tedious and error-prone, so it's usually best to put them in the setup
+configuration file, :file:`setup.cfg`\ ---see section :ref:`setup-config`.  If
+you distribute or package many Python module distributions, you might want to
+put options that apply to all of them in your personal Distutils configuration
+file (:file:`~/.pydistutils.cfg`).  If you want to temporarily disable
+this file, you can pass the :option:`!--no-user-cfg` option to :file:`setup.py`.
+
+There are three steps to building a binary RPM package, all of which are
+handled automatically by the Distutils:
+
+#. create a :file:`.spec` file, which describes the package (analogous  to the
+   Distutils setup script; in fact, much of the information in the  setup script
+   winds up in the :file:`.spec` file)
+
+#. create the source RPM
+
+#. create the "binary" RPM (which may or may not contain binary code, depending
+   on whether your module distribution contains Python extensions)
+
+Normally, RPM bundles the last two steps together; when you use the Distutils,
+all three steps are typically bundled together.
+
+If you wish, you can separate these three steps.  You can use the
+:option:`!--spec-only` option to make :command:`bdist_rpm` just create the
+:file:`.spec` file and exit; in this case, the :file:`.spec` file will be
+written to the "distribution directory"---normally :file:`dist/`, but
+customizable with the :option:`!--dist-dir` option.  (Normally, the :file:`.spec`
+file winds up deep in the "build tree," in a temporary directory created by
+:command:`bdist_rpm`.)
+
+.. % \XXX{this isn't implemented yet---is it needed?!}
+.. % You can also specify a custom \file{.spec} file with the
+.. % \longprogramopt{spec-file} option; used in conjunction with
+.. % \longprogramopt{spec-only}, this gives you an opportunity to customize
+.. % the \file{.spec} file manually:
+.. %
+.. % \ begin{verbatim}
+.. % > python setup.py bdist_rpm --spec-only
+.. % # ...edit dist/FooBar-1.0.spec
+.. % > python setup.py bdist_rpm --spec-file=dist/FooBar-1.0.spec
+.. % \ end{verbatim}
+.. %
+.. % (Although a better way to do this is probably to override the standard
+.. % \command{bdist\_rpm} command with one that writes whatever else you want
+.. % to the \file{.spec} file.)
+
+
+.. _creating-wininst:
+
+Creating Windows Installers
+===========================
+
+Executable installers are the natural format for binary distributions on
+Windows.  They display a nice graphical user interface, display some information
+about the module distribution to be installed taken from the metadata in the
+setup script, let the user select a few options, and start or cancel the
+installation.
+
+Since the metadata is taken from the setup script, creating Windows installers
+is usually as easy as running::
+
+   python setup.py bdist_wininst
+
+or the :command:`bdist` command with the :option:`!--formats` option::
+
+   python setup.py bdist --formats=wininst
+
+If you have a pure module distribution (only containing pure Python modules and
+packages), the resulting installer will be version independent and have a name
+like :file:`foo-1.0.win32.exe`.  These installers can even be created on Unix
+platforms or Mac OS X.
+
+If you have a non-pure distribution, the extensions can only be created on a
+Windows platform, and will be Python version dependent. The installer filename
+will reflect this and now has the form :file:`foo-1.0.win32-py2.0.exe`.  You
+have to create a separate installer for every Python version you want to
+support.
+
+The installer will try to compile pure modules into :term:`bytecode` after installation
+on the target system in normal and optimizing mode.  If you don't want this to
+happen for some reason, you can run the :command:`bdist_wininst` command with
+the :option:`!--no-target-compile` and/or the :option:`!--no-target-optimize`
+option.
+
+By default the installer will display the cool "Python Powered" logo when it is
+run, but you can also supply your own 152x261 bitmap which must be a Windows
+:file:`.bmp` file with the :option:`!--bitmap` option.
+
+The installer will also display a large title on the desktop background window
+when it is run, which is constructed from the name of your distribution and the
+version number.  This can be changed to another text by using the
+:option:`!--title` option.
+
+The installer file will be written to the "distribution directory" --- normally
+:file:`dist/`, but customizable with the :option:`!--dist-dir` option.
+
+.. _cross-compile-windows:
+
+Cross-compiling on Windows
+==========================
+
+Starting with Python 2.6, distutils is capable of cross-compiling between
+Windows platforms.  In practice, this means that with the correct tools
+installed, you can use a 32bit version of Windows to create 64bit extensions
+and vice-versa.
+
+To build for an alternate platform, specify the :option:`!--plat-name` option
+to the build command.  Valid values are currently 'win32', 'win-amd64' and
+'win-ia64'.  For example, on a 32bit version of Windows, you could execute::
+
+   python setup.py build --plat-name=win-amd64
+
+to build a 64bit version of your extension.  The Windows Installers also
+support this option, so the command::
+
+   python setup.py build --plat-name=win-amd64 bdist_wininst
+
+would create a 64bit installation executable on your 32bit version of Windows.
+
+To cross-compile, you must download the Python source code and cross-compile
+Python itself for the platform you are targeting - it is not possible from a
+binary installation of Python (as the .lib etc file for other platforms are
+not included.)  In practice, this means the user of a 32 bit operating
+system will need to use Visual Studio 2008 to open the
+:file:`PCBuild/PCbuild.sln` solution in the Python source tree and build the
+"x64" configuration of the 'pythoncore' project before cross-compiling
+extensions is possible.
+
+Note that by default, Visual Studio 2008 does not install 64bit compilers or
+tools.  You may need to reexecute the Visual Studio setup process and select
+these tools (using Control Panel->[Add/Remove] Programs is a convenient way to
+check or modify your existing install.)
+
+.. _postinstallation-script:
+
+The Postinstallation script
+---------------------------
+
+Starting with Python 2.3, a postinstallation script can be specified with the
+:option:`!--install-script` option.  The basename of the script must be
+specified, and the script filename must also be listed in the scripts argument
+to the setup function.
+
+This script will be run at installation time on the target system after all the
+files have been copied, with ``argv[1]`` set to :option:`!-install`, and again at
+uninstallation time before the files are removed with ``argv[1]`` set to
+:option:`!-remove`.
+
+The installation script runs embedded in the windows installer, every output
+(``sys.stdout``, ``sys.stderr``) is redirected into a buffer and will be
+displayed in the GUI after the script has finished.
+
+Some functions especially useful in this context are available as additional
+built-in functions in the installation script.
+
+
+.. function:: directory_created(path)
+              file_created(path)
+
+   These functions should be called when a directory or file is created by the
+   postinstall script at installation time.  It will register *path* with the
+   uninstaller, so that it will be removed when the distribution is uninstalled.
+   To be safe, directories are only removed if they are empty.
+
+
+.. function:: get_special_folder_path(csidl_string)
+
+   This function can be used to retrieve special folder locations on Windows like
+   the Start Menu or the Desktop.  It returns the full path to the folder.
+   *csidl_string* must be one of the following strings::
+
+      "CSIDL_APPDATA"
+
+      "CSIDL_COMMON_STARTMENU"
+      "CSIDL_STARTMENU"
+
+      "CSIDL_COMMON_DESKTOPDIRECTORY"
+      "CSIDL_DESKTOPDIRECTORY"
+
+      "CSIDL_COMMON_STARTUP"
+      "CSIDL_STARTUP"
+
+      "CSIDL_COMMON_PROGRAMS"
+      "CSIDL_PROGRAMS"
+
+      "CSIDL_FONTS"
+
+   If the folder cannot be retrieved, :exc:`OSError` is raised.
+
+   Which folders are available depends on the exact Windows version, and probably
+   also the configuration.  For details refer to Microsoft's documentation of the
+   :c:func:`SHGetSpecialFolderPath` function.
+
+
+.. function:: create_shortcut(target, description, filename[, arguments[, workdir[, iconpath[, iconindex]]]])
+
+   This function creates a shortcut. *target* is the path to the program to be
+   started by the shortcut. *description* is the description of the shortcut.
+   *filename* is the title of the shortcut that the user will see. *arguments*
+   specifies the command line arguments, if any. *workdir* is the working directory
+   for the program. *iconpath* is the file containing the icon for the shortcut,
+   and *iconindex* is the index of the icon in the file *iconpath*.  Again, for
+   details consult the Microsoft documentation for the :class:`IShellLink`
+   interface.
+
+
+Vista User Access Control (UAC)
+===============================
+
+Starting with Python 2.6, bdist_wininst supports a :option:`!--user-access-control`
+option.  The default is 'none' (meaning no UAC handling is done), and other
+valid values are 'auto' (meaning prompt for UAC elevation if Python was
+installed for all users) and 'force' (meaning always prompt for elevation).

third_party/python/Doc/distutils/commandref.rst

@@ -0,0 +1,104 @@
+.. _reference:
+
+*****************
+Command Reference
+*****************
+
+.. % \section{Building modules: the \protect\command{build} command family}
+.. % \label{build-cmds}
+.. % \subsubsection{\protect\command{build}}
+.. % \label{build-cmd}
+.. % \subsubsection{\protect\command{build\_py}}
+.. % \label{build-py-cmd}
+.. % \subsubsection{\protect\command{build\_ext}}
+.. % \label{build-ext-cmd}
+.. % \subsubsection{\protect\command{build\_clib}}
+.. % \label{build-clib-cmd}
+
+
+.. _install-cmd:
+
+Installing modules: the :command:`install` command family
+=========================================================
+
+The install command ensures that the build commands have been run and then runs
+the subcommands :command:`install_lib`, :command:`install_data` and
+:command:`install_scripts`.
+
+.. % \subsubsection{\protect\command{install\_lib}}
+.. % \label{install-lib-cmd}
+
+
+.. _install-data-cmd:
+
+:command:`install_data`
+-----------------------
+
+This command installs all data files provided with the distribution.
+
+
+.. _install-scripts-cmd:
+
+:command:`install_scripts`
+--------------------------
+
+This command installs all (Python) scripts in the distribution.
+
+.. % \subsection{Cleaning up: the \protect\command{clean} command}
+.. % \label{clean-cmd}
+
+
+.. _sdist-cmd:
+
+Creating a source distribution: the :command:`sdist` command
+============================================================
+
+.. XXX fragment moved down from above: needs context!
+
+The manifest template commands are:
+
++-------------------------------------------+-----------------------------------------------+
+| Command                                   | Description                                   |
++===========================================+===============================================+
+| :command:`include pat1 pat2 ...`          | include all files matching any of the listed  |
+|                                           | patterns                                      |
++-------------------------------------------+-----------------------------------------------+
+| :command:`exclude pat1 pat2 ...`          | exclude all files matching any of the listed  |
+|                                           | patterns                                      |
++-------------------------------------------+-----------------------------------------------+
+| :command:`recursive-include dir pat1 pat2 | include all files under *dir* matching any of |
+| ...`                                      | the listed patterns                           |
++-------------------------------------------+-----------------------------------------------+
+| :command:`recursive-exclude dir pat1 pat2 | exclude all files under *dir* matching any of |
+| ...`                                      | the listed patterns                           |
++-------------------------------------------+-----------------------------------------------+
+| :command:`global-include pat1 pat2 ...`   | include all files anywhere in the source tree |
+|                                           | matching --- & any of the listed patterns     |
++-------------------------------------------+-----------------------------------------------+
+| :command:`global-exclude pat1 pat2 ...`   | exclude all files anywhere in the source tree |
+|                                           | matching --- & any of the listed patterns     |
++-------------------------------------------+-----------------------------------------------+
+| :command:`prune dir`                      | exclude all files under *dir*                 |
++-------------------------------------------+-----------------------------------------------+
+| :command:`graft dir`                      | include all files under *dir*                 |
++-------------------------------------------+-----------------------------------------------+
+
+The patterns here are Unix-style "glob" patterns: ``*`` matches any sequence of
+regular filename characters, ``?`` matches any single regular filename
+character, and ``[range]`` matches any of the characters in *range* (e.g.,
+``a-z``, ``a-zA-Z``, ``a-f0-9_.``).  The definition of "regular filename
+character" is platform-specific: on Unix it is anything except slash; on Windows
+anything except backslash or colon.
+
+.. XXX Windows support not there yet
+
+.. % \section{Creating a built distribution: the
+.. % \protect\command{bdist} command family}
+.. % \label{bdist-cmds}
+
+.. % \subsection{\protect\command{bdist}}
+.. % \subsection{\protect\command{bdist\_dumb}}
+.. % \subsection{\protect\command{bdist\_rpm}}
+.. % \subsection{\protect\command{bdist\_wininst}}
+
+

third_party/python/Doc/distutils/configfile.rst

@@ -0,0 +1,142 @@
+.. _setup-config:
+
+************************************
+Writing the Setup Configuration File
+************************************
+
+Often, it's not possible to write down everything needed to build a distribution
+*a priori*: you may need to get some information from the user, or from the
+user's system, in order to proceed.  As long as that information is fairly
+simple---a list of directories to search for C header files or libraries, for
+example---then providing a configuration file, :file:`setup.cfg`, for users to
+edit is a cheap and easy way to solicit it.  Configuration files also let you
+provide default values for any command option, which the installer can then
+override either on the command-line or by editing the config file.
+
+The setup configuration file is a useful middle-ground between the setup
+script---which, ideally, would be opaque to installers [#]_---and the command-line to
+the setup script, which is outside of your control and entirely up to the
+installer.  In fact, :file:`setup.cfg` (and any other Distutils configuration
+files present on the target system) are processed after the contents of the
+setup script, but before the command-line.  This has  several useful
+consequences:
+
+.. % (If you have more advanced needs, such as determining which extensions
+.. % to build based on what capabilities are present on the target system,
+.. % then you need the Distutils ``auto-configuration'' facility.  This
+.. % started to appear in Distutils 0.9 but, as of this writing, isn't mature
+.. % or stable enough yet for real-world use.)
+
+* installers can override some of what you put in :file:`setup.py` by editing
+  :file:`setup.cfg`
+
+* you can provide non-standard defaults for options that are not easily set in
+  :file:`setup.py`
+
+* installers can override anything in :file:`setup.cfg` using the command-line
+  options to :file:`setup.py`
+
+The basic syntax of the configuration file is simple:
+
+.. code-block:: ini
+
+   [command]
+   option=value
+   ...
+
+where *command* is one of the Distutils commands (e.g. :command:`build_py`,
+:command:`install`), and *option* is one of the options that command supports.
+Any number of options can be supplied for each command, and any number of
+command sections can be included in the file.  Blank lines are ignored, as are
+comments, which run from a ``'#'`` character until the end of the line.  Long
+option values can be split across multiple lines simply by indenting the
+continuation lines.
+
+You can find out the list of options supported by a particular command with the
+universal :option:`!--help` option, e.g.
+
+.. code-block:: shell-session
+
+   $ python setup.py --help build_ext
+   [...]
+   Options for 'build_ext' command:
+     --build-lib (-b)     directory for compiled extension modules
+     --build-temp (-t)    directory for temporary files (build by-products)
+     --inplace (-i)       ignore build-lib and put compiled extensions into the
+                          source directory alongside your pure Python modules
+     --include-dirs (-I)  list of directories to search for header files
+     --define (-D)        C preprocessor macros to define
+     --undef (-U)         C preprocessor macros to undefine
+     --swig-opts          list of SWIG command line options
+   [...]
+
+Note that an option spelled :option:`!--foo-bar` on the command-line  is spelled
+``foo_bar`` in configuration files.
+
+.. _distutils-build-ext-inplace:
+
+For example, say you want your extensions to be built "in-place"---that is, you
+have an extension :mod:`pkg.ext`, and you want the compiled extension file
+(:file:`ext.so` on Unix, say) to be put in the same source directory as your
+pure Python modules :mod:`pkg.mod1` and :mod:`pkg.mod2`.  You can always use the
+:option:`!--inplace` option on the command-line to ensure this:
+
+.. code-block:: sh
+
+   python setup.py build_ext --inplace
+
+But this requires that you always specify the :command:`build_ext` command
+explicitly, and remember to provide :option:`!--inplace`. An easier way is to
+"set and forget" this option, by encoding it in :file:`setup.cfg`, the
+configuration file for this distribution:
+
+.. code-block:: ini
+
+   [build_ext]
+   inplace=1
+
+This will affect all builds of this module distribution, whether or not you
+explicitly specify :command:`build_ext`.  If you include :file:`setup.cfg` in
+your source distribution, it will also affect end-user builds---which is
+probably a bad idea for this option, since always building extensions in-place
+would break installation of the module distribution.  In certain peculiar cases,
+though, modules are built right in their installation directory, so this is
+conceivably a useful ability.  (Distributing extensions that expect to be built
+in their installation directory is almost always a bad idea, though.)
+
+Another example: certain commands take a lot of options that don't change from
+run to run; for example, :command:`bdist_rpm` needs to know everything required
+to generate a "spec" file for creating an RPM distribution.  Some of this
+information comes from the setup script, and some is automatically generated by
+the Distutils (such as the list of files installed).  But some of it has to be
+supplied as options to :command:`bdist_rpm`, which would be very tedious to do
+on the command-line for every run.  Hence, here is a snippet from the Distutils'
+own :file:`setup.cfg`:
+
+.. code-block:: ini
+
+   [bdist_rpm]
+   release = 1
+   packager = Greg Ward <gward@python.net>
+   doc_files = CHANGES.txt
+               README.txt
+               USAGE.txt
+               doc/
+               examples/
+
+Note that the ``doc_files`` option is simply a whitespace-separated string
+split across multiple lines for readability.
+
+
+.. seealso::
+
+   :ref:`inst-config-syntax` in "Installing Python Modules"
+      More information on the configuration files is available in the manual for
+      system administrators.
+
+
+.. rubric:: Footnotes
+
+.. [#] This ideal probably won't be achieved until auto-configuration is fully
+   supported by the Distutils.
+

third_party/python/Doc/distutils/examples.rst

@@ -0,0 +1,338 @@
+.. _examples:
+
+********
+Examples
+********
+
+This chapter provides a number of basic examples to help get started with
+distutils.  Additional information about using distutils can be found in the
+Distutils Cookbook.
+
+
+.. seealso::
+
+   `Distutils Cookbook <https://wiki.python.org/moin/Distutils/Cookbook>`_
+      Collection of recipes showing how to achieve more control over distutils.
+
+
+.. _pure-mod:
+
+Pure Python distribution (by module)
+====================================
+
+If you're just distributing a couple of modules, especially if they don't live
+in a particular package, you can specify them individually using the
+``py_modules`` option in the setup script.
+
+In the simplest case, you'll have two files to worry about: a setup script and
+the single module you're distributing, :file:`foo.py` in this example::
+
+   <root>/
+           setup.py
+           foo.py
+
+(In all diagrams in this section, *<root>* will refer to the distribution root
+directory.)  A minimal setup script to describe this situation would be::
+
+   from distutils.core import setup
+   setup(name='foo',
+         version='1.0',
+         py_modules=['foo'],
+         )
+
+Note that the name of the distribution is specified independently with the
+``name`` option, and there's no rule that says it has to be the same as
+the name of the sole module in the distribution (although that's probably a good
+convention to follow).  However, the distribution name is used to generate
+filenames, so you should stick to letters, digits, underscores, and hyphens.
+
+Since ``py_modules`` is a list, you can of course specify multiple
+modules, eg. if you're distributing modules :mod:`foo` and :mod:`bar`, your
+setup might look like this::
+
+   <root>/
+           setup.py
+           foo.py
+           bar.py
+
+and the setup script might be  ::
+
+   from distutils.core import setup
+   setup(name='foobar',
+         version='1.0',
+         py_modules=['foo', 'bar'],
+         )
+
+You can put module source files into another directory, but if you have enough
+modules to do that, it's probably easier to specify modules by package rather
+than listing them individually.
+
+
+.. _pure-pkg:
+
+Pure Python distribution (by package)
+=====================================
+
+If you have more than a couple of modules to distribute, especially if they are
+in multiple packages, it's probably easier to specify whole packages rather than
+individual modules.  This works even if your modules are not in a package; you
+can just tell the Distutils to process modules from the root package, and that
+works the same as any other package (except that you don't have to have an
+:file:`__init__.py` file).
+
+The setup script from the last example could also be written as  ::
+
+   from distutils.core import setup
+   setup(name='foobar',
+         version='1.0',
+         packages=[''],
+         )
+
+(The empty string stands for the root package.)
+
+If those two files are moved into a subdirectory, but remain in the root
+package, e.g.::
+
+   <root>/
+           setup.py
+           src/      foo.py
+                     bar.py
+
+then you would still specify the root package, but you have to tell the
+Distutils where source files in the root package live::
+
+   from distutils.core import setup
+   setup(name='foobar',
+         version='1.0',
+         package_dir={'': 'src'},
+         packages=[''],
+         )
+
+More typically, though, you will want to distribute multiple modules in the same
+package (or in sub-packages).  For example, if the :mod:`foo`  and :mod:`bar`
+modules belong in package :mod:`foobar`, one way to layout your source tree is
+::
+
+   <root>/
+           setup.py
+           foobar/
+                    __init__.py
+                    foo.py
+                    bar.py
+
+This is in fact the default layout expected by the Distutils, and the one that
+requires the least work to describe in your setup script::
+
+   from distutils.core import setup
+   setup(name='foobar',
+         version='1.0',
+         packages=['foobar'],
+         )
+
+If you want to put modules in directories not named for their package, then you
+need to use the ``package_dir`` option again.  For example, if the
+:file:`src` directory holds modules in the :mod:`foobar` package::
+
+   <root>/
+           setup.py
+           src/
+                    __init__.py
+                    foo.py
+                    bar.py
+
+an appropriate setup script would be  ::
+
+   from distutils.core import setup
+   setup(name='foobar',
+         version='1.0',
+         package_dir={'foobar': 'src'},
+         packages=['foobar'],
+         )
+
+Or, you might put modules from your main package right in the distribution
+root::
+
+   <root>/
+           setup.py
+           __init__.py
+           foo.py
+           bar.py
+
+in which case your setup script would be  ::
+
+   from distutils.core import setup
+   setup(name='foobar',
+         version='1.0',
+         package_dir={'foobar': ''},
+         packages=['foobar'],
+         )
+
+(The empty string also stands for the current directory.)
+
+If you have sub-packages, they must be explicitly listed in ``packages``,
+but any entries in ``package_dir`` automatically extend to sub-packages.
+(In other words, the Distutils does *not* scan your source tree, trying to
+figure out which directories correspond to Python packages by looking for
+:file:`__init__.py` files.)  Thus, if the default layout grows a sub-package::
+
+   <root>/
+           setup.py
+           foobar/
+                    __init__.py
+                    foo.py
+                    bar.py
+                    subfoo/
+                              __init__.py
+                              blah.py
+
+then the corresponding setup script would be  ::
+
+   from distutils.core import setup
+   setup(name='foobar',
+         version='1.0',
+         packages=['foobar', 'foobar.subfoo'],
+         )
+
+
+.. _single-ext:
+
+Single extension module
+=======================
+
+Extension modules are specified using the ``ext_modules`` option.
+``package_dir`` has no effect on where extension source files are found;
+it only affects the source for pure Python modules.  The simplest  case, a
+single extension module in a single C source file, is::
+
+   <root>/
+           setup.py
+           foo.c
+
+If the :mod:`foo` extension belongs in the root package, the setup script for
+this could be  ::
+
+   from distutils.core import setup
+   from distutils.extension import Extension
+   setup(name='foobar',
+         version='1.0',
+         ext_modules=[Extension('foo', ['foo.c'])],
+         )
+
+If the extension actually belongs in a package, say :mod:`foopkg`, then
+
+With exactly the same source tree layout, this extension can be put in the
+:mod:`foopkg` package simply by changing the name of the extension::
+
+   from distutils.core import setup
+   from distutils.extension import Extension
+   setup(name='foobar',
+         version='1.0',
+         ext_modules=[Extension('foopkg.foo', ['foo.c'])],
+         )
+
+Checking a package
+==================
+
+The ``check`` command allows you to verify if your package meta-data
+meet the minimum requirements to build a distribution.
+
+To run it, just call it using your :file:`setup.py` script. If something is
+missing, ``check`` will display a warning.
+
+Let's take an example with a simple script::
+
+    from distutils.core import setup
+
+    setup(name='foobar')
+
+Running the ``check`` command will display some warnings:
+
+.. code-block:: shell-session
+
+    $ python setup.py check
+    running check
+    warning: check: missing required meta-data: version, url
+    warning: check: missing meta-data: either (author and author_email) or
+             (maintainer and maintainer_email) must be supplied
+
+
+If you use the reStructuredText syntax in the ``long_description`` field and
+`docutils`_  is installed you can check if the syntax is fine with the
+``check`` command, using the ``restructuredtext`` option.
+
+For example, if the :file:`setup.py` script is changed like this::
+
+    from distutils.core import setup
+
+    desc = """\
+    My description
+    ==============
+
+    This is the description of the ``foobar`` package.
+    """
+
+    setup(name='foobar', version='1', author='tarek',
+        author_email='tarek@ziade.org',
+        url='http://example.com', long_description=desc)
+
+Where the long description is broken, ``check`` will be able to detect it
+by using the :mod:`docutils` parser:
+
+.. code-block:: shell-session
+
+    $ python setup.py check --restructuredtext
+    running check
+    warning: check: Title underline too short. (line 2)
+    warning: check: Could not finish the parsing.
+
+Reading the metadata
+=====================
+
+The :func:`distutils.core.setup` function provides a command-line interface
+that allows you to query the metadata fields of a project through the
+``setup.py`` script of a given project:
+
+.. code-block:: shell-session
+
+    $ python setup.py --name
+    distribute
+
+This call reads the ``name`` metadata by running the
+:func:`distutils.core.setup`  function. Although, when a source or binary
+distribution is created with Distutils, the metadata fields are written
+in a static file called :file:`PKG-INFO`. When a Distutils-based project is
+installed in Python, the :file:`PKG-INFO` file is copied alongside the modules
+and packages of the distribution under :file:`NAME-VERSION-pyX.X.egg-info`,
+where ``NAME`` is the name of the project, ``VERSION`` its version as defined
+in the Metadata, and ``pyX.X`` the major and minor version of Python like
+``2.7`` or ``3.2``.
+
+You can read back this static file, by using the
+:class:`distutils.dist.DistributionMetadata` class and its
+:func:`read_pkg_file` method::
+
+    >>> from distutils.dist import DistributionMetadata
+    >>> metadata = DistributionMetadata()
+    >>> metadata.read_pkg_file(open('distribute-0.6.8-py2.7.egg-info'))
+    >>> metadata.name
+    'distribute'
+    >>> metadata.version
+    '0.6.8'
+    >>> metadata.description
+    'Easily download, build, install, upgrade, and uninstall Python packages'
+
+Notice that the class can also be instantiated with a metadata file path to
+loads its values::
+
+    >>> pkg_info_path = 'distribute-0.6.8-py2.7.egg-info'
+    >>> DistributionMetadata(pkg_info_path).name
+    'distribute'
+
+
+.. % \section{Multiple extension modules}
+.. % \label{multiple-ext}
+
+.. % \section{Putting it all together}
+
+
+.. _docutils: http://docutils.sourceforge.net

third_party/python/Doc/distutils/extending.rst

@@ -0,0 +1,96 @@
+.. _extending-distutils:
+
+*******************
+Extending Distutils
+*******************
+
+Distutils can be extended in various ways.  Most extensions take the form of new
+commands or replacements for existing commands.  New commands may be written to
+support new types of platform-specific packaging, for example, while
+replacements for existing commands may be made to modify details of how the
+command operates on a package.
+
+Most extensions of the distutils are made within :file:`setup.py` scripts that
+want to modify existing commands; many simply add a few file extensions that
+should be copied into packages in addition to :file:`.py` files as a
+convenience.
+
+Most distutils command implementations are subclasses of the
+:class:`distutils.cmd.Command` class.  New commands may directly inherit from
+:class:`Command`, while replacements often derive from :class:`Command`
+indirectly, directly subclassing the command they are replacing.  Commands are
+required to derive from :class:`Command`.
+
+.. % \section{Extending existing commands}
+.. % \label{extend-existing}
+
+.. % \section{Writing new commands}
+.. % \label{new-commands}
+.. % \XXX{Would an uninstall command be a good example here?}
+
+
+Integrating new commands
+========================
+
+There are different ways to integrate new command implementations into
+distutils.  The most difficult is to lobby for the inclusion of the new features
+in distutils itself, and wait for (and require) a version of Python that
+provides that support.  This is really hard for many reasons.
+
+The most common, and possibly the most reasonable for most needs, is to include
+the new implementations with your :file:`setup.py` script, and cause the
+:func:`distutils.core.setup` function use them::
+
+   from distutils.command.build_py import build_py as _build_py
+   from distutils.core import setup
+
+   class build_py(_build_py):
+       """Specialized Python source builder."""
+
+       # implement whatever needs to be different...
+
+   setup(cmdclass={'build_py': build_py},
+         ...)
+
+This approach is most valuable if the new implementations must be used to use a
+particular package, as everyone interested in the package will need to have the
+new command implementation.
+
+Beginning with Python 2.4, a third option is available, intended to allow new
+commands to be added which can support existing :file:`setup.py` scripts without
+requiring modifications to the Python installation.  This is expected to allow
+third-party extensions to provide support for additional packaging systems, but
+the commands can be used for anything distutils commands can be used for.  A new
+configuration option, ``command_packages`` (command-line option
+:option:`!--command-packages`), can be used to specify additional packages to be
+searched for modules implementing commands.  Like all distutils options, this
+can be specified on the command line or in a configuration file.  This option
+can only be set in the ``[global]`` section of a configuration file, or before
+any commands on the command line.  If set in a configuration file, it can be
+overridden from the command line; setting it to an empty string on the command
+line causes the default to be used.  This should never be set in a configuration
+file provided with a package.
+
+This new option can be used to add any number of packages to the list of
+packages searched for command implementations; multiple package names should be
+separated by commas.  When not specified, the search is only performed in the
+:mod:`distutils.command` package.  When :file:`setup.py` is run with the option
+``--command-packages distcmds,buildcmds``, however, the packages
+:mod:`distutils.command`, :mod:`distcmds`, and :mod:`buildcmds` will be searched
+in that order.  New commands are expected to be implemented in modules of the
+same name as the command by classes sharing the same name.  Given the example
+command line option above, the command :command:`bdist_openpkg` could be
+implemented by the class :class:`distcmds.bdist_openpkg.bdist_openpkg` or
+:class:`buildcmds.bdist_openpkg.bdist_openpkg`.
+
+
+Adding new distribution types
+=============================
+
+Commands that create distributions (files in the :file:`dist/` directory) need
+to add ``(command, filename)`` pairs to ``self.distribution.dist_files`` so that
+:command:`upload` can upload it to PyPI.  The *filename* in the pair contains no
+path information, only the name of the file itself.  In dry-run mode, pairs
+should still be added to represent what would have been created.
+
+

third_party/python/Doc/distutils/index.rst

@@ -0,0 +1,41 @@
+.. _distutils-index:
+
+##############################################
+  Distributing Python Modules (Legacy version)
+##############################################
+
+:Authors: Greg Ward, Anthony Baxter
+:Email: distutils-sig@python.org
+
+.. seealso::
+
+   :ref:`distributing-index`
+      The up to date module distribution documentations
+
+This document describes the Python Distribution Utilities ("Distutils") from
+the module developer's point of view, describing how to use the Distutils to
+make Python modules and extensions easily available to a wider audience with
+very little overhead for build/release/install mechanics.
+
+.. note::
+
+   This guide only covers the basic tools for building and distributing
+   extensions that are provided as part of this version of Python. Third party
+   tools offer easier to use and more secure alternatives. Refer to the `quick
+   recommendations section <https://packaging.python.org/en/latest/current/>`__
+   in the Python Packaging User Guide for more information.
+
+.. toctree::
+   :maxdepth: 2
+   :numbered:
+
+   introduction.rst
+   setupscript.rst
+   configfile.rst
+   sourcedist.rst
+   builtdist.rst
+   packageindex.rst
+   examples.rst
+   extending.rst
+   commandref.rst
+   apiref.rst

third_party/python/Doc/distutils/introduction.rst

@@ -0,0 +1,212 @@
+.. _distutils-intro:
+
+****************************
+An Introduction to Distutils
+****************************
+
+This document covers using the Distutils to distribute your Python modules,
+concentrating on the role of developer/distributor: if you're looking for
+information on installing Python modules, you should refer to the
+:ref:`install-index` chapter.
+
+
+.. _distutils-concepts:
+
+Concepts & Terminology
+======================
+
+Using the Distutils is quite simple, both for module developers and for
+users/administrators installing third-party modules.  As a developer, your
+responsibilities (apart from writing solid, well-documented and well-tested
+code, of course!) are:
+
+* write a setup script (:file:`setup.py` by convention)
+
+* (optional) write a setup configuration file
+
+* create a source distribution
+
+* (optional) create one or more built (binary) distributions
+
+Each of these tasks is covered in this document.
+
+Not all module developers have access to a multitude of platforms, so it's not
+always feasible to expect them to create a multitude of built distributions.  It
+is hoped that a class of intermediaries, called *packagers*, will arise to
+address this need.  Packagers will take source distributions released by module
+developers, build them on one or more platforms, and release the resulting built
+distributions.  Thus, users on the most popular platforms will be able to
+install most popular Python module distributions in the most natural way for
+their platform, without having to run a single setup script or compile a line of
+code.
+
+
+.. _distutils-simple-example:
+
+A Simple Example
+================
+
+The setup script is usually quite simple, although since it's written in Python,
+there are no arbitrary limits to what you can do with it, though you should be
+careful about putting arbitrarily expensive operations in your setup script.
+Unlike, say, Autoconf-style configure scripts, the setup script may be run
+multiple times in the course of building and installing your module
+distribution.
+
+If all you want to do is distribute a module called :mod:`foo`, contained in a
+file :file:`foo.py`, then your setup script can be as simple as this::
+
+   from distutils.core import setup
+   setup(name='foo',
+         version='1.0',
+         py_modules=['foo'],
+         )
+
+Some observations:
+
+* most information that you supply to the Distutils is supplied as keyword
+  arguments to the :func:`setup` function
+
+* those keyword arguments fall into two categories: package metadata (name,
+  version number) and information about what's in the package (a list of pure
+  Python modules, in this case)
+
+* modules are specified by module name, not filename (the same will hold true
+  for packages and extensions)
+
+* it's recommended that you supply a little more metadata, in particular your
+  name, email address and a URL for the project (see section :ref:`setup-script`
+  for an example)
+
+To create a source distribution for this module, you would create a setup
+script, :file:`setup.py`, containing the above code, and run this command from a
+terminal::
+
+   python setup.py sdist
+
+For Windows, open a command prompt window (:menuselection:`Start -->
+Accessories`) and change the command to::
+
+   setup.py sdist
+
+:command:`sdist` will create an archive file (e.g., tarball on Unix, ZIP file on Windows)
+containing your setup script :file:`setup.py`, and your module :file:`foo.py`.
+The archive file will be named :file:`foo-1.0.tar.gz` (or :file:`.zip`), and
+will unpack into a directory :file:`foo-1.0`.
+
+If an end-user wishes to install your :mod:`foo` module, all they have to do is
+download :file:`foo-1.0.tar.gz` (or :file:`.zip`), unpack it, and---from the
+:file:`foo-1.0` directory---run ::
+
+   python setup.py install
+
+which will ultimately copy :file:`foo.py` to the appropriate directory for
+third-party modules in their Python installation.
+
+This simple example demonstrates some fundamental concepts of the Distutils.
+First, both developers and installers have the same basic user interface, i.e.
+the setup script.  The difference is which Distutils *commands* they use: the
+:command:`sdist` command is almost exclusively for module developers, while
+:command:`install` is more often for installers (although most developers will
+want to install their own code occasionally).
+
+If you want to make things really easy for your users, you can create one or
+more built distributions for them.  For instance, if you are running on a
+Windows machine, and want to make things easy for other Windows users, you can
+create an executable installer (the most appropriate type of built distribution
+for this platform) with the :command:`bdist_wininst` command.  For example::
+
+   python setup.py bdist_wininst
+
+will create an executable installer, :file:`foo-1.0.win32.exe`, in the current
+directory.
+
+Other useful built distribution formats are RPM, implemented by the
+:command:`bdist_rpm` command, Solaris :program:`pkgtool`
+(:command:`bdist_pkgtool`), and HP-UX :program:`swinstall`
+(:command:`bdist_sdux`).  For example, the following command will create an RPM
+file called :file:`foo-1.0.noarch.rpm`::
+
+   python setup.py bdist_rpm
+
+(The :command:`bdist_rpm` command uses the :command:`rpm` executable, therefore
+this has to be run on an RPM-based system such as Red Hat Linux, SuSE Linux, or
+Mandrake Linux.)
+
+You can find out what distribution formats are available at any time by running
+::
+
+   python setup.py bdist --help-formats
+
+
+.. _python-terms:
+
+General Python terminology
+==========================
+
+If you're reading this document, you probably have a good idea of what modules,
+extensions, and so forth are.  Nevertheless, just to be sure that everyone is
+operating from a common starting point, we offer the following glossary of
+common Python terms:
+
+module
+   the basic unit of code reusability in Python: a block of code imported by some
+   other code.  Three types of modules concern us here: pure Python modules,
+   extension modules, and packages.
+
+pure Python module
+   a module written in Python and contained in a single :file:`.py` file (and
+   possibly associated :file:`.pyc` files).  Sometimes referred to as a
+   "pure module."
+
+extension module
+   a module written in the low-level language of the Python implementation: C/C++
+   for Python, Java for Jython. Typically contained in a single dynamically
+   loadable pre-compiled file, e.g. a shared object (:file:`.so`) file for Python
+   extensions on Unix, a DLL (given the :file:`.pyd` extension) for Python
+   extensions on Windows, or a Java class file for Jython extensions.  (Note that
+   currently, the Distutils only handles C/C++ extensions for Python.)
+
+package
+   a module that contains other modules; typically contained in a directory in the
+   filesystem and distinguished from other directories by the presence of a file
+   :file:`__init__.py`.
+
+root package
+   the root of the hierarchy of packages.  (This isn't really a package, since it
+   doesn't have an :file:`__init__.py` file.  But we have to call it something.)
+   The vast majority of the standard library is in the root package, as are many
+   small, standalone third-party modules that don't belong to a larger module
+   collection. Unlike regular packages, modules in the root package can be found in
+   many directories: in fact, every directory listed in ``sys.path`` contributes
+   modules to the root package.
+
+
+.. _distutils-term:
+
+Distutils-specific terminology
+==============================
+
+The following terms apply more specifically to the domain of distributing Python
+modules using the Distutils:
+
+module distribution
+   a collection of Python modules distributed together as a single downloadable
+   resource and meant to be installed *en masse*.  Examples of some well-known
+   module distributions are NumPy, SciPy, Pillow,
+   or mxBase.  (This would be called a *package*, except that term is
+   already taken in the Python context: a single module distribution may contain
+   zero, one, or many Python packages.)
+
+pure module distribution
+   a module distribution that contains only pure Python modules and packages.
+   Sometimes referred to as a "pure distribution."
+
+non-pure module distribution
+   a module distribution that contains at least one extension module.  Sometimes
+   referred to as a "non-pure distribution."
+
+distribution root
+   the top-level directory of your source tree (or  source distribution); the
+   directory where :file:`setup.py` exists.  Generally  :file:`setup.py` will be
+   run from this directory.

third_party/python/Doc/distutils/packageindex.rst

@@ -0,0 +1,253 @@
+.. index::
+   single: Python Package Index (PyPI)
+   single: PyPI; (see Python Package Index (PyPI))
+
+.. _package-index:
+
+*******************************
+The Python Package Index (PyPI)
+*******************************
+
+The `Python Package Index (PyPI)`_ stores :ref:`meta-data <meta-data>`
+describing distributions packaged with distutils, as well as package data like
+distribution files if a package author wishes.
+
+Distutils provides the :command:`register` and :command:`upload` commands for
+pushing meta-data and distribution files to PyPI, respectively.  See
+:ref:`package-commands` for information on these commands.
+
+
+PyPI overview
+=============
+
+PyPI lets you submit any number of versions of your distribution to the index.
+If you alter the meta-data for a particular version, you can submit it again
+and the index will be updated.
+
+PyPI holds a record for each (name, version) combination submitted.  The first
+user to submit information for a given name is designated the Owner of that
+name.  Changes can be submitted through the :command:`register` command or
+through the web interface.  Owners can designate other users as Owners or
+Maintainers.  Maintainers can edit the package information, but not designate
+new Owners or Maintainers.
+
+By default PyPI displays only the newest version of a given package.  The web
+interface lets one change this default behavior and manually select which
+versions to display and hide.
+
+For each version, PyPI displays a home page.  The home page is created from
+the ``long_description`` which can be submitted via the :command:`register`
+command.  See :ref:`package-display` for more information.
+
+
+.. _package-commands:
+
+Distutils commands
+==================
+
+Distutils exposes two commands for submitting package data to PyPI: the
+:ref:`register <package-register>` command for submitting meta-data to PyPI
+and the :ref:`upload <package-upload>` command for submitting distribution
+files.  Both commands read configuration data from a special file called a
+:ref:`.pypirc file <pypirc>`.
+
+
+.. _package-register:
+
+The ``register`` command
+------------------------
+
+The distutils command :command:`register` is used to submit your distribution's
+meta-data to an index server. It is invoked as follows::
+
+    python setup.py register
+
+Distutils will respond with the following prompt::
+
+    running register
+    We need to know who you are, so please choose either:
+        1. use your existing login,
+        2. register as a new user,
+        3. have the server generate a new password for you (and email it to you), or
+        4. quit
+    Your selection [default 1]:
+
+Note: if your username and password are saved locally, you will not see this
+menu.  Also, refer to :ref:`pypirc` for how to store your credentials in a
+:file:`.pypirc` file.
+
+If you have not registered with PyPI, then you will need to do so now. You
+should choose option 2, and enter your details as required. Soon after
+submitting your details, you will receive an email which will be used to confirm
+your registration.
+
+Once you are registered, you may choose option 1 from the menu. You will be
+prompted for your PyPI username and password, and :command:`register` will then
+submit your meta-data to the index.
+
+See :ref:`package-cmdoptions` for options to the :command:`register` command.
+
+
+.. _package-upload:
+
+The ``upload`` command
+----------------------
+
+The distutils command :command:`upload` pushes the distribution files to PyPI.
+
+The command is invoked immediately after building one or more distribution
+files.  For example, the command ::
+
+    python setup.py sdist bdist_wininst upload
+
+will cause the source distribution and the Windows installer to be uploaded to
+PyPI.  Note that these will be uploaded even if they are built using an earlier
+invocation of :file:`setup.py`, but that only distributions named on the command
+line for the invocation including the :command:`upload` command are uploaded.
+
+If a :command:`register` command was previously called in the same command,
+and if the password was entered in the prompt, :command:`upload` will reuse the
+entered password.  This is useful if you do not want to store a password in
+clear text in a :file:`.pypirc` file.
+
+You can use the ``--sign`` option to tell :command:`upload` to sign each
+uploaded file using GPG (GNU Privacy Guard).  The  :program:`gpg` program must
+be available for execution on the system :envvar:`PATH`.  You can also specify
+which key to use for signing using the ``--identity=name`` option.
+
+See :ref:`package-cmdoptions` for additional options to the :command:`upload`
+command.
+
+
+.. _package-cmdoptions:
+
+Additional command options
+--------------------------
+
+This section describes options common to both the :command:`register` and
+:command:`upload` commands.
+
+The ``--repository`` or ``-r`` option lets you specify a PyPI server
+different from the default.  For example::
+
+    python setup.py sdist bdist_wininst upload -r https://example.com/pypi
+
+For convenience, a name can be used in place of the URL when the
+:file:`.pypirc` file is configured to do so.  For example::
+
+    python setup.py register -r other
+
+See :ref:`pypirc` for more information on defining alternate servers.
+
+The ``--show-response`` option displays the full response text from the PyPI
+server, which is useful when debugging problems with registering and uploading.
+
+
+.. index::
+   single: .pypirc file
+   single: Python Package Index (PyPI); .pypirc file
+
+.. _pypirc:
+
+The ``.pypirc`` file
+--------------------
+
+The :command:`register` and :command:`upload` commands both check for the
+existence of a :file:`.pypirc` file at the location :file:`$HOME/.pypirc`.
+If this file exists, the command uses the username, password, and repository
+URL configured in the file.  The format of a :file:`.pypirc` file is as
+follows:
+
+.. code-block:: ini
+
+    [distutils]
+    index-servers =
+        pypi
+
+    [pypi]
+    repository: <repository-url>
+    username: <username>
+    password: <password>
+
+The *distutils* section defines an *index-servers* variable that lists the
+name of all sections describing a repository.
+
+Each section describing a repository defines three variables:
+
+- *repository*, that defines the url of the PyPI server. Defaults to
+    ``https://upload.pypi.org/legacy/``.
+- *username*, which is the registered username on the PyPI server.
+- *password*, that will be used to authenticate. If omitted the user
+    will be prompt to type it when needed.
+
+If you want to define another server a new section can be created and
+listed in the *index-servers* variable:
+
+.. code-block:: ini
+
+    [distutils]
+    index-servers =
+        pypi
+        other
+
+    [pypi]
+    repository: <repository-url>
+    username: <username>
+    password: <password>
+
+    [other]
+    repository: https://example.com/pypi
+    username: <username>
+    password: <password>
+
+This allows the :command:`register` and :command:`upload` commands to be
+called with the ``--repository`` option as described in
+:ref:`package-cmdoptions`.
+
+Specifically, you might want to add the `PyPI Test Repository
+<https://wiki.python.org/moin/TestPyPI>`_ to your ``.pypirc`` to facilitate
+testing before doing your first upload to ``PyPI`` itself.
+
+
+.. _package-display:
+
+PyPI package display
+====================
+
+The ``long_description`` field plays a special role at PyPI. It is used by
+the server to display a home page for the registered package.
+
+If you use the `reStructuredText <http://docutils.sourceforge.net/rst.html>`_
+syntax for this field, PyPI will parse it and display an HTML output for
+the package home page.
+
+The ``long_description`` field can be attached to a text file located
+in the package::
+
+    from distutils.core import setup
+
+    with open('README.txt') as file:
+        long_description = file.read()
+
+    setup(name='Distutils',
+          long_description=long_description)
+
+In that case, :file:`README.txt` is a regular reStructuredText text file located
+in the root of the package besides :file:`setup.py`.
+
+To prevent registering broken reStructuredText content, you can use the
+:program:`rst2html` program that is provided by the :mod:`docutils` package and
+check the ``long_description`` from the command line:
+
+.. code-block:: shell-session
+
+    $ python setup.py --long-description | rst2html.py > output.html
+
+:mod:`docutils` will display a warning if there's something wrong with your
+syntax.  Because PyPI applies additional checks (e.g. by passing ``--no-raw``
+to ``rst2html.py`` in the command above), being able to run the command above
+without warnings does not guarantee that PyPI will convert the content
+successfully.
+
+
+.. _Python Package Index (PyPI): https://pypi.org

third_party/python/Doc/distutils/setupscript.rst

@@ -0,0 +1,695 @@
+.. _setup-script:
+
+************************
+Writing the Setup Script
+************************
+
+The setup script is the centre of all activity in building, distributing, and
+installing modules using the Distutils.  The main purpose of the setup script is
+to describe your module distribution to the Distutils, so that the various
+commands that operate on your modules do the right thing.  As we saw in section
+:ref:`distutils-simple-example` above, the setup script consists mainly of a call to
+:func:`setup`, and most information supplied to the Distutils by the module
+developer is supplied as keyword arguments to :func:`setup`.
+
+Here's a slightly more involved example, which we'll follow for the next couple
+of sections: the Distutils' own setup script.  (Keep in mind that although the
+Distutils are included with Python 1.6 and later, they also have an independent
+existence so that Python 1.5.2 users can use them to install other module
+distributions.  The Distutils' own setup script, shown here, is used to install
+the package into Python 1.5.2.) ::
+
+    #!/usr/bin/env python
+
+    from distutils.core import setup
+
+    setup(name='Distutils',
+          version='1.0',
+          description='Python Distribution Utilities',
+          author='Greg Ward',
+          author_email='gward@python.net',
+          url='https://www.python.org/sigs/distutils-sig/',
+          packages=['distutils', 'distutils.command'],
+         )
+
+There are only two differences between this and the trivial one-file
+distribution presented in section :ref:`distutils-simple-example`: more metadata, and the
+specification of pure Python modules by package, rather than by module.  This is
+important since the Distutils consist of a couple of dozen modules split into
+(so far) two packages; an explicit list of every module would be tedious to
+generate and difficult to maintain.  For more information on the additional
+meta-data, see section :ref:`meta-data`.
+
+Note that any pathnames (files or directories) supplied in the setup script
+should be written using the Unix convention, i.e. slash-separated.  The
+Distutils will take care of converting this platform-neutral representation into
+whatever is appropriate on your current platform before actually using the
+pathname.  This makes your setup script portable across operating systems, which
+of course is one of the major goals of the Distutils.  In this spirit, all
+pathnames in this document are slash-separated.
+
+This, of course, only applies to pathnames given to Distutils functions.  If
+you, for example, use standard Python functions such as :func:`glob.glob` or
+:func:`os.listdir` to specify files, you should be careful to write portable
+code instead of hardcoding path separators::
+
+    glob.glob(os.path.join('mydir', 'subdir', '*.html'))
+    os.listdir(os.path.join('mydir', 'subdir'))
+
+
+.. _listing-packages:
+
+Listing whole packages
+======================
+
+The ``packages`` option tells the Distutils to process (build, distribute,
+install, etc.) all pure Python modules found in each package mentioned in the
+``packages`` list.  In order to do this, of course, there has to be a
+correspondence between package names and directories in the filesystem.  The
+default correspondence is the most obvious one, i.e. package :mod:`distutils` is
+found in the directory :file:`distutils` relative to the distribution root.
+Thus, when you say ``packages = ['foo']`` in your setup script, you are
+promising that the Distutils will find a file :file:`foo/__init__.py` (which
+might be spelled differently on your system, but you get the idea) relative to
+the directory where your setup script lives.  If you break this promise, the
+Distutils will issue a warning but still process the broken package anyway.
+
+If you use a different convention to lay out your source directory, that's no
+problem: you just have to supply the ``package_dir`` option to tell the
+Distutils about your convention.  For example, say you keep all Python source
+under :file:`lib`, so that modules in the "root package" (i.e., not in any
+package at all) are in :file:`lib`, modules in the :mod:`foo` package are in
+:file:`lib/foo`, and so forth.  Then you would put ::
+
+    package_dir = {'': 'lib'}
+
+in your setup script.  The keys to this dictionary are package names, and an
+empty package name stands for the root package.  The values are directory names
+relative to your distribution root.  In this case, when you say ``packages =
+['foo']``, you are promising that the file :file:`lib/foo/__init__.py` exists.
+
+Another possible convention is to put the :mod:`foo` package right in
+:file:`lib`, the :mod:`foo.bar` package in :file:`lib/bar`, etc.  This would be
+written in the setup script as ::
+
+    package_dir = {'foo': 'lib'}
+
+A ``package: dir`` entry in the ``package_dir`` dictionary implicitly
+applies to all packages below *package*, so the :mod:`foo.bar` case is
+automatically handled here.  In this example, having ``packages = ['foo',
+'foo.bar']`` tells the Distutils to look for :file:`lib/__init__.py` and
+:file:`lib/bar/__init__.py`.  (Keep in mind that although ``package_dir``
+applies recursively, you must explicitly list all packages in
+``packages``: the Distutils will *not* recursively scan your source tree
+looking for any directory with an :file:`__init__.py` file.)
+
+
+.. _listing-modules:
+
+Listing individual modules
+==========================
+
+For a small module distribution, you might prefer to list all modules rather
+than listing packages---especially the case of a single module that goes in the
+"root package" (i.e., no package at all).  This simplest case was shown in
+section :ref:`distutils-simple-example`; here is a slightly more involved example::
+
+    py_modules = ['mod1', 'pkg.mod2']
+
+This describes two modules, one of them in the "root" package, the other in the
+:mod:`pkg` package.  Again, the default package/directory layout implies that
+these two modules can be found in :file:`mod1.py` and :file:`pkg/mod2.py`, and
+that :file:`pkg/__init__.py` exists as well. And again, you can override the
+package/directory correspondence using the ``package_dir`` option.
+
+
+.. _describing-extensions:
+
+Describing extension modules
+============================
+
+Just as writing Python extension modules is a bit more complicated than writing
+pure Python modules, describing them to the Distutils is a bit more complicated.
+Unlike pure modules, it's not enough just to list modules or packages and expect
+the Distutils to go out and find the right files; you have to specify the
+extension name, source file(s), and any compile/link requirements (include
+directories, libraries to link with, etc.).
+
+.. XXX read over this section
+
+All of this is done through another keyword argument to :func:`setup`, the
+``ext_modules`` option.  ``ext_modules`` is just a list of
+:class:`~distutils.core.Extension` instances, each of which describes a
+single extension module.
+Suppose your distribution includes a single extension, called :mod:`foo` and
+implemented by :file:`foo.c`.  If no additional instructions to the
+compiler/linker are needed, describing this extension is quite simple::
+
+    Extension('foo', ['foo.c'])
+
+The :class:`Extension` class can be imported from :mod:`distutils.core` along
+with :func:`setup`.  Thus, the setup script for a module distribution that
+contains only this one extension and nothing else might be::
+
+    from distutils.core import setup, Extension
+    setup(name='foo',
+          version='1.0',
+          ext_modules=[Extension('foo', ['foo.c'])],
+          )
+
+The :class:`Extension` class (actually, the underlying extension-building
+machinery implemented by the :command:`build_ext` command) supports a great deal
+of flexibility in describing Python extensions, which is explained in the
+following sections.
+
+
+Extension names and packages
+----------------------------
+
+The first argument to the :class:`~distutils.core.Extension` constructor is
+always the name of the extension, including any package names.  For example, ::
+
+    Extension('foo', ['src/foo1.c', 'src/foo2.c'])
+
+describes an extension that lives in the root package, while ::
+
+    Extension('pkg.foo', ['src/foo1.c', 'src/foo2.c'])
+
+describes the same extension in the :mod:`pkg` package.  The source files and
+resulting object code are identical in both cases; the only difference is where
+in the filesystem (and therefore where in Python's namespace hierarchy) the
+resulting extension lives.
+
+If you have a number of extensions all in the same package (or all under the
+same base package), use the ``ext_package`` keyword argument to
+:func:`setup`.  For example, ::
+
+    setup(...,
+          ext_package='pkg',
+          ext_modules=[Extension('foo', ['foo.c']),
+                       Extension('subpkg.bar', ['bar.c'])],
+         )
+
+will compile :file:`foo.c` to the extension :mod:`pkg.foo`, and :file:`bar.c` to
+:mod:`pkg.subpkg.bar`.
+
+
+Extension source files
+----------------------
+
+The second argument to the :class:`~distutils.core.Extension` constructor is
+a list of source
+files.  Since the Distutils currently only support C, C++, and Objective-C
+extensions, these are normally C/C++/Objective-C source files.  (Be sure to use
+appropriate extensions to distinguish C++ source files: :file:`.cc` and
+:file:`.cpp` seem to be recognized by both Unix and Windows compilers.)
+
+However, you can also include SWIG interface (:file:`.i`) files in the list; the
+:command:`build_ext` command knows how to deal with SWIG extensions: it will run
+SWIG on the interface file and compile the resulting C/C++ file into your
+extension.
+
+.. XXX SWIG support is rough around the edges and largely untested!
+
+This warning notwithstanding, options to SWIG can be currently passed like
+this::
+
+    setup(...,
+          ext_modules=[Extension('_foo', ['foo.i'],
+                                 swig_opts=['-modern', '-I../include'])],
+          py_modules=['foo'],
+         )
+
+Or on the commandline like this::
+
+    > python setup.py build_ext --swig-opts="-modern -I../include"
+
+On some platforms, you can include non-source files that are processed by the
+compiler and included in your extension.  Currently, this just means Windows
+message text (:file:`.mc`) files and resource definition (:file:`.rc`) files for
+Visual C++. These will be compiled to binary resource (:file:`.res`) files and
+linked into the executable.
+
+
+Preprocessor options
+--------------------
+
+Three optional arguments to :class:`~distutils.core.Extension` will help if
+you need to specify include directories to search or preprocessor macros to
+define/undefine: ``include_dirs``, ``define_macros``, and ``undef_macros``.
+
+For example, if your extension requires header files in the :file:`include`
+directory under your distribution root, use the ``include_dirs`` option::
+
+    Extension('foo', ['foo.c'], include_dirs=['include'])
+
+You can specify absolute directories there; if you know that your extension will
+only be built on Unix systems with X11R6 installed to :file:`/usr`, you can get
+away with ::
+
+    Extension('foo', ['foo.c'], include_dirs=['/usr/include/X11'])
+
+You should avoid this sort of non-portable usage if you plan to distribute your
+code: it's probably better to write C code like  ::
+
+    #include <X11/Xlib.h>
+
+If you need to include header files from some other Python extension, you can
+take advantage of the fact that header files are installed in a consistent way
+by the Distutils :command:`install_headers` command.  For example, the Numerical
+Python header files are installed (on a standard Unix installation) to
+:file:`/usr/local/include/python1.5/Numerical`. (The exact location will differ
+according to your platform and Python installation.)  Since the Python include
+directory---\ :file:`/usr/local/include/python1.5` in this case---is always
+included in the search path when building Python extensions, the best approach
+is to write C code like  ::
+
+    #include <Numerical/arrayobject.h>
+
+If you must put the :file:`Numerical` include directory right into your header
+search path, though, you can find that directory using the Distutils
+:mod:`distutils.sysconfig` module::
+
+    from distutils.sysconfig import get_python_inc
+    incdir = os.path.join(get_python_inc(plat_specific=1), 'Numerical')
+    setup(...,
+          Extension(..., include_dirs=[incdir]),
+          )
+
+Even though this is quite portable---it will work on any Python installation,
+regardless of platform---it's probably easier to just write your C code in the
+sensible way.
+
+You can define and undefine pre-processor macros with the ``define_macros`` and
+``undef_macros`` options. ``define_macros`` takes a list of ``(name, value)``
+tuples, where ``name`` is the name of the macro to define (a string) and
+``value`` is its value: either a string or ``None``.  (Defining a macro ``FOO``
+to ``None`` is the equivalent of a bare ``#define FOO`` in your C source: with
+most compilers, this sets ``FOO`` to the string ``1``.)  ``undef_macros`` is
+just a list of macros to undefine.
+
+For example::
+
+    Extension(...,
+              define_macros=[('NDEBUG', '1'),
+                             ('HAVE_STRFTIME', None)],
+              undef_macros=['HAVE_FOO', 'HAVE_BAR'])
+
+is the equivalent of having this at the top of every C source file::
+
+    #define NDEBUG 1
+    #define HAVE_STRFTIME
+    #undef HAVE_FOO
+    #undef HAVE_BAR
+
+
+Library options
+---------------
+
+You can also specify the libraries to link against when building your extension,
+and the directories to search for those libraries.  The ``libraries`` option is
+a list of libraries to link against, ``library_dirs`` is a list of directories
+to search for libraries at  link-time, and ``runtime_library_dirs`` is a list of
+directories to  search for shared (dynamically loaded) libraries at run-time.
+
+For example, if you need to link against libraries known to be in the standard
+library search path on target systems ::
+
+    Extension(...,
+              libraries=['gdbm', 'readline'])
+
+If you need to link with libraries in a non-standard location, you'll have to
+include the location in ``library_dirs``::
+
+    Extension(...,
+              library_dirs=['/usr/X11R6/lib'],
+              libraries=['X11', 'Xt'])
+
+(Again, this sort of non-portable construct should be avoided if you intend to
+distribute your code.)
+
+.. XXX Should mention clib libraries here or somewhere else!
+
+
+Other options
+-------------
+
+There are still some other options which can be used to handle special cases.
+
+The ``optional`` option is a boolean; if it is true,
+a build failure in the extension will not abort the build process, but
+instead simply not install the failing extension.
+
+The ``extra_objects`` option is a list of object files to be passed to the
+linker. These files must not have extensions, as the default extension for the
+compiler is used.
+
+``extra_compile_args`` and ``extra_link_args`` can be used to
+specify additional command line options for the respective compiler and linker
+command lines.
+
+``export_symbols`` is only useful on Windows.  It can contain a list of
+symbols (functions or variables) to be exported. This option is not needed when
+building compiled extensions: Distutils  will automatically add ``initmodule``
+to the list of exported symbols.
+
+The ``depends`` option is a list of files that the extension depends on
+(for example header files). The build command will call the compiler on the
+sources to rebuild extension if any on this files has been modified since the
+previous build.
+
+Relationships between Distributions and Packages
+================================================
+
+A distribution may relate to packages in three specific ways:
+
+#. It can require packages or modules.
+
+#. It can provide packages or modules.
+
+#. It can obsolete packages or modules.
+
+These relationships can be specified using keyword arguments to the
+:func:`distutils.core.setup` function.
+
+Dependencies on other Python modules and packages can be specified by supplying
+the *requires* keyword argument to :func:`setup`. The value must be a list of
+strings.  Each string specifies a package that is required, and optionally what
+versions are sufficient.
+
+To specify that any version of a module or package is required, the string
+should consist entirely of the module or package name. Examples include
+``'mymodule'`` and ``'xml.parsers.expat'``.
+
+If specific versions are required, a sequence of qualifiers can be supplied in
+parentheses.  Each qualifier may consist of a comparison operator and a version
+number.  The accepted comparison operators are::
+
+    <    >    ==
+    <=   >=   !=
+
+These can be combined by using multiple qualifiers separated by commas (and
+optional whitespace).  In this case, all of the qualifiers must be matched; a
+logical AND is used to combine the evaluations.
+
+Let's look at a bunch of examples:
+
++-------------------------+----------------------------------------------+
+| Requires Expression     | Explanation                                  |
++=========================+==============================================+
+| ``==1.0``               | Only version ``1.0`` is compatible           |
++-------------------------+----------------------------------------------+
+| ``>1.0, !=1.5.1, <2.0`` | Any version after ``1.0`` and before ``2.0`` |
+|                         | is compatible, except ``1.5.1``              |
++-------------------------+----------------------------------------------+
+
+Now that we can specify dependencies, we also need to be able to specify what we
+provide that other distributions can require.  This is done using the *provides*
+keyword argument to :func:`setup`. The value for this keyword is a list of
+strings, each of which names a Python module or package, and optionally
+identifies the version.  If the version is not specified, it is assumed to match
+that of the distribution.
+
+Some examples:
+
++---------------------+----------------------------------------------+
+| Provides Expression | Explanation                                  |
++=====================+==============================================+
+| ``mypkg``           | Provide ``mypkg``, using the distribution    |
+|                     | version                                      |
++---------------------+----------------------------------------------+
+| ``mypkg (1.1)``     | Provide ``mypkg`` version 1.1, regardless of |
+|                     | the distribution version                     |
++---------------------+----------------------------------------------+
+
+A package can declare that it obsoletes other packages using the *obsoletes*
+keyword argument.  The value for this is similar to that of the *requires*
+keyword: a list of strings giving module or package specifiers.  Each specifier
+consists of a module or package name optionally followed by one or more version
+qualifiers.  Version qualifiers are given in parentheses after the module or
+package name.
+
+The versions identified by the qualifiers are those that are obsoleted by the
+distribution being described.  If no qualifiers are given, all versions of the
+named module or package are understood to be obsoleted.
+
+.. _distutils-installing-scripts:
+
+Installing Scripts
+==================
+
+So far we have been dealing with pure and non-pure Python modules, which are
+usually not run by themselves but imported by scripts.
+
+Scripts are files containing Python source code, intended to be started from the
+command line.  Scripts don't require Distutils to do anything very complicated.
+The only clever feature is that if the first line of the script starts with
+``#!`` and contains the word "python", the Distutils will adjust the first line
+to refer to the current interpreter location. By default, it is replaced with
+the current interpreter location.  The :option:`!--executable` (or :option:`!-e`)
+option will allow the interpreter path to be explicitly overridden.
+
+The ``scripts`` option simply is a list of files to be handled in this
+way.  From the PyXML setup script::
+
+    setup(...,
+          scripts=['scripts/xmlproc_parse', 'scripts/xmlproc_val']
+          )
+
+.. versionchanged:: 3.1
+   All the scripts will also be added to the ``MANIFEST`` file if no template is
+   provided.  See :ref:`manifest`.
+
+
+.. _distutils-installing-package-data:
+
+Installing Package Data
+=======================
+
+Often, additional files need to be installed into a package.  These files are
+often data that's closely related to the package's implementation, or text files
+containing documentation that might be of interest to programmers using the
+package.  These files are called :dfn:`package data`.
+
+Package data can be added to packages using the ``package_data`` keyword
+argument to the :func:`setup` function.  The value must be a mapping from
+package name to a list of relative path names that should be copied into the
+package.  The paths are interpreted as relative to the directory containing the
+package (information from the ``package_dir`` mapping is used if appropriate);
+that is, the files are expected to be part of the package in the source
+directories. They may contain glob patterns as well.
+
+The path names may contain directory portions; any necessary directories will be
+created in the installation.
+
+For example, if a package should contain a subdirectory with several data files,
+the files can be arranged like this in the source tree::
+
+    setup.py
+    src/
+        mypkg/
+            __init__.py
+            module.py
+            data/
+                tables.dat
+                spoons.dat
+                forks.dat
+
+The corresponding call to :func:`setup` might be::
+
+    setup(...,
+          packages=['mypkg'],
+          package_dir={'mypkg': 'src/mypkg'},
+          package_data={'mypkg': ['data/*.dat']},
+          )
+
+
+.. versionchanged:: 3.1
+   All the files that match ``package_data`` will be added to the ``MANIFEST``
+   file if no template is provided.  See :ref:`manifest`.
+
+
+.. _distutils-additional-files:
+
+Installing Additional Files
+===========================
+
+The ``data_files`` option can be used to specify additional files needed
+by the module distribution: configuration files, message catalogs, data files,
+anything which doesn't fit in the previous categories.
+
+``data_files`` specifies a sequence of (*directory*, *files*) pairs in the
+following way::
+
+    setup(...,
+          data_files=[('bitmaps', ['bm/b1.gif', 'bm/b2.gif']),
+                      ('config', ['cfg/data.cfg']),
+                      ('/etc/init.d', ['init-script'])]
+         )
+
+Note that you can specify the directory names where the data files will be
+installed, but you cannot rename the data files themselves.
+
+Each (*directory*, *files*) pair in the sequence specifies the installation
+directory and the files to install there.  If *directory* is a relative path, it
+is interpreted relative to the installation prefix (Python's ``sys.prefix`` for
+pure-Python packages, ``sys.exec_prefix`` for packages that contain extension
+modules).  Each file name in *files* is interpreted relative to the
+:file:`setup.py` script at the top of the package source distribution.  No
+directory information from *files* is used to determine the final location of
+the installed file; only the name of the file is used.
+
+You can specify the ``data_files`` options as a simple sequence of files
+without specifying a target directory, but this is not recommended, and the
+:command:`install` command will print a warning in this case. To install data
+files directly in the target directory, an empty string should be given as the
+directory.
+
+.. versionchanged:: 3.1
+   All the files that match ``data_files`` will be added to the ``MANIFEST``
+   file if no template is provided.  See :ref:`manifest`.
+
+
+.. _meta-data:
+
+Additional meta-data
+====================
+
+The setup script may include additional meta-data beyond the name and version.
+This information includes:
+
++----------------------+---------------------------+-----------------+--------+
+| Meta-Data            | Description               | Value           | Notes  |
++======================+===========================+=================+========+
+| ``name``             | name of the package       | short string    | \(1)   |
++----------------------+---------------------------+-----------------+--------+
+| ``version``          | version of this release   | short string    | (1)(2) |
++----------------------+---------------------------+-----------------+--------+
+| ``author``           | package author's name     | short string    | \(3)   |
++----------------------+---------------------------+-----------------+--------+
+| ``author_email``     | email address of the      | email address   | \(3)   |
+|                      | package author            |                 |        |
++----------------------+---------------------------+-----------------+--------+
+| ``maintainer``       | package maintainer's name | short string    | \(3)   |
++----------------------+---------------------------+-----------------+--------+
+| ``maintainer_email`` | email address of the      | email address   | \(3)   |
+|                      | package maintainer        |                 |        |
++----------------------+---------------------------+-----------------+--------+
+| ``url``              | home page for the package | URL             | \(1)   |
++----------------------+---------------------------+-----------------+--------+
+| ``description``      | short, summary            | short string    |        |
+|                      | description of the        |                 |        |
+|                      | package                   |                 |        |
++----------------------+---------------------------+-----------------+--------+
+| ``long_description`` | longer description of the | long string     | \(5)   |
+|                      | package                   |                 |        |
++----------------------+---------------------------+-----------------+--------+
+| ``download_url``     | location where the        | URL             | \(4)   |
+|                      | package may be downloaded |                 |        |
++----------------------+---------------------------+-----------------+--------+
+| ``classifiers``      | a list of classifiers     | list of strings | \(4)   |
++----------------------+---------------------------+-----------------+--------+
+| ``platforms``        | a list of platforms       | list of strings |        |
++----------------------+---------------------------+-----------------+--------+
+| ``license``          | license for the package   | short string    | \(6)   |
++----------------------+---------------------------+-----------------+--------+
+
+Notes:
+
+(1)
+    These fields are required.
+
+(2)
+    It is recommended that versions take the form *major.minor[.patch[.sub]]*.
+
+(3)
+    Either the author or the maintainer must be identified. If maintainer is
+    provided, distutils lists it as the author in :file:`PKG-INFO`.
+
+(4)
+    These fields should not be used if your package is to be compatible with Python
+    versions prior to 2.2.3 or 2.3.  The list is available from the `PyPI website
+    <https://pypi.org/>`_.
+
+(5)
+    The ``long_description`` field is used by PyPI when you are
+    :ref:`registering <package-register>` a package, to
+    :ref:`build its home page <package-display>`.
+
+(6)
+    The ``license`` field is a text indicating the license covering the
+    package where the license is not a selection from the "License" Trove
+    classifiers. See the ``Classifier`` field. Notice that
+    there's a ``licence`` distribution option which is deprecated but still
+    acts as an alias for ``license``.
+
+'short string'
+    A single line of text, not more than 200 characters.
+
+'long string'
+    Multiple lines of plain text in reStructuredText format (see
+    http://docutils.sourceforge.net/).
+
+'list of strings'
+    See below.
+
+Encoding the version information is an art in itself. Python packages generally
+adhere to the version format *major.minor[.patch][sub]*. The major number is 0
+for initial, experimental releases of software. It is incremented for releases
+that represent major milestones in a package. The minor number is incremented
+when important new features are added to the package. The patch number
+increments when bug-fix releases are made. Additional trailing version
+information is sometimes used to indicate sub-releases.  These are
+"a1,a2,...,aN" (for alpha releases, where functionality and API may change),
+"b1,b2,...,bN" (for beta releases, which only fix bugs) and "pr1,pr2,...,prN"
+(for final pre-release release testing). Some examples:
+
+0.1.0
+    the first, experimental release of a package
+
+1.0.1a2
+    the second alpha release of the first patch version of 1.0
+
+``classifiers`` are specified in a Python list::
+
+    setup(...,
+          classifiers=[
+              'Development Status :: 4 - Beta',
+              'Environment :: Console',
+              'Environment :: Web Environment',
+              'Intended Audience :: End Users/Desktop',
+              'Intended Audience :: Developers',
+              'Intended Audience :: System Administrators',
+              'License :: OSI Approved :: Python Software Foundation License',
+              'Operating System :: MacOS :: MacOS X',
+              'Operating System :: Microsoft :: Windows',
+              'Operating System :: POSIX',
+              'Programming Language :: Python',
+              'Topic :: Communications :: Email',
+              'Topic :: Office/Business',
+              'Topic :: Software Development :: Bug Tracking',
+              ],
+          )
+
+.. _debug-setup-script:
+
+Debugging the setup script
+==========================
+
+Sometimes things go wrong, and the setup script doesn't do what the developer
+wants.
+
+Distutils catches any exceptions when running the setup script, and print a
+simple error message before the script is terminated.  The motivation for this
+behaviour is to not confuse administrators who don't know much about Python and
+are trying to install a package.  If they get a big long traceback from deep
+inside the guts of Distutils, they may think the package or the Python
+installation is broken because they don't read all the way down to the bottom
+and see that it's a permission problem.
+
+On the other hand, this doesn't help the developer to find the cause of the
+failure. For this purpose, the :envvar:`DISTUTILS_DEBUG` environment variable can be set
+to anything except an empty string, and distutils will now print detailed
+information about what it is doing, dump the full traceback when an exception
+occurs, and print the whole command line when an external program (like a C
+compiler) fails.

third_party/python/Doc/distutils/sourcedist.rst

@@ -0,0 +1,236 @@
+.. _source-dist:
+
+******************************
+Creating a Source Distribution
+******************************
+
+As shown in section :ref:`distutils-simple-example`, you use the :command:`sdist` command
+to create a source distribution.  In the simplest case, ::
+
+   python setup.py sdist
+
+(assuming you haven't specified any :command:`sdist` options in the setup script
+or config file), :command:`sdist` creates the archive of the default format for
+the current platform.  The default format is a gzip'ed tar file
+(:file:`.tar.gz`) on Unix, and ZIP file on Windows.
+
+You can specify as many formats as you like using the :option:`!--formats`
+option, for example::
+
+   python setup.py sdist --formats=gztar,zip
+
+to create a gzipped tarball and a zip file.  The available formats are:
+
++-----------+-------------------------+---------+
+| Format    | Description             | Notes   |
++===========+=========================+=========+
+| ``zip``   | zip file (:file:`.zip`) | (1),(3) |
++-----------+-------------------------+---------+
+| ``gztar`` | gzip'ed tar file        | \(2)    |
+|           | (:file:`.tar.gz`)       |         |
++-----------+-------------------------+---------+
+| ``bztar`` | bzip2'ed tar file       |         |
+|           | (:file:`.tar.bz2`)      |         |
++-----------+-------------------------+---------+
+| ``xztar`` | xz'ed tar file          |         |
+|           | (:file:`.tar.xz`)       |         |
++-----------+-------------------------+---------+
+| ``ztar``  | compressed tar file     | \(4)    |
+|           | (:file:`.tar.Z`)        |         |
++-----------+-------------------------+---------+
+| ``tar``   | tar file (:file:`.tar`) |         |
++-----------+-------------------------+---------+
+
+.. versionchanged:: 3.5
+   Added support for the ``xztar`` format.
+
+Notes:
+
+(1)
+   default on Windows
+
+(2)
+   default on Unix
+
+(3)
+   requires either external :program:`zip` utility or :mod:`zipfile` module (part
+   of the standard Python library since Python 1.6)
+
+(4)
+   requires the :program:`compress` program. Notice that this format is now
+   pending for deprecation and will be removed in the future versions of Python.
+
+When using any ``tar`` format (``gztar``, ``bztar``, ``xztar``, ``ztar`` or
+``tar``), under Unix you can specify the ``owner`` and ``group`` names
+that will be set for each member of the archive.
+
+For example, if you want all files of the archive to be owned by root::
+
+    python setup.py sdist --owner=root --group=root
+
+
+.. _manifest:
+
+Specifying the files to distribute
+==================================
+
+If you don't supply an explicit list of files (or instructions on how to
+generate one), the :command:`sdist` command puts a minimal default set into the
+source distribution:
+
+* all Python source files implied by the ``py_modules`` and
+  ``packages`` options
+
+* all C source files mentioned in the ``ext_modules`` or
+  ``libraries`` options
+
+  .. XXX getting C library sources currently broken---no
+         :meth:`get_source_files` method in :file:`build_clib.py`!
+
+* scripts identified by the ``scripts`` option
+  See :ref:`distutils-installing-scripts`.
+
+* anything that looks like a test script: :file:`test/test\*.py` (currently, the
+  Distutils don't do anything with test scripts except include them in source
+  distributions, but in the future there will be a standard for testing Python
+  module distributions)
+
+* :file:`README.txt` (or :file:`README`), :file:`setup.py` (or whatever  you
+  called your setup script), and :file:`setup.cfg`
+
+* all files that matches the ``package_data`` metadata.
+  See :ref:`distutils-installing-package-data`.
+
+* all files that matches the ``data_files`` metadata.
+  See :ref:`distutils-additional-files`.
+
+Sometimes this is enough, but usually you will want to specify additional files
+to distribute.  The typical way to do this is to write a *manifest template*,
+called :file:`MANIFEST.in` by default.  The manifest template is just a list of
+instructions for how to generate your manifest file, :file:`MANIFEST`, which is
+the exact list of files to include in your source distribution.  The
+:command:`sdist` command processes this template and generates a manifest based
+on its instructions and what it finds in the filesystem.
+
+If you prefer to roll your own manifest file, the format is simple: one filename
+per line, regular files (or symlinks to them) only.  If you do supply your own
+:file:`MANIFEST`, you must specify everything: the default set of files
+described above does not apply in this case.
+
+.. versionchanged:: 3.1
+   An existing generated :file:`MANIFEST` will be regenerated without
+   :command:`sdist` comparing its modification time to the one of
+   :file:`MANIFEST.in` or :file:`setup.py`.
+
+.. versionchanged:: 3.1.3
+   :file:`MANIFEST` files start with a comment indicating they are generated.
+   Files without this comment are not overwritten or removed.
+
+.. versionchanged:: 3.2.2
+   :command:`sdist` will read a :file:`MANIFEST` file if no :file:`MANIFEST.in`
+   exists, like it used to do.
+
+
+The manifest template has one command per line, where each command specifies a
+set of files to include or exclude from the source distribution.  For an
+example, again we turn to the Distutils' own manifest template:
+
+.. code-block:: none
+
+   include *.txt
+   recursive-include examples *.txt *.py
+   prune examples/sample?/build
+
+The meanings should be fairly clear: include all files in the distribution root
+matching :file:`\*.txt`, all files anywhere under the :file:`examples` directory
+matching :file:`\*.txt` or :file:`\*.py`, and exclude all directories matching
+:file:`examples/sample?/build`.  All of this is done *after* the standard
+include set, so you can exclude files from the standard set with explicit
+instructions in the manifest template.  (Or, you can use the
+:option:`!--no-defaults` option to disable the standard set entirely.)  There are
+several other commands available in the manifest template mini-language; see
+section :ref:`sdist-cmd`.
+
+The order of commands in the manifest template matters: initially, we have the
+list of default files as described above, and each command in the template adds
+to or removes from that list of files.  Once we have fully processed the
+manifest template, we remove files that should not be included in the source
+distribution:
+
+* all files in the Distutils "build" tree (default :file:`build/`)
+
+* all files in directories named :file:`RCS`, :file:`CVS`, :file:`.svn`,
+  :file:`.hg`, :file:`.git`, :file:`.bzr` or :file:`_darcs`
+
+Now we have our complete list of files, which is written to the manifest for
+future reference, and then used to build the source distribution archive(s).
+
+You can disable the default set of included files with the
+:option:`!--no-defaults` option, and you can disable the standard exclude set
+with :option:`!--no-prune`.
+
+Following the Distutils' own manifest template, let's trace how the
+:command:`sdist` command builds the list of files to include in the Distutils
+source distribution:
+
+#. include all Python source files in the :file:`distutils` and
+   :file:`distutils/command` subdirectories (because packages corresponding to
+   those two directories were mentioned in the ``packages`` option in the
+   setup script---see section :ref:`setup-script`)
+
+#. include :file:`README.txt`, :file:`setup.py`, and :file:`setup.cfg` (standard
+   files)
+
+#. include :file:`test/test\*.py` (standard files)
+
+#. include :file:`\*.txt` in the distribution root (this will find
+   :file:`README.txt` a second time, but such redundancies are weeded out later)
+
+#. include anything matching :file:`\*.txt` or :file:`\*.py` in the sub-tree
+   under :file:`examples`,
+
+#. exclude all files in the sub-trees starting at directories matching
+   :file:`examples/sample?/build`\ ---this may exclude files included by the
+   previous two steps, so it's important that the ``prune`` command in the manifest
+   template comes after the ``recursive-include`` command
+
+#. exclude the entire :file:`build` tree, and any :file:`RCS`, :file:`CVS`,
+   :file:`.svn`, :file:`.hg`, :file:`.git`, :file:`.bzr` and :file:`_darcs`
+   directories
+
+Just like in the setup script, file and directory names in the manifest template
+should always be slash-separated; the Distutils will take care of converting
+them to the standard representation on your platform. That way, the manifest
+template is portable across operating systems.
+
+
+.. _manifest-options:
+
+Manifest-related options
+========================
+
+The normal course of operations for the :command:`sdist` command is as follows:
+
+* if the manifest file (:file:`MANIFEST` by default) exists and the first line
+  does not have a comment indicating it is generated from :file:`MANIFEST.in`,
+  then it is used as is, unaltered
+
+* if the manifest file doesn't exist or has been previously automatically
+  generated, read :file:`MANIFEST.in` and create the manifest
+
+* if neither :file:`MANIFEST` nor :file:`MANIFEST.in` exist, create a manifest
+  with just the default file set
+
+* use the list of files now in :file:`MANIFEST` (either just generated or read
+  in) to create the source distribution archive(s)
+
+There are a couple of options that modify this behaviour.  First, use the
+:option:`!--no-defaults` and :option:`!--no-prune` to disable the standard
+"include" and "exclude" sets.
+
+Second, you might just want to (re)generate the manifest, but not create a source
+distribution::
+
+   python setup.py sdist --manifest-only
+
+:option:`!-o` is a shortcut for :option:`!--manifest-only`.

third_party/python/Doc/distutils/uploading.rst

@@ -0,0 +1,7 @@
+:orphan:
+
+***************************************
+Uploading Packages to the Package Index
+***************************************
+
+The contents of this page have moved to the section :ref:`package-index`.

third_party/python/Doc/docutils.conf

@@ -0,0 +1,2 @@
+[restructuredtext parser]
+smartquotes-locales: ja: ""''

third_party/python/Doc/extending/building.rst

@@ -0,0 +1,167 @@
+.. highlightlang:: c
+
+.. _building:
+
+*****************************
+Building C and C++ Extensions
+*****************************
+
+A C extension for CPython is a shared library (e.g. a ``.so`` file on Linux,
+``.pyd`` on Windows), which exports an *initialization function*.
+
+To be importable, the shared library must be available on :envvar:`PYTHONPATH`,
+and must be named after the module name, with an appropriate extension.
+When using distutils, the correct filename is generated automatically.
+
+The initialization function has the signature:
+
+.. c:function:: PyObject* PyInit_modulename(void)
+
+It returns either a fully-initialized module, or a :c:type:`PyModuleDef`
+instance. See :ref:`initializing-modules` for details.
+
+.. highlightlang:: python
+
+For modules with ASCII-only names, the function must be named
+``PyInit_<modulename>``, with ``<modulename>`` replaced by the name of the
+module. When using :ref:`multi-phase-initialization`, non-ASCII module names
+are allowed. In this case, the initialization function name is
+``PyInitU_<modulename>``, with ``<modulename>`` encoded using Python's
+*punycode* encoding with hyphens replaced by underscores. In Python::
+
+    def initfunc_name(name):
+        try:
+            suffix = b'_' + name.encode('ascii')
+        except UnicodeEncodeError:
+            suffix = b'U_' + name.encode('punycode').replace(b'-', b'_')
+        return b'PyInit' + suffix
+
+It is possible to export multiple modules from a single shared library by
+defining multiple initialization functions. However, importing them requires
+using symbolic links or a custom importer, because by default only the
+function corresponding to the filename is found.
+See the *"Multiple modules in one library"* section in :pep:`489` for details.
+
+
+.. highlightlang:: c
+
+Building C and C++ Extensions with distutils
+============================================
+
+.. sectionauthor:: Martin v. Löwis <martin@v.loewis.de>
+
+Extension modules can be built using distutils,  which is included in Python.
+Since distutils also supports creation of binary packages, users don't
+necessarily need a compiler and distutils to install the extension.
+
+A distutils package contains a driver script, :file:`setup.py`. This is a plain
+Python file, which, in the most simple case, could look like this:
+
+.. code-block:: python3
+
+   from distutils.core import setup, Extension
+
+   module1 = Extension('demo',
+                       sources = ['demo.c'])
+
+   setup (name = 'PackageName',
+          version = '1.0',
+          description = 'This is a demo package',
+          ext_modules = [module1])
+
+
+With this :file:`setup.py`, and a file :file:`demo.c`, running ::
+
+   python setup.py build
+
+will compile :file:`demo.c`, and produce an extension module named ``demo`` in
+the :file:`build` directory. Depending on the system, the module file will end
+up in a subdirectory :file:`build/lib.system`, and may have a name like
+:file:`demo.so` or :file:`demo.pyd`.
+
+In the :file:`setup.py`, all execution is performed by calling the ``setup``
+function. This takes a variable number of keyword arguments, of which the
+example above uses only a subset. Specifically, the example specifies
+meta-information to build packages, and it specifies the contents of the
+package.  Normally, a package will contain additional modules, like Python
+source modules, documentation, subpackages, etc. Please refer to the distutils
+documentation in :ref:`distutils-index` to learn more about the features of
+distutils; this section explains building extension modules only.
+
+It is common to pre-compute arguments to :func:`setup`, to better structure the
+driver script. In the example above, the ``ext_modules`` argument to
+:func:`~distutils.core.setup` is a list of extension modules, each of which is
+an instance of
+the :class:`~distutils.extension.Extension`. In the example, the instance
+defines an extension named ``demo`` which is build by compiling a single source
+file, :file:`demo.c`.
+
+In many cases, building an extension is more complex, since additional
+preprocessor defines and libraries may be needed. This is demonstrated in the
+example below.
+
+.. code-block:: python3
+
+   from distutils.core import setup, Extension
+
+   module1 = Extension('demo',
+                       define_macros = [('MAJOR_VERSION', '1'),
+                                        ('MINOR_VERSION', '0')],
+                       include_dirs = ['/usr/local/include'],
+                       libraries = ['tcl83'],
+                       library_dirs = ['/usr/local/lib'],
+                       sources = ['demo.c'])
+
+   setup (name = 'PackageName',
+          version = '1.0',
+          description = 'This is a demo package',
+          author = 'Martin v. Loewis',
+          author_email = 'martin@v.loewis.de',
+          url = 'https://docs.python.org/extending/building',
+          long_description = '''
+   This is really just a demo package.
+   ''',
+          ext_modules = [module1])
+
+
+In this example, :func:`~distutils.core.setup` is called with additional
+meta-information, which
+is recommended when distribution packages have to be built. For the extension
+itself, it specifies preprocessor defines, include directories, library
+directories, and libraries. Depending on the compiler, distutils passes this
+information in different ways to the compiler. For example, on Unix, this may
+result in the compilation commands ::
+
+   gcc -DNDEBUG -g -O3 -Wall -Wstrict-prototypes -fPIC -DMAJOR_VERSION=1 -DMINOR_VERSION=0 -I/usr/local/include -I/usr/local/include/python2.2 -c demo.c -o build/temp.linux-i686-2.2/demo.o
+
+   gcc -shared build/temp.linux-i686-2.2/demo.o -L/usr/local/lib -ltcl83 -o build/lib.linux-i686-2.2/demo.so
+
+These lines are for demonstration purposes only; distutils users should trust
+that distutils gets the invocations right.
+
+
+.. _distributing:
+
+Distributing your extension modules
+===================================
+
+When an extension has been successfully build, there are three ways to use it.
+
+End-users will typically want to install the module, they do so by running ::
+
+   python setup.py install
+
+Module maintainers should produce source packages; to do so, they run ::
+
+   python setup.py sdist
+
+In some cases, additional files need to be included in a source distribution;
+this is done through a :file:`MANIFEST.in` file; see :ref:`manifest` for details.
+
+If the source distribution has been build successfully, maintainers can also
+create binary distributions. Depending on the platform, one of the following
+commands can be used to do so. ::
+
+   python setup.py bdist_wininst
+   python setup.py bdist_rpm
+   python setup.py bdist_dumb

third_party/python/Doc/extending/embedding.rst

@@ -0,0 +1,335 @@
+.. highlightlang:: c
+
+
+.. _embedding:
+
+***************************************
+Embedding Python in Another Application
+***************************************
+
+The previous chapters discussed how to extend Python, that is, how to extend the
+functionality of Python by attaching a library of C functions to it.  It is also
+possible to do it the other way around: enrich your C/C++ application by
+embedding Python in it.  Embedding provides your application with the ability to
+implement some of the functionality of your application in Python rather than C
+or C++. This can be used for many purposes; one example would be to allow users
+to tailor the application to their needs by writing some scripts in Python.  You
+can also use it yourself if some of the functionality can be written in Python
+more easily.
+
+Embedding Python is similar to extending it, but not quite.  The difference is
+that when you extend Python, the main program of the application is still the
+Python interpreter, while if you embed Python, the main program may have nothing
+to do with Python --- instead, some parts of the application occasionally call
+the Python interpreter to run some Python code.
+
+So if you are embedding Python, you are providing your own main program.  One of
+the things this main program has to do is initialize the Python interpreter.  At
+the very least, you have to call the function :c:func:`Py_Initialize`.  There are
+optional calls to pass command line arguments to Python.  Then later you can
+call the interpreter from any part of the application.
+
+There are several different ways to call the interpreter: you can pass a string
+containing Python statements to :c:func:`PyRun_SimpleString`, or you can pass a
+stdio file pointer and a file name (for identification in error messages only)
+to :c:func:`PyRun_SimpleFile`.  You can also call the lower-level operations
+described in the previous chapters to construct and use Python objects.
+
+
+.. seealso::
+
+   :ref:`c-api-index`
+      The details of Python's C interface are given in this manual. A great deal of
+      necessary information can be found here.
+
+
+.. _high-level-embedding:
+
+Very High Level Embedding
+=========================
+
+The simplest form of embedding Python is the use of the very high level
+interface. This interface is intended to execute a Python script without needing
+to interact with the application directly. This can for example be used to
+perform some operation on a file. ::
+
+   #include <Python.h>
+
+   int
+   main(int argc, char *argv[])
+   {
+       wchar_t *program = Py_DecodeLocale(argv[0], NULL);
+       if (program == NULL) {
+           fprintf(stderr, "Fatal error: cannot decode argv[0]\n");
+           exit(1);
+       }
+       Py_SetProgramName(program);  /* optional but recommended */
+       Py_Initialize();
+       PyRun_SimpleString("from time import time,ctime\n"
+                          "print('Today is', ctime(time()))\n");
+       if (Py_FinalizeEx() < 0) {
+           exit(120);
+       }
+       PyMem_RawFree(program);
+       return 0;
+   }
+
+The :c:func:`Py_SetProgramName` function should be called before
+:c:func:`Py_Initialize` to inform the interpreter about paths to Python run-time
+libraries.  Next, the Python interpreter is initialized with
+:c:func:`Py_Initialize`, followed by the execution of a hard-coded Python script
+that prints the date and time.  Afterwards, the :c:func:`Py_FinalizeEx` call shuts
+the interpreter down, followed by the end of the program.  In a real program,
+you may want to get the Python script from another source, perhaps a text-editor
+routine, a file, or a database.  Getting the Python code from a file can better
+be done by using the :c:func:`PyRun_SimpleFile` function, which saves you the
+trouble of allocating memory space and loading the file contents.
+
+
+.. _lower-level-embedding:
+
+Beyond Very High Level Embedding: An overview
+=============================================
+
+The high level interface gives you the ability to execute arbitrary pieces of
+Python code from your application, but exchanging data values is quite
+cumbersome to say the least. If you want that, you should use lower level calls.
+At the cost of having to write more C code, you can achieve almost anything.
+
+It should be noted that extending Python and embedding Python is quite the same
+activity, despite the different intent. Most topics discussed in the previous
+chapters are still valid. To show this, consider what the extension code from
+Python to C really does:
+
+#. Convert data values from Python to C,
+
+#. Perform a function call to a C routine using the converted values, and
+
+#. Convert the data values from the call from C to Python.
+
+When embedding Python, the interface code does:
+
+#. Convert data values from C to Python,
+
+#. Perform a function call to a Python interface routine using the converted
+   values, and
+
+#. Convert the data values from the call from Python to C.
+
+As you can see, the data conversion steps are simply swapped to accommodate the
+different direction of the cross-language transfer. The only difference is the
+routine that you call between both data conversions. When extending, you call a
+C routine, when embedding, you call a Python routine.
+
+This chapter will not discuss how to convert data from Python to C and vice
+versa.  Also, proper use of references and dealing with errors is assumed to be
+understood.  Since these aspects do not differ from extending the interpreter,
+you can refer to earlier chapters for the required information.
+
+
+.. _pure-embedding:
+
+Pure Embedding
+==============
+
+The first program aims to execute a function in a Python script. Like in the
+section about the very high level interface, the Python interpreter does not
+directly interact with the application (but that will change in the next
+section).
+
+The code to run a function defined in a Python script is:
+
+.. literalinclude:: ../includes/run-func.c
+
+
+This code loads a Python script using ``argv[1]``, and calls the function named
+in ``argv[2]``.  Its integer arguments are the other values of the ``argv``
+array.  If you :ref:`compile and link <compiling>` this program (let's call
+the finished executable :program:`call`), and use it to execute a Python
+script, such as:
+
+.. code-block:: python
+
+   def multiply(a,b):
+       print("Will compute", a, "times", b)
+       c = 0
+       for i in range(0, a):
+           c = c + b
+       return c
+
+then the result should be:
+
+.. code-block:: shell-session
+
+   $ call multiply multiply 3 2
+   Will compute 3 times 2
+   Result of call: 6
+
+Although the program is quite large for its functionality, most of the code is
+for data conversion between Python and C, and for error reporting.  The
+interesting part with respect to embedding Python starts with ::
+
+   Py_Initialize();
+   pName = PyUnicode_DecodeFSDefault(argv[1]);
+   /* Error checking of pName left out */
+   pModule = PyImport_Import(pName);
+
+After initializing the interpreter, the script is loaded using
+:c:func:`PyImport_Import`.  This routine needs a Python string as its argument,
+which is constructed using the :c:func:`PyUnicode_FromString` data conversion
+routine. ::
+
+   pFunc = PyObject_GetAttrString(pModule, argv[2]);
+   /* pFunc is a new reference */
+
+   if (pFunc && PyCallable_Check(pFunc)) {
+       ...
+   }
+   Py_XDECREF(pFunc);
+
+Once the script is loaded, the name we're looking for is retrieved using
+:c:func:`PyObject_GetAttrString`.  If the name exists, and the object returned is
+callable, you can safely assume that it is a function.  The program then
+proceeds by constructing a tuple of arguments as normal.  The call to the Python
+function is then made with::
+
+   pValue = PyObject_CallObject(pFunc, pArgs);
+
+Upon return of the function, ``pValue`` is either *NULL* or it contains a
+reference to the return value of the function.  Be sure to release the reference
+after examining the value.
+
+
+.. _extending-with-embedding:
+
+Extending Embedded Python
+=========================
+
+Until now, the embedded Python interpreter had no access to functionality from
+the application itself.  The Python API allows this by extending the embedded
+interpreter.  That is, the embedded interpreter gets extended with routines
+provided by the application. While it sounds complex, it is not so bad.  Simply
+forget for a while that the application starts the Python interpreter.  Instead,
+consider the application to be a set of subroutines, and write some glue code
+that gives Python access to those routines, just like you would write a normal
+Python extension.  For example::
+
+   static int numargs=0;
+
+   /* Return the number of arguments of the application command line */
+   static PyObject*
+   emb_numargs(PyObject *self, PyObject *args)
+   {
+       if(!PyArg_ParseTuple(args, ":numargs"))
+           return NULL;
+       return PyLong_FromLong(numargs);
+   }
+
+   static PyMethodDef EmbMethods[] = {
+       {"numargs", emb_numargs, METH_VARARGS,
+        "Return the number of arguments received by the process."},
+       {NULL, NULL, 0, NULL}
+   };
+
+   static PyModuleDef EmbModule = {
+       PyModuleDef_HEAD_INIT, "emb", NULL, -1, EmbMethods,
+       NULL, NULL, NULL, NULL
+   };
+
+   static PyObject*
+   PyInit_emb(void)
+   {
+       return PyModule_Create(&EmbModule);
+   }
+
+Insert the above code just above the :c:func:`main` function. Also, insert the
+following two statements before the call to :c:func:`Py_Initialize`::
+
+   numargs = argc;
+   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.
+With these extensions, the Python script can do things like
+
+.. code-block:: python
+
+   import emb
+   print("Number of arguments", emb.numargs())
+
+In a real application, the methods will expose an API of the application to
+Python.
+
+.. TODO: threads, code examples do not really behave well if errors happen
+   (what to watch out for)
+
+
+.. _embeddingincplusplus:
+
+Embedding Python in C++
+=======================
+
+It is also possible to embed Python in a C++ program; precisely how this is done
+will depend on the details of the C++ system used; in general you will need to
+write the main program in C++, and use the C++ compiler to compile and link your
+program.  There is no need to recompile Python itself using C++.
+
+
+.. _compiling:
+
+Compiling and Linking under Unix-like systems
+=============================================
+
+It is not necessarily trivial to find the right flags to pass to your
+compiler (and linker) in order to embed the Python interpreter into your
+application, particularly because Python needs to load library modules
+implemented as C dynamic extensions (:file:`.so` files) linked against
+it.
+
+To find out the required compiler and linker flags, you can execute the
+:file:`python{X.Y}-config` script which is generated as part of the
+installation process (a :file:`python3-config` script may also be
+available).  This script has several options, of which the following will
+be directly useful to you:
+
+* ``pythonX.Y-config --cflags`` will give you the recommended flags when
+  compiling:
+
+  .. code-block:: shell-session
+
+     $ /opt/bin/python3.4-config --cflags
+     -I/opt/include/python3.4m -I/opt/include/python3.4m -DNDEBUG -g -fwrapv -O3 -Wall -Wstrict-prototypes
+
+* ``pythonX.Y-config --ldflags`` will give you the recommended flags when
+  linking:
+
+  .. code-block:: shell-session
+
+     $ /opt/bin/python3.4-config --ldflags
+     -L/opt/lib/python3.4/config-3.4m -lpthread -ldl -lutil -lm -lpython3.4m -Xlinker -export-dynamic
+
+.. note::
+   To avoid confusion between several Python installations (and especially
+   between the system Python and your own compiled Python), it is recommended
+   that you use the absolute path to :file:`python{X.Y}-config`, as in the above
+   example.
+
+If this procedure doesn't work for you (it is not guaranteed to work for
+all Unix-like platforms; however, we welcome :ref:`bug reports <reporting-bugs>`)
+you will have to read your system's documentation about dynamic linking and/or
+examine Python's :file:`Makefile` (use :func:`sysconfig.get_makefile_filename`
+to find its location) and compilation
+options.  In this case, the :mod:`sysconfig` module is a useful tool to
+programmatically extract the configuration values that you will want to
+combine together.  For example:
+
+.. code-block:: pycon
+
+   >>> import sysconfig
+   >>> sysconfig.get_config_var('LIBS')
+   '-lpthread -ldl  -lutil'
+   >>> sysconfig.get_config_var('LINKFORSHARED')
+   '-Xlinker -export-dynamic'
+
+
+.. XXX similar documentation for Windows missing