Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Add Python 2.7.2 documentation.

  • Loading branch information...
commit 6e978f271dc3cd0a35582af8f0d97369bf12302c 1 parent 631b052
Jeff Hardy jdhardy authored
Showing with 26,120 additions and 0 deletions.
  1. +223 −0 ACKS.txt
  2. +180 −0 Makefile
  3. +144 −0 README.txt
  4. +36 −0 about.rst
  5. +73 −0 bugs.rst
  6. +26 −0 c-api/abstract.rst
  7. +122 −0 c-api/allocation.rst
  8. +559 −0 c-api/arg.rst
  9. +54 −0 c-api/bool.rst
  10. +450 −0 c-api/buffer.rst
  11. +87 −0 c-api/bytearray.rst
  12. +150 −0 c-api/capsule.rst
  13. +62 −0 c-api/cell.rst
  14. +65 −0 c-api/class.rst
  15. +59 −0 c-api/cobject.rst
  16. +50 −0 c-api/code.rst
  17. +118 −0 c-api/codec.rst
  18. +132 −0 c-api/complex.rst
  19. +109 −0 c-api/concrete.rst
  20. +181 −0 c-api/conversion.rst
  21. +239 −0 c-api/datetime.rst
  22. +55 −0 c-api/descriptor.rst
  23. +233 −0 c-api/dict.rst
  24. +621 −0 c-api/exceptions.rst
  25. +178 −0 c-api/file.rst
  26. +118 −0 c-api/float.rst
  27. +83 −0 c-api/function.rst
  28. +165 −0 c-api/gcsupport.rst
  29. +38 −0 c-api/gen.rst
  30. +276 −0 c-api/import.rst
  31. +27 −0 c-api/index.rst
  32. +1,135 −0 c-api/init.rst
  33. +139 −0 c-api/int.rst
  34. +636 −0 c-api/intro.rst
  35. +50 −0 c-api/iter.rst
  36. +62 −0 c-api/iterator.rst
  37. +189 −0 c-api/list.rst
  38. +278 −0 c-api/long.rst
  39. +83 −0 c-api/mapping.rst
  40. +100 −0 c-api/marshal.rst
  41. +209 −0 c-api/memory.rst
  42. +72 −0 c-api/method.rst
  43. +121 −0 c-api/module.rst
  44. +28 −0 c-api/none.rst
  45. +322 −0 c-api/number.rst
  46. +66 −0 c-api/objbuffer.rst
  47. +402 −0 c-api/object.rst
  48. +18 −0 c-api/objimpl.rst
  49. +74 −0 c-api/refcounting.rst
  50. +55 −0 c-api/reflection.rst
  51. +218 −0 c-api/sequence.rst
  52. +175 −0 c-api/set.rst
  53. +68 −0 c-api/slice.rst
  54. +333 −0 c-api/string.rst
  55. +298 −0 c-api/structures.rst
  56. +151 −0 c-api/sys.rst
  57. +164 −0 c-api/tuple.rst
  58. +96 −0 c-api/type.rst
  59. +1,448 −0 c-api/typeobj.rst
  60. +1,113 −0 c-api/unicode.rst
  61. +22 −0 c-api/utilities.rst
  62. +323 −0 c-api/veryhigh.rst
  63. +83 −0 c-api/weakref.rst
  64. +190 −0 conf.py
  65. +24 −0 contents.rst
  66. +19 −0 copyright.rst
  67. +1,861 −0 data/refcounts.dat
  68. +2,004 −0 distutils/apiref.rst
  69. +450 −0 distutils/builtdist.rst
  70. +60 −0 distutils/commandref.rst
  71. +130 −0 distutils/configfile.rst
  72. +241 −0 distutils/examples.rst
  73. +96 −0 distutils/extending.rst
  74. +31 −0 distutils/index.rst
  75. +208 −0 distutils/introduction.rst
  76. +104 −0 distutils/packageindex.rst
  77. +705 −0 distutils/setupscript.rst
  78. +278 −0 distutils/sourcedist.rst
  79. +77 −0 distutils/uploading.rst
  80. +91 −0 documenting/building.rst
  81. +202 −0 documenting/fromlatex.rst
  82. +38 −0 documenting/index.rst
  83. +29 −0 documenting/intro.rst
  84. +857 −0 documenting/markup.rst
  85. +243 −0 documenting/rest.rst
  86. +174 −0 documenting/style.rst
  87. +131 −0 extending/building.rst
  88. +285 −0 extending/embedding.rst
  89. +1,314 −0 extending/extending.rst
  90. +35 −0 extending/index.rst
  91. +1,585 −0 extending/newtypes.rst
  92. +282 −0 extending/windows.rst
  93. +932 −0 faq/design.rst
