[pypy-commit] benchmarks default: add cpython documentation generation by sphinx
fijal
noreply at buildbot.pypy.org
Tue Jan 17 17:21:51 CET 2012
Author: Maciej Fijalkowski <fijall at gmail.com>
Branch:
Changeset: r157:70c28be43161
Date: 2012-01-17 18:07 +0200
http://bitbucket.org/pypy/benchmarks/changeset/70c28be43161/
Log: add cpython documentation generation by sphinx
diff too long, truncating to 10000 out of 486679 lines
diff --git a/benchmarks.py b/benchmarks.py
--- a/benchmarks.py
+++ b/benchmarks.py
@@ -144,3 +144,31 @@
result.append((name, data))
return result
BM_translate.benchmark_name = 'trans'
+
+def BM_cpython_doc(base_python, changed_python, options):
+ from unladen_swallow.perf import RawResult
+ import subprocess, shutil
+ t = []
+
+ for python in [base_python, changed_python]:
+ maindir = relative('lib/cpython-doc')
+ builddir = os.path.join(os.path.join(maindir, 'tools'), 'build')
+ shutil.rmtree(builddir)
+ build = relative('lib/cpython-doc/tools/sphinx-build.py')
+ os.mkdir(builddir)
+ docdir = os.path.join(builddir, 'doctrees')
+ os.mkdir(docdir)
+ htmldir = os.path.join(builddir, 'html')
+ os.mkdir(htmldir)
+ args = base_python + [build, '-b', 'html', '-d', docdir, maindir, htmldir]
+ proc = subprocess.Popen(args, stderr=subprocess.PIPE)
+ out, err = proc.communicate()
+ retcode = proc.poll()
+ if retcode != 0:
+ print out
+ print err
+ raise Exception("sphinx-build.py failed")
+ t.append(float(out.splitlines(-1).strip()))
+ return RawResult([t[0]], [t[1]])
+
+BM_cpython_doc.benchmark_name = 'sphinx'
diff --git a/lib/cpython-doc/ACKS.txt b/lib/cpython-doc/ACKS.txt
new file mode 100644
--- /dev/null
+++ b/lib/cpython-doc/ACKS.txt
@@ -0,0 +1,237 @@
+Contributors to the Python Documentation
+----------------------------------------
+
+This section lists people who have contributed in some way to the Python
+documentation. It is probably not complete -- if you feel that you or
+anyone else should be on this list, please let us know (send email to
+docs at python.org), and we'll be glad to correct the problem.
+
+.. acks::
+
+ * Aahz
+ * Michael Abbott
+ * Steve Alexander
+ * Jim Ahlstrom
+ * Fred Allen
+ * A. Amoroso
+ * Pehr Anderson
+ * Oliver Andrich
+ * Heidi Annexstad
+ * Jesús Cea Avión
+ * Manuel Balsera
+ * Daniel Barclay
+ * Chris Barker
+ * Don Bashford
+ * Anthony Baxter
+ * Alexander Belopolsky
+ * Bennett Benson
+ * Jonathan Black
+ * Robin Boerdijk
+ * Michal Bozon
+ * Aaron Brancotti
+ * Georg Brandl
+ * Keith Briggs
+ * Ian Bruntlett
+ * Lee Busby
+ * Arnaud Calmettes
+ * Lorenzo M. Catucci
+ * Carl Cerecke
+ * Mauro Cicognini
+ * Gilles Civario
+ * Mike Clarkson
+ * Steve Clift
+ * Dave Cole
+ * Matthew Cowles
+ * Jeremy Craven
+ * Andrew Dalke
+ * Ben Darnell
+ * L. Peter Deutsch
+ * Robert Donohue
+ * Fred L. Drake, Jr.
+ * Jacques Ducasse
+ * Josip Dzolonga
+ * Jeff Epler
+ * Michael Ernst
+ * Blame Andy Eskilsson
+ * Carey Evans
+ * Martijn Faassen
+ * Carl Feynman
+ * Dan Finnie
+ * Hernán Martínez Foffani
+ * Michael Foord
+ * Stefan Franke
+ * Jim Fulton
+ * Peter Funk
+ * Lele Gaifax
+ * Matthew Gallagher
+ * Gabriel Genellina
+ * Ben Gertzfield
+ * Nadim Ghaznavi
+ * Jonathan Giddy
+ * Matt Giuca
+ * Shelley Gooch
+ * Nathaniel Gray
+ * Grant Griffin
+ * Thomas Guettler
+ * Anders Hammarquist
+ * Mark Hammond
+ * Harald Hanche-Olsen
+ * Manus Hand
+ * Gerhard Häring
+ * Travis B. Hartwell
+ * Tim Hatch
+ * Janko Hauser
+ * Ben Hayden
+ * Thomas Heller
+ * Bernhard Herzog
+ * Magnus L. Hetland
+ * Konrad Hinsen
+ * Stefan Hoffmeister
+ * Albert Hofkamp
+ * Gregor Hoffleit
+ * Steve Holden
+ * Thomas Holenstein
+ * Gerrit Holl
+ * Rob Hooft
+ * Brian Hooper
+ * Randall Hopper
+ * Michael Hudson
+ * Eric Huss
+ * Jeremy Hylton
+ * Roger Irwin
+ * Jack Jansen
+ * Philip H. Jensen
+ * Pedro Diaz Jimenez
+ * Kent Johnson
+ * Lucas de Jonge
+ * Andreas Jung
+ * Robert Kern
+ * Jim Kerr
+ * Jan Kim
+ * Kamil Kisiel
+ * Greg Kochanski
+ * Guido Kollerie
+ * Peter A. Koren
+ * Daniel Kozan
+ * Andrew M. Kuchling
+ * Dave Kuhlman
+ * Erno Kuusela
+ * Ross Lagerwall
+ * Thomas Lamb
+ * Detlef Lannert
+ * Piers Lauder
+ * Glyph Lefkowitz
+ * Robert Lehmann
+ * Marc-André Lemburg
+ * Ross Light
+ * Gediminas Liktaras
+ * Ulf A. Lindgren
+ * Everett Lipman
+ * Mirko Liss
+ * Martin von Löwis
+ * Fredrik Lundh
+ * Jeff MacDonald
+ * John Machin
+ * Andrew MacIntyre
+ * Vladimir Marangozov
+ * Vincent Marchetti
+ * Westley Martínez
+ * Laura Matson
+ * Daniel May
+ * Rebecca McCreary
+ * Doug Mennella
+ * Paolo Milani
+ * Skip Montanaro
+ * Paul Moore
+ * Ross Moore
+ * Sjoerd Mullender
+ * Dale Nagata
+ * Trent Nelson
+ * Michal Nowikowski
+ * Steffen Daode Nurpmeso
+ * Ng Pheng Siong
+ * Koray Oner
+ * Tomas Oppelstrup
+ * Denis S. Otkidach
+ * Zooko O'Whielacronx
+ * Shriphani Palakodety
+ * William Park
+ * Joonas Paalasmaa
+ * Harri Pasanen
+ * Bo Peng
+ * Tim Peters
+ * Benjamin Peterson
+ * Christopher Petrilli
+ * Justin D. Pettit
+ * Chris Phoenix
+ * François Pinard
+ * Paul Prescod
+ * Eric S. Raymond
+ * Edward K. Ream
+ * Terry J. Reedy
+ * Sean Reifschneider
+ * Bernhard Reiter
+ * Armin Rigo
+ * Wes Rishel
+ * Armin Ronacher
+ * Jim Roskind
+ * Guido van Rossum
+ * Donald Wallace Rouse II
+ * Mark Russell
+ * Nick Russo
+ * Chris Ryland
+ * Constantina S.
+ * Hugh Sasse
+ * Bob Savage
+ * Scott Schram
+ * Neil Schemenauer
+ * Barry Scott
+ * Joakim Sernbrant
+ * Justin Sheehy
+ * Charlie Shepherd
+ * Yue Shuaijie
+ * SilentGhost
+ * Michael Simcich
+ * Ionel Simionescu
+ * Michael Sloan
+ * Gregory P. Smith
+ * Roy Smith
+ * Clay Spence
+ * Nicholas Spies
+ * Tage Stabell-Kulo
+ * Frank Stajano
+ * Anthony Starks
+ * Greg Stein
+ * Peter Stoehr
+ * Mark Summerfield
+ * Reuben Sumner
+ * Kalle Svensson
+ * Jim Tittsler
+ * David Turner
+ * Sandro Tosi
+ * Ville Vainio
+ * Nadeem Vawda
+ * Martijn Vries
+ * Charles G. Waldman
+ * Greg Ward
+ * Barry Warsaw
+ * Corran Webster
+ * Glyn Webster
+ * Bob Weiner
+ * Eddy Welbourne
+ * Jeff Wheeler
+ * Mats Wichmann
+ * Gerry Wiener
+ * Timothy Wild
+ * Paul Winkler
+ * Collin Winter
+ * Blake Winton
+ * Dan Wolfe
+ * Adam Woodbeck
+ * Steven Work
+ * Thomas Wouters
+ * Ka-Ping Yee
+ * Rory Yorke
+ * Moshe Zadka
+ * Milan Zamazal
+ * Cheng Zhang
diff --git a/lib/cpython-doc/Makefile b/lib/cpython-doc/Makefile
new file mode 100644
--- /dev/null
+++ b/lib/cpython-doc/Makefile
@@ -0,0 +1,193 @@
+#
+# Makefile for Python documentation
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+#
+
+# You can set these variables from the command line.
+PYTHON = python
+SVNROOT = http://svn.python.org/projects
+SPHINXOPTS =
+PAPER =
+SOURCES =
+DISTVERSION = $(shell $(PYTHON) tools/sphinxext/patchlevel.py)
+
+ALLSPHINXOPTS = -b $(BUILDER) -d build/doctrees -D latex_paper_size=$(PAPER) \
+ $(SPHINXOPTS) . build/$(BUILDER) $(SOURCES)
+
+.PHONY: help checkout update build html htmlhelp latex text changes linkcheck \
+ suspicious coverage doctest pydoc-topics htmlview clean dist check serve \
+ autobuild-dev autobuild-stable
+
+help:
+ @echo "Please use \`make <target>' where <target> is one of"
+ @echo " clean to remove build files"
+ @echo " update to update build tools"
+ @echo " html to make standalone HTML files"
+ @echo " htmlhelp to make HTML files and a HTML help project"
+ @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+ @echo " text to make plain text files"
+ @echo " epub to make EPUB files"
+ @echo " changes to make an overview over all changed/added/deprecated items"
+ @echo " linkcheck to check all external links for integrity"
+ @echo " coverage to check documentation coverage for library and C API"
+ @echo " doctest to run doctests in the documentation"
+ @echo " pydoc-topics to regenerate the pydoc topics file"
+ @echo " dist to create a \"dist\" directory with archived docs for download"
+ @echo " suspicious to check for suspicious markup in output text"
+ @echo " check to run a check for frequent markup errors"
+ @echo " serve to serve the documentation on the localhost (8000)"
+
+# Note: if you update versions here, do the same in make.bat and README.txt
+checkout:
+ @if [ ! -d tools/sphinx ]; then \
+ echo "Checking out Sphinx..."; \
+ svn checkout $(SVNROOT)/external/Sphinx-1.0.7/sphinx tools/sphinx; \
+ fi
+ @if [ ! -d tools/docutils ]; then \
+ echo "Checking out Docutils..."; \
+ svn checkout $(SVNROOT)/external/docutils-0.6/docutils tools/docutils; \
+ fi
+ @if [ ! -d tools/jinja2 ]; then \
+ echo "Checking out Jinja..."; \
+ svn checkout $(SVNROOT)/external/Jinja-2.3.1/jinja2 tools/jinja2; \
+ fi
+ @if [ ! -d tools/pygments ]; then \
+ echo "Checking out Pygments..."; \
+ svn checkout $(SVNROOT)/external/Pygments-1.3.1/pygments tools/pygments; \
+ fi
+
+update: clean checkout
+
+build: checkout
+ mkdir -p build/$(BUILDER) build/doctrees
+ echo $(ALLSPHINXOPTS)
+ $(PYTHON) tools/sphinx-build.py $(ALLSPHINXOPTS)
+ @echo
+
+html: BUILDER = html
+html: build
+ @echo "Build finished. The HTML pages are in build/html."
+
+htmlhelp: BUILDER = htmlhelp
+htmlhelp: build
+ @echo "Build finished; now you can run HTML Help Workshop with the" \
+ "build/htmlhelp/pydoc.hhp project file."
+
+latex: BUILDER = latex
+latex: build
+ @echo "Build finished; the LaTeX files are in build/latex."
+ @echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
+ "run these through (pdf)latex."
+
+text: BUILDER = text
+text: build
+ @echo "Build finished; the text files are in build/text."
+
+epub: BUILDER = epub
+epub: build
+ @echo "Build finished; the epub files are in build/epub."
+
+changes: BUILDER = changes
+changes: build
+ @echo "The overview file is in build/changes."
+
+linkcheck: BUILDER = linkcheck
+linkcheck: build
+ @echo "Link check complete; look for any errors in the above output" \
+ "or in build/$(BUILDER)/output.txt"
+
+suspicious: BUILDER = suspicious
+suspicious: build
+ @echo "Suspicious check complete; look for any errors in the above output" \
+ "or in build/$(BUILDER)/suspicious.csv. If all issues are false" \
+ "positives, append that file to tools/sphinxext/susp-ignored.csv."
+
+coverage: BUILDER = coverage
+coverage: build
+ @echo "Coverage finished; see c.txt and python.txt in build/coverage"
+
+doctest: BUILDER = doctest
+doctest: build
+ @echo "Testing of doctests in the sources finished, look at the" \
+ "results in build/doctest/output.txt"
+
+pydoc-topics: BUILDER = pydoc-topics
+pydoc-topics: build
+ @echo "Building finished; now copy build/pydoc-topics/topics.py" \
+ "to ../Lib/pydoc_data/topics.py"
+
+htmlview: html
+ $(PYTHON) -c "import webbrowser; webbrowser.open('build/html/index.html')"
+
+clean:
+ -rm -rf build/*
+
+dist:
+ rm -rf dist
+ mkdir -p dist
+
+ # archive the HTML
+ make html
+ cp -pPR build/html dist/python-$(DISTVERSION)-docs-html
+ tar -C dist -cf dist/python-$(DISTVERSION)-docs-html.tar python-$(DISTVERSION)-docs-html
+ bzip2 -9 -k dist/python-$(DISTVERSION)-docs-html.tar
+ (cd dist; zip -q -r -9 python-$(DISTVERSION)-docs-html.zip python-$(DISTVERSION)-docs-html)
+ rm -r dist/python-$(DISTVERSION)-docs-html
+ rm dist/python-$(DISTVERSION)-docs-html.tar
+
+ # archive the text build
+ make text
+ cp -pPR build/text dist/python-$(DISTVERSION)-docs-text
+ tar -C dist -cf dist/python-$(DISTVERSION)-docs-text.tar python-$(DISTVERSION)-docs-text
+ bzip2 -9 -k dist/python-$(DISTVERSION)-docs-text.tar
+ (cd dist; zip -q -r -9 python-$(DISTVERSION)-docs-text.zip python-$(DISTVERSION)-docs-text)
+ rm -r dist/python-$(DISTVERSION)-docs-text
+ rm dist/python-$(DISTVERSION)-docs-text.tar
+
+ # archive the A4 latex
+ rm -rf build/latex
+ make latex PAPER=a4
+ -sed -i 's/makeindex/makeindex -q/' build/latex/Makefile
+ (cd build/latex; make clean && make all-pdf && make FMT=pdf zip bz2)
+ cp build/latex/docs-pdf.zip dist/python-$(DISTVERSION)-docs-pdf-a4.zip
+ cp build/latex/docs-pdf.tar.bz2 dist/python-$(DISTVERSION)-docs-pdf-a4.tar.bz2
+
+ # archive the letter latex
+ rm -rf build/latex
+ make latex PAPER=letter
+ -sed -i 's/makeindex/makeindex -q/' build/latex/Makefile
+ (cd build/latex; make clean && make all-pdf && make FMT=pdf zip bz2)
+ cp build/latex/docs-pdf.zip dist/python-$(DISTVERSION)-docs-pdf-letter.zip
+ cp build/latex/docs-pdf.tar.bz2 dist/python-$(DISTVERSION)-docs-pdf-letter.tar.bz2
+
+ # archive the epub build
+ rm -rf build/epub
+ make epub
+ mkdir -p dist/python-$(DISTVERSION)-docs-epub
+ cp -pPR build/epub/*.epub dist/python-$(DISTVERSION)-docs-epub/
+ tar -C dist -cf dist/python-$(DISTVERSION)-docs-epub.tar python-$(DISTVERSION)-docs-epub
+ bzip2 -9 -k dist/python-$(DISTVERSION)-docs-epub.tar
+ (cd dist; zip -q -r -9 python-$(DISTVERSION)-docs-epub.zip python-$(DISTVERSION)-docs-epub)
+ rm -r dist/python-$(DISTVERSION)-docs-epub
+ rm dist/python-$(DISTVERSION)-docs-epub.tar
+
+check:
+ $(PYTHON) tools/rstlint.py -i tools
+
+serve:
+ ../Tools/scripts/serve.py build/html
+
+# Targets for daily automated doc build
+
+# for development releases: always build
+autobuild-dev:
+ make update
+ make dist SPHINXOPTS='-A daily=1'
+
+# for stable releases: only build if not in pre-release stage (alpha, beta, rc)
+autobuild-stable:
+ @case $(DISTVERSION) in *[abc]*) \
+ echo "Not building; $(DISTVERSION) is not a release version."; \
+ exit 1;; \
+ esac
+ @make autobuild-dev
diff --git a/lib/cpython-doc/README.txt b/lib/cpython-doc/README.txt
new file mode 100644
--- /dev/null
+++ b/lib/cpython-doc/README.txt
@@ -0,0 +1,152 @@
+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 at http://docs.python.org/download/.
+
+Documentation on the authoring Python documentation, including information about
+both style and markup, is available in the "Documenting Python" chapter of the
+documentation. There's also a chapter intended to point out differences to
+those familiar with the previous docs written in LaTeX.
+
+
+Building the docs
+=================
+
+You need to have Python 2.4 or higher installed; the toolset used to build the
+docs is written in Python. It is called *Sphinx*, it is not included in this
+tree, but maintained separately. Also needed are the docutils, supplying the
+base markup that Sphinx uses, Jinja, a templating engine, and optionally
+Pygments, a code highlighter.
+
+
+Using make
+----------
+
+Luckily, a Makefile has been prepared so that on Unix, provided you have
+installed Python and Subversion, you can just run ::
+
+ make html
+
+to check out the necessary toolset in the `tools/` subdirectory and build the
+HTML output files. To view the generated HTML, point your favorite browser at
+the top-level index `build/html/index.html` after running "make".
+
+To use a Python interpreter that's not called ``python``, use the standard
+way to set Makefile variables, using e.g. ::
+
+ make html PYTHON=/usr/bin/python2.5
+
+Available make targets are:
+
+ * "html", which builds standalone HTML files for offline viewing.
+
+ * "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.
+
+ * "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/sphinxext/pyspecific.py` -- pydoc needs these to show topic and
+ keyword help.
+
+A "make update" updates the Subversion checkouts in `tools/`.
+
+
+Without make
+------------
+
+You'll need to install the Sphinx package, either by checking it out via ::
+
+ svn co http://svn.python.org/projects/external/Sphinx-1.0.7/sphinx tools/sphinx
+
+or by installing it from PyPI.
+
+Then, you need to install Docutils, either by checking it out via ::
+
+ svn co http://svn.python.org/projects/external/docutils-0.6/docutils tools/docutils
+
+or by installing it from http://docutils.sf.net/.
+
+You also need Jinja2, either by checking it out via ::
+
+ svn co http://svn.python.org/projects/external/Jinja-2.3.1/jinja2 tools/jinja2
+
+or by installing it from PyPI.
+
+You can optionally also install Pygments, either as a checkout via ::
+
+ svn co http://svn.python.org/projects/external/Pygments-1.3.1/pygments tools/pygments
+
+or from PyPI at http://pypi.python.org/pypi/Pygments.
+
+
+Then, make an output directory, e.g. under `build/`, and run ::
+
+ python tools/sphinx-build.py -b<builder> . build/<outputdirectory>
+
+where `<builder>` is one of html, text, latex, or htmlhelp (for explanations see
+the make targets above).
+
+
+Contributing
+============
+
+Bugs in the content should be reported to the Python bug tracker at
+http://bugs.python.org.
+
+Bugs in the toolset should be reported in the Sphinx bug tracker at
+http://www.bitbucket.org/birkenfeld/sphinx/issues/.
+
+You can also send a mail to the Python Documentation Team at docs at 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 at python.org.
+
+
+Copyright notice
+================
+
+The Python source is copyrighted, but you can freely use and copy it
+as long as you don't change or remove the copyright notice:
+
+----------------------------------------------------------------------
+Copyright (c) 2000-2012 Python Software Foundation.
+All rights reserved.
+
+Copyright (c) 2000 BeOpen.com.
+All rights reserved.
+
+Copyright (c) 1995-2000 Corporation for National Research Initiatives.
+All rights reserved.
+
+Copyright (c) 1991-1995 Stichting Mathematisch Centrum.
+All rights reserved.
+
+See the file "license.rst" for information on usage and redistribution
+of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+----------------------------------------------------------------------
diff --git a/lib/cpython-doc/about.rst b/lib/cpython-doc/about.rst
new file mode 100644
--- /dev/null
+++ b/lib/cpython-doc/about.rst
@@ -0,0 +1,36 @@
+=====================
+About these documents
+=====================
+
+
+These documents are generated from `reStructuredText`_ sources by `Sphinx`_, a
+document processor specifically written for the Python documentation.
+
+.. _reStructuredText: http://docutils.sf.net/rst.html
+.. _Sphinx: http://sphinx.pocoo.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 takes place on the
+docs at python.org mailing list. We're always looking for volunteers wanting
+to help with the docs, so feel free to send a mail there!
+
+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.sf.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.
+
+See :ref:`reporting-bugs` for information how to report bugs in this
+documentation, or Python itself.
+
+.. including the ACKS file here so that it can be maintained separately
+.. include:: ACKS.txt
+
+It is only with the input and contributions of the Python community
+that Python has such wonderful documentation -- Thank You!
diff --git a/lib/cpython-doc/bugs.rst b/lib/cpython-doc/bugs.rst
new file mode 100644
--- /dev/null
+++ b/lib/cpython-doc/bugs.rst
@@ -0,0 +1,75 @@
+.. _reporting-bugs:
+
+**************
+Reporting 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.
+
+
+Documentation bugs
+==================
+
+If you find a bug in this documentation or would like to propose an improvement,
+please send an e-mail to docs at python.org describing the bug and where you found
+it. If you have a suggestion how to fix it, include that as well.
+
+docs at python.org is a mailing list run by volunteers; your request will be
+noticed, even if it takes a while to be processed.
+
+Of course, if you want a more persistent record of your issue, you can use the
+issue tracker for documentation bugs as well.
+
+
+Using the Python issue tracker
+==============================
+
+Bug reports for Python itself should be submitted via the Python Bug Tracker
+(http://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::
+
+ `Python Developer's Guide <http://docs.python.org/devguide/>`_
+ Detailed description of the issue workflow and developers tools.
+
+ `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 <http://developer.mozilla.org/en/docs/Bug_writing_guidelines>`_
+ Information about writing a good bug report. Some of this is specific to the
+ Mozilla project, but describes general good practices.
+
diff --git a/lib/cpython-doc/c-api/abstract.rst b/lib/cpython-doc/c-api/abstract.rst
new file mode 100644
--- /dev/null
+++ b/lib/cpython-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
diff --git a/lib/cpython-doc/c-api/allocation.rst b/lib/cpython-doc/c-api/allocation.rst
new file mode 100644
--- /dev/null
+++ b/lib/cpython-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 :attr:`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 :attr:`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
+ :attr:`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.
+
diff --git a/lib/cpython-doc/c-api/arg.rst b/lib/cpython-doc/c-api/arg.rst
new file mode 100644
--- /dev/null
+++ b/lib/cpython-doc/c-api/arg.rst
@@ -0,0 +1,619 @@
+.. 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 to access an object as a contiguous chunk of memory.
+You don't have to provide raw storage for the returned unicode or bytes
+area. Also, you won't have to release any memory yourself, except with the
+``es``, ``es#``, ``et`` and ``et#`` formats.
+
+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.
+
+.. 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 NUL bytes; if it does,
+ a :exc:`TypeError` 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 bytes-like objects. 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*.
+
+``s*`` (:class:`str`, :class:`bytes`, :class:`bytearray` or buffer compatible object) [Py_buffer]
+ This format accepts Unicode objects as well as objects supporting the
+ buffer protocol.
+ 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`, :class:`bytes` or read-only buffer compatible object) [const char \*, int or :c:type:`Py_ssize_t`]
+ Like ``s*``, except that it doesn't accept mutable buffer-like objects
+ such as :class:`bytearray`. 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`, :class:`bytes`, :class:`bytearray`, buffer compatible 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`, :class:`bytes`, read-only buffer compatible 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`` (:class:`bytes`) [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 NUL bytes; if it does, a :exc:`TypeError`
+ exception is raised.
+
+``y*`` (:class:`bytes`, :class:`bytearray` or buffer compatible object) [Py_buffer]
+ This variant on ``s*`` doesn't accept Unicode objects, only objects
+ supporting the buffer protocol. **This is the recommended way to accept
+ binary data.**
+
+``y#`` (:class:`bytes`) [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 NUL characters; if it does,
+ a :exc:`TypeError` exception is raised.
+
+ .. note::
+ Since ``u`` doesn't give you back the length of the string, and it
+ may contain embedded NUL characters, it is recommended to use ``u#``
+ or ``U`` instead.
+
+``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.
+
+``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*.
+
+``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*.
+
+``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*`` (:class:`bytearray` or read-write byte-oriented buffer) [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`) [PY_LONG_LONG]
+ Convert a Python integer to a C :c:type:`long long`. This format is only
+ available on platforms that support :c:type:`long long` (or :c:type:`_int64` on
+ Windows).
+
+``K`` (:class:`int`) [unsigned PY_LONG_LONG]
+ Convert a Python integer to a C :c:type:`unsigned long long`
+ without overflow checking. This format is only available on platforms that
+ support :c:type:`unsigned long long` (or :c:type:`unsigned _int64` on Windows).
+
+``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&`` (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.
+
+``(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).
+
+``:``
+ 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. Returns true on success; on failure, it
+ returns false and raises the appropriate exception.
+
+
+.. 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. 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 :func:`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`) [Py_UNICODE \*]
+ Convert a null-terminated buffer of Unicode (UCS-2 or UCS-4) data to a Python
+ Unicode object. If the Unicode buffer pointer is *NULL*, ``None`` is returned.
+
+ ``u#`` (:class:`str`) [Py_UNICODE \*, int]
+ Convert a Unicode (UCS-2 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`) [PY_LONG_LONG]
+ Convert a C :c:type:`long long` to a Python integer object. Only available
+ on platforms that support :c:type:`long long` (or :c:type:`_int64` on
+ Windows).
+
+ ``K`` (:class:`int`) [unsigned PY_LONG_LONG]
+ Convert a C :c:type:`unsigned long long` to a Python integer object. Only
+ available on platforms that support :c:type:`unsigned long long` (or
+ :c:type:`unsigned _int64` on Windows).
+
+ ``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.
diff --git a/lib/cpython-doc/c-api/bool.rst b/lib/cpython-doc/c-api/bool.rst
new file mode 100644
--- /dev/null
+++ b/lib/cpython-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*.
diff --git a/lib/cpython-doc/c-api/buffer.rst b/lib/cpython-doc/c-api/buffer.rst
new file mode 100644
--- /dev/null
+++ b/lib/cpython-doc/c-api/buffer.rst
@@ -0,0 +1,326 @@
+.. highlightlang:: c
+
+.. _bufferobjects:
+
+Buffer Protocol
+---------------
+
+.. sectionauthor:: Greg Stein <gstein at lyra.org>
+.. sectionauthor:: Benjamin Peterson
+
+
+.. index::
+ single: buffer interface
+
+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 desireable, 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 *buffer
+protocol*. 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 a :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.
+
+
+The 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.
+
+
+.. c:type:: Py_buffer
+
+ .. c:member:: void *buf
+
+ A pointer to the start of the memory for the object.
+
+ .. c:member:: Py_ssize_t len
+ :noindex:
+
+ The total length of the memory in bytes.
+
+ .. c:member:: int readonly
+
+ An indicator of whether the buffer is read only.
+
+ .. c:member:: const char *format
+ :noindex:
+
+ A *NULL* terminated string in :mod:`struct` module style syntax giving
+ the contents of the elements available through the buffer. If this is
+ *NULL*, ``"B"`` (unsigned bytes) is assumed.
+
+ .. c:member:: int ndim
+
+ The number of dimensions the memory represents as a multi-dimensional
+ array. If it is 0, :c:data:`strides` and :c:data:`suboffsets` must be
+ *NULL*.
+
+ .. c:member:: Py_ssize_t *shape
+
+ An array of :c:type:`Py_ssize_t`\s the length of :c:data:`ndim` giving the
+ shape of the memory as a multi-dimensional array. Note that
+ ``((*shape)[0] * ... * (*shape)[ndims-1])*itemsize`` should be equal to
+ :c:data:`len`.
+
+ .. c:member:: Py_ssize_t *strides
+
+ An array of :c:type:`Py_ssize_t`\s the length of :c:data:`ndim` giving the
+ number of bytes to skip to get to a new element in each dimension.
+
+ .. c:member:: Py_ssize_t *suboffsets
+
+ An array of :c:type:`Py_ssize_t`\s the length of :c:data:`ndim`. If these
+ suboffset numbers are greater than or equal to 0, then the value stored
+ along the indicated dimension is a pointer and the suboffset value
+ dictates how many bytes to add to the pointer after de-referencing. A
+ suboffset value that it negative indicates that no de-referencing should
+ occur (striding in a contiguous memory block).
+
+ 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;
+ }
+
+
+ .. c:member:: Py_ssize_t itemsize
+
+ This is a storage for the itemsize (in bytes) of each element of the
+ shared memory. It is technically un-necessary as it can be obtained
+ using :c:func:`PyBuffer_SizeFromFormat`, however an exporter may know
+ this information without parsing the format string and it is necessary
+ to know the itemsize for proper interpretation of striding. Therefore,
+ storing it is more convenient and faster.
+
+ .. 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 should never alter this
+ value.
+
+
+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.
+
+
+.. c:function:: int PyObject_GetBuffer(PyObject *obj, Py_buffer *view, int flags)
+
+ Export a view over some internal data from the target object *obj*.
+ *obj* must not be NULL, and *view* must point to an existing
+ :c:type:`Py_buffer` structure allocated by the caller (most uses of
+ this function will simply declare a local variable of type
+ :c:type:`Py_buffer`). The *flags* argument is a bit field indicating
+ what kind of buffer is requested. The buffer interface allows
+ for complicated memory layout possibilities; however, some callers
+ won't want to handle all the complexity and instead request a simple
+ view of the target object (using :c:macro:`PyBUF_SIMPLE` for a read-only
+ view and :c:macro:`PyBUF_WRITABLE` for a read-write view).
+
+ Some exporters may not be able to share memory in every possible way and
+ may need to raise errors to signal to some consumers that something is
+ just not possible. These errors should be a :exc:`BufferError` unless
+ there is another error that is actually causing the problem. The
+ exporter can use flags information to simplify how much of the
+ :c:data:`Py_buffer` structure is filled in with non-default values and/or
+ raise an error if the object can't support a simpler view of its memory.
+
+ On success, 0 is returned and the *view* structure is filled with useful
+ values. On error, -1 is returned and an exception is raised; the *view*
+ is left in an undefined state.
+
+ The following are the possible values to the *flags* arguments.
+
+ .. c:macro:: PyBUF_SIMPLE
+
+ This is the default flag. The returned buffer exposes a read-only
+ memory area. The format of data is assumed to be raw unsigned bytes,
+ without any particular structure. This is a "stand-alone" flag
+ constant. It never needs to be '|'d to the others. The exporter will
+ raise an error if it cannot provide such a contiguous buffer of bytes.
+
+ .. c:macro:: PyBUF_WRITABLE
+
+ Like :c:macro:`PyBUF_SIMPLE`, but the returned buffer is writable. If
+ the exporter doesn't support writable buffers, an error is raised.
+
+ .. c:macro:: PyBUF_STRIDES
+
+ This implies :c:macro:`PyBUF_ND`. The returned buffer must provide
+ strides information (i.e. the strides cannot be NULL). This would be
+ used when the consumer can handle strided, discontiguous arrays.
+ Handling strides automatically assumes you can handle shape. The
+ exporter can raise an error if a strided representation of the data is
+ not possible (i.e. without the suboffsets).
+
+ .. c:macro:: PyBUF_ND
+
+ The returned buffer must provide shape information. The memory will be
+ assumed C-style contiguous (last dimension varies the fastest). The
+ exporter may raise an error if it cannot provide this kind of
+ contiguous buffer. If this is not given then shape will be *NULL*.
+
+ .. c:macro:: PyBUF_C_CONTIGUOUS
+ PyBUF_F_CONTIGUOUS
+ PyBUF_ANY_CONTIGUOUS
+
+ These flags indicate that the contiguity returned buffer must be
+ respectively, C-contiguous (last dimension varies the fastest), Fortran
+ contiguous (first dimension varies the fastest) or either one. All of
+ these flags imply :c:macro:`PyBUF_STRIDES` and guarantee that the
+ strides buffer info structure will be filled in correctly.
+
+ .. c:macro:: PyBUF_INDIRECT
+
+ This flag indicates the returned buffer must have suboffsets
+ information (which can be NULL if no suboffsets are needed). This can
+ be used when the consumer can handle indirect array referencing implied
+ by these suboffsets. This implies :c:macro:`PyBUF_STRIDES`.
+
+ .. c:macro:: PyBUF_FORMAT
+
+ The returned buffer must have true format information if this flag is
+ provided. This would be used when the consumer is going to be checking
+ for what 'kind' of data is actually stored. An exporter should always
+ be able to provide this information if requested. If format is not
+ explicitly requested then the format must be returned as *NULL* (which
+ means ``'B'``, or unsigned bytes).
+
+ .. c:macro:: PyBUF_STRIDED
+
+ This is equivalent to ``(PyBUF_STRIDES | PyBUF_WRITABLE)``.
+
+ .. c:macro:: PyBUF_STRIDED_RO
+
+ This is equivalent to ``(PyBUF_STRIDES)``.
+
+ .. c:macro:: PyBUF_RECORDS
+
+ This is equivalent to ``(PyBUF_STRIDES | PyBUF_FORMAT |
+ PyBUF_WRITABLE)``.
+
+ .. c:macro:: PyBUF_RECORDS_RO
+
+ This is equivalent to ``(PyBUF_STRIDES | PyBUF_FORMAT)``.
+
+ .. c:macro:: PyBUF_FULL
+
+ This is equivalent to ``(PyBUF_INDIRECT | PyBUF_FORMAT |
+ PyBUF_WRITABLE)``.
+
+ .. c:macro:: PyBUF_FULL_RO
+
+ This is equivalent to ``(PyBUF_INDIRECT | PyBUF_FORMAT)``.
+
+ .. c:macro:: PyBUF_CONTIG
+
+ This is equivalent to ``(PyBUF_ND | PyBUF_WRITABLE)``.
+
+ .. c:macro:: PyBUF_CONTIG_RO
+
+ This is equivalent to ``(PyBUF_ND)``.
+
+
+.. c:function:: void PyBuffer_Release(Py_buffer *view)
+
+ Release the buffer *view*. This should be called when the buffer is no
+ longer being used as it may free memory from it.
+
+
+.. c:function:: Py_ssize_t PyBuffer_SizeFromFormat(const char *)
+
+ Return the implied :c:data:`~Py_buffer.itemsize` from the struct-stype
+ :c:data:`~Py_buffer.format`.
+
+
+.. c:function:: int PyBuffer_IsContiguous(Py_buffer *view, char fortran)
+
+ Return 1 if the memory defined by the *view* is C-style (*fortran* is
+ ``'C'``) or Fortran-style (*fortran* is ``'F'``) contiguous or either one
+ (*fortran* is ``'A'``). Return 0 otherwise.
+
+
+.. c:function:: void PyBuffer_FillContiguousStrides(int ndim, Py_ssize_t *shape, Py_ssize_t *strides, Py_ssize_t itemsize, char fortran)
+
+ Fill the *strides* array with byte-strides of a contiguous (C-style if
+ *fortran* is ``'C'`` or Fortran-style if *fortran* is ``'F'``) array of the
+ given shape with the given number of bytes per element.
+
+
+.. c:function:: int PyBuffer_FillInfo(Py_buffer *view, PyObject *obj, void *buf, Py_ssize_t len, int readonly, int infoflags)
+
+ Fill in a buffer-info structure, *view*, correctly for an exporter that can
+ only share a contiguous chunk of memory of "unsigned bytes" of the given
+ length. Return 0 on success and -1 (with raising an error) on error.
+
diff --git a/lib/cpython-doc/c-api/bytearray.rst b/lib/cpython-doc/c-api/bytearray.rst
new file mode 100644
--- /dev/null
+++ b/lib/cpython-doc/c-api/bytearray.rst
@@ -0,0 +1,86 @@
+.. 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
+ buffer protocol.
+
+ .. 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.
+
+
+.. 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`.
diff --git a/lib/cpython-doc/c-api/bytes.rst b/lib/cpython-doc/c-api/bytes.rst
new file mode 100644
--- /dev/null
+++ b/lib/cpython-doc/c-api/bytes.rst
@@ -0,0 +1,192 @@
+.. 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.
+
+ +-------------------+---------------+--------------------------------+
+ | Format Characters | Type | Comment |
+ +===================+===============+================================+
+ | :attr:`%%` | *n/a* | The literal % character. |
+ +-------------------+---------------+--------------------------------+
+ | :attr:`%c` | int | A single character, |
+ | | | represented as an 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 string, 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 NUL-terminated representation of the contents of *o*. The pointer
+ refers to the internal buffer of *o*, not a copy. The data must not be
+ modified in any way, unless the string was just created using
+ ``PyBytes_FromStringAndSize(NULL, size)``. It must not be deallocated. If
+ *o* is not a string 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 a NUL-terminated representation of the contents of the object *obj*
+ through the output variables *buffer* and *length*.
+
+ If *length* is *NULL*, the resulting buffer may not contain NUL characters;
+ if it does, the function returns ``-1`` and a :exc:`TypeError` is raised.
+
+ The buffer refers to an internal string buffer of *obj*, not a copy. The data
+ must not be modified in any way, unless the string was just created using
+ ``PyBytes_FromStringAndSize(NULL, size)``. It must not be deallocated. If
+ *string* is not a string object at all, :c:func:`PyBytes_AsStringAndSize`
+ returns ``-1`` and raises :exc:`TypeError`.
+
+
+.. 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 string 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 string 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*, a memory exception is set, and ``-1`` is
+ returned.
diff --git a/lib/cpython-doc/c-api/capsule.rst b/lib/cpython-doc/c-api/capsule.rst
new file mode 100644
--- /dev/null
+++ b/lib/cpython-doc/c-api/capsule.rst
@@ -0,0 +1,150 @@
+.. highlightlang:: c
+
+.. _capsules:
+
+Capsules
+--------
+
+.. index:: object: Capsule
+
+Refer to :ref:`using-capsules` for more information on using these objects.
+
+
+.. c:type:: PyCapsule
+
+ This subtype of :c:type:`PyObject` represents an opaque value, useful for C
+ extension modules who need to pass an opaque value (as a :c:type:`void\*`
+ 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*. However, if :c:func:`PyCapsule_Import` failed to
+ import the module, and *no_block* was true, no exception is set.
+
+.. 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.
diff --git a/lib/cpython-doc/c-api/cell.rst b/lib/cpython-doc/c-api/cell.rst
new file mode 100644
--- /dev/null
+++ b/lib/cpython-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.
diff --git a/lib/cpython-doc/c-api/code.rst b/lib/cpython-doc/c-api/code.rst
new file mode 100644
--- /dev/null
+++ b/lib/cpython-doc/c-api/code.rst
@@ -0,0 +1,50 @@
+.. highlightlang:: c
+
+.. _codeobjects:
+
+Code Objects
+------------
+
+.. sectionauthor:: Jeffrey Yasskin <jyasskin at gmail.com>
+
+
+.. index::
+ object: code
+
+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(PyObject *co)
+
+ Return the number of free variables in *co*.
+
+.. c:function:: PyCodeObject *PyCode_New(int argcount, 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:: int 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.
diff --git a/lib/cpython-doc/c-api/codec.rst b/lib/cpython-doc/c-api/codec.rst
new file mode 100644
--- /dev/null
+++ b/lib/cpython-doc/c-api/codec.rst
@@ -0,0 +1,118 @@
+.. _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*.
+
+.. 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:`IncrementalEncoder` object for the given *encoding*.
+
+.. c:function:: PyObject* PyCodec_IncrementalDecoder(const char *encoding, const char *errors)
+
+ Get an :class:`IncrementalDecoder` object for the given *encoding*.
+
+.. c:function:: PyObject* PyCodec_StreamReader(const char *encoding, PyObject *stream, const char *errors)
+
+ Get a :class:`StreamReader` factory function for the given *encoding*.
+
+.. c:function:: PyObject* PyCodec_StreamWriter(const char *encoding, PyObject *stream, const char *errors)
+
+ Get a :class:`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``).
+
diff --git a/lib/cpython-doc/c-api/complex.rst b/lib/cpython-doc/c-api/complex.rst
new file mode 100644
--- /dev/null
+++ b/lib/cpython-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.
diff --git a/lib/cpython-doc/c-api/concrete.rst b/lib/cpython-doc/c-api/concrete.rst
new file mode 100644
--- /dev/null
+++ b/lib/cpython-doc/c-api/concrete.rst
@@ -0,0 +1,108 @@
+.. 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:
+
+Mapping Objects
+===============
+
+.. index:: object: mapping
+
+.. toctree::
+
+ dict.rst
+
+
+.. _otherobjects:
+
+Other Objects
+=============
+
+.. toctree::
+
+ set.rst
+ function.rst
+ method.rst
+ file.rst
+ module.rst
+ iterator.rst
+ descriptor.rst
+ slice.rst
+ memoryview.rst
+ weakref.rst
+ capsule.rst
+ cell.rst
+ gen.rst
+ datetime.rst
+ code.rst
diff --git a/lib/cpython-doc/c-api/conversion.rst b/lib/cpython-doc/c-api/conversion.rst
new file mode 100644
--- /dev/null
+++ b/lib/cpython-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:: char* PyOS_stricmp(char *s1, char *s2)
+
+ Case insensitive comparison of strings. The function works almost
+ identically to :c:func:`strcmp` except that it ignores the case.
+
+
+.. c:function:: char* PyOS_strnicmp(char *s1, 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.
diff --git a/lib/cpython-doc/c-api/datetime.rst b/lib/cpython-doc/c-api/datetime.rst
new file mode 100644
--- /dev/null
+++ b/lib/cpython-doc/c-api/datetime.rst
@@ -0,0 +1,184 @@
+.. 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 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()``.
diff --git a/lib/cpython-doc/c-api/descriptor.rst b/lib/cpython-doc/c-api/descriptor.rst
new file mode 100644
--- /dev/null
+++ b/lib/cpython-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 *)
diff --git a/lib/cpython-doc/c-api/dict.rst b/lib/cpython-doc/c-api/dict.rst
new file mode 100644
--- /dev/null
+++ b/lib/cpython-doc/c-api/dict.rst
@@ -0,0 +1,218 @@
+.. 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 *dict)
+
+ Return a proxy object for a mapping which enforces read-only behavior.
+ This is normally used to create a proxy 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, 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.
+
+
+.. 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\*`.
+
+
+.. 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, or ``a.update(b)`` in
+ Python. 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
diff --git a/lib/cpython-doc/c-api/exceptions.rst b/lib/cpython-doc/c-api/exceptions.rst
new file mode 100644
--- /dev/null
+++ b/lib/cpython-doc/c-api/exceptions.rst
@@ -0,0 +1,750 @@
+.. highlightlang:: c
+
+
+.. _exceptionhandling:
+
+******************
+Exception Handling
+******************
+
+The functions described in this chapter will let you handle and raise Python
+exceptions. It is important to understand some of the basics of Python
+exception handling. It works somewhat like the Unix :c:data:`errno` variable:
+there is a global indicator (per thread) of the last error that occurred. Most
+functions don't clear this on success, but will set it to indicate the cause of
+the error on failure. Most functions also return an error indicator, usually
+*NULL* if they are supposed to return a pointer, or ``-1`` if they return an
+integer (exception: the :c:func:`PyArg_\*` functions return ``1`` for success and
+``0`` for failure).
+
+When a function must fail because some function it called failed, it generally
+doesn't set the error indicator; the function it called already set it. It is
+responsible for either handling the error and clearing the exception or
+returning after cleaning up any resources it holds (such as object references or
+memory allocations); it should *not* continue normally if it is not prepared to
+handle the error. If returning due to an error, it is important to indicate to
+the caller that an error has been set. If the error is not handled or carefully
+propagated, additional calls into the Python/C API may not behave as intended
+and may fail in mysterious ways.
+
+The error indicator consists of three Python objects corresponding to the result
+of ``sys.exc_info()``. API functions exist to interact with the error indicator
+in various ways. There is a separate error indicator for each thread.
+
+.. XXX Order of these should be more thoughtful.
+ Either alphabetical or some kind of structure.
+
+
+.. c:function:: void PyErr_PrintEx(int set_sys_last_vars)
+
+ Print a standard traceback to ``sys.stderr`` and clear the error indicator.
+ Call this function only when the error indicator is set. (Otherwise it will
+ cause a fatal error!)
+
+ If *set_sys_last_vars* is nonzero, the variables :data:`sys.last_type`,
+ :data:`sys.last_value` and :data:`sys.last_traceback` will be set to the
+ type, value and traceback of the printed exception, respectively.
+
+
+.. c:function:: void PyErr_Print()
+
+ Alias for ``PyErr_PrintEx(1)``.
+
+
+.. c:function:: PyObject* PyErr_Occurred()
+
+ Test whether the error indicator is set. If set, return the exception *type*
+ (the first argument to the last call to one of the :c:func:`PyErr_Set\*`
+ functions or to :c:func:`PyErr_Restore`). If not set, return *NULL*. You do not
+ own a reference to the return value, so you do not need to :c:func:`Py_DECREF`
+ it.
+
+ .. note::
+
+ Do not compare the return value to a specific exception; use
+ :c:func:`PyErr_ExceptionMatches` instead, shown below. (The comparison could
+ easily fail since the exception may be an instance instead of a class, in the
+ case of a class exception, or it may the a subclass of the expected exception.)
+
+
+.. c:function:: int PyErr_ExceptionMatches(PyObject *exc)
+
+ Equivalent to ``PyErr_GivenExceptionMatches(PyErr_Occurred(), exc)``. This
+ should only be called when an exception is actually set; a memory access
+ violation will occur if no exception has been raised.
+
+
+.. c:function:: int PyErr_GivenExceptionMatches(PyObject *given, PyObject *exc)
+
+ Return true if the *given* exception matches the exception in *exc*. If
+ *exc* is a class object, this also returns true when *given* is an instance
+ of a subclass. If *exc* is a tuple, all exceptions in the tuple (and
+ recursively in subtuples) are searched for a match.
+
+
+.. c:function:: void PyErr_NormalizeException(PyObject**exc, PyObject**val, PyObject**tb)
+
+ Under certain circumstances, the values returned by :c:func:`PyErr_Fetch` below
+ can be "unnormalized", meaning that ``*exc`` is a class object but ``*val`` is
+ not an instance of the same class. This function can be used to instantiate
+ the class in that case. If the values are already normalized, nothing happens.
+ The delayed normalization is implemented to improve performance.
+
+
+.. c:function:: void PyErr_Clear()
+
+ Clear the error indicator. If the error indicator is not set, there is no
+ effect.
+
+
+.. c:function:: void PyErr_Fetch(PyObject **ptype, PyObject **pvalue, PyObject **ptraceback)
+
+ Retrieve the error indicator into three variables whose addresses are passed.
+ If the error indicator is not set, set all three variables to *NULL*. If it is
+ set, it will be cleared and you own a reference to each object retrieved. The
+ value and traceback object may be *NULL* even when the type object is not.
+
+ .. note::
+
+ This function is normally only used by code that needs to handle exceptions or
+ by code that needs to save and restore the error indicator temporarily.
+
+
+.. c:function:: void PyErr_Restore(PyObject *type, PyObject *value, PyObject *traceback)
+
+ Set the error indicator from the three objects. If the error indicator is
+ already set, it is cleared first. If the objects are *NULL*, the error
+ indicator is cleared. Do not pass a *NULL* type and non-*NULL* value or
+ traceback. The exception type should be a class. Do not pass an invalid
+ exception type or value. (Violating these rules will cause subtle problems
+ later.) This call takes away a reference to each object: you must own a
+ reference to each object before the call and after the call you no longer own
+ these references. (If you don't understand this, don't use this function. I
+ warned you.)
+
+ .. note::
+
+ This function is normally only used by code that needs to save and restore the
+ error indicator temporarily; use :c:func:`PyErr_Fetch` to save the current
+ exception state.
+
+
+.. c:function:: void PyErr_SetString(PyObject *type, const char *message)
+
+ This is the most common way to set the error indicator. The first argument
+ specifies the exception type; it is normally one of the standard exceptions,
+ e.g. :c:data:`PyExc_RuntimeError`. You need not increment its reference count.
+ The second argument is an error message; it is decoded from ``'utf-8``'.
+
+
+.. c:function:: void PyErr_SetObject(PyObject *type, PyObject *value)
+
+ This function is similar to :c:func:`PyErr_SetString` but lets you specify an
+ arbitrary Python object for the "value" of the exception.
+
+
+.. c:function:: PyObject* PyErr_Format(PyObject *exception, const char *format, ...)
+
+ This function sets the error indicator and returns *NULL*. *exception*
+ should be a Python exception class. The *format* and subsequent
+ parameters help format the error message; they have the same meaning and
+ values as in :c:func:`PyUnicode_FromFormat`. *format* is an ASCII-encoded
+ string.
+
+
+.. c:function:: void PyErr_SetNone(PyObject *type)
+
+ This is a shorthand for ``PyErr_SetObject(type, Py_None)``.
+
+
+.. c:function:: int PyErr_BadArgument()
+
+ This is a shorthand for ``PyErr_SetString(PyExc_TypeError, message)``, where
+ *message* indicates that a built-in operation was invoked with an illegal
+ argument. It is mostly for internal use.
+
+
+.. c:function:: PyObject* PyErr_NoMemory()
+
+ This is a shorthand for ``PyErr_SetNone(PyExc_MemoryError)``; it returns *NULL*
+ so an object allocation function can write ``return PyErr_NoMemory();`` when it
+ runs out of memory.
+
+
+.. c:function:: PyObject* PyErr_SetFromErrno(PyObject *type)
+
+ .. index:: single: strerror()
+
+ This is a convenience function to raise an exception when a C library function
+ has returned an error and set the C variable :c:data:`errno`. It constructs a
+ tuple object whose first item is the integer :c:data:`errno` value and whose
+ second item is the corresponding error message (gotten from :c:func:`strerror`),
+ and then calls ``PyErr_SetObject(type, object)``. On Unix, when the
+ :c:data:`errno` value is :const:`EINTR`, indicating an interrupted system call,
+ this calls :c:func:`PyErr_CheckSignals`, and if that set the error indicator,
+ leaves it set to that. The function always returns *NULL*, so a wrapper
+ function around a system call can write ``return PyErr_SetFromErrno(type);``
+ when the system call returns an error.
+
+
+.. c:function:: PyObject* PyErr_SetFromErrnoWithFilename(PyObject *type, const char *filename)
+
+ Similar to :c:func:`PyErr_SetFromErrno`, with the additional behavior that if
+ *filename* is not *NULL*, it is passed to the constructor of *type* as a third
+ parameter. In the case of exceptions such as :exc:`IOError` and :exc:`OSError`,
+ this is used to define the :attr:`filename` attribute of the exception instance.
+ *filename* is decoded from the filesystem encoding
+ (:func:`sys.getfilesystemencoding`).
+
+
+.. c:function:: PyObject* PyErr_SetFromWindowsErr(int ierr)
+
+ This is a convenience function to raise :exc:`WindowsError`. If called with
+ *ierr* of :c:data:`0`, the error code returned by a call to :c:func:`GetLastError`
+ is used instead. It calls the Win32 function :c:func:`FormatMessage` to retrieve
+ the Windows description of error code given by *ierr* or :c:func:`GetLastError`,
+ then it constructs a tuple object whose first item is the *ierr* value and whose
+ second item is the corresponding error message (gotten from
+ :c:func:`FormatMessage`), and then calls ``PyErr_SetObject(PyExc_WindowsError,
+ object)``. This function always returns *NULL*. Availability: Windows.
+
+
+.. c:function:: PyObject* PyErr_SetExcFromWindowsErr(PyObject *type, int ierr)
+
+ Similar to :c:func:`PyErr_SetFromWindowsErr`, with an additional parameter
+ specifying the exception type to be raised. Availability: Windows.
+
+
+.. c:function:: PyObject* PyErr_SetFromWindowsErrWithFilename(int ierr, const char *filename)
+
+ Similar to :c:func:`PyErr_SetFromWindowsErr`, with the additional behavior that
+ if *filename* is not *NULL*, it is passed to the constructor of
+ :exc:`WindowsError` as a third parameter. *filename* is decoded from the
+ filesystem encoding (:func:`sys.getfilesystemencoding`). Availability:
+ Windows.
+
+
+.. c:function:: PyObject* PyErr_SetExcFromWindowsErrWithFilename(PyObject *type, int ierr, char *filename)
+
+ Similar to :c:func:`PyErr_SetFromWindowsErrWithFilename`, with an additional
+ parameter specifying the exception type to be raised. Availability: Windows.
+
+
+.. c:function:: void PyErr_SyntaxLocationEx(char *filename, int lineno, int col_offset)
+
+ Set file, line, and offset information for the current exception. If the
+ current exception is not a :exc:`SyntaxError`, then it sets additional
+ attributes, which make the exception printing subsystem think the exception
+ is a :exc:`SyntaxError`. *filename* is decoded from the filesystem encoding
+ (:func:`sys.getfilesystemencoding`).
+
+.. versionadded:: 3.2
+
+
+.. c:function:: void PyErr_SyntaxLocation(char *filename, int lineno)
+
+ Like :c:func:`PyErr_SyntaxLocationExc`, but the col_offset parameter is
+ omitted.
+
+
+.. c:function:: void PyErr_BadInternalCall()
+
+ This is a shorthand for ``PyErr_SetString(PyExc_SystemError, message)``,
+ where *message* indicates that an internal operation (e.g. a Python/C API
+ function) was invoked with an illegal argument. It is mostly for internal
+ use.
+
+
+.. c:function:: int PyErr_WarnEx(PyObject *category, char *message, int stack_level)
+
+ Issue a warning message. The *category* argument is a warning category (see
+ below) or *NULL*; the *message* argument is an UTF-8 encoded string. *stack_level* is a
+ positive number giving a number of stack frames; the warning will be issued from
+ the currently executing line of code in that stack frame. A *stack_level* of 1
+ is the function calling :c:func:`PyErr_WarnEx`, 2 is the function above that,
+ and so forth.
+
+ This function normally prints a warning message to *sys.stderr*; however, it is
+ also possible that the user has specified that warnings are to be turned into
+ errors, and in that case this will raise an exception. It is also possible that
+ the function raises an exception because of a problem with the warning machinery
+ (the implementation imports the :mod:`warnings` module to do the heavy lifting).
+ The return value is ``0`` if no exception is raised, or ``-1`` if an exception
+ is raised. (It is not possible to determine whether a warning message is
+ actually printed, nor what the reason is for the exception; this is
+ intentional.) If an exception is raised, the caller should do its normal
+ exception handling (for example, :c:func:`Py_DECREF` owned references and return
+ an error value).
+
+ Warning categories must be subclasses of :c:data:`Warning`; the default warning
+ category is :c:data:`RuntimeWarning`. The standard Python warning categories are
+ available as global variables whose names are ``PyExc_`` followed by the Python
+ exception name. These have the type :c:type:`PyObject\*`; they are all class
+ objects. Their names are :c:data:`PyExc_Warning`, :c:data:`PyExc_UserWarning`,
+ :c:data:`PyExc_UnicodeWarning`, :c:data:`PyExc_DeprecationWarning`,
+ :c:data:`PyExc_SyntaxWarning`, :c:data:`PyExc_RuntimeWarning`, and
+ :c:data:`PyExc_FutureWarning`. :c:data:`PyExc_Warning` is a subclass of
+ :c:data:`PyExc_Exception`; the other warning categories are subclasses of
+ :c:data:`PyExc_Warning`.
+
+ For information about warning control, see the documentation for the
+ :mod:`warnings` module and the :option:`-W` option in the command line
+ documentation. There is no C API for warning control.
+
+
+.. c:function:: int PyErr_WarnExplicit(PyObject *category, const char *message, const char *filename, int lineno, const char *module, PyObject *registry)
+
+ Issue a warning message with explicit control over all warning attributes. This
+ is a straightforward wrapper around the Python function
+ :func:`warnings.warn_explicit`, see there for more information. The *module*
+ and *registry* arguments may be set to *NULL* to get the default effect
+ described there. *message* and *module* are UTF-8 encoded strings,
+ *filename* is decoded from the filesystem encoding
+ (:func:`sys.getfilesystemencoding`).
+
+
+.. c:function:: int PyErr_WarnFormat(PyObject *category, Py_ssize_t stack_level, const char *format, ...)
+
+ Function similar to :c:func:`PyErr_WarnEx`, but use
+ :c:func:`PyUnicode_FromFormat` to format the warning message. *format* is
+ an ASCII-encoded string.
+
+ .. versionadded:: 3.2
+
+.. c:function:: int PyErr_CheckSignals()
+
+ .. index::
+ module: signal
+ single: SIGINT
+ single: KeyboardInterrupt (built-in exception)
+
+ This function interacts with Python's signal handling. It checks whether a
+ signal has been sent to the processes and if so, invokes the corresponding
+ signal handler. If the :mod:`signal` module is supported, this can invoke a
+ signal handler written in Python. In all cases, the default effect for
+ :const:`SIGINT` is to raise the :exc:`KeyboardInterrupt` exception. If an
+ exception is raised the error indicator is set and the function returns ``-1``;
+ otherwise the function returns ``0``. The error indicator may or may not be
+ cleared if it was previously set.
+
+
+.. c:function:: void PyErr_SetInterrupt()
+
+ .. index::
+ single: SIGINT
+ single: KeyboardInterrupt (built-in exception)
+
+ This function simulates the effect of a :const:`SIGINT` signal arriving --- the
+ next time :c:func:`PyErr_CheckSignals` is called, :exc:`KeyboardInterrupt` will
+ be raised. It may be called without holding the interpreter lock.
+
+ .. % XXX This was described as obsolete, but is used in
+ .. % _thread.interrupt_main() (used from IDLE), so it's still needed.
+
+
+.. c:function:: int PySignal_SetWakeupFd(int fd)
+
+ This utility function specifies a file descriptor to which a ``'\0'`` byte will
+ be written whenever a signal is received. It returns the previous such file
+ descriptor. The value ``-1`` disables the feature; this is the initial state.
+ This is equivalent to :func:`signal.set_wakeup_fd` in Python, but without any
+ error checking. *fd* should be a valid file descriptor. The function should
+ only be called from the main thread.
+
+
+.. c:function:: PyObject* PyErr_NewException(char *name, PyObject *base, PyObject *dict)
+
+ This utility function creates and returns a new exception class. The *name*
+ argument must be the name of the new exception, a C string of the form
+ ``module.classname``. The *base* and *dict* arguments are normally *NULL*.
+ This creates a class object derived from :exc:`Exception` (accessible in C as
+ :c:data:`PyExc_Exception`).
+
+ The :attr:`__module__` attribute of the new class is set to the first part (up
+ to the last dot) of the *name* argument, and the class name is set to the last
+ part (after the last dot). The *base* argument can be used to specify alternate
+ base classes; it can either be only one class or a tuple of classes. The *dict*
+ argument can be used to specify a dictionary of class variables and methods.
+
+
+.. c:function:: PyObject* PyErr_NewExceptionWithDoc(char *name, char *doc, PyObject *base, PyObject *dict)
+
+ Same as :c:func:`PyErr_NewException`, except that the new exception class can
+ easily be given a docstring: If *doc* is non-*NULL*, it will be used as the
+ docstring for the exception class.
+
+ .. versionadded:: 3.2
+
+
+.. c:function:: void PyErr_WriteUnraisable(PyObject *obj)
+
+ This utility function prints a warning message to ``sys.stderr`` when an
+ exception has been set but it is impossible for the interpreter to actually
+ raise the exception. It is used, for example, when an exception occurs in an
+ :meth:`__del__` method.
+
+ The function is called with a single argument *obj* that identifies the context
+ in which the unraisable exception occurred. The repr of *obj* will be printed in
+ the warning message.
+
+
+Exception Objects
+=================
+
+.. c:function:: PyObject* PyException_GetTraceback(PyObject *ex)
+
+ Return the traceback associated with the exception as a new reference, as
+ accessible from Python through :attr:`__traceback__`. If there is no
+ traceback associated, this returns *NULL*.
+
+
+.. c:function:: int PyException_SetTraceback(PyObject *ex, PyObject *tb)
+
+ Set the traceback associated with the exception to *tb*. Use ``Py_None`` to
+ clear it.
+
+
+.. c:function:: PyObject* PyException_GetContext(PyObject *ex)
+
+ Return the context (another exception instance during whose handling *ex* was
+ raised) associated with the exception as a new reference, as accessible from
+ Python through :attr:`__context__`. If there is no context associated, this
+ returns *NULL*.
+
+
+.. c:function:: void PyException_SetContext(PyObject *ex, PyObject *ctx)
+
+ Set the context associated with the exception to *ctx*. Use *NULL* to clear
+ it. There is no type check to make sure that *ctx* is an exception instance.
+ This steals a reference to *ctx*.
+
+
+.. c:function:: PyObject* PyException_GetCause(PyObject *ex)
+
+ Return the cause (another exception instance set by ``raise ... from ...``)
+ associated with the exception as a new reference, as accessible from Python
+ through :attr:`__cause__`. If there is no cause associated, this returns
+ *NULL*.
+
+
+.. c:function:: void PyException_SetCause(PyObject *ex, PyObject *ctx)
+
+ Set the cause associated with the exception to *ctx*. Use *NULL* to clear
+ it. There is no type check to make sure that *ctx* is an exception instance.
+ This steals a reference to *ctx*.
+
+
+.. _unicodeexceptions:
+
+Unicode Exception Objects
+=========================
+
+The following functions are used to create and modify Unicode exceptions from C.
+
+.. c:function:: PyObject* PyUnicodeDecodeError_Create(const char *encoding, const char *object, Py_ssize_t length, Py_ssize_t start, Py_ssize_t end, const char *reason)
+
+ Create a :class:`UnicodeDecodeError` object with the attributes *encoding*,
+ *object*, *length*, *start*, *end* and *reason*. *encoding* and *reason* are
+ UTF-8 encoded strings.
+
+.. c:function:: PyObject* PyUnicodeEncodeError_Create(const char *encoding, const Py_UNICODE *object, Py_ssize_t length, Py_ssize_t start, Py_ssize_t end, const char *reason)
+
+ Create a :class:`UnicodeEncodeError` object with the attributes *encoding*,
+ *object*, *length*, *start*, *end* and *reason*. *encoding* and *reason* are
+ UTF-8 encoded strings.
+
+.. c:function:: PyObject* PyUnicodeTranslateError_Create(const Py_UNICODE *object, Py_ssize_t length, Py_ssize_t start, Py_ssize_t end, const char *reason)
+
+ Create a :class:`UnicodeTranslateError` object with the attributes *object*,
+ *length*, *start*, *end* and *reason*. *reason* is an UTF-8 encoded string.
+
+.. c:function:: PyObject* PyUnicodeDecodeError_GetEncoding(PyObject *exc)
+ PyObject* PyUnicodeEncodeError_GetEncoding(PyObject *exc)
+
+ Return the *encoding* attribute of the given exception object.
+
+.. c:function:: PyObject* PyUnicodeDecodeError_GetObject(PyObject *exc)
+ PyObject* PyUnicodeEncodeError_GetObject(PyObject *exc)
+ PyObject* PyUnicodeTranslateError_GetObject(PyObject *exc)
+
+ Return the *object* attribute of the given exception object.
+
+.. c:function:: int PyUnicodeDecodeError_GetStart(PyObject *exc, Py_ssize_t *start)
+ int PyUnicodeEncodeError_GetStart(PyObject *exc, Py_ssize_t *start)
+ int PyUnicodeTranslateError_GetStart(PyObject *exc, Py_ssize_t *start)
+
+ Get the *start* attribute of the given exception object and place it into
+ *\*start*. *start* must not be *NULL*. Return ``0`` on success, ``-1`` on
+ failure.
+
+.. c:function:: int PyUnicodeDecodeError_SetStart(PyObject *exc, Py_ssize_t start)
+ int PyUnicodeEncodeError_SetStart(PyObject *exc, Py_ssize_t start)
+ int PyUnicodeTranslateError_SetStart(PyObject *exc, Py_ssize_t start)
+
+ Set the *start* attribute of the given exception object to *start*. Return
+ ``0`` on success, ``-1`` on failure.
+
+.. c:function:: int PyUnicodeDecodeError_GetEnd(PyObject *exc, Py_ssize_t *end)
+ int PyUnicodeEncodeError_GetEnd(PyObject *exc, Py_ssize_t *end)
+ int PyUnicodeTranslateError_GetEnd(PyObject *exc, Py_ssize_t *end)
+
+ Get the *end* attribute of the given exception object and place it into
+ *\*end*. *end* must not be *NULL*. Return ``0`` on success, ``-1`` on
+ failure.
+
+.. c:function:: int PyUnicodeDecodeError_SetEnd(PyObject *exc, Py_ssize_t end)
+ int PyUnicodeEncodeError_SetEnd(PyObject *exc, Py_ssize_t end)
+ int PyUnicodeTranslateError_SetEnd(PyObject *exc, Py_ssize_t end)
+
+ Set the *end* attribute of the given exception object to *end*. Return ``0``
+ on success, ``-1`` on failure.
+
+.. c:function:: PyObject* PyUnicodeDecodeError_GetReason(PyObject *exc)
+ PyObject* PyUnicodeEncodeError_GetReason(PyObject *exc)
+ PyObject* PyUnicodeTranslateError_GetReason(PyObject *exc)
+
+ Return the *reason* attribute of the given exception object.
+
+.. c:function:: int PyUnicodeDecodeError_SetReason(PyObject *exc, const char *reason)
+ int PyUnicodeEncodeError_SetReason(PyObject *exc, const char *reason)
+ int PyUnicodeTranslateError_SetReason(PyObject *exc, const char *reason)
+
+ Set the *reason* attribute of the given exception object to *reason*. Return
+ ``0`` on success, ``-1`` on failure.
+
+
+Recursion Control
+=================
+
+These two functions provide a way to perform safe recursive calls at the C
+level, both in the core and in extension modules. They are needed if the
+recursive code does not necessarily invoke Python code (which tracks its
+recursion depth automatically).
+
+.. c:function:: int Py_EnterRecursiveCall(char *where)
+
+ Marks a point where a recursive C-level call is about to be performed.
+
+ If :const:`USE_STACKCHECK` is defined, this function checks if the OS
+ stack overflowed using :c:func:`PyOS_CheckStack`. In this is the case, it
+ sets a :exc:`MemoryError` and returns a nonzero value.
+
+ The function then checks if the recursion limit is reached. If this is the
+ case, a :exc:`RuntimeError` is set and a nonzero value is returned.
+ Otherwise, zero is returned.
+
+ *where* should be a string such as ``" in instance check"`` to be
+ concatenated to the :exc:`RuntimeError` message caused by the recursion depth
+ limit.
+
+.. c:function:: void Py_LeaveRecursiveCall()
+
+ Ends a :c:func:`Py_EnterRecursiveCall`. Must be called once for each
+ *successful* invocation of :c:func:`Py_EnterRecursiveCall`.
+
+Properly implementing :attr:`tp_repr` for container types requires
+special recursion handling. In addition to protecting the stack,
+:attr:`tp_repr` also needs to track objects to prevent cycles. The
+following two functions facilitate this functionality. Effectively,
+these are the C equivalent to :func:`reprlib.recursive_repr`.
+
+.. c:function:: int Py_ReprEnter(PyObject *object)
+
+ Called at the beginning of the :attr:`tp_repr` implementation to
+ detect cycles.
+
+ If the object has already been processed, the function returns a
+ positive integer. In that case the :attr:`tp_repr` implementation
+ should return a string object indicating a cycle. As examples,
+ :class:`dict` objects return ``{...}`` and :class:`list` objects
+ return ``[...]``.
+
+ The function will return a negative integer if the recursion limit
+ is reached. In that case the :attr:`tp_repr` implementation should
+ typically return ``NULL``.
+
+ Otherwise, the function returns zero and the :attr:`tp_repr`
+ implementation can continue normally.
+
+.. c:function:: void Py_ReprLeave(PyObject *object)
+
+ Ends a :c:func:`Py_ReprEnter`. Must be called once for each
+ invocation of :c:func:`Py_ReprEnter` that returns zero.
+
+
+.. _standardexceptions:
+
+Standard Exceptions
+===================
+
+All standard Python exceptions are available as global variables whose names are
+``PyExc_`` followed by the Python exception name. These have the type
+:c:type:`PyObject\*`; they are all class objects. For completeness, here are all
+the variables:
+
++-----------------------------------------+---------------------------------+----------+
+| C Name | Python Name | Notes |
++=========================================+=================================+==========+
+| :c:data:`PyExc_BaseException` | :exc:`BaseException` | \(1) |
++-----------------------------------------+---------------------------------+----------+
+| :c:data:`PyExc_Exception` | :exc:`Exception` | \(1) |
++-----------------------------------------+---------------------------------+----------+
+| :c:data:`PyExc_ArithmeticError` | :exc:`ArithmeticError` | \(1) |
++-----------------------------------------+---------------------------------+----------+
+| :c:data:`PyExc_LookupError` | :exc:`LookupError` | \(1) |
++-----------------------------------------+---------------------------------+----------+
+| :c:data:`PyExc_AssertionError` | :exc:`AssertionError` | |
++-----------------------------------------+---------------------------------+----------+
+| :c:data:`PyExc_AttributeError` | :exc:`AttributeError` | |
++-----------------------------------------+---------------------------------+----------+
+| :c:data:`PyExc_BlockingIOError` | :exc:`BlockingIOError` | |
++-----------------------------------------+---------------------------------+----------+
+| :c:data:`PyExc_BrokenPipeError` | :exc:`BrokenPipeError` | |
++-----------------------------------------+---------------------------------+----------+
+| :c:data:`PyExc_ChildProcessError` | :exc:`ChildProcessError` | |
++-----------------------------------------+---------------------------------+----------+
+| :c:data:`PyExc_ConnectionError` | :exc:`ConnectionError` | |
++-----------------------------------------+---------------------------------+----------+
+| :c:data:`PyExc_ConnectionAbortedError` | :exc:`ConnectionAbortedError` | |
++-----------------------------------------+---------------------------------+----------+
+| :c:data:`PyExc_ConnectionRefusedError` | :exc:`ConnectionRefusedError` | |
++-----------------------------------------+---------------------------------+----------+
+| :c:data:`PyExc_ConnectionResetError` | :exc:`ConnectionResetError` | |
++-----------------------------------------+---------------------------------+----------+
+| :c:data:`PyExc_FileExistsError` | :exc:`FileExistsError` | |
++-----------------------------------------+---------------------------------+----------+
+| :c:data:`PyExc_FileNotFoundError` | :exc:`FileNotFoundError` | |
++-----------------------------------------+---------------------------------+----------+
+| :c:data:`PyExc_EOFError` | :exc:`EOFError` | |
++-----------------------------------------+---------------------------------+----------+
+| :c:data:`PyExc_FloatingPointError` | :exc:`FloatingPointError` | |
++-----------------------------------------+---------------------------------+----------+
+| :c:data:`PyExc_ImportError` | :exc:`ImportError` | |
++-----------------------------------------+---------------------------------+----------+
+| :c:data:`PyExc_IndexError` | :exc:`IndexError` | |
++-----------------------------------------+---------------------------------+----------+
+| :c:data:`PyExc_InterruptedError` | :exc:`InterruptedError` | |
++-----------------------------------------+---------------------------------+----------+
+| :c:data:`PyExc_IsADirectoryError` | :exc:`IsADirectoryError` | |
++-----------------------------------------+---------------------------------+----------+
+| :c:data:`PyExc_KeyError` | :exc:`KeyError` | |
++-----------------------------------------+---------------------------------+----------+
+| :c:data:`PyExc_KeyboardInterrupt` | :exc:`KeyboardInterrupt` | |
++-----------------------------------------+---------------------------------+----------+
+| :c:data:`PyExc_MemoryError` | :exc:`MemoryError` | |
++-----------------------------------------+---------------------------------+----------+
+| :c:data:`PyExc_NameError` | :exc:`NameError` | |
++-----------------------------------------+---------------------------------+----------+
+| :c:data:`PyExc_NotADirectoryError` | :exc:`NotADirectoryError` | |
++-----------------------------------------+---------------------------------+----------+
+| :c:data:`PyExc_NotImplementedError` | :exc:`NotImplementedError` | |
++-----------------------------------------+---------------------------------+----------+
+| :c:data:`PyExc_OSError` | :exc:`OSError` | \(1) |
++-----------------------------------------+---------------------------------+----------+
+| :c:data:`PyExc_OverflowError` | :exc:`OverflowError` | |
++-----------------------------------------+---------------------------------+----------+
+| :c:data:`PyExc_PermissionError` | :exc:`PermissionError` | |
++-----------------------------------------+---------------------------------+----------+
+| :c:data:`PyExc_ProcessLookupError` | :exc:`ProcessLookupError` | |
++-----------------------------------------+---------------------------------+----------+
+| :c:data:`PyExc_ReferenceError` | :exc:`ReferenceError` | \(2) |
++-----------------------------------------+---------------------------------+----------+
+| :c:data:`PyExc_RuntimeError` | :exc:`RuntimeError` | |
++-----------------------------------------+---------------------------------+----------+
+| :c:data:`PyExc_SyntaxError` | :exc:`SyntaxError` | |
++-----------------------------------------+---------------------------------+----------+
+| :c:data:`PyExc_SystemError` | :exc:`SystemError` | |
++-----------------------------------------+---------------------------------+----------+
+| :c:data:`PyExc_TimeoutError` | :exc:`TimeoutError` | |
++-----------------------------------------+---------------------------------+----------+
+| :c:data:`PyExc_SystemExit` | :exc:`SystemExit` | |
++-----------------------------------------+---------------------------------+----------+
+| :c:data:`PyExc_TypeError` | :exc:`TypeError` | |
++-----------------------------------------+---------------------------------+----------+
+| :c:data:`PyExc_ValueError` | :exc:`ValueError` | |
++-----------------------------------------+---------------------------------+----------+
+| :c:data:`PyExc_ZeroDivisionError` | :exc:`ZeroDivisionError` | |
++-----------------------------------------+---------------------------------+----------+
+
+.. versionadded:: 3.3
+ :c:data:`PyExc_BlockingIOError`, :c:data:`PyExc_BrokenPipeError`,
+ :c:data:`PyExc_ChildProcessError`, :c:data:`PyExc_ConnectionError`,
+ :c:data:`PyExc_ConnectionAbortedError`, :c:data:`PyExc_ConnectionRefusedError`,
+ :c:data:`PyExc_ConnectionResetError`, :c:data:`PyExc_FileExistsError`,
+ :c:data:`PyExc_FileNotFoundError`, :c:data:`PyExc_InterruptedError`,
+ :c:data:`PyExc_IsADirectoryError`, :c:data:`PyExc_NotADirectoryError`,
+ :c:data:`PyExc_PermissionError`, :c:data:`PyExc_ProcessLookupError`
+ and :c:data:`PyExc_TimeoutError` were introduced following :pep:`3151`.
+
+
+These are compatibility aliases to :c:data:`PyExc_OSError`:
+
++-------------------------------------+----------+
+| C Name | Notes |
++=====================================+==========+
+| :c:data:`PyExc_EnvironmentError` | |
++-------------------------------------+----------+
+| :c:data:`PyExc_IOError` | |
++-------------------------------------+----------+
+| :c:data:`PyExc_WindowsError` | \(3) |
++-------------------------------------+----------+
+
+.. versionchanged:: 3.3
+ These aliases used to be separate exception types.
+
+
+.. index::
+ single: PyExc_BaseException
+ single: PyExc_Exception
+ single: PyExc_ArithmeticError
+ single: PyExc_LookupError
+ single: PyExc_AssertionError
+ single: PyExc_AttributeError
+ single: PyExc_BlockingIOError
+ single: PyExc_BrokenPipeError
+ single: PyExc_ConnectionError
+ single: PyExc_ConnectionAbortedError
+ single: PyExc_ConnectionRefusedError
+ single: PyExc_ConnectionResetError
+ single: PyExc_EOFError
+ single: PyExc_FileExistsError
+ single: PyExc_FileNotFoundError
+ single: PyExc_FloatingPointError
+ single: PyExc_ImportError
+ single: PyExc_IndexError
+ single: PyExc_InterruptedError
+ single: PyExc_IsADirectoryError
+ single: PyExc_KeyError
+ single: PyExc_KeyboardInterrupt
+ single: PyExc_MemoryError
+ single: PyExc_NameError
+ single: PyExc_NotADirectoryError
+ single: PyExc_NotImplementedError
+ single: PyExc_OSError
+ single: PyExc_OverflowError
+ single: PyExc_PermissionError
+ single: PyExc_ProcessLookupError
+ single: PyExc_ReferenceError
+ single: PyExc_RuntimeError
+ single: PyExc_SyntaxError
+ single: PyExc_SystemError
+ single: PyExc_SystemExit
+ single: PyExc_TimeoutError
+ single: PyExc_TypeError
+ single: PyExc_ValueError
+ single: PyExc_ZeroDivisionError
+ single: PyExc_EnvironmentError
+ single: PyExc_IOError
+ single: PyExc_WindowsError
+
+Notes:
+
+(1)
+ This is a base class for other standard exceptions.
+
+(2)
+ This is the same as :exc:`weakref.ReferenceError`.
+
+(3)
+ Only defined on Windows; protect code that uses this by testing that the
+ preprocessor macro ``MS_WINDOWS`` is defined.
diff --git a/lib/cpython-doc/c-api/file.rst b/lib/cpython-doc/c-api/file.rst
new file mode 100644
--- /dev/null
+++ b/lib/cpython-doc/c-api/file.rst
@@ -0,0 +1,75 @@
+.. 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, char *name, char *mode, int buffering, char *encoding, char *errors, 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:`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:`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.
diff --git a/lib/cpython-doc/c-api/float.rst b/lib/cpython-doc/c-api/float.rst
new file mode 100644
--- /dev/null
+++ b/lib/cpython-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.
diff --git a/lib/cpython-doc/c-api/function.rst b/lib/cpython-doc/c-api/function.rst
new file mode 100644
--- /dev/null
+++ b/lib/cpython-doc/c-api/function.rst
@@ -0,0 +1,107 @@
+.. 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, name and *__module__* are retrieved from the code
+ object, the argument defaults and closure are set to *NULL*.
+
+
+.. c:function:: PyObject* PyFunction_NewWithQualName(PyObject *code, PyObject *globals, PyObject *qualname)
+
+ As :c:func:`PyFunction_New`, but also allows to set 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.
diff --git a/lib/cpython-doc/c-api/gcsupport.rst b/lib/cpython-doc/c-api/gcsupport.rst
new file mode 100644
--- /dev/null
+++ b/lib/cpython-doc/c-api/gcsupport.rst
@@ -0,0 +1,152 @@
+.. 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 :attr:`tp_flags` field of the type object must
+include the :const:`Py_TPFLAGS_HAVE_GC` and provide an implementation of the
+:attr:`tp_traverse` handler. If instances of the type are mutable, a
+:attr:`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.
+
+
+.. 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 :attr:`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.
+
+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
+ (:attr:`tp_dealloc` handler) should call this for the object before any of
+ the fields used by the :attr:`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.
+
+The :attr:`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 :attr:`tp_traverse` handler.
+ The function should be called with an object to traverse as *object* and
+ the third parameter to the :attr:`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 :attr:`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 :attr:`tp_traverse` handlers, a :c:func:`Py_VISIT` macro is
+provided. In order to use this macro, the :attr:`tp_traverse` implementation
+must name its arguments exactly *visit* and *arg*:
+
+
+.. c:function:: void Py_VISIT(PyObject *o)
+
+ Call the *visit* callback, with arguments *o* and *arg*. If *visit* returns
+ a non-zero value, then return it. Using this macro, :attr:`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 :attr:`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.
diff --git a/lib/cpython-doc/c-api/gen.rst b/lib/cpython-doc/c-api/gen.rst
new file mode 100644
--- /dev/null
+++ b/lib/cpython-doc/c-api/gen.rst
@@ -0,0 +1,38 @@
+.. 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`.
+
+
+.. 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(ob)
+
+ Return true if *ob* is a generator object; *ob* must not be *NULL*.
+
+
+.. c:function:: int PyGen_CheckExact(ob)
+
+ Return true if *ob*'s type is *PyGen_Type* is a generator object; *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 parameter must not be
+ *NULL*.
diff --git a/lib/cpython-doc/c-api/import.rst b/lib/cpython-doc/c-api/import.rst
new file mode 100644
--- /dev/null
+++ b/lib/cpython-doc/c-api/import.rst
@@ -0,0 +1,300 @@
+.. 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 version of :c:func:`PyImport_ImportModule` does not block. It's intended
+ to be used in C functions that import other modules to execute a function.
+ The import may block if another thread holds the import lock. The function
+ :c:func:`PyImport_ImportModuleNoBlock` never blocks. It first tries to fetch
+ the module from sys.modules and falls back to :c:func:`PyImport_ImportModule`
+ unless the lock is held, in which case the function will raise an
+ :exc:`ImportError`.
+
+
+.. c:function:: PyObject* PyImport_ImportModuleEx(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__`, 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.
+
+ 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(char *name, PyObject *globals, PyObject *locals, PyObject *fromlist, int level)
+
+ Similar to :c:func:`PyImport_ImportModuleLevelObject`, but the name is an
+ UTF-8 encoded string instead of a Unicode object.
+
+.. 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(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:`__file__` attribute will be set to the code object's
+ :c:member:`co_filename`.
+
+ 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(char *name, PyObject *co, 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(char *name, PyObject *co, char *pathname, char *cpathname)
+
+ Like :c:func:`PyImport_ExecCodeModuleObject`, but *name*, *pathname* and
+ *cpathname* are UTF-8 encoded strings.
+
+ .. versionadded:: 3.2
+
+
+.. c:function:: long PyImport_GetMagicNumber()
+
+ Return the magic number for Python bytecode files (a.k.a. :file:`.pyc` and
+ :file:`.pyo` files). The magic number should be present in the first four bytes
+ of the bytecode file, in little-endian byte order.
+
+
+.. c:function:: const char * PyImport_GetMagicTag()
+
+ Return the magic tag string for :pep:`3147` format Python bytecode file
+ names.
+
+ .. 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 an importer 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 it should fall back to the built-in import mechanism.
+ Cache the result in :data:`sys.path_importer_cache`. Return a new reference
+ to the importer 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:: PyObject* _PyImport_FixupExtension(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
+
+
+.. c:function:: int PyImport_ImportFrozenModule(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:: 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`.
diff --git a/lib/cpython-doc/c-api/index.rst b/lib/cpython-doc/c-api/index.rst
new file mode 100644
--- /dev/null
+++ b/lib/cpython-doc/c-api/index.rst
@@ -0,0 +1,27 @@
+.. _c-api-index:
+
+##################################
+ Python/C API Reference Manual
+##################################
+
+:Release: |version|
+:Date: |today|
+
+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
+ veryhigh.rst
+ refcounting.rst
+ exceptions.rst
+ utilities.rst
+ abstract.rst
+ concrete.rst
+ init.rst
+ memory.rst
+ objimpl.rst
diff --git a/lib/cpython-doc/c-api/init.rst b/lib/cpython-doc/c-api/init.rst
new file mode 100644
--- /dev/null
+++ b/lib/cpython-doc/c-api/init.rst
@@ -0,0 +1,1134 @@
+.. highlightlang:: c
+
+
+.. _initialization:
+
+*****************************************
+Initialization, Finalization, and Threads
+*****************************************
+
+
+Initializing and finalizing the interpreter
+===========================================
+
+
+.. c:function:: void Py_Initialize()
+
+ .. index::
+ single: Py_SetProgramName()
+ single: PyEval_InitThreads()
+ single: modules (in module sys)
+ single: path (in module sys)
+ module: builtins
+ module: __main__
+ module: sys
+ triple: module; search; path
+ single: PySys_SetArgv()
+ single: PySys_SetArgvEx()
+ single: Py_Finalize()
+
+ Initialize the Python interpreter. In an application embedding Python, this
+ should be called before using any other Python/C API functions; with the
+ exception of :c:func:`Py_SetProgramName`, :c:func:`Py_SetPythonHome` and :c:func:`Py_SetPath`. This initializes
+ the table of loaded modules (``sys.modules``), and creates the fundamental
+ modules :mod:`builtins`, :mod:`__main__` and :mod:`sys`. It also initializes
+ the module search path (``sys.path``). It does not set ``sys.argv``; use
+ :c:func:`PySys_SetArgvEx` for that. This is a no-op when called for a second time
+ (without calling :c:func:`Py_Finalize` first). There is no return value; it is a
+ fatal error if the initialization fails.
+
+
+.. c:function:: void Py_InitializeEx(int initsigs)
+
+ This function works like :c:func:`Py_Initialize` if *initsigs* is 1. If
+ *initsigs* is 0, it skips initialization registration of signal handlers, which
+ might be useful when Python is embedded.
+
+
+.. c:function:: int Py_IsInitialized()
+
+ Return true (nonzero) when the Python interpreter has been initialized, false
+ (zero) if not. After :c:func:`Py_Finalize` is called, this returns false until
+ :c:func:`Py_Initialize` is called again.
+
+
+.. c:function:: void Py_Finalize()
+
+ Undo all initializations made by :c:func:`Py_Initialize` and subsequent use of
+ Python/C API functions, and destroy all sub-interpreters (see
+ :c:func:`Py_NewInterpreter` below) that were created and not yet destroyed since
+ the last call to :c:func:`Py_Initialize`. Ideally, this frees all memory
+ allocated by the Python interpreter. This is a no-op when called for a second
+ time (without calling :c:func:`Py_Initialize` again first). There is no return
+ value; errors during finalization are ignored.
+
+ This function is provided for a number of reasons. An embedding application
+ might want to restart Python without having to restart the application itself.
+ An application that has loaded the Python interpreter from a dynamically
+ loadable library (or DLL) might want to free all memory allocated by Python
+ before unloading the DLL. During a hunt for memory leaks in an application a
+ developer might want to free all memory allocated by Python before exiting from
+ the application.
+
+ **Bugs and caveats:** The destruction of modules and objects in modules is done
+ in random order; this may cause destructors (:meth:`__del__` methods) to fail
+ when they depend on other objects (even functions) or modules. Dynamically
+ loaded extension modules loaded by Python are not unloaded. Small amounts of
+ memory allocated by the Python interpreter may not be freed (if you find a leak,
+ please report it). Memory tied up in circular references between objects is not
+ freed. Some memory allocated by extension modules may not be freed. Some
+ extensions may not work properly if their initialization routine is called more
+ than once; this can happen if an application calls :c:func:`Py_Initialize` and
+ :c:func:`Py_Finalize` more than once.
+
+
+Process-wide parameters
+=======================
+
+
+.. c:function:: void Py_SetProgramName(wchar_t *name)
+
+ .. index::
+ single: Py_Initialize()
+ single: main()
+ single: Py_GetPath()
+
+ This function should be called before :c:func:`Py_Initialize` is called for
+ the first time, if it is called at all. It tells the interpreter the value
+ of the ``argv[0]`` argument to the :c:func:`main` function of the program
+ (converted to wide characters).
+ This is used by :c:func:`Py_GetPath` and some other functions below to find
+ the Python run-time libraries relative to the interpreter executable. The
+ default value is ``'python'``. The argument should point to a
+ zero-terminated wide character string in static storage whose contents will not
+ change for the duration of the program's execution. No code in the Python
+ interpreter will change the contents of this storage.
+
+
+.. c:function:: wchar* Py_GetProgramName()
+
+ .. index:: single: Py_SetProgramName()
+
+ Return the program name set with :c:func:`Py_SetProgramName`, or the default.
+ The returned string points into static storage; the caller should not modify its
+ value.
+
+
+.. c:function:: wchar_t* Py_GetPrefix()
+
+ Return the *prefix* for installed platform-independent files. This is derived
+ through a number of complicated rules from the program name set with
+ :c:func:`Py_SetProgramName` and some environment variables; for example, if the
+ program name is ``'/usr/local/bin/python'``, the prefix is ``'/usr/local'``. The
+ returned string points into static storage; the caller should not modify its
+ value. This corresponds to the :makevar:`prefix` variable in the top-level
+ :file:`Makefile` and the ``--prefix`` argument to the :program:`configure`
+ script at build time. The value is available to Python code as ``sys.prefix``.
+ It is only useful on Unix. See also the next function.
+
+
+.. c:function:: wchar_t* Py_GetExecPrefix()
+
+ Return the *exec-prefix* for installed platform-*dependent* files. This is
+ derived through a number of complicated rules from the program name set with
+ :c:func:`Py_SetProgramName` and some environment variables; for example, if the
+ program name is ``'/usr/local/bin/python'``, the exec-prefix is
+ ``'/usr/local'``. The returned string points into static storage; the caller
+ should not modify its value. This corresponds to the :makevar:`exec_prefix`
+ variable in the top-level :file:`Makefile` and the ``--exec-prefix``
+ argument to the :program:`configure` script at build time. The value is
+ available to Python code as ``sys.exec_prefix``. It is only useful on Unix.
+
+ Background: The exec-prefix differs from the prefix when platform dependent
+ files (such as executables and shared libraries) are installed in a different
+ directory tree. In a typical installation, platform dependent files may be
+ installed in the :file:`/usr/local/plat` subtree while platform independent may
+ be installed in :file:`/usr/local`.
+
+ Generally speaking, a platform is a combination of hardware and software
+ families, e.g. Sparc machines running the Solaris 2.x operating system are
+ considered the same platform, but Intel machines running Solaris 2.x are another
+ platform, and Intel machines running Linux are yet another platform. Different
+ major revisions of the same operating system generally also form different
+ platforms. Non-Unix operating systems are a different story; the installation
+ strategies on those systems are so different that the prefix and exec-prefix are
+ meaningless, and set to the empty string. Note that compiled Python bytecode
+ files are platform independent (but not independent from the Python version by
+ which they were compiled!).
+
+ System administrators will know how to configure the :program:`mount` or
+ :program:`automount` programs to share :file:`/usr/local` between platforms
+ while having :file:`/usr/local/plat` be a different filesystem for each
+ platform.
+
+
+.. c:function:: wchar_t* Py_GetProgramFullPath()
+
+ .. index::
+ single: Py_SetProgramName()
+ single: executable (in module sys)
+
+ Return the full program name of the Python executable; this is computed as a
+ side-effect of deriving the default module search path from the program name
+ (set by :c:func:`Py_SetProgramName` above). The returned string points into
+ static storage; the caller should not modify its value. The value is available
+ to Python code as ``sys.executable``.
+
+
+.. c:function:: wchar_t* Py_GetPath()
+
+ .. index::
+ triple: module; search; path
+ single: path (in module sys)
+ single: Py_SetPath()
+
+ Return the default module search path; this is computed from the program name
+ (set by :c:func:`Py_SetProgramName` above) and some environment variables.
+ The returned string consists of a series of directory names separated by a
+ platform dependent delimiter character. The delimiter character is ``':'``
+ on Unix and Mac OS X, ``';'`` on Windows. The returned string points into
+ static storage; the caller should not modify its value. The list
+ :data:`sys.path` is initialized with this value on interpreter startup; it
+ can be (and usually is) modified later to change the search path for loading
+ modules.
+
+ .. XXX should give the exact rules
+
+
+.. c:function:: void Py_SetPath(const wchar_t *)
+
+ .. index::
+ triple: module; search; path
+ single: path (in module sys)
+ single: Py_GetPath()
+
+ Set the default module search path. If this function is called before
+ :c:func:`Py_Initialize`, then :c:func:`Py_GetPath` won't attempt to compute a
+ default search path but uses the one provided instead. This is useful if
+ Python is embedded by an application that has full knowledge of the location
+ of all modules. The path components should be separated by semicolons.
+
+ This also causes :data:`sys.executable` to be set only to the raw program
+ name (see :c:func:`Py_SetProgramName`) and for :data:`sys.prefix` and
+ :data:`sys.exec_prefix` to be empty. It is up to the caller to modify these
+ if required after calling :c:func:`Py_Initialize`.
+
+
+.. c:function:: const char* Py_GetVersion()
+
+ Return the version of this Python interpreter. This is a string that looks
+ something like ::
+
+ "3.0a5+ (py3k:63103M, May 12 2008, 00:53:55) \n[GCC 4.2.3]"
+
+ .. index:: single: version (in module sys)
+
+ The first word (up to the first space character) is the current Python version;
+ the first three characters are the major and minor version separated by a
+ period. The returned string points into static storage; the caller should not
+ modify its value. The value is available to Python code as :data:`sys.version`.
+
+
+.. c:function:: const char* Py_GetPlatform()
+
+ .. index:: single: platform (in module sys)
+
+ Return the platform identifier for the current platform. On Unix, this is
+ formed from the "official" name of the operating system, converted to lower
+ case, followed by the major revision number; e.g., for Solaris 2.x, which is
+ also known as SunOS 5.x, the value is ``'sunos5'``. On Mac OS X, it is
+ ``'darwin'``. On Windows, it is ``'win'``. The returned string points into
+ static storage; the caller should not modify its value. The value is available
+ to Python code as ``sys.platform``.
+
+
+.. c:function:: const char* Py_GetCopyright()
+
+ Return the official copyright string for the current Python version, for example
+
+ ``'Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam'``
+
+ .. index:: single: copyright (in module sys)
+
+ The returned string points into static storage; the caller should not modify its
+ value. The value is available to Python code as ``sys.copyright``.
+
+
+.. c:function:: const char* Py_GetCompiler()
+
+ Return an indication of the compiler used to build the current Python version,
+ in square brackets, for example::
+
+ "[GCC 2.7.2.2]"
+
+ .. index:: single: version (in module sys)
+
+ The returned string points into static storage; the caller should not modify its
+ value. The value is available to Python code as part of the variable
+ ``sys.version``.
+
+
+.. c:function:: const char* Py_GetBuildInfo()
+
+ Return information about the sequence number and build date and time of the
+ current Python interpreter instance, for example ::
+
+ "#67, Aug 1 1997, 22:34:28"
+
+ .. index:: single: version (in module sys)
+
+ The returned string points into static storage; the caller should not modify its
+ value. The value is available to Python code as part of the variable
+ ``sys.version``.
+
+
+.. c:function:: void PySys_SetArgvEx(int argc, wchar_t **argv, int updatepath)
+
+ .. index::
+ single: main()
+ single: Py_FatalError()
+ single: argv (in module sys)
+
+ Set :data:`sys.argv` based on *argc* and *argv*. These parameters are
+ similar to those passed to the program's :c:func:`main` function with the
+ difference that the first entry should refer to the script file to be
+ executed rather than the executable hosting the Python interpreter. If there
+ isn't a script that will be run, the first entry in *argv* can be an empty
+ string. If this function fails to initialize :data:`sys.argv`, a fatal
+ condition is signalled using :c:func:`Py_FatalError`.
+
+ If *updatepath* is zero, this is all the function does. If *updatepath*
+ is non-zero, the function also modifies :data:`sys.path` according to the
+ following algorithm:
+
+ - If the name of an existing script is passed in ``argv[0]``, the absolute
+ path of the directory where the script is located is prepended to
+ :data:`sys.path`.
+ - Otherwise (that is, if *argc* is 0 or ``argv[0]`` doesn't point
+ to an existing file name), an empty string is prepended to
+ :data:`sys.path`, which is the same as prepending the current working
+ directory (``"."``).
+
+ .. note::
+ It is recommended that applications embedding the Python interpreter
+ for purposes other than executing a single script pass 0 as *updatepath*,
+ and update :data:`sys.path` themselves if desired.
+ See `CVE-2008-5983 <http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2008-5983>`_.
+
+ On versions before 3.1.3, you can achieve the same effect by manually
+ popping the first :data:`sys.path` element after having called
+ :c:func:`PySys_SetArgv`, for example using::
+
+ PyRun_SimpleString("import sys; sys.path.pop(0)\n");
+
+ .. versionadded:: 3.1.3
+
+ .. XXX impl. doesn't seem consistent in allowing 0/NULL for the params;
+ check w/ Guido.
+
+
+.. c:function:: void PySys_SetArgv(int argc, wchar_t **argv)
+
+ This function works like :c:func:`PySys_SetArgvEx` with *updatepath* set to 1.
+
+
+.. c:function:: void Py_SetPythonHome(wchar_t *home)
+
+ Set the default "home" directory, that is, the location of the standard
+ Python libraries. See :envvar:`PYTHONHOME` for the meaning of the
+ argument string.
+
+ The argument should point to a zero-terminated character string in static
+ storage whose contents will not change for the duration of the program's
+ execution. No code in the Python interpreter will change the contents of
+ this storage.
+
+
+.. c:function:: w_char* Py_GetPythonHome()
+
+ Return the default "home", that is, the value set by a previous call to
+ :c:func:`Py_SetPythonHome`, or the value of the :envvar:`PYTHONHOME`
+ environment variable if it is set.
+
+
+.. _threads:
+
+Thread State and the Global Interpreter Lock
+============================================
+
+.. index::
+ single: global interpreter lock
+ single: interpreter lock
+ single: lock, interpreter
+
+The Python interpreter is not fully thread-safe. In order to support
+multi-threaded Python programs, there's a global lock, called the :term:`global
+interpreter lock` or :term:`GIL`, that must be held by the current thread before
+it can safely access Python objects. Without the lock, even the simplest
+operations could cause problems in a multi-threaded program: for example, when
+two threads simultaneously increment the reference count of the same object, the
+reference count could end up being incremented only once instead of twice.
+
+.. index:: single: setswitchinterval() (in module sys)
+
+Therefore, the rule exists that only the thread that has acquired the
+:term:`GIL` may operate on Python objects or call Python/C API functions.
+In order to emulate concurrency of execution, the interpreter regularly
+tries to switch threads (see :func:`sys.setswitchinterval`). The lock is also
+released around potentially blocking I/O operations like reading or writing
+a file, so that other Python threads can run in the meantime.
+
+.. index::
+ single: PyThreadState
+ single: PyThreadState
+
+The Python interpreter keeps some thread-specific bookkeeping information
+inside a data structure called :c:type:`PyThreadState`. There's also one
+global variable pointing to the current :c:type:`PyThreadState`: it can
+be retrieved using :c:func:`PyThreadState_Get`.
+
+Releasing the GIL from extension code
+-------------------------------------
+
+Most extension code manipulating the :term:`GIL` has the following simple
+structure::
+
+ Save the thread state in a local variable.
+ Release the global interpreter lock.
+ ... Do some blocking I/O operation ...
+ Reacquire the global interpreter lock.
+ Restore the thread state from the local variable.
+
+This is so common that a pair of macros exists to simplify it::
+
+ Py_BEGIN_ALLOW_THREADS
+ ... Do some blocking I/O operation ...
+ Py_END_ALLOW_THREADS
+
+.. index::
+ single: Py_BEGIN_ALLOW_THREADS
+ single: Py_END_ALLOW_THREADS
+
+The :c:macro:`Py_BEGIN_ALLOW_THREADS` macro opens a new block and declares a
+hidden local variable; the :c:macro:`Py_END_ALLOW_THREADS` macro closes the
+block. These two macros are still available when Python is compiled without
+thread support (they simply have an empty expansion).
+
+When thread support is enabled, the block above expands to the following code::
+
+ PyThreadState *_save;
+
+ _save = PyEval_SaveThread();
+ ...Do some blocking I/O operation...
+ PyEval_RestoreThread(_save);
+
+.. index::
+ single: PyEval_RestoreThread()
+ single: PyEval_SaveThread()
+
+Here is how these functions work: the global interpreter lock is used to protect the pointer to the
+current thread state. When releasing the lock and saving the thread state,
+the current thread state pointer must be retrieved before the lock is released
+(since another thread could immediately acquire the lock and store its own thread
+state in the global variable). Conversely, when acquiring the lock and restoring
+the thread state, the lock must be acquired before storing the thread state
+pointer.
+
+.. note::
+ Calling system I/O functions is the most common use case for releasing
+ the GIL, but it can also be useful before calling long-running computations
+ which don't need access to Python objects, such as compression or
+ cryptographic functions operating over memory buffers. For example, the
+ standard :mod:`zlib` and :mod:`hashlib` modules release the GIL when
+ compressing or hashing data.
+
+Non-Python created threads
+--------------------------
+
+When threads are created using the dedicated Python APIs (such as the
+:mod:`threading` module), a thread state is automatically associated to them
+and the code showed above is therefore correct. However, when threads are
+created from C (for example by a third-party library with its own thread
+management), they don't hold the GIL, nor is there a thread state structure
+for them.
+
+If you need to call Python code from these threads (often this will be part
+of a callback API provided by the aforementioned third-party library),
+you must first register these threads with the interpreter by
+creating a thread state data structure, then acquiring the GIL, and finally
+storing their thread state pointer, before you can start using the Python/C
+API. When you are done, you should reset the thread state pointer, release
+the GIL, and finally free the thread state data structure.
+
+The :c:func:`PyGILState_Ensure` and :c:func:`PyGILState_Release` functions do
+all of the above automatically. The typical idiom for calling into Python
+from a C thread is::
+
+ PyGILState_STATE gstate;
+ gstate = PyGILState_Ensure();
+
+ /* Perform Python actions here. */
+ result = CallSomeFunction();
+ /* evaluate result or handle exception */
+
+ /* Release the thread. No Python API allowed beyond this point. */
+ PyGILState_Release(gstate);
+
+Note that the :c:func:`PyGILState_\*` functions assume there is only one global
+interpreter (created automatically by :c:func:`Py_Initialize`). Python
+supports the creation of additional interpreters (using
+:c:func:`Py_NewInterpreter`), but mixing multiple interpreters and the
+:c:func:`PyGILState_\*` API is unsupported.
+
+Another important thing to note about threads is their behaviour in the face
+of the C :c:func:`fork` call. On most systems with :c:func:`fork`, after a
+process forks only the thread that issued the fork will exist. That also
+means any locks held by other threads will never be released. Python solves
+this for :func:`os.fork` by acquiring the locks it uses internally before
+the fork, and releasing them afterwards. In addition, it resets any
+:ref:`lock-objects` in the child. When extending or embedding Python, there
+is no way to inform Python of additional (non-Python) locks that need to be
+acquired before or reset after a fork. OS facilities such as
+:c:func:`pthread_atfork` would need to be used to accomplish the same thing.
+Additionally, when extending or embedding Python, calling :c:func:`fork`
+directly rather than through :func:`os.fork` (and returning to or calling
+into Python) may result in a deadlock by one of Python's internal locks
+being held by a thread that is defunct after the fork.
+:c:func:`PyOS_AfterFork` tries to reset the necessary locks, but is not
+always able to.
+
+
+High-level API
+--------------
+
+These are the most commonly used types and functions when writing C extension
+code, or when embedding the Python interpreter:
+
+.. c:type:: PyInterpreterState
+
+ This data structure represents the state shared by a number of cooperating
+ threads. Threads belonging to the same interpreter share their module
+ administration and a few other internal items. There are no public members in
+ this structure.
+
+ Threads belonging to different interpreters initially share nothing, except
+ process state like available memory, open file descriptors and such. The global
+ interpreter lock is also shared by all threads, regardless of to which
+ interpreter they belong.
+
+
+.. c:type:: PyThreadState
+
+ This data structure represents the state of a single thread. The only public
+ data member is :c:type:`PyInterpreterState \*`:attr:`interp`, which points to
+ this thread's interpreter state.
+
+
+.. c:function:: void PyEval_InitThreads()
+
+ .. index::
+ single: PyEval_AcquireThread()
+ single: PyEval_ReleaseThread()
+ single: PyEval_SaveThread()
+ single: PyEval_RestoreThread()
+
+ Initialize and acquire the global interpreter lock. It should be called in the
+ main thread before creating a second thread or engaging in any other thread
+ operations such as ``PyEval_ReleaseThread(tstate)``. It is not needed before
+ calling :c:func:`PyEval_SaveThread` or :c:func:`PyEval_RestoreThread`.
+
+ This is a no-op when called for a second time.
+
+ .. versionchanged:: 3.2
+ This function cannot be called before :c:func:`Py_Initialize()` anymore.
+
+ .. index:: module: _thread
+
+ .. note::
+ When only the main thread exists, no GIL operations are needed. This is a
+ common situation (most Python programs do not use threads), and the lock
+ operations slow the interpreter down a bit. Therefore, the lock is not
+ created initially. This situation is equivalent to having acquired the lock:
+ when there is only a single thread, all object accesses are safe. Therefore,
+ when this function initializes the global interpreter lock, it also acquires
+ it. Before the Python :mod:`_thread` module creates a new thread, knowing
+ that either it has the lock or the lock hasn't been created yet, it calls
+ :c:func:`PyEval_InitThreads`. When this call returns, it is guaranteed that
+ the lock has been created and that the calling thread has acquired it.
+
+ It is **not** safe to call this function when it is unknown which thread (if
+ any) currently has the global interpreter lock.
+
+ This function is not available when thread support is disabled at compile time.
+
+
+.. c:function:: int PyEval_ThreadsInitialized()
+
+ Returns a non-zero value if :c:func:`PyEval_InitThreads` has been called. This
+ function can be called without holding the GIL, and therefore can be used to
+ avoid calls to the locking API when running single-threaded. This function is
+ not available when thread support is disabled at compile time.
+
+
+.. c:function:: PyThreadState* PyEval_SaveThread()
+
+ Release the global interpreter lock (if it has been created and thread
+ support is enabled) and reset the thread state to *NULL*, returning the
+ previous thread state (which is not *NULL*). If the lock has been created,
+ the current thread must have acquired it. (This function is available even
+ when thread support is disabled at compile time.)
+
+
+.. c:function:: void PyEval_RestoreThread(PyThreadState *tstate)
+
+ Acquire the global interpreter lock (if it has been created and thread
+ support is enabled) and set the thread state to *tstate*, which must not be
+ *NULL*. If the lock has been created, the current thread must not have
+ acquired it, otherwise deadlock ensues. (This function is available even
+ when thread support is disabled at compile time.)
+
+
+.. c:function:: PyThreadState* PyThreadState_Get()
+
+ Return the current thread state. The global interpreter lock must be held.
+ When the current thread state is *NULL*, this issues a fatal error (so that
+ the caller needn't check for *NULL*).
+
+
+.. c:function:: PyThreadState* PyThreadState_Swap(PyThreadState *tstate)
+
+ Swap the current thread state with the thread state given by the argument
+ *tstate*, which may be *NULL*. The global interpreter lock must be held
+ and is not released.
+
+
+.. c:function:: void PyEval_ReInitThreads()
+
+ This function is called from :c:func:`PyOS_AfterFork` to ensure that newly
+ created child processes don't hold locks referring to threads which
+ are not running in the child process.
+
+
+The following functions use thread-local storage, and are not compatible
+with sub-interpreters:
+
+.. c:function:: PyGILState_STATE PyGILState_Ensure()
+
+ Ensure that the current thread is ready to call the Python C API regardless
+ of the current state of Python, or of the global interpreter lock. This may
+ be called as many times as desired by a thread as long as each call is
+ matched with a call to :c:func:`PyGILState_Release`. In general, other
+ thread-related APIs may be used between :c:func:`PyGILState_Ensure` and
+ :c:func:`PyGILState_Release` calls as long as the thread state is restored to
+ its previous state before the Release(). For example, normal usage of the
+ :c:macro:`Py_BEGIN_ALLOW_THREADS` and :c:macro:`Py_END_ALLOW_THREADS` macros is
+ acceptable.
+
+ The return value is an opaque "handle" to the thread state when
+ :c:func:`PyGILState_Ensure` was called, and must be passed to
+ :c:func:`PyGILState_Release` to ensure Python is left in the same state. Even
+ though recursive calls are allowed, these handles *cannot* be shared - each
+ unique call to :c:func:`PyGILState_Ensure` must save the handle for its call
+ to :c:func:`PyGILState_Release`.
+
+ When the function returns, the current thread will hold the GIL and be able
+ to call arbitrary Python code. Failure is a fatal error.
+
+
+.. c:function:: void PyGILState_Release(PyGILState_STATE)
+
+ Release any resources previously acquired. After this call, Python's state will
+ be the same as it was prior to the corresponding :c:func:`PyGILState_Ensure` call
+ (but generally this state will be unknown to the caller, hence the use of the
+ GILState API).
+
+ Every call to :c:func:`PyGILState_Ensure` must be matched by a call to
+ :c:func:`PyGILState_Release` on the same thread.
+
+
+.. c:function:: PyThreadState PyGILState_GetThisThreadState()
+
+ Get the current thread state for this thread. May return ``NULL`` if no
+ GILState API has been used on the current thread. Note that the main thread
+ always has such a thread-state, even if no auto-thread-state call has been
+ made on the main thread. This is mainly a helper/diagnostic function.
+
+
+The following macros are normally used without a trailing semicolon; look for
+example usage in the Python source distribution.
+
+
+.. c:macro:: Py_BEGIN_ALLOW_THREADS
+
+ This macro expands to ``{ PyThreadState *_save; _save = PyEval_SaveThread();``.
+ Note that it contains an opening brace; it must be matched with a following
+ :c:macro:`Py_END_ALLOW_THREADS` macro. See above for further discussion of this
+ macro. It is a no-op when thread support is disabled at compile time.
+
+
+.. c:macro:: Py_END_ALLOW_THREADS
+
+ This macro expands to ``PyEval_RestoreThread(_save); }``. Note that it contains
+ a closing brace; it must be matched with an earlier
+ :c:macro:`Py_BEGIN_ALLOW_THREADS` macro. See above for further discussion of
+ this macro. It is a no-op when thread support is disabled at compile time.
+
+
+.. c:macro:: Py_BLOCK_THREADS
+
+ This macro expands to ``PyEval_RestoreThread(_save);``: it is equivalent to
+ :c:macro:`Py_END_ALLOW_THREADS` without the closing brace. It is a no-op when
+ thread support is disabled at compile time.
+
+
+.. c:macro:: Py_UNBLOCK_THREADS
+
+ This macro expands to ``_save = PyEval_SaveThread();``: it is equivalent to
+ :c:macro:`Py_BEGIN_ALLOW_THREADS` without the opening brace and variable
+ declaration. It is a no-op when thread support is disabled at compile time.
+
+
+Low-level API
+-------------
+
+All of the following functions are only available when thread support is enabled
+at compile time, and must be called only when the global interpreter lock has
+been created.
+
+
+.. c:function:: PyInterpreterState* PyInterpreterState_New()
+
+ Create a new interpreter state object. The global interpreter lock need not
+ be held, but may be held if it is necessary to serialize calls to this
+ function.
+
+
+.. c:function:: void PyInterpreterState_Clear(PyInterpreterState *interp)
+
+ Reset all information in an interpreter state object. The global interpreter
+ lock must be held.
+
+
+.. c:function:: void PyInterpreterState_Delete(PyInterpreterState *interp)
+
+ Destroy an interpreter state object. The global interpreter lock need not be
+ held. The interpreter state must have been reset with a previous call to
+ :c:func:`PyInterpreterState_Clear`.
+
+
+.. c:function:: PyThreadState* PyThreadState_New(PyInterpreterState *interp)
+
+ Create a new thread state object belonging to the given interpreter object.
+ The global interpreter lock need not be held, but may be held if it is
+ necessary to serialize calls to this function.
+
+
+.. c:function:: void PyThreadState_Clear(PyThreadState *tstate)
+
+ Reset all information in a thread state object. The global interpreter lock
+ must be held.
+
+
+.. c:function:: void PyThreadState_Delete(PyThreadState *tstate)
+
+ Destroy a thread state object. The global interpreter lock need not be held.
+ The thread state must have been reset with a previous call to
+ :c:func:`PyThreadState_Clear`.
+
+
+.. c:function:: PyObject* PyThreadState_GetDict()
+
+ Return a dictionary in which extensions can store thread-specific state
+ information. Each extension should use a unique key to use to store state in
+ the dictionary. It is okay to call this function when no current thread state
+ is available. If this function returns *NULL*, no exception has been raised and
+ the caller should assume no current thread state is available.
+
+
+.. c:function:: int PyThreadState_SetAsyncExc(long id, PyObject *exc)
+
+ Asynchronously raise an exception in a thread. The *id* argument is the thread
+ id of the target thread; *exc* is the exception object to be raised. This
+ function does not steal any references to *exc*. To prevent naive misuse, you
+ must write your own C extension to call this. Must be called with the GIL held.
+ Returns the number of thread states modified; this is normally one, but will be
+ zero if the thread id isn't found. If *exc* is :const:`NULL`, the pending
+ exception (if any) for the thread is cleared. This raises no exceptions.
+
+
+.. c:function:: void PyEval_AcquireThread(PyThreadState *tstate)
+
+ Acquire the global interpreter lock and set the current thread state to
+ *tstate*, which should not be *NULL*. The lock must have been created earlier.
+ If this thread already has the lock, deadlock ensues.
+
+ :c:func:`PyEval_RestoreThread` is a higher-level function which is always
+ available (even when thread support isn't enabled or when threads have
+ not been initialized).
+
+
+.. c:function:: void PyEval_ReleaseThread(PyThreadState *tstate)
+
+ Reset the current thread state to *NULL* and release the global interpreter
+ lock. The lock must have been created earlier and must be held by the current
+ thread. The *tstate* argument, which must not be *NULL*, is only used to check
+ that it represents the current thread state --- if it isn't, a fatal error is
+ reported.
+
+ :c:func:`PyEval_SaveThread` is a higher-level function which is always
+ available (even when thread support isn't enabled or when threads have
+ not been initialized).
+
+
+.. c:function:: void PyEval_AcquireLock()
+
+ Acquire the global interpreter lock. The lock must have been created earlier.
+ If this thread already has the lock, a deadlock ensues.
+
+ .. deprecated:: 3.2
+ This function does not update the current thread state. Please use
+ :c:func:`PyEval_RestoreThread` or :c:func:`PyEval_AcquireThread`
+ instead.
+
+
+.. c:function:: void PyEval_ReleaseLock()
+
+ Release the global interpreter lock. The lock must have been created earlier.
+
+ .. deprecated:: 3.2
+ This function does not update the current thread state. Please use
+ :c:func:`PyEval_SaveThread` or :c:func:`PyEval_ReleaseThread`
+ instead.
+
+
+Sub-interpreter support
+=======================
+
+While in most uses, you will only embed a single Python interpreter, there
+are cases where you need to create several independent interpreters in the
+same process and perhaps even in the same thread. Sub-interpreters allow
+you to do that. You can switch between sub-interpreters using the
+:c:func:`PyThreadState_Swap` function. You can create and destroy them
+using the following functions:
+
+
+.. c:function:: PyThreadState* Py_NewInterpreter()
+
+ .. index::
+ module: builtins
+ module: __main__
+ module: sys
+ single: stdout (in module sys)
+ single: stderr (in module sys)
+ single: stdin (in module sys)
+
+ Create a new sub-interpreter. This is an (almost) totally separate environment
+ for the execution of Python code. In particular, the new interpreter has
+ separate, independent versions of all imported modules, including the
+ fundamental modules :mod:`builtins`, :mod:`__main__` and :mod:`sys`. The
+ table of loaded modules (``sys.modules``) and the module search path
+ (``sys.path``) are also separate. The new environment has no ``sys.argv``
+ variable. It has new standard I/O stream file objects ``sys.stdin``,
+ ``sys.stdout`` and ``sys.stderr`` (however these refer to the same underlying
+ file descriptors).
+
+ The return value points to the first thread state created in the new
+ sub-interpreter. This thread state is made in the current thread state.
+ Note that no actual thread is created; see the discussion of thread states
+ below. If creation of the new interpreter is unsuccessful, *NULL* is
+ returned; no exception is set since the exception state is stored in the
+ current thread state and there may not be a current thread state. (Like all
+ other Python/C API functions, the global interpreter lock must be held before
+ calling this function and is still held when it returns; however, unlike most
+ other Python/C API functions, there needn't be a current thread state on
+ entry.)
+
+ .. index::
+ single: Py_Finalize()
+ single: Py_Initialize()
+
+ Extension modules are shared between (sub-)interpreters as follows: the first
+ time a particular extension is imported, it is initialized normally, and a
+ (shallow) copy of its module's dictionary is squirreled away. When the same
+ extension is imported by another (sub-)interpreter, a new module is initialized
+ and filled with the contents of this copy; the extension's ``init`` function is
+ not called. Note that this is different from what happens when an extension is
+ imported after the interpreter has been completely re-initialized by calling
+ :c:func:`Py_Finalize` and :c:func:`Py_Initialize`; in that case, the extension's
+ ``initmodule`` function *is* called again.
+
+ .. index:: single: close() (in module os)
+
+
+.. c:function:: void Py_EndInterpreter(PyThreadState *tstate)
+
+ .. index:: single: Py_Finalize()
+
+ Destroy the (sub-)interpreter represented by the given thread state. The given
+ thread state must be the current thread state. See the discussion of thread
+ states below. When the call returns, the current thread state is *NULL*. All
+ thread states associated with this interpreter are destroyed. (The global
+ interpreter lock must be held before calling this function and is still held
+ when it returns.) :c:func:`Py_Finalize` will destroy all sub-interpreters that
+ haven't been explicitly destroyed at that point.
+
+
+Bugs and caveats
+----------------
+
+Because sub-interpreters (and the main interpreter) are part of the same
+process, the insulation between them isn't perfect --- for example, using
+low-level file operations like :func:`os.close` they can
+(accidentally or maliciously) affect each other's open files. Because of the
+way extensions are shared between (sub-)interpreters, some extensions may not
+work properly; this is especially likely when the extension makes use of
+(static) global variables, or when the extension manipulates its module's
+dictionary after its initialization. It is possible to insert objects created
+in one sub-interpreter into a namespace of another sub-interpreter; this should
+be done with great care to avoid sharing user-defined functions, methods,
+instances or classes between sub-interpreters, since import operations executed
+by such objects may affect the wrong (sub-)interpreter's dictionary of loaded
+modules.
+
+Also note that combining this functionality with :c:func:`PyGILState_\*` APIs
+is delicate, because these APIs assume a bijection between Python thread states
+and OS-level threads, an assumption broken by the presence of sub-interpreters.
+It is highly recommended that you don't switch sub-interpreters between a pair
+of matching :c:func:`PyGILState_Ensure` and :c:func:`PyGILState_Release` calls.
+Furthermore, extensions (such as :mod:`ctypes`) using these APIs to allow calling
+of Python code from non-Python created threads will probably be broken when using
+sub-interpreters.
+
+
+Asynchronous Notifications
+==========================
+
+A mechanism is provided to make asynchronous notifications to the main
+interpreter thread. These notifications take the form of a function
+pointer and a void argument.
+
+.. index:: single: setcheckinterval() (in module sys)
+
+Every check interval, when the global interpreter lock is released and
+reacquired, Python will also call any such provided functions. This can be used
+for example by asynchronous IO handlers. The notification can be scheduled from
+a worker thread and the actual call than made at the earliest convenience by the
+main thread where it has possession of the global interpreter lock and can
+perform any Python API calls.
+
+.. c:function:: int Py_AddPendingCall(int (*func)(void *), void *arg)
+
+ .. index:: single: Py_AddPendingCall()
+
+ Post a notification to the Python main thread. If successful, *func* will be
+ called with the argument *arg* at the earliest convenience. *func* will be
+ called having the global interpreter lock held and can thus use the full
+ Python API and can take any action such as setting object attributes to
+ signal IO completion. It must return 0 on success, or -1 signalling an
+ exception. The notification function won't be interrupted to perform another
+ asynchronous notification recursively, but it can still be interrupted to
+ switch threads if the global interpreter lock is released, for example, if it
+ calls back into Python code.
+
+ This function returns 0 on success in which case the notification has been
+ scheduled. Otherwise, for example if the notification buffer is full, it
+ returns -1 without setting any exception.
+
+ This function can be called on any thread, be it a Python thread or some
+ other system thread. If it is a Python thread, it doesn't matter if it holds
+ the global interpreter lock or not.
+
+ .. versionadded:: 3.1
+
+
+.. _profiling:
+
+Profiling and Tracing
+=====================
+
+.. sectionauthor:: Fred L. Drake, Jr. <fdrake at acm.org>
+
+
+The Python interpreter provides some low-level support for attaching profiling
+and execution tracing facilities. These are used for profiling, debugging, and
+coverage analysis tools.
+
+This C interface allows the profiling or tracing code to avoid the overhead of
+calling through Python-level callable objects, making a direct C function call
+instead. The essential attributes of the facility have not changed; the
+interface allows trace functions to be installed per-thread, and the basic
+events reported to the trace function are the same as had been reported to the
+Python-level trace functions in previous versions.
+
+
+.. c:type:: int (*Py_tracefunc)(PyObject *obj, PyFrameObject *frame, int what, PyObject *arg)
+
+ The type of the trace function registered using :c:func:`PyEval_SetProfile` and
+ :c:func:`PyEval_SetTrace`. The first parameter is the object passed to the
+ registration function as *obj*, *frame* is the frame object to which the event
+ pertains, *what* is one of the constants :const:`PyTrace_CALL`,
+ :const:`PyTrace_EXCEPTION`, :const:`PyTrace_LINE`, :const:`PyTrace_RETURN`,
+ :const:`PyTrace_C_CALL`, :const:`PyTrace_C_EXCEPTION`, or
+ :const:`PyTrace_C_RETURN`, and *arg* depends on the value of *what*:
+
+ +------------------------------+--------------------------------------+
+ | Value of *what* | Meaning of *arg* |
+ +==============================+======================================+
+ | :const:`PyTrace_CALL` | Always *NULL*. |
+ +------------------------------+--------------------------------------+
+ | :const:`PyTrace_EXCEPTION` | Exception information as returned by |
+ | | :func:`sys.exc_info`. |
+ +------------------------------+--------------------------------------+
+ | :const:`PyTrace_LINE` | Always *NULL*. |
+ +------------------------------+--------------------------------------+
+ | :const:`PyTrace_RETURN` | Value being returned to the caller, |
+ | | or *NULL* if caused by an exception. |
+ +------------------------------+--------------------------------------+
+ | :const:`PyTrace_C_CALL` | Function object being called. |
+ +------------------------------+--------------------------------------+
+ | :const:`PyTrace_C_EXCEPTION` | Function object being called. |
+ +------------------------------+--------------------------------------+
+ | :const:`PyTrace_C_RETURN` | Function object being called. |
+ +------------------------------+--------------------------------------+
+
+
+.. c:var:: int PyTrace_CALL
+
+ The value of the *what* parameter to a :c:type:`Py_tracefunc` function when a new
+ call to a function or method is being reported, or a new entry into a generator.
+ Note that the creation of the iterator for a generator function is not reported
+ as there is no control transfer to the Python bytecode in the corresponding
+ frame.
+
+
+.. c:var:: int PyTrace_EXCEPTION
+
+ The value of the *what* parameter to a :c:type:`Py_tracefunc` function when an
+ exception has been raised. The callback function is called with this value for
+ *what* when after any bytecode is processed after which the exception becomes
+ set within the frame being executed. The effect of this is that as exception
+ propagation causes the Python stack to unwind, the callback is called upon
+ return to each frame as the exception propagates. Only trace functions receives
+ these events; they are not needed by the profiler.
+
+
+.. c:var:: int PyTrace_LINE
+
+ The value passed as the *what* parameter to a trace function (but not a
+ profiling function) when a line-number event is being reported.
+
+
+.. c:var:: int PyTrace_RETURN
+
+ The value for the *what* parameter to :c:type:`Py_tracefunc` functions when a
+ call is returning without propagating an exception.
+
+
+.. c:var:: int PyTrace_C_CALL
+
+ The value for the *what* parameter to :c:type:`Py_tracefunc` functions when a C
+ function is about to be called.
+
+
+.. c:var:: int PyTrace_C_EXCEPTION
+
+ The value for the *what* parameter to :c:type:`Py_tracefunc` functions when a C
+ function has raised an exception.
+
+
+.. c:var:: int PyTrace_C_RETURN
+
+ The value for the *what* parameter to :c:type:`Py_tracefunc` functions when a C
+ function has returned.
+
+
+.. c:function:: void PyEval_SetProfile(Py_tracefunc func, PyObject *obj)
+
+ Set the profiler function to *func*. The *obj* parameter is passed to the
+ function as its first parameter, and may be any Python object, or *NULL*. If
+ the profile function needs to maintain state, using a different value for *obj*
+ for each thread provides a convenient and thread-safe place to store it. The
+ profile function is called for all monitored events except the line-number
+ events.
+
+
+.. c:function:: void PyEval_SetTrace(Py_tracefunc func, PyObject *obj)
+
+ Set the tracing function to *func*. This is similar to
+ :c:func:`PyEval_SetProfile`, except the tracing function does receive line-number
+ events.
+
+.. c:function:: PyObject* PyEval_GetCallStats(PyObject *self)
+
+ Return a tuple of function call counts. There are constants defined for the
+ positions within the tuple:
+
+ +-------------------------------+-------+
+ | Name | Value |
+ +===============================+=======+
+ | :const:`PCALL_ALL` | 0 |
+ +-------------------------------+-------+
+ | :const:`PCALL_FUNCTION` | 1 |
+ +-------------------------------+-------+
+ | :const:`PCALL_FAST_FUNCTION` | 2 |
+ +-------------------------------+-------+
+ | :const:`PCALL_FASTER_FUNCTION`| 3 |
+ +-------------------------------+-------+
+ | :const:`PCALL_METHOD` | 4 |
+ +-------------------------------+-------+
+ | :const:`PCALL_BOUND_METHOD` | 5 |
+ +-------------------------------+-------+
+ | :const:`PCALL_CFUNCTION` | 6 |
+ +-------------------------------+-------+
+ | :const:`PCALL_TYPE` | 7 |
+ +-------------------------------+-------+
+ | :const:`PCALL_GENERATOR` | 8 |
+ +-------------------------------+-------+
+ | :const:`PCALL_OTHER` | 9 |
+ +-------------------------------+-------+
+ | :const:`PCALL_POP` | 10 |
+ +-------------------------------+-------+
+
+ :const:`PCALL_FAST_FUNCTION` means no argument tuple needs to be created.
+ :const:`PCALL_FASTER_FUNCTION` means that the fast-path frame setup code is used.
+
+ If there is a method call where the call can be optimized by changing
+ the argument tuple and calling the function directly, it gets recorded
+ twice.
+
+ This function is only present if Python is compiled with :const:`CALL_PROFILE`
+ defined.
+
+.. _advanced-debugging:
+
+Advanced Debugger Support
+=========================
+
+.. sectionauthor:: Fred L. Drake, Jr. <fdrake at acm.org>
+
+
+These functions are only intended to be used by advanced debugging tools.
+
+
+.. c:function:: PyInterpreterState* PyInterpreterState_Head()
+
+ Return the interpreter state object at the head of the list of all such objects.
+
+
+.. c:function:: PyInterpreterState* PyInterpreterState_Next(PyInterpreterState *interp)
+
+ Return the next interpreter state object after *interp* from the list of all
+ such objects.
+
+
+.. c:function:: PyThreadState * PyInterpreterState_ThreadHead(PyInterpreterState *interp)
+
+ Return the a pointer to the first :c:type:`PyThreadState` object in the list of
+ threads associated with the interpreter *interp*.
+
+
+.. c:function:: PyThreadState* PyThreadState_Next(PyThreadState *tstate)
+
+ Return the next thread state object after *tstate* from the list of all such
+ objects belonging to the same :c:type:`PyInterpreterState` object.
+
diff --git a/lib/cpython-doc/c-api/intro.rst b/lib/cpython-doc/c-api/intro.rst
new file mode 100644
--- /dev/null
+++ b/lib/cpython-doc/c-api/intro.rst
@@ -0,0 +1,630 @@
+.. 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 ``sys.version[:3]``. 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, PyString_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)
+ {
+ int i, n;
+
+ n = PyObject_Length(target);
+ if (n < 0)
+ return -1;
+ for (i = 0; i < n; i++) {
+ PyObject *index = PyLong_FromLong(i);
+ if (!index)
+ return -1;
+ if (PyObject_SetItem(target, index, item) < 0)
+ 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)
+ {
+ int i, n;
+ long total = 0;
+ 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 */
+ total += PyLong_AsLong(item);
+ }
+ return total;
+ }
+
+.. index:: single: sum_list()
+
+::
+
+ long
+ sum_sequence(PyObject *sequence)
+ {
+ int i, n;
+ long total = 0;
+ 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))
+ total += PyLong_AsLong(item);
+ 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 that 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_Finalize`. 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_Finalize`
+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.
+
diff --git a/lib/cpython-doc/c-api/iter.rst b/lib/cpython-doc/c-api/iter.rst
new file mode 100644
--- /dev/null
+++ b/lib/cpython-doc/c-api/iter.rst
@@ -0,0 +1,47 @@
+.. highlightlang:: c
+
+.. _iterator:
+
+Iterator Protocol
+=================
+
+There are only a couple of 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*. If the object is an iterator,
+ this retrieves the next value from the iteration, and returns *NULL* with no
+ exception set if there are no remaining items. If the object is not an
+ iterator, :exc:`TypeError` is raised, or if there is an error in 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 */
+ }
diff --git a/lib/cpython-doc/c-api/iterator.rst b/lib/cpython-doc/c-api/iterator.rst
new file mode 100644
--- /dev/null
+++ b/lib/cpython-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.
diff --git a/lib/cpython-doc/c-api/list.rst b/lib/cpython-doc/c-api/list.rst
new file mode 100644
--- /dev/null
+++ b/lib/cpython-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
diff --git a/lib/cpython-doc/c-api/long.rst b/lib/cpython-doc/c-api/long.rst
new file mode 100644
--- /dev/null
+++ b/lib/cpython-doc/c-api/long.rst
@@ -0,0 +1,237 @@
+.. highlightlang:: c
+
+.. _longobjects:
+
+Integer Objects
+---------------
+
+.. index:: object: long integer
+ object: integer
+
+All integers are implemented as "long" integer objects of arbitrary size.
+
+.. 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(PY_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 PY_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(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``, the radix will be
+ determined based on the leading characters of *str*: if *str* starts with
+ ``'0x'`` or ``'0X'``, radix 16 will be used; if *str* starts with ``'0o'`` or
+ ``'0O'``, radix 8 will be used; if *str* starts with ``'0b'`` or ``'0B'``,
+ radix 2 will be used; otherwise radix 10 will be used. If *base* is not
+ ``0``, it must be between ``2`` and ``36``, inclusive. Leading spaces 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 *pylong)
+
+ .. index::
+ single: LONG_MAX
+ single: OverflowError (built-in exception)
+
+ Return a C :c:type:`long` representation of the contents of *pylong*. If
+ *pylong* is greater than :const:`LONG_MAX`, raise an :exc:`OverflowError`,
+ and return -1. Convert non-long objects automatically to long first,
+ and return -1 if that raises exceptions.
+
+.. c:function:: long PyLong_AsLongAndOverflow(PyObject *pylong, int *overflow)
+
+ Return a C :c:type:`long` representation of the contents of
+ *pylong*. If *pylong* 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 (for example a TypeError or
+ MemoryError), then ``-1`` will be returned and *\*overflow* will
+ be ``0``.
+
+
+.. c:function:: PY_LONG_LONG PyLong_AsLongLongAndOverflow(PyObject *pylong, int *overflow)
+
+ Return a C :c:type:`long long` representation of the contents of
+ *pylong*. If *pylong* 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 (for example a TypeError or
+ MemoryError), then ``-1`` will be returned and *\*overflow* will
+ be ``0``.
+
+ .. 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 the contents of *pylong*.
+ If *pylong* is greater than :const:`PY_SSIZE_T_MAX`, an :exc:`OverflowError`
+ is raised and ``-1`` will be returned.
+
+
+.. 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 the contents of *pylong*.
+ If *pylong* is greater than :const:`ULONG_MAX`, an :exc:`OverflowError` is
+ raised.
+
+
+.. c:function:: size_t PyLong_AsSize_t(PyObject *pylong)
+
+ Return a :c:type:`size_t` representation of the contents of *pylong*. If
+ *pylong* is greater than the maximum value for a :c:type:`size_t`, an
+ :exc:`OverflowError` is raised.
+
+
+.. c:function:: PY_LONG_LONG PyLong_AsLongLong(PyObject *pylong)
+
+ .. index::
+ single: OverflowError (built-in exception)
+
+ Return a C :c:type:`long long` from a Python integer. If *pylong*
+ cannot be represented as a :c:type:`long long`, an
+ :exc:`OverflowError` is raised and ``-1`` is returned.
+
+
+.. c:function:: unsigned PY_LONG_LONG PyLong_AsUnsignedLongLong(PyObject *pylong)
+
+ .. index::
+ single: OverflowError (built-in exception)
+
+ Return a C :c:type:`unsigned long long` from a Python integer. If
+ *pylong* cannot be represented as an :c:type:`unsigned long long`,
+ an :exc:`OverflowError` is raised and ``(unsigned long long)-1`` is
+ returned.
+
+ .. versionchanged:: 3.1
+ A negative *pylong* now raises :exc:`OverflowError`, not :exc:`TypeError`.
+
+
+.. c:function:: unsigned long PyLong_AsUnsignedLongMask(PyObject *io)
+
+ Return a C :c:type:`unsigned long` from a Python integer, without checking for
+ overflow.
+
+
+.. c:function:: unsigned PY_LONG_LONG PyLong_AsUnsignedLongLongMask(PyObject *io)
+
+ Return a C :c:type:`unsigned long long` from a Python integer, without
+ checking for overflow.
+
+
+.. c:function:: double PyLong_AsDouble(PyObject *pylong)
+
+ Return a C :c:type:`double` representation of the contents of *pylong*. If
+ *pylong* cannot be approximately represented as a :c:type:`double`, an
+ :exc:`OverflowError` exception is raised and ``-1.0`` will be returned.
+
+
+.. 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`.
diff --git a/lib/cpython-doc/c-api/mapping.rst b/lib/cpython-doc/c-api/mapping.rst
new file mode 100644
--- /dev/null
+++ b/lib/cpython-doc/c-api/mapping.rst
@@ -0,0 +1,79 @@
+.. highlightlang:: c
+
+.. _mapping:
+
+Mapping Protocol
+================
+
+
+.. c:function:: int PyMapping_Check(PyObject *o)
+
+ Return ``1`` if the object provides mapping protocol, and ``0`` otherwise. 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. For
+ objects that do not provide mapping protocol, this is equivalent to the Python
+ expression ``len(o)``.
+
+
+.. c:function:: int PyMapping_DelItemString(PyObject *o, char *key)
+
+ Remove the mapping for object *key* from the object *o*. Return ``-1`` on
+ failure. This is equivalent to the Python statement ``del o[key]``.
+
+
+.. c:function:: int PyMapping_DelItem(PyObject *o, PyObject *key)
+
+ Remove the mapping for object *key* from the object *o*. Return ``-1`` on
+ failure. This is equivalent to the Python statement ``del o[key]``.
+
+
+.. c:function:: int PyMapping_HasKeyString(PyObject *o, char *key)
+
+ On success, 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.
+
+
+.. 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.
+
+
+.. c:function:: PyObject* PyMapping_Keys(PyObject *o)
+
+ On success, return a list of the keys in object *o*. On failure, return *NULL*.
+ This is equivalent to the Python expression ``list(o.keys())``.
+
+
+.. c:function:: PyObject* PyMapping_Values(PyObject *o)
+
+ On success, return a list of the values in object *o*. On failure, return
+ *NULL*. This is equivalent to the Python expression ``list(o.values())``.
+
+
+.. c:function:: PyObject* PyMapping_Items(PyObject *o)
+
+ On success, return a list of the items in object *o*, where each item is a tuple
+ containing a key-value pair. On failure, return *NULL*. This is equivalent to
+ the Python expression ``list(o.items())``.
+
+
+.. c:function:: PyObject* PyMapping_GetItemString(PyObject *o, char *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 PyMapping_SetItemString(PyObject *o, char *key, PyObject *v)
+
+ Map the object *key* to the value *v* in object *o*. Returns ``-1`` on failure.
+ This is the equivalent of the Python statement ``o[key] = v``.
diff --git a/lib/cpython-doc/c-api/marshal.rst b/lib/cpython-doc/c-api/marshal.rst
new file mode 100644
--- /dev/null
+++ b/lib/cpython-doc/c-api/marshal.rst
@@ -0,0 +1,89 @@
+.. 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 string object containing the marshalled representation of *value*.
+ *version* indicates the file format.
+
+
+The following functions allow marshalled values to be read back in.
+
+XXX What about error detection? It appears that reading past the end of the
+file will always result in a negative numeric value (where that's relevant),
+but it's not clear that negative values won't be handled properly when there's
+no error. What's the right way to tell? Should only non-negative values be
+written using these routines?
+
+
+.. 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`.
+
+
+.. 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`.
+
+
+.. 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` 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` or :exc:`TypeError`) and returns *NULL*.
+
+
+.. c:function:: PyObject* PyMarshal_ReadObjectFromString(char *string, Py_ssize_t len)
+
+ Return a Python object from the data stream in a character buffer
+ containing *len* bytes pointed to by *string*. On error, sets the
+ appropriate exception (:exc:`EOFError` or :exc:`TypeError`) and returns
+ *NULL*.
+
diff --git a/lib/cpython-doc/c-api/memory.rst b/lib/cpython-doc/c-api/memory.rst
new file mode 100644
--- /dev/null
+++ b/lib/cpython-doc/c-api/memory.rst
@@ -0,0 +1,209 @@
+.. highlightlang:: c
+
+
+.. _memory:
+
+*****************
+Memory Management
+*****************
+
+.. sectionauthor:: Vladimir Marangozov <Vladimir.Marangozov at 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 she regularly manipulates 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 = PyString_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.
+
+
+.. _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:
+
+
+.. 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 :c:func:`PyMem_Malloc(1)` had
+ been called instead. The memory will not have been initialized in any way.
+
+
+.. 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 :c:func:`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` or :c:func:`PyMem_Realloc`. 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` or :c:func:`PyMem_Realloc`. Otherwise, or
+ if :c:func:`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.
+
+:c:func:`PyMem_MALLOC`, :c:func:`PyMem_REALLOC`, :c:func:`PyMem_FREE`.
+
+:c:func:`PyMem_NEW`, :c:func:`PyMem_RESIZE`, :c:func:`PyMem_DEL`.
+
+
+.. _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 = PyString_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 = PyString_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.
+
diff --git a/lib/cpython-doc/c-api/memoryview.rst b/lib/cpython-doc/c-api/memoryview.rst
new file mode 100644
--- /dev/null
+++ b/lib/cpython-doc/c-api/memoryview.rst
@@ -0,0 +1,52 @@
+.. 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
+ readable and writable, otherwise it will be read-only.
+
+
+.. c:function:: PyObject *PyMemoryView_FromBuffer(Py_buffer *view)
+
+ Create a memoryview object wrapping the given buffer structure *view*.
+ The memoryview object then owns the buffer represented by *view*, which
+ means you shouldn't try to call :c:func:`PyBuffer_Release` yourself: it
+ will be done on deallocation of the memoryview object.
+
+
+.. c:function:: PyObject *PyMemoryView_GetContiguous(PyObject *obj, int buffertype, char order)
+
+ Create a memoryview object to a 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 *obj)
+
+ Return a pointer to the buffer structure wrapped by the given
+ memoryview object. The object **must** be a memoryview instance;
+ this macro doesn't check its type, you must do it yourself or you
+ will risk crashes.
+
diff --git a/lib/cpython-doc/c-api/method.rst b/lib/cpython-doc/c-api/method.rst
new file mode 100644
--- /dev/null
+++ b/lib/cpython-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
+an 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.
+
diff --git a/lib/cpython-doc/c-api/module.rst b/lib/cpython-doc/c-api/module.rst
new file mode 100644
--- /dev/null
+++ b/lib/cpython-doc/c-api/module.rst
@@ -0,0 +1,231 @@
+.. highlightlang:: c
+
+.. _moduleobjects:
+
+Module Objects
+--------------
+
+.. index:: object: module
+
+There are only a few functions special to module objects.
+
+
+.. 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)
+
+ Return a new module object with the :attr:`__name__` attribute set to *name*.
+ Only the module's :attr:`__doc__` and :attr:`__name__` attributes are filled in;
+ the caller is responsible for providing a :attr:`__file__` attribute.
+
+ .. versionadded:: 3.3
+
+
+.. c:function:: PyObject* PyModule_New(const char *name)
+
+ Similar to :c:func:`PyImport_NewObject`, but the name is an 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:`__dict__` attribute of the module object. This
+ function never fails. It is recommended extensions use other
+ :c:func:`PyModule_\*` and :c:func:`PyObject_\*` functions rather than directly
+ manipulate a module's :attr:`__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:: 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.
+
+
+.. 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 with
+ :c:func:`PyModule_Create`.
+
+
+Initializing C modules
+^^^^^^^^^^^^^^^^^^^^^^
+
+These functions are usually used in the module initialization function.
+
+.. c:function:: PyObject* PyModule_Create(PyModuleDef *module)
+
+ Create a new module object, given the definition in *module*. This behaves
+ like :c:func:`PyModule_Create2` with *module_api_version* set to
+ :const:`PYTHON_API_VERSION`.
+
+
+.. c:function:: PyObject* PyModule_Create2(PyModuleDef *module, int module_api_version)
+
+ Create a new module object, given the definition in *module*, 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.
+
+
+.. c:type:: PyModuleDef
+
+ This struct holds all information that is needed to create a module object.
+ There is usually only one static variable of that type for each module, which
+ is statically initialized and then passed to :c:func:`PyModule_Create` in the
+ module initialization function.
+
+ .. 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
+
+ If the module object needs additional memory, this should be set to the
+ number of bytes to allocate; a pointer to the block of memory can be
+ retrieved with :c:func:`PyModule_GetState`. If no memory is needed, set
+ this to ``-1``.
+
+ This memory should be used, rather than static globals, to hold per-module
+ state, since it is then safe for use in multiple sub-interpreters. It is
+ freed when the module object is deallocated, after the :c:member:`m_free`
+ function has been called, if present.
+
+ .. 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:: inquiry m_reload
+
+ Currently unused, should be *NULL*.
+
+ .. c:member:: traverseproc m_traverse
+
+ A traversal function to call during GC traversal of the module object, or
+ *NULL* if not needed.
+
+ .. c:member:: inquiry m_clear
+
+ A clear function to call during GC clearing of the module object, or
+ *NULL* if not needed.
+
+ .. c:member:: freefunc m_free
+
+ A function to call during deallocation of the module object, or *NULL* if
+ not needed.
+
+
+.. 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*.
diff --git a/lib/cpython-doc/c-api/none.rst b/lib/cpython-doc/c-api/none.rst
new file mode 100644
--- /dev/null
+++ b/lib/cpython-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.)
diff --git a/lib/cpython-doc/c-api/number.rst b/lib/cpython-doc/c-api/number.rst
new file mode 100644
--- /dev/null
+++ b/lib/cpython-doc/c-api/number.rst
@@ -0,0 +1,265 @@
+.. 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_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_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 True if *o* is an index integer (has the nb_index slot of the
+ tp_as_number structure filled in).
diff --git a/lib/cpython-doc/c-api/objbuffer.rst b/lib/cpython-doc/c-api/objbuffer.rst
new file mode 100644
--- /dev/null
+++ b/lib/cpython-doc/c-api/objbuffer.rst
@@ -0,0 +1,51 @@
+.. 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``.
+
+
+.. 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.
+
diff --git a/lib/cpython-doc/c-api/object.rst b/lib/cpython-doc/c-api/object.rst
new file mode 100644
--- /dev/null
+++ b/lib/cpython-doc/c-api/object.rst
@@ -0,0 +1,361 @@
+.. 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.
+
+
+.. 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.
+
+
+.. 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:`__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*. Returns ``-1`` on failure. This is the equivalent of the Python statement
+ ``o.attr_name = v``.
+
+
+.. 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*. Returns ``-1`` on failure. This is the equivalent of the Python statement
+ ``o.attr_name = v``.
+
+
+.. c:function:: int PyObject_GenericSetAttr(PyObject *o, PyObject *name, PyObject *value)
+
+ Generic attribute setter function that is meant to be put into a type
+ object's ``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 the attribute in the instance dictionary. Otherwise, the
+ attribute is set in the object's :attr:`__dict__` (if present). 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_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.
+
+
+.. 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.
+
+
+.. c:function:: PyObject* PyObject_Str(PyObject *o)
+
+ .. index:: builtin: str
+
+ 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.
+
+.. 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_IsInstance(PyObject *inst, PyObject *cls)
+
+ Returns ``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 type object rather than a class object, :c:func:`PyObject_IsInstance`
+ returns ``1`` if *inst* is of type *cls*. 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 *inst* is not a
+ class instance and *cls* is neither a type object, nor a class object, nor a
+ tuple, *inst* must have a :attr:`__class__` attribute --- the class relationship
+ of the value of that attribute with *cls* will be used to determine the result
+ of this function.
+
+
+Subclass determination is done in a fairly straightforward way, but includes a
+wrinkle that implementors of extensions to the class system may want to be aware
+of. If :class:`A` and :class:`B` are class objects, :class:`B` is a subclass of
+:class:`A` if it inherits from :class:`A` either directly or indirectly. If
+either is not a class object, a more general mechanism is used to determine the
+class relationship of the two objects. When testing if *B* is a subclass of
+*A*, if *A* is *B*, :c:func:`PyObject_IsSubclass` returns true. If *A* and *B*
+are different objects, *B*'s :attr:`__bases__` attribute is searched in a
+depth-first fashion for *A* --- the presence of the :attr:`__bases__` attribute
+is considered sufficient for this determination.
+
+
+.. c:function:: int PyObject_IsSubclass(PyObject *derived, PyObject *cls)
+
+ Returns ``1`` if the class *derived* is identical to or derived from the class
+ *cls*, otherwise returns ``0``. In case of an error, returns ``-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 either *derived* or *cls* is not an actual class object (or tuple),
+ this function uses the generic algorithm described above.
+
+
+.. 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, 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.
+
+
+.. c:function:: PyObject* PyObject_CallMethod(PyObject *o, char *method, 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.
+
+
+.. 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_Length(PyObject *o)
+ Py_ssize_t PyObject_Size(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:: 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*. Returns ``-1`` on failure. This is the
+ equivalent of the Python statement ``o[key] = v``.
+
+
+.. c:function:: int PyObject_DelItem(PyObject *o, PyObject *key)
+
+ Delete the mapping for *key* from *o*. Returns ``-1`` on failure. This is the
+ equivalent of 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.
diff --git a/lib/cpython-doc/c-api/objimpl.rst b/lib/cpython-doc/c-api/objimpl.rst
new file mode 100644
--- /dev/null
+++ b/lib/cpython-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
diff --git a/lib/cpython-doc/c-api/refcounting.rst b/lib/cpython-doc/c-api/refcounting.rst
new file mode 100644
--- /dev/null
+++ b/lib/cpython-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`.
+
diff --git a/lib/cpython-doc/c-api/reflection.rst b/lib/cpython-doc/c-api/reflection.rst
new file mode 100644
--- /dev/null
+++ b/lib/cpython-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*.
diff --git a/lib/cpython-doc/c-api/sequence.rst b/lib/cpython-doc/c-api/sequence.rst
new file mode 100644
--- /dev/null
+++ b/lib/cpython-doc/c-api/sequence.rst
@@ -0,0 +1,162 @@
+.. highlightlang:: c
+
+.. _sequence:
+
+Sequence Protocol
+=================
+
+
+.. c:function:: int PySequence_Check(PyObject *o)
+
+ Return ``1`` if the object provides sequence protocol, and ``0`` otherwise.
+ 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.
+ For objects that do not provide sequence protocol, 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*. Returns ``-1`` on failure. This
+ is the equivalent of the Python statement ``o[i] = v``. This function *does
+ not* steal a reference to *v*.
+
+
+.. 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 arbitrary sequence *o*. The
+ returned list is guaranteed to be new.
+
+
+.. c:function:: PyObject* PySequence_Tuple(PyObject *o)
+
+ .. index:: builtin: tuple
+
+ Return a tuple object with the same contents as the arbitrary sequence *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)
+
+ Returns the sequence *o* as a tuple, 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, raises :exc:`TypeError` with *m* as the message text.
+
+
+.. 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.
+
+
+.. 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.
diff --git a/lib/cpython-doc/c-api/set.rst b/lib/cpython-doc/c-api/set.rst
new file mode 100644
--- /dev/null
+++ b/lib/cpython-doc/c-api/set.rst
@@ -0,0 +1,166 @@
+.. highlightlang:: c
+
+.. _setobjects:
+
+Set Objects
+-----------
+
+.. sectionauthor:: Raymond D. Hettinger <python at 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 an 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:`discard`
+ method, this function does not automatically convert unhashable sets into
+ temporary frozensets. Raise :exc:`PyExc_SystemError` if *set* is an 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 an 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
diff --git a/lib/cpython-doc/c-api/slice.rst b/lib/cpython-doc/c-api/slice.rst
new file mode 100644
--- /dev/null
+++ b/lib/cpython-doc/c-api/slice.rst
@@ -0,0 +1,58 @@
+.. 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.
diff --git a/lib/cpython-doc/c-api/structures.rst b/lib/cpython-doc/c-api/structures.rst
new file mode 100644
--- /dev/null
+++ b/lib/cpython-doc/c-api/structures.rst
@@ -0,0 +1,284 @@
+.. 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. It
+ corresponds to the fields defined by the expansion of the ``PyObject_HEAD``
+ macro.
+
+
+.. 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. It corresponds to the
+ fields defined by the expansion of the ``PyObject_VAR_HEAD`` macro.
+
+These macros are used in the definition of :c:type:`PyObject` and
+:c:type:`PyVarObject`:
+
+.. XXX need to document PEP 3123 changes here
+
+.. c:macro:: PyObject_HEAD
+
+ This is a macro which expands to the declarations of the fields of the
+ :c:type:`PyObject` type; it is used when declaring new types which represent
+ objects without a varying length. The specific fields it expands to depend
+ on the definition of :c:macro:`Py_TRACE_REFS`. By default, that macro is
+ not defined, and :c:macro:`PyObject_HEAD` expands to::
+
+ Py_ssize_t ob_refcnt;
+ PyTypeObject *ob_type;
+
+ When :c:macro:`Py_TRACE_REFS` is defined, it expands to::
+
+ PyObject *_ob_next, *_ob_prev;
+ Py_ssize_t ob_refcnt;
+ PyTypeObject *ob_type;
+
+
+.. c:macro:: PyObject_VAR_HEAD
+
+ This is a macro which expands to the declarations of the fields of the
+ :c:type:`PyVarObject` type; it is used when declaring new types which
+ represent objects with a length that varies from instance to instance.
+ This macro always expands to::
+
+ PyObject_HEAD
+ Py_ssize_t ob_size;
+
+ Note that :c:macro:`PyObject_HEAD` is part of the expansion, and that its own
+ expansion varies depending on the definition of :c:macro:`Py_TRACE_REFS`.
+
+
+.. 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 a 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 (but note that :const:`METH_KEYWORDS`
+alone is equivalent to ``METH_VARARGS | METH_KEYWORDS``). 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 is typically 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`. Only :c:macro:`T_OBJECT` and :c:macro:`T_OBJECT_EX`
+ members can be deleted. (They are set to *NULL*).
diff --git a/lib/cpython-doc/c-api/sys.rst b/lib/cpython-doc/c-api/sys.rst
new file mode 100644
--- /dev/null
+++ b/lib/cpython-doc/c-api/sys.rst
@@ -0,0 +1,186 @@
+.. highlightlang:: c
+
+.. _os:
+
+Operating System Utilities
+==========================
+
+
+.. 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)`.
+
+.. _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(char *name)
+
+ Return the object *name* from the :mod:`sys` module or *NULL* if it does
+ not exist, without setting an exception.
+
+.. c:function:: FILE *PySys_GetFile(char *name, FILE *def)
+
+ Return the :c:type:`FILE*` associated with the object *name* in the
+ :mod:`sys` module, or *def* if *name* is not in the module or is not associated
+ with a :c:type:`FILE*`.
+
+.. c:function:: int PySys_SetObject(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_Finalize()
+ single: exit()
+
+ Exit the current process. This calls :c:func:`Py_Finalize` and then calls the
+ standard C library function ``exit(status)``.
+
+
+.. c:function:: int Py_AtExit(void (*func) ())
+
+ .. index::
+ single: Py_Finalize()
+ single: cleanup functions
+
+ Register a cleanup function to be called by :c:func:`Py_Finalize`. 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*.
diff --git a/lib/cpython-doc/c-api/tuple.rst b/lib/cpython-doc/c-api/tuple.rst
new file mode 100644
--- /dev/null
+++ b/lib/cpython-doc/c-api/tuple.rst
@@ -0,0 +1,110 @@
+.. 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.
diff --git a/lib/cpython-doc/c-api/type.rst b/lib/cpython-doc/c-api/type.rst
new file mode 100644
--- /dev/null
+++ b/lib/cpython-doc/c-api/type.rst
@@ -0,0 +1,86 @@
+.. 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:: long PyType_GetFlags(PyTypeObject* type)
+
+ Return the :attr:`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
+ :attr:`tp_flags` itself is not part of the limited API.
+
+ .. versionadded:: 3.2
+
+.. 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(PyObject *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(PyObject *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*.
+
+
+.. c:function:: PyObject* PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)
+
+ XXX: Document.
+
+
+.. c:function:: PyObject* PyType_GenericNew(PyTypeObject *type, PyObject *args, PyObject *kwds)
+
+ XXX: Document.
+
+
+.. 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.
diff --git a/lib/cpython-doc/c-api/typeobj.rst b/lib/cpython-doc/c-api/typeobj.rst
new file mode 100644
More information about the pypy-commit
mailing list