Sorry, we could not display the entire diff because too many files (555) changed.
223 ACKS.txt
View
@@ -0,0 +1,223 @@
+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@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
+ * 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.
+ * Josip Dzolonga
+ * Jeff Epler
+ * Michael Ernst
+ * Blame Andy Eskilsson
+ * Carey Evans
+ * Martijn Faassen
+ * Carl Feynman
+ * Dan Finnie
+ * Hernán Martínez Foffani
+ * Stefan Franke
+ * Jim Fulton
+ * Peter Funk
+ * Lele Gaifax
+ * Matthew Gallagher
+ * Gabriel Genellina
+ * Ben Gertzfield
+ * Nadim Ghaznavi
+ * Jonathan Giddy
+ * 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
+ * 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
+ * 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
+ * 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
+ * Michal Nowikowski
+ * 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
+ * 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
+ * Ville Vainio
+ * 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
+ * Steven Work
+ * Thomas Wouters
+ * Ka-Ping Yee
+ * Rory Yorke
+ * Moshe Zadka
+ * Milan Zamazal
+ * Cheng Zhang
180 Makefile
View
@@ -0,0 +1,180 @@
+#
+# 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 " 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-0.6.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
+ $(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."
+
+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/*
+ -rm -rf tools/sphinx
+ -rm -rf tools/pygments
+ -rm -rf tools/jinja2
+ -rm -rf tools/docutils
+
+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
+
+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
144 README.txt
View
@@ -0,0 +1,144 @@
+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".
+
+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.
+
+ * "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-0.6.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@python.org,
+and we will process your request as soon as possible.
+
+If you want to help the Documentation Team, you are always welcome. Just send
+a mail to docs@python.org.
+
+
+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-2008 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.
+----------------------------------------------------------------------
36 about.rst
View
@@ -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@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!
73 bugs.rst
View
@@ -0,0 +1,73 @@
+.. _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@python.org describing the bug and where you found
+it. If you have a suggestion how to fix it, include that as well.
+
+docs@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. See http://www.python.org/dev/workflow/ for a detailed
+description of the issue workflow.
+
+
+.. seealso::
+
+ `How to Report Bugs Effectively <http://www.chiark.greenend.org.uk/~sgtatham/bugs.html>`_
+ Article which goes into some detail about how to create a useful bug report.
+ This describes what kind of information is useful and why it is useful.
+
+ `Bug Writing Guidelines <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.
+
26 c-api/abstract.rst
View
@@ -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 :cfunc:`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
+ objbuffer.rst
122 c-api/allocation.rst
View
@@ -0,0 +1,122 @@
+.. highlightlang:: c
+
+.. _allocating-objects:
+
+Allocating Objects on the Heap
+==============================
+
+
+.. cfunction:: PyObject* _PyObject_New(PyTypeObject *type)
+
+
+.. cfunction:: PyVarObject* _PyObject_NewVar(PyTypeObject *type, Py_ssize_t size)
+
+ .. versionchanged:: 2.5
+ This function used an :ctype:`int` type for *size*. This might require
+ changes in your code for properly supporting 64-bit systems.
+
+
+.. cfunction:: void _PyObject_Del(PyObject *op)
+
+
+.. cfunction:: 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.
+
+
+.. cfunction:: PyVarObject* PyObject_InitVar(PyVarObject *op, PyTypeObject *type, Py_ssize_t size)
+
+ This does everything :cfunc:`PyObject_Init` does, and also initializes the
+ length information for a variable-size object.
+
+ .. versionchanged:: 2.5
+ This function used an :ctype:`int` type for *size*. This might require
+ changes in your code for properly supporting 64-bit systems.
+
+
+.. cfunction:: 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.
+
+
+.. cfunction:: 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.
+
+ .. versionchanged:: 2.5
+ This function used an :ctype:`int` type for *size*. This might require
+ changes in your code for properly supporting 64-bit systems.
+
+
+.. cfunction:: void PyObject_Del(PyObject *op)
+
+ Releases memory allocated to an object using :cfunc:`PyObject_New` or
+ :cfunc:`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.
+
+
+.. cfunction:: PyObject* Py_InitModule(char *name, PyMethodDef *methods)
+
+ Create a new module object based on a name and table of functions,
+ returning the new module object.
+
+ .. versionchanged:: 2.3
+ Older versions of Python did not support *NULL* as the value for the
+ *methods* argument.
+
+
+.. cfunction:: PyObject* Py_InitModule3(char *name, PyMethodDef *methods, char *doc)
+
+ Create a new module object based on a name and table of functions,
+ returning the new module object. If *doc* is non-*NULL*, it will be used
+ to define the docstring for the module.
+
+ .. versionchanged:: 2.3
+ Older versions of Python did not support *NULL* as the value for the
+ *methods* argument.
+
+
+.. cfunction:: PyObject* Py_InitModule4(char *name, PyMethodDef *methods, char *doc, PyObject *self, int apiver)
+
+ Create a new module object based on a name and table of functions,
+ returning the new module object. If *doc* is non-*NULL*, it will be used
+ to define the docstring for the module. If *self* is non-*NULL*, it will
+ passed to the functions of the module as their (otherwise *NULL*) first
+ parameter. (This was added as an experimental feature, and there are no
+ known uses in the current version of Python.) For *apiver*, the only value
+ which should be passed is defined by the constant
+ :const:`PYTHON_API_VERSION`.
+
+ .. note::
+
+ Most uses of this function should probably be using the
+ :cfunc:`Py_InitModule3` instead; only use this if you are sure you need
+ it.
+
+ .. versionchanged:: 2.3
+ Older versions of Python did not support *NULL* as the value for the
+ *methods* argument.
+
+
+.. cvar:: PyObject _Py_NoneStruct
+
+ Object which is visible in Python as ``None``. This should only be
+ accessed using the ``Py_None`` macro, which evaluates to a pointer to this
+ object.
559 c-api/arg.rst
View
@@ -0,0 +1,559 @@
+.. 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, :cfunc:`PyArg_ParseTuple`,
+:cfunc:`PyArg_ParseTupleAndKeywords`, and :cfunc:`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.
+
+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.
+
+``s`` (string or Unicode) [const char \*]
+ Convert a Python string or Unicode object to a C pointer to a character
+ string. You must not provide storage for the string itself; a pointer to
+ an existing string is stored into 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 the default
+ encoding. If this conversion fails, a :exc:`UnicodeError` is raised.
+
+``s#`` (string, Unicode or any read buffer compatible object) [const char \*, int (or :ctype:`Py_ssize_t`, see below)]
+ This variant on ``s`` stores into two C variables, the first one a pointer
+ to a character string, the second one its length. In this case the Python
+ string may contain embedded null bytes. Unicode objects pass back a
+ pointer to the default encoded string version of the object if such a
+ conversion is possible. All other read-buffer compatible objects pass back
+ a reference to the raw internal data representation.
+
+ Starting with Python 2.5 the type of the length argument can be controlled
+ by defining the macro :cmacro:`PY_SSIZE_T_CLEAN` before including
+ :file:`Python.h`. If the macro is defined, length is a :ctype:`Py_ssize_t`
+ rather than an int.
+
+``s*`` (string, Unicode, or any buffer compatible object) [Py_buffer]
+ Similar to ``s#``, this code fills a Py_buffer structure provided by the
+ caller. The buffer gets locked, so that the caller can subsequently use
+ the buffer even inside a ``Py_BEGIN_ALLOW_THREADS`` block; the caller is
+ responsible for calling ``PyBuffer_Release`` with the structure after it
+ has processed the data.
+
+ .. versionadded:: 2.6
+
+``z`` (string, Unicode 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#`` (string, Unicode, ``None`` or any read buffer compatible object) [const char \*, int]
+ This is to ``s#`` as ``z`` is to ``s``.
+
+``z*`` (string, Unicode, ``None`` or any buffer compatible object) [Py_buffer]
+ This is to ``s*`` as ``z`` is to ``s``.
+
+ .. versionadded:: 2.6
+
+``u`` (Unicode) [Py_UNICODE \*]
+ Convert a Python Unicode object to a C pointer to a NUL-terminated buffer
+ of 16-bit Unicode (UTF-16) data. As with ``s``, there is no need to
+ provide storage for the Unicode data buffer; a pointer to the existing
+ Unicode data is stored into the :ctype:`Py_UNICODE` pointer variable whose
+ address you pass.
+
+``u#`` (Unicode) [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. Non-Unicode objects
+ are handled by interpreting their read-buffer pointer as pointer to a
+ :ctype:`Py_UNICODE` array.
+
+``es`` (string, Unicode or character buffer compatible object) [const char \*encoding, char \*\*buffer]
+ This variant on ``s`` is used for encoding Unicode and objects convertible
+ to 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 :ctype:`const char\*` which points to the name of an encoding as
+ a NUL-terminated string, or *NULL*, in which case the default encoding is
+ used. An exception is raised if the named encoding is not known to Python.
+ The second argument must be a :ctype:`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.
+
+ :cfunc:`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
+ :cfunc:`PyMem_Free` to free the allocated buffer after use.
+
+``et`` (string, Unicode or character buffer compatible object) [const char \*encoding, char \*\*buffer]
+ Same as ``es`` except that 8-bit string objects are passed through without
+ recoding them. Instead, the implementation assumes that the string object
+ uses the encoding passed in as parameter.
+
+``es#`` (string, Unicode or character buffer compatible object) [const char \*encoding, char \*\*buffer, int \*buffer_length]
+ This variant on ``s#`` is used for encoding Unicode and objects convertible
+ to 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 :ctype:`const char\*` which points to the name of an encoding as a
+ NUL-terminated string, or *NULL*, in which case the default encoding is
+ used. An exception is raised if the named encoding is not known to Python.
+ The second argument must be a :ctype:`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 :cfunc:`PyMem_Free` to free the allocated buffer
+ after usage.
+
+ If *\*buffer* points to a non-*NULL* pointer (an already allocated buffer),
+ :cfunc:`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#`` (string, Unicode or character buffer compatible object) [const char \*encoding, char \*\*buffer, int \*buffer_length]
+ Same as ``es#`` except that string objects are passed through without
+ recoding them. Instead, the implementation assumes that the string object
+ uses the encoding passed in as parameter.
+
+``b`` (integer) [unsigned char]
+ Convert a nonnegative Python integer to an unsigned tiny int, stored in a C
+ :ctype:`unsigned char`.
+
+``B`` (integer) [unsigned char]
+ Convert a Python integer to a tiny int without overflow checking, stored in
+ a C :ctype:`unsigned char`.
+
+ .. versionadded:: 2.3
+
+``h`` (integer) [short int]
+ Convert a Python integer to a C :ctype:`short int`.
+
+``H`` (integer) [unsigned short int]
+ Convert a Python integer to a C :ctype:`unsigned short int`, without
+ overflow checking.
+
+ .. versionadded:: 2.3
+
+``i`` (integer) [int]
+ Convert a Python integer to a plain C :ctype:`int`.
+
+``I`` (integer) [unsigned int]
+ Convert a Python integer to a C :ctype:`unsigned int`, without overflow
+ checking.
+
+ .. versionadded:: 2.3
+
+``l`` (integer) [long int]
+ Convert a Python integer to a C :ctype:`long int`.
+
+``k`` (integer) [unsigned long]
+ Convert a Python integer or long integer to a C :ctype:`unsigned long`
+ without overflow checking.
+
+ .. versionadded:: 2.3
+
+``L`` (integer) [PY_LONG_LONG]
+ Convert a Python integer to a C :ctype:`long long`. This format is only
+ available on platforms that support :ctype:`long long` (or :ctype:`_int64`
+ on Windows).
+
+``K`` (integer) [unsigned PY_LONG_LONG]
+ Convert a Python integer or long integer to a C :ctype:`unsigned long long`
+ without overflow checking. This format is only available on platforms that
+ support :ctype:`unsigned long long` (or :ctype:`unsigned _int64` on
+ Windows).
+
+ .. versionadded:: 2.3
+
+``n`` (integer) [Py_ssize_t]
+ Convert a Python integer or long integer to a C :ctype:`Py_ssize_t`.
+
+ .. versionadded:: 2.5
+
+``c`` (string of length 1) [char]
+ Convert a Python character, represented as a string of length 1, to a C
+ :ctype:`char`.
+
+``f`` (float) [float]
+ Convert a Python floating point number to a C :ctype:`float`.
+
+``d`` (float) [double]
+ Convert a Python floating point number to a C :ctype:`double`.
+
+``D`` (complex) [Py_complex]
+ Convert a Python complex number to a C :ctype:`Py_complex` structure.
+
+``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 :ctype:`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 :ctype:`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
+ :ctype:`void\*` argument that was passed to the :cfunc:`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.
+
+``S`` (string) [PyStringObject \*]
+ Like ``O`` but requires that the Python object is a string object. Raises
+ :exc:`TypeError` if the object is not a string object. The C variable may
+ also be declared as :ctype:`PyObject\*`.
+
+``U`` (Unicode string) [PyUnicodeObject \*]
+ Like ``O`` but requires that the Python object is a Unicode object. Raises
+ :exc:`TypeError` if the object is not a Unicode object. The C variable may
+ also be declared as :ctype:`PyObject\*`.
+
+``t#`` (read-only character buffer) [char \*, int]
+ Like ``s#``, but accepts any object which implements the read-only buffer
+ interface. The :ctype:`char\*` variable is set to point to the first byte
+ of the buffer, and the :ctype:`int` is set to the length of the buffer.
+ Only single-segment buffer objects are accepted; :exc:`TypeError` is raised
+ for all others.
+
+``w`` (read-write character buffer) [char \*]
+ Similar to ``s``, but accepts any object which implements the read-write
+ buffer interface. The caller must determine the length of the buffer by
+ other means, or use ``w#`` instead. Only single-segment buffer objects are
+ accepted; :exc:`TypeError` is raised for all others.
+
+``w#`` (read-write character buffer) [char \*, Py_ssize_t]
+ Like ``s#``, but accepts any object which implements the read-write buffer
+ interface. The :ctype:`char \*` variable is set to point to the first byte
+ of the buffer, and the :ctype:`Py_ssize_t` is set to the length of the
+ buffer. Only single-segment buffer objects are accepted; :exc:`TypeError`
+ is raised for all others.
+
+``w*`` (read-write byte-oriented buffer) [Py_buffer]
+ This is to ``w`` what ``s*`` is to ``s``.
+
+ .. versionadded:: 2.6
+
+``(items)`` (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.
+
+ .. note::
+
+ Prior to Python version 1.5.2, this format specifier only accepted a
+ tuple containing the individual parameters, not an arbitrary sequence.
+ Code which previously caused :exc:`TypeError` to be raised here may now
+ proceed without an exception. This is not expected to be a problem for
+ existing code.
+
+It is possible to pass Python long integers where integers are requested;
+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, :cfunc:`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 :cfunc:`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 :cfunc:`PyArg_Parse\*` functions
+return true, otherwise they return false and raise an appropriate exception.
+When the :cfunc:`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.
+
+
+.. cfunction:: 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.
+
+
+.. cfunction:: int PyArg_VaParse(PyObject *args, const char *format, va_list vargs)
+
+ Identical to :cfunc:`PyArg_ParseTuple`, except that it accepts a va_list
+ rather than a variable number of arguments.
+
+
+.. cfunction:: 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.
+
+
+.. cfunction:: int PyArg_VaParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *keywords[], va_list vargs)
+
+ Identical to :cfunc:`PyArg_ParseTupleAndKeywords`, except that it accepts a
+ va_list rather than a variable number of arguments.
+
+
+.. cfunction:: 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.
+
+
+.. cfunction:: 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 :ctype:`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 :cfunc:`PyArg_UnpackTuple` in this example is entirely
+ equivalent to this call to :cfunc:`PyArg_ParseTuple`::
+
+ PyArg_ParseTuple(args, "O|O:ref", &object, &callback)
+
+ .. versionadded:: 2.2
+
+ .. versionchanged:: 2.5
+ This function used an :ctype:`int` type for *min* and *max*. This might
+ require changes in your code for properly supporting 64-bit systems.
+
+
+.. cfunction:: PyObject* Py_BuildValue(const char *format, ...)
+
+ Create a new value based on a format string similar to those accepted by
+ the :cfunc:`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.
+
+ :cfunc:`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 :cfunc:`Py_BuildValue`. In other words, if your code invokes
+ :cfunc:`malloc` and passes the allocated memory to :cfunc:`Py_BuildValue`,
+ your code is responsible for calling :cfunc:`free` for that memory once
+ :cfunc:`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`` (string) [char \*]
+ Convert a null-terminated C string to a Python object. If the C string
+ pointer is *NULL*, ``None`` is used.
+
+ ``s#`` (string) [char \*, int]
+ Convert a C string and its length to a Python object. If the C string
+ pointer is *NULL*, the length is ignored and ``None`` is returned.
+
+ ``z`` (string or ``None``) [char \*]
+ Same as ``s``.
+
+ ``z#`` (string or ``None``) [char \*, int]
+ Same as ``s#``.
+
+ ``u`` (Unicode string) [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#`` (Unicode string) [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.
+
+ ``i`` (integer) [int]
+ Convert a plain C :ctype:`int` to a Python integer object.
+
+ ``b`` (integer) [char]
+ Convert a plain C :ctype:`char` to a Python integer object.
+
+ ``h`` (integer) [short int]
+ Convert a plain C :ctype:`short int` to a Python integer object.
+
+ ``l`` (integer) [long int]
+ Convert a C :ctype:`long int` to a Python integer object.
+
+ ``B`` (integer) [unsigned char]
+ Convert a C :ctype:`unsigned char` to a Python integer object.
+
+ ``H`` (integer) [unsigned short int]
+ Convert a C :ctype:`unsigned short int` to a Python integer object.
+
+ ``I`` (integer/long) [unsigned int]
+ Convert a C :ctype:`unsigned int` to a Python integer object or a Python
+ long integer object, if it is larger than ``sys.maxint``.
+
+ ``k`` (integer/long) [unsigned long]
+ Convert a C :ctype:`unsigned long` to a Python integer object or a
+ Python long integer object, if it is larger than ``sys.maxint``.
+
+ ``L`` (long) [PY_LONG_LONG]
+ Convert a C :ctype:`long long` to a Python long integer object. Only
+ available on platforms that support :ctype:`long long`.
+
+ ``K`` (long) [unsigned PY_LONG_LONG]
+ Convert a C :ctype:`unsigned long long` to a Python long integer object.
+ Only available on platforms that support :ctype:`unsigned long long`.
+
+ ``n`` (int) [Py_ssize_t]
+ Convert a C :ctype:`Py_ssize_t` to a Python integer or long integer.
+
+ .. versionadded:: 2.5
+
+ ``c`` (string of length 1) [char]
+ Convert a C :ctype:`int` representing a character to a Python string of
+ length 1.
+
+ ``d`` (float) [double]
+ Convert a C :ctype:`double` to a Python floating point number.
+
+ ``f`` (float) [float]
+ Same as ``d``.
+
+ ``D`` (complex) [Py_complex \*]
+ Convert a C :ctype:`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, :cfunc:`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
+ :ctype:`void \*`) as its argument and should return a "new" Python
+ object, or *NULL* if an error occurred.
+
+ ``(items)`` (tuple) [*matching-items*]
+ Convert a sequence of C values to a Python tuple with the same number of
+ items.
+
+ ``[items]`` (list) [*matching-items*]
+ Convert a sequence of C values to a Python list with the same number of
+ items.
+
+ ``{items}`` (dictionary) [*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.
+
+.. cfunction:: PyObject* Py_VaBuildValue(const char *format, va_list vargs)
+
+ Identical to :cfunc:`Py_BuildValue`, except that it accepts a va_list
+ rather than a variable number of arguments.
54 c-api/bool.rst
View
@@ -0,0 +1,54 @@
+.. 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.
+
+
+.. cfunction:: int PyBool_Check(PyObject *o)
+
+ Return true if *o* is of type :cdata:`PyBool_Type`.
+
+ .. versionadded:: 2.3
+
+
+.. cvar:: 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.
+
+
+.. cvar:: 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.
+
+
+.. cmacro:: Py_RETURN_FALSE
+
+ Return :const:`Py_False` from a function, properly incrementing its reference
+ count.
+
+ .. versionadded:: 2.4
+
+
+.. cmacro:: Py_RETURN_TRUE
+
+ Return :const:`Py_True` from a function, properly incrementing its reference
+ count.
+
+ .. versionadded:: 2.4
+
+
+.. cfunction:: PyObject* PyBool_FromLong(long v)
+
+ Return a new reference to :const:`Py_True` or :const:`Py_False` depending on the
+ truth value of *v*.
+
+ .. versionadded:: 2.3
450 c-api/buffer.rst
View
@@ -0,0 +1,450 @@
+.. highlightlang:: c
+
+.. _bufferobjects:
+
+Buffers and Memoryview Objects
+------------------------------
+
+.. sectionauthor:: Greg Stein <gstein@lyra.org>
+.. sectionauthor:: Benjamin Peterson
+
+
+.. index::
+ object: buffer
+ single: buffer interface
+
+Python objects implemented in C can export a group of functions called the
+"buffer interface." These functions can be used by an object to expose its
+data in a raw, byte-oriented format. Clients of the object can use the buffer
+interface to access the object data directly, without needing to copy it
+first.
+
+Two examples of objects that support the buffer interface are strings and
+arrays. The string object exposes the character contents in the buffer
+interface's byte-oriented form. An array can also expose its contents, but it
+should be noted that array elements may be multi-byte values.
+
+An example user of the buffer interface is the file object's :meth:`write`
+method. Any object that can export a series of bytes through the buffer
+interface can be written to a file. There are a number of format codes to
+:cfunc:`PyArg_ParseTuple` that operate against an object's buffer interface,
+returning data from the target object.
+
+Starting from version 1.6, Python has been providing Python-level buffer
+objects and a C-level buffer API so that any built-in or used-defined type can
+expose its characteristics. Both, however, have been deprecated because of
+various shortcomings, and have been officially removed in Python 3.0 in favour
+of a new C-level buffer API and a new Python-level object named
+:class:`memoryview`.
+
+The new buffer API has been backported to Python 2.6, and the
+:class:`memoryview` object has been backported to Python 2.7. It is strongly
+advised to use them rather than the old APIs, unless you are blocked from
+doing so for compatibility reasons.
+
+
+The new-style Py_buffer struct
+==============================
+
+
+.. ctype:: Py_buffer
+
+ .. cmember:: void *buf
+
+ A pointer to the start of the memory for the object.
+
+ .. cmember:: Py_ssize_t len
+ :noindex:
+
+ The total length of the memory in bytes.
+
+ .. cmember:: int readonly
+
+ An indicator of whether the buffer is read only.
+
+ .. cmember:: 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.
+
+ .. cmember:: int ndim
+
+ The number of dimensions the memory represents as a multi-dimensional
+ array. If it is 0, :cdata:`strides` and :cdata:`suboffsets` must be
+ *NULL*.
+
+ .. cmember:: Py_ssize_t *shape
+
+ An array of :ctype:`Py_ssize_t`\s the length of :cdata:`ndim` giving the
+ shape of the memory as a multi-dimensional array. Note that
+ ``((*shape)[0] * ... * (*shape)[ndims-1])*itemsize`` should be equal to
+ :cdata:`len`.
+
+ .. cmember:: Py_ssize_t *strides
+
+ An array of :ctype:`Py_ssize_t`\s the length of :cdata:`ndim` giving the
+ number of bytes to skip to get to a new element in each dimension.
+
+ .. cmember:: Py_ssize_t *suboffsets
+
+ An array of :ctype:`Py_ssize_t`\s the length of :cdata:`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-dimesional 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;
+ }
+
+
+ .. cmember:: 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 :cfunc:`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.
+
+ .. cmember:: 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
+========================
+
+
+.. cfunction:: int PyObject_CheckBuffer(PyObject *obj)
+
+ Return 1 if *obj* supports the buffer interface otherwise 0.
+
+
+.. cfunction:: int PyObject_GetBuffer(PyObject *obj, Py_buffer *view, int flags)
+
+ Export *obj* into a :ctype:`Py_buffer`, *view*. These arguments must
+ never be *NULL*. The *flags* argument is a bit field indicating what
+ kind of buffer the caller is prepared to deal with and therefore what
+ kind of buffer the exporter is allowed to return. The buffer interface
+ allows for complicated memory sharing possibilities, but some caller may
+ not be able to handle all the complexity but may want to see if the
+ exporter will let them take a simpler view to its memory.
+
+ 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
+ :cdata:`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.
+
+ 0 is returned on success and -1 on error.
+
+ The following table gives possible values to the *flags* arguments.
+
+ +------------------------------+---------------------------------------------------+
+ | Flag | Description |
+ +==============================+===================================================+
+ | :cmacro:`PyBUF_SIMPLE` | This is the default flag state. The returned |
+ | | buffer may or may not have writable memory. The |
+ | | format of the data will be assumed to be unsigned |
+ | | bytes. 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. |
+ | | |
+ +------------------------------+---------------------------------------------------+
+ | :cmacro:`PyBUF_WRITABLE` | The returned buffer must be writable. If it is |
+ | | not writable, then raise an error. |
+ +------------------------------+---------------------------------------------------+
+ | :cmacro:`PyBUF_STRIDES` | This implies :cmacro:`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). |
+ | | |
+ +------------------------------+---------------------------------------------------+
+ | :cmacro:`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*. |
+ | | |
+ | | |
+ | | |
+ +------------------------------+---------------------------------------------------+
+ |:cmacro:`PyBUF_C_CONTIGUOUS` | These flags indicate that the contiguity returned |
+ |:cmacro:`PyBUF_F_CONTIGUOUS` | buffer must be respectively, C-contiguous (last |
+ |:cmacro:`PyBUF_ANY_CONTIGUOUS`| dimension varies the fastest), Fortran contiguous |
+ | | (first dimension varies the fastest) or either |
+ | | one. All of these flags imply |
+ | | :cmacro:`PyBUF_STRIDES` and guarantee that the |
+ | | strides buffer info structure will be filled in |
+ | | correctly. |
+ | | |
+ +------------------------------+---------------------------------------------------+
+ | :cmacro:`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 :cmacro:`PyBUF_STRIDES`. |
+ | | |
+ | | |
+ | | |
+ +------------------------------+---------------------------------------------------+
+ | :cmacro:`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) |
+ +------------------------------+---------------------------------------------------+
+ | :cmacro:`PyBUF_STRIDED` | This is equivalent to ``(PyBUF_STRIDES | |
+ | | PyBUF_WRITABLE)``. |
+ +------------------------------+---------------------------------------------------+
+ | :cmacro:`PyBUF_STRIDED_RO` | This is equivalent to ``(PyBUF_STRIDES)``. |
+ | | |
+ +------------------------------+---------------------------------------------------+
+ | :cmacro:`PyBUF_RECORDS` | This is equivalent to ``(PyBUF_STRIDES | |
+ | | PyBUF_FORMAT | PyBUF_WRITABLE)``. |
+ +------------------------------+---------------------------------------------------+
+ | :cmacro:`PyBUF_RECORDS_RO` | This is equivalent to ``(PyBUF_STRIDES | |
+ | | PyBUF_FORMAT)``. |
+ +------------------------------+---------------------------------------------------+
+ | :cmacro:`PyBUF_FULL` | This is equivalent to ``(PyBUF_INDIRECT | |
+ | | PyBUF_FORMAT | PyBUF_WRITABLE)``. |
+ +------------------------------+---------------------------------------------------+
+ | :cmacro:`PyBUF_FULL_RO` | This is equivalent to ``(PyBUF_INDIRECT | |
+ | | PyBUF_FORMAT)``. |
+ +------------------------------+---------------------------------------------------+
+ | :cmacro:`PyBUF_CONTIG` | This is equivalent to ``(PyBUF_ND | |
+ | | PyBUF_WRITABLE)``. |
+ +------------------------------+---------------------------------------------------+
+ | :cmacro:`PyBUF_CONTIG_RO` | This is equivalent to ``(PyBUF_ND)``. |
+ | | |
+ +------------------------------+---------------------------------------------------+
+
+
+.. cfunction:: 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.
+
+
+.. cfunction:: Py_ssize_t PyBuffer_SizeFromFormat(const char *)
+
+ Return the implied :cdata:`~Py_buffer.itemsize` from the struct-stype
+ :cdata:`~Py_buffer.format`.
+
+
+.. cfunction:: 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.
+
+
+.. cfunction:: 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.
+
+
+.. cfunction:: 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.
+
+
+MemoryView objects
+==================
+
+.. versionadded:: 2.7
+
+A :class:`memoryview` object exposes the new C level buffer interface as a
+Python object which can then be passed around like any other object.
+
+.. cfunction:: PyObject *PyMemoryView_FromObject(PyObject *obj)
+
+ Create a memoryview object from an object that defines the new buffer
+ interface.
+
+
+.. cfunction:: PyObject *PyMemoryView_FromBuffer(Py_buffer *view)
+
+ Create a memoryview object wrapping the given buffer-info structure *view*.
+ The memoryview object then owns the buffer, which means you shouldn't
+ try to release it yourself: it will be released on deallocation of the
+ memoryview object.
+
+
+.. cfunction:: 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 copy is made and the memoryview points to a
+ new bytes object.
+
+
+.. cfunction:: 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`.
+
+
+.. cfunction:: Py_buffer *PyMemoryView_GET_BUFFER(PyObject *obj)
+
+ Return a pointer to the buffer-info structure wrapped by the given
+ 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.
+
+
+Old-style buffer objects
+========================
+
+.. index:: single: PyBufferProcs
+
+More information on the old buffer interface is provided in the section
+:ref:`buffer-structs`, under the description for :ctype:`PyBufferProcs`.
+
+A "buffer object" is defined in the :file:`bufferobject.h` header (included by
+:file:`Python.h`). These objects look very similar to string objects at the
+Python programming level: they support slicing, indexing, concatenation, and
+some other standard string operations. However, their data can come from one
+of two sources: from a block of memory, or from another object which exports
+the buffer interface.
+
+Buffer objects are useful as a way to expose the data from another object's
+buffer interface 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.
+
+
+.. ctype:: PyBufferObject
+
+ This subtype of :ctype:`PyObject` represents a buffer object.
+
+
+.. cvar:: PyTypeObject PyBuffer_Type
+
+ .. index:: single: BufferType (in module types)
+
+ The instance of :ctype:`PyTypeObject` which represents the Python buffer type;
+ it is the same object as ``buffer`` and ``types.BufferType`` in the Python
+ layer. .
+
+
+.. cvar:: int Py_END_OF_BUFFER
+
+ This constant may be passed as the *size* parameter to
+ :cfunc:`PyBuffer_FromObject` or :cfunc:`PyBuffer_FromReadWriteObject`. It
+ indicates that the new :ctype:`PyBufferObject` should refer to *base*
+ object from the specified *offset* to the end of its exported buffer.
+ Using this enables the caller to avoid querying the *base* object for its
+ length.
+
+
+.. cfunction:: int PyBuffer_Check(PyObject *p)
+
+ Return true if the argument has type :cdata:`PyBuffer_Type`.
+
+
+.. cfunction:: PyObject* PyBuffer_FromObject(PyObject *base, Py_ssize_t offset, Py_ssize_t size)
+
+ Return a new read-only buffer object. This raises :exc:`TypeError` if
+ *base* doesn't support the read-only buffer protocol or doesn't provide
+ exactly one buffer segment, or it raises :exc:`ValueError` if *offset* is
+ less than zero. The buffer will hold a reference to the *base* object, and
+ the buffer's contents will refer to the *base* object's buffer interface,
+ starting as position *offset* and extending for *size* bytes. If *size* is
+ :const:`Py_END_OF_BUFFER`, then the new buffer's contents extend to the
+ length of the *base* object's exported buffer data.
+
+ .. versionchanged:: 2.5
+ This function used an :ctype:`int` type for *offset* and *size*. This
+ might require changes in your code for properly supporting 64-bit
+ systems.
+
+
+.. cfunction:: PyObject* PyBuffer_FromReadWriteObject(PyObject *base, Py_ssize_t offset, Py_ssize_t size)
+
+ Return a new writable buffer object. Parameters and exceptions are similar
+ to those for :cfunc:`PyBuffer_FromObject`. If the *base* object does not
+ export the writeable buffer protocol, then :exc:`TypeError` is raised.
+
+ .. versionchanged:: 2.5
+ This function used an :ctype:`int` type for *offset* and *size*. This
+ might require changes in your code for properly supporting 64-bit
+ systems.
+
+
+.. cfunction:: PyObject* PyBuffer_FromMemory(void *ptr, Py_ssize_t size)
+
+ Return a new read-only buffer object that reads from a specified location
+ in memory, with a specified size. The caller is responsible for ensuring
+ that the memory buffer, passed in as *ptr*, is not deallocated while the
+ returned buffer object exists. Raises :exc:`ValueError` if *size* is less
+ than zero. Note that :const:`Py_END_OF_BUFFER` may *not* be passed for the
+ *size* parameter; :exc:`ValueError` will be raised in that case.
+
+ .. versionchanged:: 2.5
+ This function used an :ctype:`int` type for *size*. This might require
+ changes in your code for properly supporting 64-bit systems.
+
+
+.. cfunction:: PyObject* PyBuffer_FromReadWriteMemory(void *ptr, Py_ssize_t size)
+
+ Similar to :cfunc:`PyBuffer_FromMemory`, but the returned buffer is
+ writable.
+
+ .. versionchanged:: 2.5
+ This function used an :ctype:`int` type for *size*. This might require
+ changes in your code for properly supporting 64-bit systems.
+
+
+.. cfunction:: PyObject* PyBuffer_New(Py_ssize_t size)
+
+ Return a new writable buffer object that maintains its own memory buffer of
+ *size* bytes. :exc:`ValueError` is returned if *size* is not zero or
+ positive. Note that the memory buffer (as returned by
+ :cfunc:`PyObject_AsWriteBuffer`) is not specifically aligned.
+
+ .. versionchanged:: 2.5
+ This function used an :ctype:`int` type for *size*. This might require
+ changes in your code for properly supporting 64-bit systems.
87 c-api/bytearray.rst
View
@@ -0,0 +1,87 @@
+.. highlightlang:: c
+
+.. _bytearrayobjects:
+
+Byte Array Objects
+------------------
+
+.. index:: object: bytearray
+
+.. versionadded:: 2.6
+
+
+.. ctype:: PyByteArrayObject
+
+ This subtype of :ctype:`PyObject` represents a Python bytearray object.
+
+
+.. cvar:: PyTypeObject PyByteArray_Type
+
+ This instance of :ctype:`PyTypeObject` represents the Python bytearray type;
+ it is the same object as ``bytearray`` in the Python layer.
+
+Type check macros
+^^^^^^^^^^^^^^^^^
+
+.. cfunction:: 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.
+
+
+.. cfunction:: 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
+^^^^^^^^^^^^^^^^^^^^
+
+.. cfunction:: 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
+
+
+.. cfunction:: 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.
+
+
+.. cfunction:: PyObject* PyByteArray_Concat(PyObject *a, PyObject *b)
+
+ Concat bytearrays *a* and *b* and return a new bytearray with the result.
+
+
+.. cfunction:: Py_ssize_t PyByteArray_Size(PyObject *bytearray)
+
+ Return the size of *bytearray* after checking for a *NULL* pointer.
+
+
+.. cfunction:: char* PyByteArray_AsString(PyObject *bytearray)
+
+ Return the contents of *bytearray* as a char array after checking for a
+ *NULL* pointer.
+
+
+.. cfunction:: 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.
+
+.. cfunction:: char* PyByteArray_AS_STRING(PyObject *bytearray)
+
+ Macro version of :cfunc:`PyByteArray_AsString`.
+
+
+.. cfunction:: Py_ssize_t PyByteArray_GET_SIZE(PyObject *bytearray)
+
+ Macro version of :cfunc:`PyByteArray_Size`.
150 c-api/capsule.rst
View
@@ -0,0 +1,150 @@
+.. highlightlang:: c
+
+.. _capsules:
+
+Capsules
+--------
+
+.. index:: object: Capsule
+
+Refer to :ref:`using-capsules` for more information on using these objects.
+
+
+.. ctype:: PyCapsule
+
+ This subtype of :ctype:`PyObject` represents an opaque value, useful for C
+ extension modules who need to pass an opaque value (as a :ctype:`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.
+
+.. ctype:: PyCapsule_Destructor
+
+ The type of a destructor callback for a capsule. Defined as::
+
+ typedef void (*PyCapsule_Destructor)(PyObject *);
+
+ See :cfunc:`PyCapsule_New` for the semantics of PyCapsule_Destructor
+ callbacks.
+
+
+.. cfunction:: int PyCapsule_CheckExact(PyObject *p)
+
+ Return true if its argument is a :ctype:`PyCapsule`.
+
+
+.. cfunction:: PyObject* PyCapsule_New(void *pointer, const char *name, PyCapsule_Destructor destructor)
+
+ Create a :ctype:`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 :cfunc:`PyCapsule_Import`.
+
+
+.. cfunction:: 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 :cfunc:`strcmp` to compare capsule
+ names.
+
+
+.. cfunction:: 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 :cfunc:`PyCapsule_IsValid` or
+ :cfunc:`PyErr_Occurred` to disambiguate.
+
+
+.. cfunction:: 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 :cfunc:`PyCapsule_IsValid` or
+ :cfunc:`PyErr_Occurred` to disambiguate.
+
+
+.. cfunction:: 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 :cfunc:`PyCapsule_IsValid` or
+ :cfunc:`PyErr_Occurred` to disambiguate.
+
+
+.. cfunction:: 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 :cfunc:`PyImport_ImportModuleNoBlock`). If *no_block* is false,
+ import the module conventionally (using :cfunc:`PyImport_ImportModule`).
+
+ Return the capsule's internal *pointer* on success. On failure, set an
+ exception and return *NULL*. However, if :cfunc:`PyCapsule_Import` failed to
+ import the module, and *no_block* was true, no exception is set.
+
+.. cfunction:: int PyCapsule_IsValid(PyObject *capsule, const char *name)
+
+ Determines whether or not *capsule* is a valid capsule. A valid capsule is
+ non-*NULL*, passes :cfunc:`PyCapsule_CheckExact`, has a non-*NULL* pointer
+ stored in it, and its internal name matches the *name* parameter. (See
+ :cfunc:`PyCapsule_GetPointer` for information on how capsule names are
+ compared.)
+
+ In other words, if :cfunc:`PyCapsule_IsValid` returns a true value, calls to
+ any of the accessors (any function starting with :cfunc:`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.
+
+.. cfunction:: 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.
+
+.. cfunction:: 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.
+
+.. cfunction:: 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.
+
+.. cfunction:: 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.
62 c-api/cell.rst
View
@@ -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.
+
+
+.. ctype:: PyCellObject
+
+ The C structure used for cell objects.
+
+
+.. cvar:: PyTypeObject PyCell_Type
+
+ The type object corresponding to cell objects.
+
+
+.. cfunction:: int PyCell_Check(ob)
+
+ Return true if *ob* is a cell object; *ob* must not be *NULL*.
+
+
+.. cfunction:: PyObject* PyCell_New(PyObject *ob)
+
+ Create and return a new cell object containing the value *ob*. The parameter may
+ be *NULL*.
+
+
+.. cfunction:: PyObject* PyCell_Get(PyObject *cell)
+
+ Return the contents of the cell *cell*.
+
+
+.. cfunction:: PyObject* PyCell_GET(PyObject *cell)
+
+ Return the contents of the cell *cell*, but without checking that *cell* is
+ non-*NULL* and a cell object.
+
+
+.. cfunction:: 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.
+
+
+.. cfunction:: 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.
65 c-api/class.rst
View
@@ -0,0 +1,65 @@
+.. highlightlang:: c
+
+.. _classobjects:
+
+Class and Instance Objects
+--------------------------
+
+.. index:: object: class
+
+Note that the class objects described here represent old-style classes, which
+will go away in Python 3. When creating new types for extension modules, you
+will want to work with type objects (section :ref:`typeobjects`).
+
+
+.. ctype:: PyClassObject
+
+ The C structure of the objects used to describe built-in classes.
+
+
+.. cvar:: PyObject* PyClass_Type
+
+ .. index:: single: ClassType (in module types)
+
+ This is the type object for class objects; it is the same object as
+ ``types.ClassType`` in the Python layer.
+
+
+.. cfunction:: int PyClass_Check(PyObject *o)
+
+ Return true if the object *o* is a class object, including instances of types
+ derived from the standard class object. Return false in all other cases.
+
+
+.. cfunction:: int PyClass_IsSubclass(PyObject *klass, PyObject *base)
+
+ Return true if *klass* is a subclass of *base*. Return false in all other cases.
+
+
+.. index:: object: instance
+
+There are very few functions specific to instance objects.
+
+
+.. cvar:: PyTypeObject PyInstance_Type
+
+ Type object for class instances.
+
+
+.. cfunction:: int PyInstance_Check(PyObject *obj)
+
+ Return true if *obj* is an instance.
+
+
+.. cfunction:: PyObject* PyInstance_New(PyObject *class, PyObject *arg, PyObject *kw)
+
+ Create a new instance of a specific class. The parameters *arg* and *kw* are
+ used as the positional and keyword parameters to the object's constructor.
+
+
+.. cfunction:: PyObject* PyInstance_NewRaw(PyObject *class, PyObject *dict)
+
+ Create a new instance of a specific class without calling its constructor.
+ *class* is the class of new object. The *dict* parameter will be used as the
+ object's :attr:`__dict__`; if *NULL*, a new dictionary will be created for the
+ instance.
59 c-api/cobject.rst
View
@@ -0,0 +1,59 @@
+.. highlightlang:: c
+
+.. _cobjects:
+
+CObjects
+--------
+
+.. index:: object: CObject
+
+
+.. warning::
+
+ The CObject API is deprecated as of Python 2.7. Please switch to the new
+ :ref:`capsules` API.
+
+.. ctype:: PyCObject
+
+ This subtype of :ctype:`PyObject` represents an opaque value, useful for C
+ extension modules who need to pass an opaque value (as a :ctype:`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.
+
+
+.. cfunction:: int PyCObject_Check(PyObject *p)
+
+ Return true if its argument is a :ctype:`PyCObject`.
+
+
+.. cfunction:: PyObject* PyCObject_FromVoidPtr(void* cobj, void (*destr)(void *))
+
+ Create a :ctype:`PyCObject` from the ``void *`` *cobj*. The *destr* function
+ will be called when the object is reclaimed, unless it is *NULL*.
+
+
+.. cfunction:: PyObject* PyCObject_FromVoidPtrAndDesc(void* cobj, void* desc, void (*destr)(void *, void *))
+
+ Create a :ctype:`PyCObject` from the :ctype:`void \*` *cobj*. The *destr*
+ function will be called when the object is reclaimed. The *desc* argument can
+ be used to pass extra callback data for the destructor function.
+
+
+.. cfunction:: void* PyCObject_AsVoidPtr(PyObject* self)
+
+ Return the object :ctype:`void \*` that the :ctype:`PyCObject` *self* was
+ created with.
+
+
+.. cfunction:: void* PyCObject_GetDesc(PyObject* self)
+
+ Return the description :ctype:`void \*` that the :ctype:`PyCObject` *self* was
+ created with.
+
+
+.. cfunction:: int PyCObject_SetVoidPtr(PyObject* self, void* cobj)
+
+ Set the void pointer inside *self* to *cobj*. The :ctype:`PyCObject` must not
+ have an associated destructor. Return true on success, false on failure.
50 c-api/code.rst
View
@@ -0,0 +1,50 @@
+.. highlightlang:: c
+
+.. _codeobjects:
+
+Code Objects
+------------
+
+.. sectionauthor:: Jeffrey Yasskin <jyasskin@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.
+
+.. ctype:: PyCodeObject
+
+ The C structure of the objects used to describe code objects. The
+ fields of this type are subject to change at any time.
+
+
+.. cvar:: PyTypeObject PyCode_Type
+
+ This is an instance of :ctype:`PyTypeObject` representing the Python
+ :class:`code` type.
+
+
+.. cfunction:: int PyCode_Check(PyObject *co)
+
+ Return true if *co* is a :class:`code` object
+
+.. cfunction:: int PyCode_GetNumFree(PyObject *co)
+
+ Return the number of free variables in *co*.
+
+.. cfunction:: 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 :cfunc:`PyCode_NewEmpty` instead. Calling
+ :cfunc:`PyCode_New` directly can bind you to a precise Python
+ version since the definition of the bytecode changes often.
+
+
+.. cfunction:: 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
+ :keyword:`exec` or :func:`eval` the resulting code object.
118 c-api/codec.rst
View
@@ -0,0 +1,118 @@
+.. _codec-registry:
+
+Codec registry and support functions
+====================================
+
+.. cfunction:: 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.
+
+.. cfunction:: int PyCodec_KnownEncoding(const char *encoding)
+
+ Return ``1`` or ``0`` depending on whether there is a registered codec for
+ the given *encoding*.
+
+.. cfunction:: 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.
+
+.. cfunction:: 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.
+
+.. cfunction:: PyObject* PyCodec_Encoder(const char *encoding)
+
+ Get an encoder function for the given *encoding*.
+
+.. cfunction:: PyObject* PyCodec_Decoder(const char *encoding)
+
+ Get a decoder function for the given *encoding*.
+
+.. cfunction:: PyObject* PyCodec_IncrementalEncoder(const char *encoding, const char *errors)
+
+ Get an :class:`IncrementalEncoder` object for the given *encoding*.
+
+.. cfunction:: PyObject* PyCodec_IncrementalDecoder(const char *encoding, const char *errors)
+
+ Get an :class:`IncrementalDecoder` object for the given *encoding*.
+
+.. cfunction:: PyObject* PyCodec_StreamReader(const char *encoding, PyObject *stream, const char *errors)
+
+ Get a :class:`StreamReader` factory function for the given *encoding*.
+
+.. cfunction:: 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
+------------------------------------------------
+
+.. cfunction:: 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.
+
+.. cfunction:: 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.
+
+.. cfunction:: PyObject* PyCodec_StrictErrors(PyObject *exc)
+
+ Raise *exc* as an exception.
+
+.. cfunction:: PyObject* PyCodec_IgnoreErrors(PyObject *exc)
+
+ Ignore the unicode error, skipping the faulty input.
+
+.. cfunction:: PyObject* PyCodec_ReplaceErrors(PyObject *exc)
+
+ Replace the unicode encode error with ``?`` or ``U+FFFD``.
+
+.. cfunction:: PyObject* PyCodec_XMLCharRefReplaceErrors(PyObject *exc)
+
+ Replace the unicode encode error with XML character references.
+
+.. cfunction:: PyObject* PyCodec_BackslashReplaceErrors(PyObject *exc)
+
+ Replace the unicode encode error with backslash escapes (``\x``, ``\u`` and
+ ``\U``).
+
132 c-api/complex.rst
View
@@ -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.
+
+
+.. ctype:: 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;
+
+
+.. cfunction:: Py_complex _Py_c_sum(Py_complex left, Py_complex right)
+
+ Return the sum of two complex numbers, using the C :ctype:`Py_complex`
+ representation.
+
+
+.. cfunction:: Py_complex _Py_c_diff(Py_complex left, Py_complex right)
+
+ Return the difference between two complex numbers, using the C
+ :ctype:`Py_complex` representation.
+
+
+.. cfunction:: Py_complex _Py_c_neg(Py_complex complex)
+
+ Return the negation of the complex number *complex*, using the C
+ :ctype:`Py_complex` representation.
+
+
+.. cfunction:: Py_complex _Py_c_prod(Py_complex left, Py_complex right)
+
+ Return the product of two complex numbers, using the C :ctype:`Py_complex`
+ representation.
+
+
+.. cfunction:: Py_complex _Py_c_quot(Py_complex dividend, Py_complex divisor)
+
+ Return the quotient of two complex numbers, using the C :ctype:`Py_complex`
+ representation.
+
+
+.. cfunction:: Py_complex _Py_c_pow(Py_complex num, Py_complex exp)
+
+ Return the exponentiation of *num* by *exp*, using the C :ctype:`Py_complex`
+ representation.
+
+
+Complex Numbers as Python Objects
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+
+.. ctype:: PyComplexObject
+
+ This subtype of :ctype:`PyObject` represents a Python complex number object.
+
+
+.. cvar:: PyTypeObject PyComplex_Type
+
+ This instance of :ctype:`PyTypeObject` represents the Python complex number
+ type. It is the same object as ``complex`` and ``types.ComplexType``.
+
+
+.. cfunction:: int PyComplex_Check(PyObject *p)
+
+ Return true if its argument is a :ctype:`PyComplexObject` or a subtype of
+ :ctype:`PyComplexObject`.
+
+ .. versionchanged:: 2.2
+ Allowed subtypes to be accepted.
+
+
+.. cfunction:: int PyComplex_CheckExact(PyObject *p)
+
+ Return true if its argument is a :ctype:`PyComplexObject`, but not a subtype of
+ :ctype:`PyComplexObject`.
+
+ .. versionadded:: 2.2
+
+
+.. cfunction:: PyObject* PyComplex_FromCComplex(Py_complex v)
+
+ Create a new Python complex number object from a C :ctype:`Py_complex` value.
+
+
+.. cfunction:: PyObject* PyComplex_FromDoubles(double real, double imag)
+